Посібник з інтеграції API Mistral

Розуміння зміни базової URL-адреси

Ваш код надсилає запити до базової URL-адреси та додає ключ. Щоб перейти на інший OpenAI-сумісний ендпоінт, ви змінюєте лише ці два значення, а все інше залишається без змін. Шлях /v1/chat/completions залишається незмінним, тому тіло запиту та тіло відповіді зберігають свою структуру.

Зберігайте старий базовий URL у значенні конфігурації, а не в коді. Так ви зможете повернутися назад в один крок, якщо в продакшені виникне проблема.

Сумісність SDK: Клієнти OpenAI проти Mistral

Більшість бібліотек клієнтів приймають кастомний base URL. Офіційний SDK OpenAI, LangChain та LlamaIndex все це підтримують, а звичайний HTTP-клієнт також працює. Встановіть base URL на https://mistralapibaseurl.com/v1 і передайте новий ключ.

• Перевірте версію SDK, оскільки дуже старі випуски ігнорують налаштування базової URL-адреси.
• Перевірте, що клієнт передає ключ у Authorization header як Bearer-токен.

Налаштування ідентифікатора моделі

Надішліть ідентифікатор моделі uncensored. Це єдина модель, яку пропонує сервіс, тому id не змінюється між запитами, і вам не потрібна логіка вибору моделі.

Запустіть один запит з коротким промптом. Відповідь і блок використання означають, що базовий URL, ключ та id моделі всі правильні.

Реалізація потокових відповідей

Встановити stream: true отримувати відповідь у вигляді подій, що надходять від сервера. Кожна подія містить невеликий шматок тексту, а остання подія містить статистику використання.

Виводьте чанки по мірі їх надходження та зберігайте повний текст у буфері, щоб повідомлення зберігалося після завершення потоку. Вимірюйте час до отримання першого токена; цей показник визначає, наскільки швидко реагує чат для користувача.

Увімкнення виклику функцій та інструментів

Передайте масив tools у тому ж форматі, який ви вже використовуєте. Модель повертає виклик інструмента з назвою функції та аргументами у форматі JSON. Запустіть функцію у своєму коді, надішліть результат назад як повідомлення інструмента та прочитайте остаточну відповідь.

1. Визначте один інструмент з двома обов'язковими аргументами та протестуйте його окремо.
2. Протестуйте випадок, коли потрібно виконати два виклики інструментів послідовно.
3. Перевіряйте аргументи перед виконанням будь-яких дій, що змінюють дані.

Керування вікнами контексту та токенами

Розмір контекстного вікна становить 100 000 токенів. Довгі чати заповнюють його, тому обрізайте старі повідомлення або стисніть їх, перш ніж досягти ліміту. Кожен запит може повертати до 16 000 токенів виводу, а за замовчуванням — 2 048, тому встановіть max_tokens для відповідей, яких ви очікуєте.

Порахуйте токени з поля usage кожної відповіді. Оцінки за кількістю слів часто мають велику похибку для коду та текстів іншими мовами.

Обробка лімітів швидкості та повторних спроб

Кожен ключ дозволяє 300 запитів на хвилину та 8 одночасних запитів. Коли ви перевищуєте ліміт, отримуєте відповідь 429. Повторюйте спроби лише для 429 та 5xx відповідей з експоненційним сповільненням та обмеженням загального часу очікування.

Ніколи не повторюйте спробу для 400 або 401, тому що той самий запит буде невдалим знову. Спочатку виправте запит або ключ.

Налагодження поширених помилок API

Статус	Зазвичай причина	Що робити
400	Неправильний формат JSON або невідоме поле	Перевірте тіло запиту на відповідність формату, який ви надсилаєте
401	Відсутній або неправильний ключ	Скопіюйте ключ знову та перевірте заголовок Authorization
402	Кредит використано	Поповнюйте баланс; мінімальна сума поповнення — $20.
429	Ліміт швидкості вичерпано	Зачекайте та спробуйте знову пізніше

Логуйте код стану та ідентифікатор запиту для кожної невдачі, щоб швидко відстежити проблему.

Міграція з API конкурентів

Заплануйте перехід у три етапи: середовище тестування, невелика частка живого трафіку, а потім повний перехід. Тримайте обидва базові URL у конфігурації під час середнього етапу та порівнюйте відповіді та затримку на однакових промптах.

Порівнюйте витрати на власне використання, а не навіяні ціни. Помножте кількість вхідних та вихідних токенів з поля usage на $0.15 та $0.50 за 1M токенів і зіставте це зі своїм поточним рахунком.