Миграция OpenAI API на Kimi K3: чек-лист 2026

Последняя проверка: 2 августа 2026 года. Документация сверена с официальными материалами Kimi API, GitHub-описанием Kimi K3 и справочником OpenAI API. (github.com)

Миграция OpenAI API на Kimi K3 не считается завершённой после успешной замены base_url и имени модели. Сначала необходимо проверить сохранение полного сообщения ассистента, многошаговый tool calling, потоковый вывод, JSON-структуры, кеширование и обработку ошибок, а затем запустить Kimi K3 в режиме двух бэкендов с быстрым откатом.

Материал рассчитан на три группы читателей:

• разработчиков, которые поддерживают приложение на OpenAI SDK и добавляют второй API-бэкенд;
• команды, запускающие кодовые Agent-сценарии и сервисы с инструментами;
• платформенных инженеров, которым нужны измеримые критерии допуска в production, а не субъективное впечатление от нескольких удачных ответов.

Начните с разделения «интерфейс работает» и «приложение совместимо»

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

Официальная документация Kimi указывает на OpenAI-совместимый формат вызовов и возможность использовать OpenAI SDK напрямую. При этом у API есть собственные ограничения и расширения, поэтому миграцию следует рассматривать как адаптацию поведения, а не как механическую замену поставщика. (platform.kimi.ai)

Уровень проверки	Что считается доказанным	Что ещё нельзя считать доказанным
Авторизация	Ключ принят, endpoint доступен	Правильная модель, лимиты и обработка ошибок
Минимальный текстовый ответ	Простая цепочка request-response работает	Многошаговый Agent и контекст
Один tool call	Схема функции распознана	Повторный вызов, несколько инструментов и возврат результата
Структурированный ответ	JSON можно получить на одном примере	Устойчивость к пустым полям, частичному выводу и retry
Серый трафик	Отдельные задачи успешно проходят	Безопасность полной замены production-маршрута

Важно. Критерий «ответ пришёл» слишком слаб для приложения, которое хранит историю, вызывает функции и рассчитывает на строгую схему результата. Для допуска нужен набор воспроизводимых сценариев с одинаковыми входными данными.

Шаг 1. Зафиксируйте старый маршрут и соберите контрольные образцы

Перед изменением клиента команда должна создать набор реальных, но обезличенных запросов. В него желательно включить:

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

Для каждого образца сохраняются входные сообщения, выбранные параметры, HTTP-статус, finish_reason, наличие tool_calls, ошибки десериализации, число повторов и итоговый результат. Ключи API, персональные данные, названия проектов и внутренние URL необходимо заменить заполнителями.

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

Шаг 2. Проверьте базовый Kimi K3 API отдельным клиентом

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

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KIMI_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

response = client.chat.completions.create(
    model=os.environ["KIMI_MODEL"],
    messages=[
        {"role": "system", "content": "Отвечайте кратко и структурированно."},
        {"role": "user", "content": "Проверьте базовый вызов."},
    ],
)

print(response.choices[0].message)

Адрес endpoint, использование OpenAI SDK и формат chat.completions подтверждены официальным описанием API. В production-репозитории ключ не должен попадать в код, клиентскую часть, публичные логи или тестовые фикстуры. (platform.kimi.ai)

Поле	Что проверить	Проходной результат
base_url	Используется официальный адрес API с версией /v1	Запрос уходит в нужный backend
model	Имя модели берётся из переменной окружения	Нет жёстко зашитой старой модели
Authorization	Ключ добавляется сервером	В логах нет полного секрета
messages	Системное и пользовательское сообщения сохраняются	Ответ содержит ожидаемую структуру
Ошибки	Обрабатываются 400, 401, 429, 500	Ошибка попадает в наблюдаемую категорию

Проверка считается пройденной, если приложение получает ожидаемый объект ответа, корректно извлекает текст и не меняет старый маршрут. На этом этапе запрещено направлять весь production-трафик на новый backend.

Шаг 3. Проверьте многоходовую историю, включая reasoning_content

