Blog

Guía de uso

Práctica de procesamiento de respuestas de Kimi K3: JSON completo, interrupciones de streaming y límites del reintento

Nov 18, 2026
Imagen de portada geométrica abstracta con dos conjuntos de cintas planas entrelazadas formando una rejilla abierta sobre un fondo verde azulado oscuro, acentuada con un discreto color latón.
En esta página

Primero distingue las dos rutas de respuesta

Con la misma interfaz de Kimi K3, lo que recibes pueden ser dos cosas completamente distintas: una respuesta JSON completa, o una secuencia de bloques de streaming que llegan en orden. La primera es una entrega documental de «pregunta y respuesta»; la segunda es una secuencia incremental que «empuja mientras genera». La raíz de muchos bugs de procesamiento de respuestas no es un error de parseo, sino no haber aclarado desde el principio en cuál de las dos rutas estás.

Ambas rutas comparten el mismo protocolo de solicitud (openai_chat_completions, versión de contrato 2); las diferencias se concentran en la forma de consumo:

  • No streaming: tras retornar la solicitud, obtienes un cuerpo de respuesta completo; el texto, el contenido de razonamiento y el uso están dentro, y basta con leerlo una vez.
  • Streaming: la respuesta se abre en modo opcional, el servidor empuja chunks de forma continua y el flujo termina con el marcador SSE [DONE]. A mitad del proceso puedes recibir decenas o cientos de bloques, o puede cortarse; [DONE] solo indica que el flujo terminó, no que el contenido esté completo.

Confirma esto primero; solo así tiene sentido todo lo que sigue. Si en tu cadena de negocio coexisten ambas formas de llamada (por ejemplo, un procesamiento por lotes en segundo plano y un chat en el frontend que comparten un mismo wrapper), conviene etiquetar explícitamente la ruta en el cliente, en lugar de distinguirlas con una heurística implícita como «¿hay callback?»; eso sembrará minas de fallos de deserialización durante una refactorización.

Una regla de decisión sencilla: usa streaming cuando necesites mostrar el texto al usuario palabra por palabra o cuando la salida pueda ser muy larga; usa no streaming cuando necesites obtener un resultado estructurado de una sola vez y luego persistirlo o procesarlo de nuevo. El código de parseo de ambas rutas debe escribirse por separado; lo único compartido es la construcción de la solicitud y el mapeo de errores.

La misma entrada de solicitud se bifurca en dos rutas de consumo: una devuelve la respuesta entera y la otra devuelve fragmentos por tramos.

Analizar el JSON completo: texto, contenido de razonamiento y campos estructurados

La respuesta no streaming sigue el formato del cuerpo de respuesta de OpenAI Chat Completions, pero hay un punto que se pasa por alto con facilidad: el texto y el contenido de razonamiento son dos campos distintos.

El texto ocupa la posición estándar del contenido del mensaje, mientras que el proceso de razonamiento de Kimi K3 se entrega mediante el campo reasoning_content. Esto implica que tu capa de parseo debe hacer al menos tres cosas:

  • Tomar de la posición estándar del contenido del mensaje la respuesta final orientada al usuario;
  • Comprobar si existe reasoning_content y, si existe, decidir si registrarlo en logs, mostrarlo al usuario o descartarlo;
  • Guardar por separado usage para la facturación y el cómputo de cuotas.

Mostrar reasoning_content como texto es un accidente habitual: está orientado a escenarios de depuración y explicabilidad; si entra directamente en textos de producto o respuestas de atención al cliente, el tono y el contenido no son adecuados. Lo correcto es darle una ruta de consumo independiente, por ejemplo, enviarlo a un log de depuración o a una entrada opcional del tipo «ver proceso de razonamiento».

Cómo usar la salida estructurada

El contrato admite el parámetro response_format y la capacidad de salida estructurada jsonObject. Puedes pedir al modelo que devuelva un objeto JSON y así eliminar una capa de extracción frágil por expresiones regulares. Pero hay dos premisas que conviene dejar claras: la capacidad jsonObject no equivale a soportar el modo JSON Schema; y la salida estructurada tampoco es una garantía de «siempre exitosa».

