Migration API: Устранение распространенных ошибок интеграции LLM

Неверная конфигурация базового URL

Первая точка отказа почти всегда — базовый URL. При смене провайдера необходимо обновить конечную точку, к которой обращается ваш SDK. Неправильный URL приводит к ошибке 404 или 403 ещё до того, как полезная нагрузка покинет вашу машину.

Убедитесь, что ваш клиент указывает на правильный домен. Для нашего сервиса базовый URL — https://api.apimigration.com/v1. Этот URL работает со стандартными SDK OpenAI, просто изменив base_url параметр.

• Проверьте протокол (HTTPS vs HTTP).
• Проверьте наличие лишних слешей в конфигурации клиента.
• Убедитесь, что путь версии (/v1) соответствует спецификации вашего API.

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'

Игнорирование ограничений контекстного окна

Ваша модель имеет жесткий лимит в 100,000 токенов для суммы входных и выходных данных. Если вы превысите этот лимит, API отклонит запрос или молча обрежет историю в зависимости от реализации. Всегда отслеживайте использование токенов, чтобы избежать этого предела.

Кроме того, максимальный объем вывода на запрос составляет 16,000 токенов. Если вы не установите max_tokens, по умолчанию 2 048 токенов. Эта разница значительна для задач генерации длинных текстов.

• Отслеживайте общее количество токенов на запрос.
• Установить max_tokens явно для длинных выводов.
• Реализуйте логику скользящего окна для очень длинных разговоров.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

Неправильная реализация потоковой передачи

Потоковые ответы требуют специфической обработки событий Server-Sent Events (SSE). Если вы воспринимаете поток как единый объект JSON, ваш код зависнет или выдаст ошибку. Каждый фрагмент содержит частичные данные, а последний фрагмент включает статистику использования токенов.

Читайте поток инкрементально. Обрабатывайте каждое событие по мере его поступления. Это снижает воспринимаемую задержку для конечных пользователей. Не ждите всего ответа перед обработкой.

• Откройте соединение и читайте построчно.
• Разбор data: строк как JSON.
• Обработка [DONE] корректно сигнализирует.

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Tell the story in second person."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Игнорирование ограничений частоты запросов

Наш API позволяет выполнять 300 запросов в минуту на один ключ. Если ваше приложение испытывает всплески активности, вы получите ошибки 429 Too Many Requests. Вы должны реализовать экспоненциальное замедление с повторными попытками (exponential backoff) для корректной обработки этих ошибок.

Параллельные запросы также ограничены 8 одновременно на ключ. Превышение этого лимита может привести к исчерпанию пула соединений. Тщательно отслеживайте параллельные подключения.

• Реализуйте экспоненциальное замедление для ошибок 429.
• Ограничьте одновременные подключения до 8.
• Используйте паттерн «Circuit Breaker» при высокой нагрузке.

Copyimport OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.apimigration.com/v1", apiKey: process.env.API_KEY });

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);

Предполагая стандартные форматы JSON

Хотя мы следуем форматам, совместимым с OpenAI, предположения могут нарушить вашу интеграцию. Убедитесь, что вы запрашиваете json_object в response_format if you need strict JSON. Without this, the model may return markdown or plain text.

Внимательно разбирайте ответ. Проверяйте структуру JSON перед использованием. Это предотвращает ошибки времени выполнения в downstream-сервисах.

• Установить response_format для {"type": "json_object"}.
• Проверьте JSON перед парсингом.
• Обрабатывайте некорректные ответы корректно.

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'

Пренебрежение обработкой ошибок

API могут выходить из строя. Сетевые таймауты, ошибки сервера и некорректные полезные нагрузки случаются. Ваш код должен обрабатывать эти ошибки без сбоев. Логируйте детали ошибок для отладки.

Проверьте код ошибки и сообщение. Повторяйте попытку при временных ошибках. Быстро завершайте работу при постоянных ошибках. Это различие экономит время и ресурсы.

• Вести логи кодов ошибок и сообщений.
• Повторяйте запросы при ошибках 5xx с замедлением.
• Быстро ошибайтесь при ошибках 4xx.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

Проблемы с оплатой и ротацией ключей

Наш API использует предоплаченный кредит через криптовалюту. Кредит не истекает. Если у вас закончится кредит, запросы будут отклонены. Следите за балансом и пополняйте его, прежде чем он достигнет нуля.

Каждый аккаунт имеет один активный ключ. Генерация нового ключа немедленно аннулирует старый. Убедитесь, что ваше развертывание обновляет ключ атомарно, чтобы избежать простоев.

• Регулярно отслеживайте баланс кредитов.
• Вращайте ключи атомарно.
• Update all instances simultaneously.

Copyimport OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.apimigration.com/v1", apiKey: process.env.API_KEY });

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);

Сводка лучших практик

Успех миграции зависит от внимания к деталям. Проверьте базовый URL. Соблюдайте ограничения контекста. Корректно обрабатывайте потоковую передачу данных. Управляйте ограничениями частоты запросов. Проверяйте JSON. Обрабатывайте ошибки. Управляйте платежами и ключами. Следование этим шагам обеспечивает плавный переход.

Тщательно протестируйте интеграцию перед запуском. Используйте пробный кредит, чтобы проверить настройку. Это предотвратит дорогостоящие простои в продакшене.

• Проверьте базовый URL.
• Уважайте ограничения контекста.
• Обработка потоковой передачи должна быть корректной.
• Управление лимитами.
• Проверьте JSON.
• Обрабатывайте ошибки.
• Управляйте платежами и ключами.

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'