Наиболее опасная несовместимость появляется не в первом, а во втором запросе. Kimi K3 использует режим сохранённого рассуждения: для многошаговых диалогов и вызовов инструментов полный ответ ассистента должен возвращаться в messages без потери reasoning_content и tool_calls. Это прямо указано в официальном описании Kimi K3. (github.com)

Нельзя делать так:

assistant_message = {
    "role": "assistant",
    "content": response.choices[0].message.content,
}

Такой адаптер удаляет поля, которые могут понадобиться модели на следующем ходе. Безопаснее сохранить сообщение целиком в формате, который допускает используемый SDK:

assistant_message = response.choices[0].message.model_dump(
    exclude_none=True
)

messages.append(assistant_message)

Для проверки следует выполнить не один вопрос, а последовательность:

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

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

Действие приёмки: сравнить сериализованное сообщение, полученное от Kimi K3, с тем, что реально отправляется на следующем ходе. Проверить наличие role, content, reasoning_content, tool_calls и идентификаторов вызовов.

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

Откат: при потере любого поля сценарий остаётся на старом backend, пока команда не исправит слой нормализации сообщений.

Шаг 4. Проверьте tool calling на нескольких функциях

Совместимое описание функций ещё не означает совместимый цикл исполнения. В Kimi API поддерживается массив tools, а схема параметров функции должна соответствовать допустимому подмножеству JSON Schema; официальная документация также указывает ограничение до 128 инструментов в одном запросе. (platform.kimi.ai)

Для первой проверки достаточно двух безопасных функций, например get_weather и calculate_total. Тест должен заставить Agent:

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

Нужно сверить четыре связи:

• имя функции в tool_calls совпадает с зарегистрированным именем;
• аргументы успешно проходят JSON-парсинг;
• tool_call_id результата совпадает с идентификатором вызова;
• сообщения с результатами добавляются в правильном порядке.

Элемент цикла	Ошибка, которую нужно обнаружить	Проверка
Описание инструмента	Модель не понимает назначение функции	Сравнить name, description и схему
tool_choice	Старое значение не поддерживается	Проверить none, auto и значение по умолчанию
tool_calls	Адаптер теряет один из вызовов	Сохранить весь массив и каждый id
tool_call_id	Результат приписывается не той функции	Сопоставить журнал вызова и ответ функции
Повторный ход	Модель не продолжает после результата	Выполнить минимум два последовательных tool call

Официальное руководство по миграции предупреждает, что значение tool_choice="required" может не поддерживаться в текущем варианте Kimi API. Поэтому приложение, которое полагается на принудительный выбор функции, должно либо изменить управляющую инструкцию, либо оставить такой сценарий на старом backend. (platform.kimi.ai)

Сигнал проблемы: первый вызов завершается, но второй запрос возвращает обычный текст вместо функции, получает ошибку о формате сообщения или запускает функцию повторно.

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

Опытный ориентир. Если простой запрос с одной функцией проходит, а многоинструментальная задача ломается, сначала проверяется сериализация цикла и идентификаторы, а не «способности модели». В подобных случаях ошибка часто находится между SDK и исполнительным кодом.

Шаг 5. Разберите потоковый вывод и структурированный JSON

Потоковый режим нужно принимать как последовательность событий, а не как набор готовых сообщений. Kimi API поддерживает stream: true, однако существующий парсер может ожидать только дельты content. Для Agent-сценариев этого недостаточно: нужно отдельно проверять рассуждение, аргументы функций и финальное состояние ответа. (platform.kimi.ai)

В тестовом адаптере следует завести отдельные накопители:

reasoning_parts = []
content_parts = []
tool_fragments = []

for chunk in stream:
    delta = chunk.choices[0].delta

    if getattr(delta, "reasoning_content", None):
        reasoning_parts.append(delta.reasoning_content)

    if getattr(delta, "content", None):
        content_parts.append(delta.content)

    if getattr(delta, "tool_calls", None):
        tool_fragments.append(delta.tool_calls)

Проверяются четыре сценария:

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

Сценарий	Что фиксируется	Условие допуска
Только текст	Полнота content	Финальный текст совпадает с контрольным форматом
Рассуждение	Отдельное накопление reasoning_content	Поле не смешивается с пользовательским текстом
Tool call	Имя и аргументы по частям	После сборки получается валидный JSON
Structured Output	Схема и обязательные поля	Ошибка входит в retry-логику
Обрыв потока	Таймаут и неполный результат	Нет ложного статуса «успешно»