Intenta analizar el JSON solo cuando la respuesta se haya completado normalmente y el contenido esté íntegro. Después del parseo aún debes manejar tres tipos de fallo:

  • Fallo de parseo: el contenido devuelto no es JSON válido, o faltan campos o el tipo no coincide. En ese caso no deberías lanzar la cadena cruda directamente al negocio upstream, sino entrar en una rama de degradación.
  • Fallo de validación de Schema: la sintaxis JSON es válida, pero no cumple la estructura que declaraste. jsonObject no garantiza restricciones a nivel de JSON Schema; el lado del negocio debe validar por sí mismo los campos, los tipos y los obligatorios.
  • Truncamiento: cuando la longitud de salida alcanza el límite de tokens de salida de este modelo (131072), finish_reason puede ser length y el JSON puede terminar a mitad. No puedes tratar length como un éxito completo de JSON. Un parser de JSON incompleto dará error, y el caso más peligroso es que «apenas logre parsear» y tú sigas ejecutando lógica de negocio con medio objeto.

Se recomienda añadir tras el parseo una validación de integridad de campos de negocio y de evidencia, en lugar de depender solo de la validez sintáctica del JSON. La ventana de contexto es de 1000000; en escenarios de documentos largos la entrada no es el cuello de botella, pero el truncamiento de salida sigue siendo un límite real.

El sobre de respuesta se descompone en capas: texto, contenido de razonamiento y uso forman cada uno su propia rama y fluyen hacia su propio consumidor.

Lectura en streaming: [DONE], finish_reason y uso

En modo streaming, el servidor empuja chunks en orden y el marcador de terminación de red de SSE es [DONE]. La frase suena anodina, pero se malinterpreta a menudo: [DONE] solo indica que este flujo ha terminado, no que la generación haya sido exitosa ni que el contenido esté completo.

Para determinar el estado final hay que mirar choices[].finish_reason de cada chunk. Actualmente el frontend identifica el estado final por un finish_reason no vacío; incluso si se recibió [DONE], la ausencia de finish_reason debe considerarse una interrupción. Un frame error dentro del flujo indica que esta solicitud falló.

El flujo puede terminar en varios estados:

  1. Finalización normal: finish_reason es un estado final exitoso y después se recibe [DONE]; el contenido acumulado puede considerarse un resultado completo;
  2. Truncamiento por longitud: finish_reason=length, la salida se truncó por el límite de longitud, el contenido puede estar incompleto y no puede tratarse como un éxito completo de JSON;
  3. Otras causas no exitosas: como el filtrado de contenido, que deben tratarse por separado y no como una finalización normal;
  4. Corte a mitad: cierre de conexión, timeout o recepción de un frame error dentro del flujo; en ese momento solo hay contenido parcial y debe marcarse como fallo o incompleto.

El último caso es el que más fácilmente se implementa como «lo que llegue, eso vale». Para mostrar un chat quizá sea aceptable (el usuario ve media frase y puede reenviar), pero para persistir en base de datos, facturar o disparar acciones downstream son datos erróneos. Usa como criterio de integridad «¿se recibió el estado final exitoso finish_reason?», no solo [DONE].

El uso se agrega al terminar el flujo

En modo streaming, usage puede aparecer en un frame choices:[] posterior a finish_reason. El cliente debe leer todo el flujo y luego agregar el uso; no se puede garantizar que [DONE] por sí mismo lleve usage.

Esto impone dos restricciones directas de codificación:

  • No factures ni liquidas cuotas en el primer chunk. En ese momento no sabes cuánto medirá la salida final ni tienes el campo de uso.
  • No acumules uso en los bloques intermedios ni trates [DONE] como portador del uso. Los bloques intermedios no contienen datos de uso fiables; cualquier «estimación» se desviará del valor final.

El orden correcto es: durante el streaming solo te encargas de acumular texto y estado; tras leer el flujo, agregas el uso desde el frame choices:[] y realizas una liquidación. Si el flujo se corta a mitad y ya mostraste contenido al usuario, el estado de uso de esta llamada es desconocido: necesitas un estado de «incompleto», en lugar de contabilizar por defecto 0 o un valor estimado.

Además, hay que distinguir los metadatos internos de los campos de red: etiquetas como response.stream.terminal=done y response.usage.delivery=final_chunk son metadatos internos de la plataforma, no campos de red de SSE ni cadenas de terminación que el cliente deba comparar. El cliente solo debe depender de [DONE], finish_reason, los frames error y el propio campo usage.

