Руководство по использованию
Практика обработки ответов Kimi K3: полный JSON, прерывание потока и границы повторных попыток
На этой странице
Сначала разберитесь с двумя путями получения ответа
С одним и тем же интерфейсом Kimi K3 вы можете получить две совершенно разные вещи: один полный JSON-ответ либо последовательность потоковых блоков данных, приходящих по порядку. Первое — это доставка документа в формате «вопрос-ответ», второе — инкрементальная последовательность «генерация с одновременной отправкой». Причина многих багов обработки ответов не в том, что парсинг написан неправильно, а в том, что с самого начала не было понятно, на каком пути вы находитесь.
Оба пути используют один и тот же протокол запроса (openai_chat_completions, версия контракта 2), различия сосредоточены в способе потребления:
- Без потока: после возврата запроса вы получаете полное тело ответа, в котором есть и основной текст, и содержимое рассуждений, и использование — достаточно прочитать один раз.
- С потоком: ответ включается в опциональном режиме, сервер непрерывно отправляет chunk'и и в итоге завершает поток маркером SSE
[DONE]. По пути вы можете получить десятки или сотни блоков, а можете оборваться на середине;[DONE]означает только конец потока, а не полноту содержимого.
Сначала подтвердите это — тогда все дальнейшие рассуждения обретут смысл. Если в вашей бизнес-цепочке одновременно присутствуют оба типа вызовов (например, фоновая пакетная обработка и фронтенд-диалог используют одну обёртку), рекомендуется явно помечать путь на клиенте, а не различать их неявным образом вроде «есть ли колбэк» — это заложит мину десериализации при рефакторинге.
Простое правило выбора: используйте потоковый режим, когда нужно показывать пользователю текст посимвольно или вывод может быть очень длинным; используйте режим без потока, когда нужно за один раз получить структурированный результат для последующего сохранения в базу или вторичной обработки. Код парсинга для двух путей следует писать раздельно, общими должны быть только части построения запроса и отображения ошибок.

Разбор полного JSON: основной текст, содержимое рассуждений и структурированные поля
Ответ без потока следует формату тела ответа OpenAI Chat Completions, но есть легко упускаемый момент: основной текст и содержимое рассуждений — это два разных поля.
Основной текст находится на стандартной позиции содержимого сообщения, а процесс рассуждений Kimi K3 передаётся через поле reasoning_content. Это значит, что ваш слой разбора должен как минимум делать три вещи:
- брать из содержимого сообщения финальный ответ, предназначенный пользователю;
- проверять наличие
reasoning_contentи, если оно есть, решать: писать в лог, показывать пользователю или просто отбрасывать; - отдельно сохранять
usageдля биллинга и учёта квот.
Показывать reasoning_content как основной текст — частая авария: оно предназначено для отладки и сценариев объяснимости, а прямое попадание в продуктовый текст или ответы поддержки неуместно и по тону, и по содержанию. Правильный подход — выделить для него отдельный путь потребления, например запись в отладочный лог или опциональный вход вроде «Посмотреть ход рассуждений».
Как использовать структурированный вывод
Контракт поддерживает параметр response_format и возможность структурированного вывода jsonObject. Вы можете попросить модель вернуть JSON-объект, избавившись от хрупкого слоя извлечения через регулярные выражения. Но нужно чётко назвать два условия: возможность jsonObject не означает поддержку режима JSON Schema; структурированный вывод также не является гарантией «обязательного успеха».
Пытайтесь разбирать JSON только после того, как ответ нормально завершён и содержимое полное. Даже после разбора нужно обрабатывать три типа сбоев:
- Сбой разбора: возвращённое содержимое не является валидным JSON, либо поля отсутствуют или имеют неверный тип. В этом случае не следует бросать исходную строку напрямую в вышестоящий бизнес, а нужно перейти в ветку деградации.
- Сбой валидации схемы: синтаксис JSON валиден, но структура не соответствует объявленной.
jsonObjectне гарантирует ограничения уровня JSON Schema, бизнес-стороне всё равно нужно самостоятельно проверять поля, типы и обязательные элементы. - Усечение: когда длина вывода достигает лимита выходных токенов данной модели (131072),
finish_reasonможет бытьlength, и JSON может оборваться на середине. Нельзя считатьlengthуспешным полным JSON. Неполный парсер JSON выдаст ошибку, но опаснее ситуация, когда он «едва-едва разобрался», а вы продолжаете бизнес-логику с половиной объекта.
Рекомендуется после разбора добавлять проверку полноты бизнес-полей и проверку доказательств, а не полагаться только на синтаксическую валидность JSON. Контекстное окно составляет 1000000, поэтому в длинных документах вход не является узким местом, но усечение вывода всё равно остаётся реальной границей.

