Приёмка смены провайдера Kimi K3 API

На странице модели Kimi K3 указаны 2,8 трлн параметров и контекст до 1 048 576 токенов — это уже не тот endpoint, который стоит принимать по принципу «текст вернулся, значит всё работает». (huggingface.co)

Решение на эту неделю: до миграции заморозьте базовую конфигурацию, затем проведите контрактные тесты, теневую проверку реальных Agent-задач и только после этого запускайте малый этап постепенного включения трафика с автоматическим откатом. На 28 июля 2026 года официальный API и уже доступный endpoint Fireworks можно держать в рабочем сравнении, а Together AI оставлять в списке ожидающих приёмки: его официальная страница пока сообщает о скором появлении Kimi K3 в Serverless API. (platform.moonshot.ai)

Эта инструкция нужна:

• командам, которые уже используют официальный API Kimi K3 и хотят добавить резервного поставщика;
• платформенным инженерам, переходящим с другой модели и проверяющим tool calling, JSON и мультимодальный ввод;
• техническим руководителям, которым нужно подписать решение по качеству, стабильности, стоимости и обработке данных.

Последнее обновление: 28 июля 2026 года. Статус площадок и доступность функций проверены по официальным страницам Moonshot AI, Fireworks и Together AI.

Почему успешный текстовый запрос ещё ничего не доказывает

Типичный провал выглядит безобидно. Инженер меняет базовый URL, подставляет новый ключ, отправляет короткое сообщение и получает ответ с HTTP 200. Через день Agent пытается вызвать функцию, но вместо структурированного аргумента получает обычный текст. Или поток обрывается после нескольких событий, а повторная отправка запускает уже выполненное действие второй раз.

Для производственной миграции опасны как минимум пять скрытых различий.

1. Несовпадение идентификатора модели. Официальная документация Kimi API показывает модель kimi-k3, тогда как у провайдера может использоваться собственный путь или имя. Нельзя строить маршрутизацию по предположению, что название сохранится.

2. Разная семантика ответа. В документации официального API отдельно описаны tool_calls, reasoning_content, поля usage и объект ошибки. Если ваш адаптер читает только message.content, он может пропустить вызов инструмента или неправильно посчитать токены. (platform.moonshot.ai)

3. Несовместимые потоковые события. Два API могут оба называться OpenAI-совместимыми, но по-разному передавать фрагменты аргументов, финальный статус и причину остановки. Для обычного чата это заметно не всегда. Для Agent это меняет конечный автомат выполнения.

4. Изменение мультимодального формата. Официальная документация описывает текст, изображения и видео как разные элементы массива content. Сторонний endpoint может принимать только часть этих вариантов или использовать другую обработку ссылок, base64 и файловых идентификаторов.

5. Риск повторного выполнения. Если тайм-аут произошёл после фактического запуска внешней функции, без идемпотентного ключа повтор может создать второй заказ, повторно изменить запись или дважды списать ресурс. Это уже не проблема качества модели, а ошибка миграционной архитектуры.

Поэтому проверка «ответ пришёл» должна занимать только первый слой. Настоящая приёмка подтверждает, что новый endpoint сохраняет контракт, состояние диалога, порядок действий и правила аварийного возврата.

До подключения зафиксируйте исходную линию

Начните не с SDK, а с инвентаризации текущего официального API. Вам нужно сохранить версию приложения, модель, параметры запроса, тайм-ауты, политику повторов и типы задач. Если одновременно изменить системный prompt, формат сообщений и поставщика, вы не сможете определить причину ухудшения.

Минимальный файл базовой линии должен содержать:

• URL и идентификатор модели;
• структуру messages, включая системные инструкции;
• значения temperature, top_p, лимита вывода и режима потока;
• список инструментов и их JSON-схемы;
• ожидаемые finish_reason;
• правила повторной отправки;
• минимальный и максимальный тайм-аут;
• перечень задач: код, документы, изображения, поиск, вызов API;
• пример нормального, ошибочного и прерванного ответа;
• текущие показатели завершения задачи и долю ручных исправлений.

Сохраните эти данные в репозитории рядом с тестами. Не храните реальные персональные данные и секреты. Для теневых запросов используйте обезличивание, а результаты разделяйте по типу нагрузки.