Для JSON нужно тестировать не только правильный пример. В контрольный набор добавляются пустое необязательное поле, пропущенное обязательное поле, лишнее поле и аргументы с экранированными символами. Kimi API документирует режимы JSON Object и Structured Output, но приложение всё равно обязано проверять фактический объект после десериализации. (platform.kimi.ai)

Шаг 6. Проверьте кеш, длинный контекст и стоимость успешной задачи

Публичная цена токена не показывает полную стоимость Agent-сценария. При сравнении нужно учитывать:

• сколько сообщений реально сохраняется в истории;
• повторяется ли фиксированный системный префикс;
• используется ли prompt_cache_key;
• сколько токенов уходит на рассуждение;
• сколько раз выполняется retry;
• не запускается ли один и тот же инструмент повторно после ошибки парсинга.

Официальная страница Kimi K3 указывает контекстное окно в 1 048 576 токенов, но это не означает, что каждое приложение должно отправлять весь доступный контекст. Длинная история увеличивает объём проверки, время обработки и стоимость неудачной попытки. (github.com)

В отдельном журнале на каждую задачу записываются:

• входные и выходные токены;
• число вызовов инструментов;
• число попыток;
• время до первого фрагмента;
• полное время завершения;
• размер сообщения после сериализации;
• признак кеш-попадания, если он доступен;
• итог: успех, ручная доработка или откат.

Сигнал проблемы: новый backend кажется дешевле на одиночном запросе, но итоговая стоимость завершённой задачи растёт из-за повторов, лишних tool call и повторной отправки большого префикса.

Критерий прохождения: сравнивается не цена миллиона токенов, а стоимость одной корректно завершённой бизнес-задачи.

Откат: для сценариев с нестабильным кешем, длинной историей или высоким числом повторов сохраняется старый маршрут до получения подтверждённых логов.

FAQ: ответы перед переключением production

Полностью ли Kimi K3 совместим с OpenAI API?

Нет, совместимость следует понимать как совместимость интерфейса, а не полное поведенческое равенство. Базовые запросы можно отправлять через OpenAI SDK после смены base_url, ключа и модели, однако reasoning_content, сохранение полного assistant message, ограничения tool_choice и особенности потокового вывода требуют отдельной проверки на реальном приложении.

Как изменить OpenAI SDK для вызова Kimi K3?

Обычно достаточно создать отдельный клиент с ключом Kimi, указать официальный base_url и имя модели, а затем сохранить прежнюю бизнес-логику только для простого текстового сценария. Для Agent-приложений дополнительно нужно проверить передачу reasoning_content, tool_calls, tool_call_id, результаты функций и параметры структурированного вывода.

Почему после перехода на Kimi K3 ломается многошаговый вызов инструментов?

Частая причина — адаптер сохраняет только content и удаляет reasoning_content либо часть tool_calls перед следующим запросом. Другие варианты — неверный tool_call_id, изменение порядка сообщений или использование неподдерживаемого tool_choice. Ошибку следует искать в сериализации и цикле выполнения, а не сразу считать признаком слабой работы модели.

Чем потоковый ответ Kimi K3 отличается от привычного парсера?

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

Как безопасно провести серый запуск после миграции?

Сначала нужно направить на Kimi K3 только низкорисковые задачи с сохранением старого маршрута, полного журнала и ручной проверки. До расширения доли трафика следует задать пороги успешности, таймаутов, повторов, ручной доработки и стоимости завершённой задачи. Любой сценарий, не прошедший порог, должен автоматически оставаться на прежнем backend.

Шаг 7. Запустите серый трафик с формальными порогами

После технической проверки создаётся маршрутизатор с двумя ветками:

запрос
  ├─ контрольные и низкорисковые задачи → Kimi K3
  ├─ чувствительные или непрошедшие сценарии → старый backend
  └─ ошибка, таймаут или нарушение схемы → автоматический откат

В конфигурации должны присутствовать:

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

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