Потоковое чтение: [DONE], finish_reason и использование
В потоковом режиме сервер отправляет chunk'и по порядку, а сетевым маркером завершения SSE является [DONE]. Звучит банально, но это часто понимают неверно: [DONE] лишь означает, что поток закончился, а не что генерация успешна и содержимое полно.
Терминальное состояние определяется по choices[].finish_reason в каждом chunk'е. Текущий фронтенд распознаёт терминальное состояние по непустому finish_reason; даже если получен [DONE], отсутствие finish_reason всё равно следует считать прерыванием. Кадр error внутри потока означает, что данный запрос завершился неудачей.
Поток может завершиться в нескольких состояниях:
- Нормальное завершение:
finish_reasonнаходится в успешном терминальном состоянии, затем приходит[DONE], накопленное содержимое можно считать полным результатом; - Усечение по длине:
finish_reason=length, вывод обрезан из-за лимита длины, содержимое может быть неполным и не может считаться успешным полным JSON; - Другие неуспешные причины: например, фильтрация содержимого; их нужно обрабатывать отдельно и не считать нормальным завершением;
- Обрыв на середине: соединение закрыто, таймаут или получен кадр
errorвнутри потока; в этом случае есть только часть содержимого, и это следует помечать как сбой или незавершённость.
Последний случай чаще всего реализуют как «что получили, то и ладно». Для отображения чата это, возможно, приемлемо (пользователь увидит половину фразы и может отправить заново), но для сохранения в базу, биллинга и запуска нижестоящих действий это неверные данные. Используйте критерий «получено ли успешное терминальное состояние finish_reason» для определения полноты, а не смотрите только на [DONE].
Использование агрегируется после окончания потока
В потоковом режиме usage может появляться в кадре choices:[] после finish_reason. Клиент должен прочитать весь поток и затем агрегировать использование; нельзя гарантировать, что сам [DONE] несёт usage.
Отсюда два прямых ограничения для кода:
- Не выполняйте биллинг или списание квоты на первом chunk'е. В этот момент вы не знаете, насколько длинным будет итоговый вывод, и не имеете поля использования.
- Не накапливайте использование по промежуточным блокам и не считайте
[DONE]носителем использования. В промежуточных блоках нет надёжных данных об использовании, любая «оценка» будет отклоняться от итогового значения.
Правильный порядок: во время потока только накапливайте текст и состояние, после чтения потока агрегируйте использование из кадра choices:[] и выполните один расчёт. Если поток оборвался на середине и вы уже показали пользователю содержимое, то состояние использования этого вызова неизвестно — вам нужен статус «незавершено», а не учёт по умолчанию как 0 или по оценке.
Кроме того, различайте внутренние метаданные и сетевые поля: response.stream.terminal=done, response.usage.delivery=final_chunk — это внутренние метаданные платформы, а не сетевые поля SSE и не строки завершения, которые должен сопоставлять клиент. Клиент должен полагаться только на [DONE], finish_reason, кадры error и само поле usage.
Ещё одна практическая деталь: при накоплении текста добавляйте в список и затем выполняйте join, а не конкатенируйте строки многократно — при длинном выводе разница в производительности заметна.