Otro detalle práctico: al acumular texto, usa una lista con append y luego join, en lugar de concatenar cadenas repetidamente; en salidas largas la diferencia de rendimiento es notable.

La línea de tiempo superior llega a un bloque terminal de color latón con un finish_reason exitoso; la línea inferior se corta a mitad y no alcanza un estado final exitoso, por lo que no puede asumirse que se obtuvo un resultado completo.

Por qué reintentar un POST no es una idempotencia gratuita

Muchas lógicas de reintento se escriben así: la solicitud lanza una excepción de timeout, se captura, se espera un momento y se reenvía. Este artículo solo trata la semántica de operaciones POST de generación como las completaciones de chat: este tipo de reintento puede causar facturación duplicada y efectos secundarios duplicados, y no puede tratarse como idempotencia gratuita.

La razón es sencilla: el timeout es un juicio del cliente, no una promesa del servidor. Cuando suena tu temporizador de este lado, la solicitud puede haber llegado completa al servidor, haber comenzado a razonar o incluso haberse completado y facturado, y solo la respuesta se perdió en el camino de vuelta. El cliente no puede distinguir ambas situaciones solo por el tipo de excepción:

  • La solicitud no llegó al servidor; el reintento no producirá una segunda ejecución;
  • La solicitud ya fue aceptada y produjo efecto; el reintento es una segunda llamada.

Los «efectos» de una completación de chat suelen incluir el consumo de tokens y la facturación, así como las acciones que disparas en tu lado de negocio a partir de la respuesta (escribir en base de datos, publicar formularios, enviar mensajes). Reejecutar un POST cuyo resultado es incierto equivale a hacer esos efectos secundarios dos veces. No es un riesgo teórico: la fluctuación de red, el timeout de la pasarela y el reinicio de conexiones por dispositivos intermedios producen este estado ambiguo de forma estable.

Más problemático aún: una respuesta 5xx completa, un timeout, una desconexión o un fallo de parseo de JSON no pueden demostrar que la solicitud no se generó, no se cobró o no tuvo efectos secundarios. El error que ves solo indica que el cliente no obtuvo un resultado utilizable en esta ocasión.

Por tanto, la premisa correcta para reintentar no es «hubo un error», sino «esta solicitud con certeza no se ejecutó». Antes de escribir cualquier código de reintento, responde esta pregunta; si no puedes responderla, no reejecutes automáticamente.

Delimitar los límites del reintento: en qué casos se puede reejecutar

Convertir el reintento en una tabla por niveles es más fiable que escribir un for retry in range(3) uniforme. A continuación se presenta la estrategia de tratamiento según el tipo de error.

Claramente no ejecutado, se puede reintentar

  • Fallo al establecer la conexión (fallo de DNS, conexión rechazada): la solicitud evidentemente no llegó al servidor, es un caso claro de no enviado y el reintento no producirá una segunda ejecución.
  • Respuesta de limitación de tasa (por ejemplo, 429): solo cuando la documentación de la interfaz o la semántica de la respuesta garantice explícitamente que se rechaza antes de la ejecución, se puede reintentar con backoff según esa semántica; no debe inferirse que no se ejecutó o no se facturó solo por un 429 u otro código de estado. El backoff debe incluir jitter aleatorio para evitar que varios clientes reintenten sincronizados.
  • Mecanismo de deduplicación explícitamente proporcionado por la interfaz y realmente utilizado por el servidor: solo cuando la documentación de la interfaz lo indique claramente y el servidor realmente deduplique con base en ello, se puede reintentar según su semántica. Los identificadores de solicitud generados por el propio cliente solo sirven para trazabilidad; no puede suponerse que una cabecera o un campo tengan efecto idempotente.

