Migration API: Усунення несправностей поширених помилок інтеграції LLM

Неправильна конфігурація базової URL

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

Переконайтеся, що ваш клієнт вказує на правильний домен. Для нашого сервісу базова URL-адреса — https://api.apimigration.com/v1. Ця URL-адреса працює зі стандартними SDK OpenAI, просто змінивши base_url параметр.

• Перевірте протокол (HTTPS проти 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, за замовчуванням — 2048 токенів. Ця різниця є суттєвою для задач генерації довгих текстів.

• Моніторьте загальну кількість токенів на запит.
• Встановити 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)

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

Потокові відповіді вимагають специфічної обробки подій, надісланих сервером (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 якщо вам потрібен суворий JSON. Без цього модель може повернути markdown або звичайний текст.

Уважно парсуйте відповідь. Перевірте структуру JSON перед її використанням. Це запобігає помилкам часу виконання в нижчестоячих сервісах.

• Встановити 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"}]
  }'