Одновременно заведите реестр статуса площадок. На дату публикации официальная страница Fireworks указывает Kimi K3 как готовый к использованию через Serverless API; там же заявлены function calling и поддержка изображений. (fireworks.ai) Страница Together AI, напротив, сообщает, что Kimi K3 «coming soon» для Serverless API. Это означает: Together AI нельзя считать равноправным производственным кандидатом только потому, что карточка модели уже появилась в каталоге. (together.ai)

Проверяйте также ограничения, которые могут остановить миграцию:

• нужны ли изображения или видео;
• обязательны ли function calling и параллельные вызовы;
• требуется ли строгий JSON;
• допускается ли длинный контекст;
• можно ли использовать провайдера для чувствительных данных;
• есть ли подтверждённые лимиты, регион обработки и политика хранения;
• доступна ли аварийная маршрутизация без изменения бизнес-логики.

На этом шаге не выбирайте победителя. Вы только отделяете «можно тестировать сейчас» от «нужно дождаться официального открытия».

Контрактные тесты должны ловить различия протокола

Первый тестовый прогон выполняйте на минимальном наборе запросов. Он не должен измерять интеллект модели. Его задача — проверить, что приложение и endpoint одинаково понимают интерфейс.

Ниже приведён базовый пример для проверки статуса, модели и структуры ответа:

curl -sS "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Ответьте одним словом: готово"}
    ],
    "temperature": 0,
    "stream": false
  }' | jq '{
    model,
    object,
    finish_reason: .choices[0].finish_reason,
    content: .choices[0].message.content,
    usage
  }'

Ожидаемый результат — не конкретная формулировка текста, а наличие обязательных полей. Запишите фактический ответ целиком в артефакт теста. Значение model может отличаться от отправленного. Это не обязательно ошибка, но адаптер должен понимать, что именно вернул сервер.

Затем пройдите пять независимых сценариев.

Авторизация и ошибки

Проверьте действительный ключ, просроченный ключ, пустой ключ и неверный идентификатор модели. Сравните HTTP-код, error.type, error.code и текст сообщения. Официальная схема Kimi API показывает отдельный объект ошибки для ответов 400, 401 и 500. Ваш обработчик должен различать отказ клиента, ошибку авторизации и временную ошибку сервера.

Потоковая выдача

Отправьте один запрос с stream: true. Сохраните все события до финального маркера. Проверьте, что:

• текст не теряется между фрагментами;
• аргументы функции не склеиваются с обычным текстом;
• финальный статус приходит даже при пустом содержимом;
• закрытие соединения фиксируется как ошибка, а не как успешный ответ;
• повтор не запускается после уже полученного tool_call.

Инструменты

Используйте функцию с обязательным и необязательным полем:

{
  "type": "function",
  "function": {
    "name": "create_ticket",
    "description": "Создать внутреннюю заявку",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "title": {"type": "string"},
        "priority": {
          "type": "string",
          "enum": ["low", "normal", "high"]
        }
      },
      "required": ["title", "priority"],
      "additionalProperties": false
    }
  }
}

Проверяйте имя функции, валидность JSON, enum, обязательные поля и отсутствие лишних аргументов. Отдельно отправьте запрос с двумя инструментами и запрос, в котором функция должна быть запрещена. Если провайдер возвращает текстовое описание вместо tool_calls, миграция не проходит независимо от качества обычного ответа.

Структурированный вывод

Попросите модель вернуть объект с фиксированной схемой. Не сравнивайте только строковое содержимое. Проверяйте JSON-парсинг, типы полей, обязательность ключей и поведение при невозможности заполнить значение. Если бизнес-логика ожидает массив, а endpoint возвращает строку с JSON внутри, это несовместимость контракта.

Учёт использования

Сверьте prompt_tokens, completion_tokens, total_tokens и кэшированные токены, если поле поддерживается. Нельзя считать стоимость по локальному счётчику символов: провайдер может иначе учитывать служебные сообщения, рассуждения, изображения или повторные попытки.

Теневая проверка показывает реальную цену совместимости

После контрактного набора подключайте теневой поток. Копия обезличенного production-запроса отправляется в текущий endpoint и кандидату, но результат кандидата не показывается пользователю и не может запускать реальные инструменты.

Вам нужны четыре класса заданий:

1. короткие ответы и классификация;
2. длинные документы с цитированием и извлечением полей;
3. кодовые задачи с проверкой тестами;
4. многошаговые Agent-сценарии с вызовами инструментов.

Для каждого задания храните:

• входной идентификатор;
• хэш нормализованного prompt;
• версию приложения;
• провайдера и модель;
• время первого фрагмента;
• общее время ответа;
• число повторов;
• результат разбора;
• последовательность tool calls;
• итог задачи;
• причину отказа.

Публичные тесты модели полезны для ориентира, но не заменяют ваши данные. На странице Kimi K3 заявлены мультимодальность и контекст до 1 048 576 токенов, однако это не доказывает, что конкретный endpoint сохранит одинаковую обработку документов, изображений и длинных диалогов.

Сравнивайте не только похожесть текста. Для Agent важнее:

• достигнута ли конечная цель;
• правильно ли выбран инструмент;
• не потеряно ли состояние после нескольких ходов;
• не появились ли лишние вызовы;
• распознаётся ли ошибка и корректно ли выполняется восстановление;
• требуется ли ручная правка результата.

Полезно разделить расхождения на три группы. Безопасные — другая формулировка при том же результате. Исправимые — небольшая разница в JSON, которую можно обработать адаптером. Блокирующие — неверный инструмент, потеря обязательного поля, повтор действия, утечка данных или невозможность отката.

FAQ: что проверить перед заменой endpoint

Можно ли считать API совместимым, если меняется только базовый URL?

Нет. Совместимость базового маршрута подтверждает лишь возможность отправить HTTP-запрос. Она не подтверждает одинаковые model ID, streaming, ошибки, usage, function calling, JSON-режим и мультимодальные поля. Используйте адаптер с нормализованной внутренней схемой и принимайте поставщика только после сравнения фактических ответов.

Как понять, что миграция инструментов завершена?

Проверьте полную цепочку: модель выбрала нужную функцию, аргументы прошли JSON-схему, приложение выполнило действие, результат вернулся в историю, а следующий ответ сохранил состояние. Отдельно моделируйте тайм-аут после выполнения функции. Если повтор приводит к повторному действию, сначала внедрите идемпотентность, затем продолжайте приёмку.

Что делать с Together AI до официального запуска Kimi K3?

Не подставляйте предполагаемую цену, лимиты или набор функций в производственный план. Зафиксируйте статус как «ожидает подтверждения», подпишитесь на изменения официальной страницы и подготовьте тот же контрактный набор тестов. После появления рабочего endpoint повторите проверку с фактическими ответами, а не переносите результаты с другой площадки.

Нужно ли тестировать визуальные запросы отдельно?

Да. Текстовый контракт не проверяет передачу изображения или видео, размер вложения, порядок элементов content, ошибки декодирования и влияние мультимодального ввода на лимиты. Если ваш Agent анализирует скриншоты, PDF-страницы или схемы, хотя бы один теневой набор должен содержать реальные обезличенные визуальные задания.

Постепенное включение начинайте с задач, которые можно быстро вернуть

После теневого сравнения не переключайте весь трафик. Выберите малорисковые сценарии: внутренние черновики, классификацию, подготовку предложений или ночные задания. Не начинайте с платежей, изменения прав, публикации контента и операций с физическими ресурсами.

Порядок постепенного включения:

1. включите новый endpoint только для тестовой команды;
2. ограничьте типы задач и максимальный бюджет;
3. выключите реальные побочные действия или переведите их в режим подтверждения;
4. включите подробное логирование идентификатора запроса;
5. проверьте автоматический возврат на прежний endpoint;
6. расширяйте долю трафика только после закрытия стоп-условий.

Минимальная схема маршрутизации должна различать временную ошибку, ошибку контракта и бизнес-ошибку:

def choose_provider(task):
    if task.contains_sensitive_data:
        return "baseline"

    if task.requires_vision and not candidate.supports_vision:
        return "baseline"

    if task.requires_tools and not candidate.tool_contract_passed:
        return "baseline"

    return "candidate"

Повторная отправка должна быть ограничена. Для запроса без побочных действий можно повторить обращение после временного ответа. Для tool calling сначала проверьте журнал выполнения. Если функция уже получила подтверждение, повторяйте только чтение состояния, а не саму операцию.

Контролируйте пять отказов: тайм-аут, ограничение частоты, пустой ответ, разрыв потока и неверный вызов инструмента. Для каждого заранее назначьте действие: повтор, переход на исходный endpoint, ручная проверка или блокировка задания.

