---
name: openai-migration
description: Перенести существующую интеграцию с OpenAI на aLLModel (allmodel.ru) с минимальными изменениями — заменить baseURL, API-ключ и стратегию выбора модели.
metadata:
  version: 0.0.0
  homepage: https://allmodel.ru
---

# Миграция с OpenAI на aLLModel

Этот навык помогает перенести существующий проект, использующий OpenAI SDK, на aLLModel с минимальными изменениями. API aLLModel полностью OpenAI-совместимый, поэтому клиентский код почти не меняется.

## Предварительные требования

1. Зарегистрируйтесь на https://allmodel.ru и подтвердите email в профиле.
2. Пополните баланс (запросы списываются с кошелька).
3. Создайте API-ключ: https://allmodel.ru/dashboard?tab=api-keys

Базовый URL API:

```text
https://allmodel.ru/api/v1
```

Ключи начинаются с `sk_alm_` и передаются как `X-API-Key: <ключ>` или `Authorization: Bearer <ключ>`.

## Минимальный diff

| Что | OpenAI | aLLModel |
|---|---|---|
| baseURL | `https://api.openai.com/v1` | `https://allmodel.ru/api/v1` |
| Ключ | `sk-...` | `sk_alm_...` |
| Модель | `gpt-4o` и др. | имя из каталога `/api/v1/models` |
| Формат ответа | OpenAI | идентичен |

### before (OpenAI)

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Привет!" }],
});
```

### after (aLLModel)

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://allmodel.ru/api/v1",
  apiKey: process.env.ALLMODEL_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Привет!" }],
});
```

Изменений три: `baseURL`, `apiKey`, и проверка имени модели.

## Выбор модели

Имена моделей можно менять, поэтому не зашивайте их жёстко. Получите актуальный каталог:

```bash
curl https://allmodel.ru/api/v1/models
```

Ответ — `object: "list"` с `data[]`, где `id` — имя модели для запросов. Выберите модель с нужными характеристиками (контекст, стоимость, поддержка инструментов). Проверяйте заменитель каждой модели при миграции.

## Что поддерживается

- `/chat/completions` — запросы и ответы в OpenAI-формате, включая `system`/`user`/`assistant`/`tool` роли;
- streaming — SSE чанки `data: {...}` с `delta`, завершение `data: [DONE]`;
- tool calling — `tools` и `tool_choice`, ответ содержит `tool_calls`;
- дополнительные параметры запроса передаются как есть;
- `usage` и `cost` в ответе — для контроля расходов.

## Порядок миграции

1. Создайте API-ключ и проверьте, что баланс положительный.
2. Замените `baseURL` и `apiKey` (ключ — в переменную окружения).
3. Обновите жёстко заданные имена моделей по данным из `/api/v1/models`.
4. Прогоните существующие тесты запросов: обычный ответ, streaming, tool calling.
5. Убедитесь, что ответ содержит `usage`/`cost` и они корректно обрабатываются.

## Ошибки при миграции

| Код | Причина | Что делать |
|---|---|---|
| 400 | Невалидная модель или запрос | Проверьте имя модели в каталоге |
| 401 | Неверный ключ | Проверьте `sk_alm_...` ключ и срок действия |
| 402 | Недостаточно средств | Пополните баланс |
| 429 | Слишком много запросов | Добавьте ретраи с задержкой |

## Checklist

- [ ] `baseURL` заменён на `https://allmodel.ru/api/v1`
- [ ] API-ключ в переменной окружения, не в коде
- [ ] Имена моделей взяты из `/api/v1/models`
- [ ] Streaming работает
- [ ] Tool calling работает
- [ ] `usage` и `cost` обрабатываются

## Каноническая документация

- Полная документация одним файлом: https://allmodel.ru/llms-full.txt
- Обзор API: https://allmodel.ru/docs.md/api/obzor-api.md
- Обращения к моделям: https://allmodel.ru/docs.md/api/obrashcheniya-k-modelyam.md
- Аутентификация и ключи: https://allmodel.ru/docs.md/api/autentifikaciya.md