Почему повтор POST не является бесплатной идемпотентностью
Многие реализации повторов выглядят так: запрос выбросил исключение таймаута, его перехватывают, ждут немного, отправляют заново. Здесь рассматривается только семантика POST-операций генерации, таких как дополнение диалога: такой повтор может привести к повторной оплате и повторным побочным эффектам, его нельзя считать бесплатной идемпотентностью.
Причина проста: таймаут — это решение клиента, а не обещание сервера. Когда срабатывает ваш таймер, запрос мог уже полностью дойти до сервера, начать инференс, даже завершиться и быть оплаченным, а потерялся только ответ на обратном пути. Клиент не может только по типу исключения различить две ситуации:
- запрос не дошёл до сервера — повтор не создаст второго выполнения;
- запрос принят и дал эффект — повтор станет вторым вызовом.
«Эффект» дополнения диалога обычно включает расход токенов и биллинг, а также действия, которые вы запускаете на бизнес-стороне по ответу (запись в базу, отправка формы, отправка сообщения). Повторная отправка POST с неопределённым результатом означает выполнить эти побочные эффекты дважды. Это не теоретический риск: колебания сети, таймауты шлюза, сброс соединения промежуточным устройством стабильно создают такие неоднозначные состояния.
Сложнее то, что полный ответ 5xx, таймаут, разрыв соединения или сбой разбора JSON не доказывают, что запрос не сгенерировал результат, не списал средства и не вызвал побочных эффектов. Увиденная вами ошибка говорит лишь о том, что клиент на этот раз не получил пригодного результата.
Поэтому правильное условие для повтора — не «произошла ошибка», а «этот запрос точно не был выполнен». Прежде чем писать любой код повторов, ответьте на этот вопрос; если ответить не можете — не выполняйте автоматический повтор.
Определение границ повторов: в каких случаях можно повторять
Сделать повторы в виде таблицы уровней надёжнее, чем писать единый for retry in range(3). Ниже — стратегия обработки по типам ошибок.
Явно не выполнено — можно повторить
- Сбой установки соединения (сбой DNS, соединение отклонено): запрос явно не дошёл до сервера, это явно неотправленный запрос, повтор не создаст второго выполнения.
- Ответ об ограничении частоты (например, 429): повторяйте с откатом только тогда, когда документация интерфейса или семантика ответа явно гарантируют отказ до выполнения; по одному лишь 429 или другому коду состояния нельзя делать вывод о невыполнении или отсутствии списания. Откат должен включать случайный джиттер, чтобы несколько клиентов не повторяли синхронно.
- Механизм дедупликации, явно предоставленный интерфейсом и фактически используемый сервером: повторяйте согласно его семантике только тогда, когда документация интерфейса явно это описывает и сервер действительно на этом основании дедуплицирует. Идентификаторы запросов, сгенерированные самим клиентом, служат только для трассировки; нельзя предполагать, что какой-либо заголовок или поле обладает идемпотентным эффектом.
Результат неизвестен — требуется явная обработка
- Таймаут: самая опасная категория. Таймаут не доказывает, что запрос не выполнен; повторная отправка может создать новую платную генерацию. Идентификатор запроса, сгенерированный клиентом, служит только для трассировки; предотвратить повторный инференс и повторное списание может только механизм дедупликации, который сервер явно поддерживает и фактически использует. Бизнес-дедупликация в лучшем случае предотвращает повторные нижестоящие действия, но не может помешать модели снова сгенерировать результат и списать средства. Если семантика серверной дедупликации не подтверждена, не выполняйте автоматический повтор, а сообщите об ошибке пользователю или перейдите в ручной/асинхронный компенсационный процесс.
- Полный ответ 5xx: даже если тело ответа полностью читаемо, это не доказывает, что не было генерации, списания или побочных эффектов. Повторять можно только при явном невыполнении либо когда документация интерфейса явно указывает, что сервер фактически дедуплицирует по идентификатору; иначе обрабатывайте как неизвестный результат.
- Сбой разбора ответа: включает сбой разбора JSON и сбой валидации схемы. Запрос мог успешно выполниться и быть оплаченным, сбой разбора не доказывает отсутствие генерации. Повтор может привести к повторному списанию и повторным побочным эффектам; рекомендуется явно помечать результат как неизвестный и записывать это для последующей сверки использования.
- Обрыв потока на середине или получение кадра
errorвнутри потока: ранее отправленное содержимое нельзя склеивать с новым результатом; повтор будет рассматриваться как совершенно новая генерация.
Не выполнять автоматический повтор
- Ошибка параметров запроса (ошибки категории параметров среди 4xx): сколько раз ни повторяй, результат один и тот же, это только усилит ошибку.
- Отказ по модерации содержимого: повтор не изменит заключение.
- Любой случай, когда вы не можете определить «применён ли эффект» и нет серверной семантики дедупликации.
Зафиксируйте границы в коде
Две инженерные практики стоит закрепить: задайте верхнюю границу числа повторов (обычно достаточно 1–2) и применяйте их только к случаям явной неотправки или когда документация интерфейса явно гарантирует отказ до выполнения; при каждом повторе записывайте идентификатор запроса, тип ошибки и затраченное время, потому что «сколько раз повторяли» напрямую определяет ваш счёт за использование и путь диагностики. Для повторов потоковых запросов нужна дополнительная осторожность: повтор после обрыва соединения на середине создаст совершенно новую платную генерацию, и ранее отправленное содержимое нельзя склеивать с новым результатом.
Если вы ещё на этапе выбора, сначала посмотрите страницу модели Kimi K3, чтобы разобраться в деталях контракта, а затем решите, насколько гранулярной должна быть стратегия повторов.
Чек-лист внедрения
Соберите предыдущие правила в список, по которому можно сверяться пункт за пунктом на ревью:
- Явно ли различает клиент два пути потребления — потоковый и без потока, — а не полагается на неявное определение?
- Разделяет ли разбор без потока основной текст и
reasoning_content, и не попадает лиreasoning_contentнапрямую в видимый пользователю текст? - Сохраняется ли
usageотдельно и можно ли связать его с бизнес-записями? - Разбирается ли структурированный вывод только после нормального завершения ответа с полным содержимым, и есть ли отдельная обработка сбоя разбора, сбоя валидации схемы, сбоя проверки бизнес-полей и доказательств, а также
finish_reason=length? - Распознаётся ли терминальное состояние при потоковом чтении по непустому
finish_reason, а не только по ожиданию[DONE]? - Рассматривается ли
[DONE]только как маркер конца потока, а отсутствиеfinish_reasonпомечается как прерывание? - Агрегируется ли использование после чтения потока из кадра
choices:[], без предположения, что[DONE]несёт usage? - Распознаётся ли кадр
errorвнутри потока как сбой, а не как нормальное завершение? - Разделены ли повторы по типам ошибок и применяются ли они только к случаям явной неотправки или когда документация интерфейса явно гарантирует отказ до выполнения?
- Обрабатываются ли таймаут, обрыв соединения, полный 5xx или сбой разбора JSON как «неизвестный результат» явно, а не обещанием безопасности повтора?
- Есть ли верхняя граница числа повторов, и оставляет ли каждый повтор лог, пригодный для сверки использования?
- Рассматривается ли повтор после обрыва потока как новая генерация, а не как продолжение?
Этому списку не нужно соответствовать сразу целиком, но каждый пункт соответствует реальной проблеме, которая случается в продакшене. Сначала займитесь двумя пунктами — критерием терминального состояния finish_reason и границами повторов — выгода будет самой непосредственной.
Похожие статьи
Все статьи →-
Руководство по использованию
Руководство по генерации изображений из текста в базовой версии Nano Banana: формат кадра, свободное пространство и использование промптов
Используйте поля aspect_ratio и prompt интерфейса задач для генерации изображений с чёткой композицией для баннеров и социальных карточек
-
Руководство по использованию
Практика структурированного извлечения данных с GLM 5.3: каждое поле JSON должно иметь основание в исходном тексте
Извлечение полей в режиме JSON-объекта: отсутствующие значения, цитаты и бизнес-валидация не дают ошибкам попасть в хранилище
-
Руководство по использованию
MiniMax Music 3: руководство по созданию коротких песен: как разделять текст песни, теги секций и брифинг по аранжировке
На основе двух обязательных входных параметров текущего контракта спроектируйте воспроизводимый запрос короткой песни