Не принимайте заявления о хранении данных без проверки официальных условий. На странице Fireworks отдельно указаны Serverless, on-demand deployment, function calling и поддержка изображений; это полезно для первичного статуса, но требования вашей организации к региону, журналам и удержанию данных нужно сверять с договорными и техническими документами перед передачей чувствительных запросов.

Первая неделя должна считать задачу, а не только токены

Публичная цена — лишь один элемент расчёта. На официальной странице Fireworks для Kimi K3 указана ставка 3,00 доллара за 1 млн входных токенов, 0,30 доллара за 1 млн кэшированных входных токенов и 15,00 долларов за 1 млн выходных токенов. Это подтверждённые данные для указанного endpoint на момент проверки, но они не дают полной стоимости Agent-сценария. (fireworks.ai)

Включите в недельный отчёт:

• входные токены;
• выходные токены;
• кэшированные токены;
• неудачные запросы;
• повторные попытки;
• прерванные длинные задачи;
• вызовы резервного endpoint;
• инженерное время на адаптеры и мониторинг;
• стоимость хранения журналов и тестовых артефактов;
• ручные исправления результата.

Если новый поставщик дешевле на единицу вывода, но чаще генерирует лишние рассуждения, вызывает инструмент повторно или требует дополнительную нормализацию JSON, экономия может исчезнуть. Считайте стоимость завершённой задачи:

стоимость задачи =
токены
+ повторы
+ резервные вызовы
+ инфраструктура тестирования
+ сопровождение адаптера
+ ручная обработка ошибок

Для Together AI оставьте поля цены, лимитов и фактического расхода пустыми до появления официальной доступности. Страница модели сообщает о будущем подключении к Serverless API, поэтому прогнозная ставка не является основанием для финансового решения.

Таблица статуса и минимальная матрица приёмки

Данные в таблице сверены по официальной документации Kimi API и карточкам Kimi K3 на страницах Moonshot AI, Fireworks и Together AI.

Условия для финального решения

Используйте не общий балл, а последовательные ветки.

• Если контрактные тесты, tool calling, JSON и потоковая выдача проходят, то переходите к теневому трафику.
• Если текст работает, но инструменты или структурированный вывод не подтверждены, то оставляйте endpoint только для некритичных текстовых задач.
• Если теневой прогон показывает расхождения, которые исправляются адаптером без изменения бизнес-логики, то повторяйте тест на нормализованном контракте.
• Если есть повторные действия, потеря состояния или неработающий откат, то кандидат не допускается к постепенному включению.
• Если Together AI ещё не предоставил рабочий endpoint, то не включайте его в производственный план и не заполняйте финансовую модель прогнозными значениями.
• Если качество приемлемо, но стоимость, обработка данных или лимиты не объяснимы, то используйте режим основной и резервной площадки, а не полную замену.
• Если все блокирующие проверки пройдены и малый этап включения стабилен, то расширяйте трафик постепенно, сохраняя регулярную регрессию.

После запуска оставьте еженедельный набор контрольных запросов. Провайдер может изменить модельный идентификатор, серверную реализацию, лимиты или поведение потоковой выдачи без изменения вашего кода. Регрессия должна проверять не только текст, но и функции, JSON, мультимодальность, повторы и откат.

Если вы запускаете такие тесты с локального Mac, заранее проверьте воспроизводимость среды, секретов и CI. Для этого пригодится справка SpinMac по рабочим окружениям. Если нагрузка требует постоянного теневого трафика и ночных регрессий, сравните её с доступностью аренды Mac-среды SpinMac.

Оставлять текущий официальный API как исходную линию обычно разумнее, чем сразу переносить весь production на первого доступного поставщика. Прямая миграция на стороннюю платформу создаёт сразу несколько слабых мест: другой формат ошибок, неравномерное поведение tool calling, неполную прозрачность стоимости и отдельные требования к обработке данных. Если у команды нет устройств для длительных теневых прогонов, автоматических регрессий и проверки macOS-окружения, аренда Mac у SpinMac может оказаться более предсказуемым вариантом для временного тестового контура, чем перегрузка рабочих ноутбуков или покупка оборудования под короткий этап миграции.

Критерий готовности простой: поставщик должен не просто вернуть ответ Kimi K3, а доказать, что ваш Agent безопасно продолжает работу, корректно вызывает инструменты, учитывает расходы и возвращается к прежнему endpoint без повторного выполнения действий.