Resultado desconocido, requiere tratamiento explícito

  • Timeout: es la categoría más peligrosa. Un timeout no demuestra que la solicitud no se ejecutó; reenviar puede producir una nueva generación facturada. Los identificadores de solicitud generados por el cliente solo sirven para trazabilidad; solo si el servidor soporta explícitamente un mecanismo de deduplicación y lo usa realmente puede evitarse el razonamiento duplicado y la facturación duplicada. La deduplicación del lado del negocio evita como máximo acciones downstream duplicadas, no impide que el modelo vuelva a generar y a cobrar. Si no puedes confirmar la semántica de deduplicación del servidor, no reejecutes automáticamente: informa el error al usuario o pasa a un proceso de compensación manual o asíncrono.
  • Respuesta 5xx completa: incluso si el cuerpo de respuesta es completo y legible, no demuestra que no se generó, no se cobró ni no hubo efectos secundarios. Solo puede reintentarse cuando sea claramente no ejecutado o cuando la documentación de la interfaz indique explícitamente que el servidor deduplicará realmente según el identificador; en caso contrario, trátalo como resultado desconocido.
  • Fallo de parseo de la respuesta: incluye fallo de parseo de JSON y fallo de validación de Schema. La solicitud puede haberse completado con éxito y haberse facturado; el fallo de parseo no demuestra que no se generó. El reintento puede causar cobro duplicado y efectos secundarios duplicados; se recomienda marcarlo explícitamente como resultado desconocido y registrarlo para verificar el uso a posteriori.
  • Desconexión a mitad del streaming o recepción de un frame error dentro del flujo: el contenido ya empujado no puede concatenarse con el nuevo resultado; una reejecución se considerará una generación completamente nueva.

No reintentar automáticamente

  • Error en los parámetros de la solicitud (errores de parámetros dentro de 4xx): reintentar cualquier número de veces da el mismo resultado y solo amplifica el error.
  • Rechazo por moderación de contenido: reejecutar no cambia la conclusión.
  • Cualquier situación en la que no puedas determinar «si ya surtió efecto» y no exista semántica de deduplicación del servidor.

Escribir los límites en el código

Vale la pena fijar dos restricciones de ingeniería: poner un límite superior al número de reintentos (normalmente 1 o 2 son suficientes) y aplicarlos solo a casos claramente no enviados o en los que la documentación de la interfaz garantice explícitamente el rechazo antes de la ejecución; registra en cada reintento el identificador de solicitud, el tipo de error y la duración, porque «cuántas veces se reintentó» determina directamente tu factura de uso y la ruta de diagnóstico. Los reintentos de solicitudes en streaming requieren una atención adicional: reejecutar tras una desconexión a mitad genera una generación facturada completamente nueva, y el contenido ya empujado no puede concatenarse con el nuevo resultado.

Si aún estás en fase de selección, puedes consultar primero la página del modelo Kimi K3 para conocer los detalles del contrato y luego decidir el nivel de granularidad de la estrategia de reintento.

Lista de verificación para la implementación

Condensa las reglas anteriores en una lista que pueda contrastarse punto por punto durante una revisión:

  • ¿El cliente distingue explícitamente las dos rutas de consumo, streaming y no streaming, en lugar de basarse en una heurística implícita?
  • ¿El parseo no streaming trata por separado el texto y reasoning_content, y reasoning_content no entra directamente en textos visibles para el usuario?
  • ¿Se guarda usage por separado y puede asociarse con los registros de negocio?
  • ¿La salida estructurada se analiza solo cuando la respuesta se completa normalmente y el contenido está íntegro, con un fallback independiente para fallos de parseo, fallos de validación de Schema, fallos de validación de negocio y de evidencia, y finish_reason=length?
  • ¿La lectura en streaming identifica el estado final por un finish_reason no vacío, en lugar de esperar solo [DONE]?
  • ¿Se trata [DONE] solo como marcador de fin de flujo y se marca como interrupción cuando falta finish_reason?
  • ¿El uso se agrega desde el frame choices:[] después de leer el flujo, sin asumir que [DONE] lleva usage?
  • ¿El frame error dentro del flujo se identifica como fallo, en lugar de tratarse como una finalización normal?
  • ¿El reintento está clasificado por tipo de error y solo se aplica a casos claramente no enviados o en los que la documentación de la interfaz garantice explícitamente el rechazo antes de la ejecución?
  • ¿El timeout, la desconexión, un 5xx completo o un fallo de parseo de JSON se tratan explícitamente como «resultado desconocido», en lugar de prometer que el reintento es seguro?
  • ¿El número de reintentos tiene un límite superior y cada reintento deja logs que permitan verificar el uso?
  • ¿La reejecución tras una interrupción del streaming se considera una generación nueva y no una continuación?

No es necesario cumplir toda la lista de una vez, pero cada punto corresponde a un problema real que puede ocurrir en producción. Aborda primero el criterio de estado final finish_reason y los límites del reintento; son los que dan mayor beneficio directo.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API