Метрика допуска	Как измерять	Действие при провале
Корректность результата	Сравнить с эталонным ответом или проверкой бизнес-правил	Оставить сценарий на старом backend
Завершение tool loop	Проверить все вызовы и результаты	Отключить тип задачи
Ошибки схемы	Посчитать ошибки JSON и десериализации	Исправить parser или включить retry
Таймауты	Учитывать весь цикл, а не только первый ответ	Снизить долю трафика или увеличить защитный лимит
Ручная доработка	Проверить реальные операционные исправления	Не расширять серый пул
Стоимость успеха	Считать токены, повторы и инструменты	Пересмотреть маршрут и кеширование

Принципиально важно не объединять все сценарии в один показатель. Текстовый помощник, кодовый Agent и сервис с несколькими инструментами имеют разные причины отказа. Если один класс задач проходит, это не даёт основания переключать остальные.

Финальная приёмка перед production

Перед заявкой «миграция завершена» инженер должен поставить отметки напротив каждого пункта:

• [ ] Ключ, endpoint и модель проверяются в отдельном конфигурационном профиле.
• [ ] Простой текстовый запрос проходит без изменения старого маршрута.
• [ ] Полное сообщение ассистента сохраняется при многоходовом диалоге.
• [ ] reasoning_content не удаляется слоем SDK или внутренним DTO.
• [ ] tool_calls сохраняются целиком, включая аргументы и идентификаторы.
• [ ] Результат каждой функции возвращается с правильным tool_call_id.
• [ ] Проверен сценарий с несколькими последовательными инструментами.
• [ ] Не используется неподдерживаемое значение tool_choice.
• [ ] Потоковый reasoning_content и content обрабатываются раздельно.
• [ ] Частичный JSON не считается успешным ответом.
• [ ] Ошибка схемы попадает в существующий механизм повторов.
• [ ] Кеширование и повторная отправка префикса отражаются в расчёте стоимости.
• [ ] В журнале видны таймауты, повторы, tool calls и итог задачи.
• [ ] Для каждого класса задач определён старый резервный маршрут.
• [ ] Серый запуск можно отключить без выпуска новой версии приложения.
• [ ] Секреты не попадают в клиентский код и открытые логи.

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

Что выбрать: немедленная замена или двухконтурная миграция

Немедленная замена оправдана только для простого приложения без истории, инструментов, потокового парсера и строгой схемы ответа. Для Agent-сервиса это редкий случай. Если приложение выполняет действия, вызывает внешние функции или сохраняет состояние между ходами, двухконтурная схема почти всегда безопаснее: Kimi K3 получает ограниченный класс задач, а старый backend остаётся доступным для отката.

Нужно также учитывать, где выполняется тестирование. Локальный ноутбук плохо подходит для длительного параллельного прогона нескольких SDK, повторов и потоковых клиентов: рабочая сессия может завершиться, сеть — измениться, а ручной журнал — оказаться неполным. Постоянно доступная среда позволяет запускать один и тот же набор запросов по расписанию и сравнивать результаты после обновления SDK или API. Для такого сценария можно изучить панель управления удалённой средой nuvcloud, не смешивая тестовые ключи с production-секретами.

Если текущая схема основана на одном OpenAI API-клиенте, её слабые места — отсутствие резервного маршрута, сложность воспроизведения ошибок и риск незаметной потери полей в адаптере. Полный переход на Kimi K3 без повторной проверки добавляет ещё один риск: интерфейс может выглядеть знакомо, но цикл Agent, потоковые события и структурированный результат ведут себя иначе. Поэтому аренда постоянного облачного Mac у nuvcloud может оказаться удобнее для команды, которой нужно неделями держать несколько клиентов и тестовых процессов онлайн, собирать логи и вручную проверять серый трафик. Для долгой стабильной нагрузки или задач, требующих физических устройств и локальных интерфейсов, собственная инфраструктура всё равно может быть рациональнее.

Перед переключением production следует скопировать этот чек-лист в отдельную тестовую среду, прогнать реальные обезличенные запросы через оба маршрута и только после прохождения порогов расширять долю Kimi K3.

Дополнительное чтение

• Чек-лист переноса между API-маршрутами
• Развёртывание API-посредника для постепенного переключения трафика