Guia de uso
Kimi K3 na prática: tratamento de respostas, streaming interrompido e limites de retry
Nesta página
Primeiro, distinga os dois caminhos de resposta
Com a mesma interface do Kimi K3, o que você recebe pode ser duas coisas completamente diferentes: uma resposta JSON completa ou uma sequência de blocos de streaming que chegam em ordem. A primeira é uma entrega de documento de "pergunta e resposta"; a segunda é uma sequência incremental de "gerar e enviar à medida que gera". A raiz de muitos bugs de tratamento de resposta não está na escrita do parser, mas em não ter deixado claro, desde o início, em qual caminho você está.
Os dois caminhos compartilham o mesmo protocolo de requisição (openai_chat_completions, versão de contrato 2); a diferença está concentrada na forma de consumo:
- Não streaming: após a requisição retornar, você recebe um corpo de resposta completo, com texto, conteúdo de raciocínio e uso dentro dele; basta ler uma vez.
- Streaming: a resposta é ativada em modo opcional, o servidor envia chunks continuamente e por fim encerra o stream com o marcador SSE
[DONE]. No meio do caminho você pode receber dezenas ou centenas de blocos, ou a conexão pode cair no meio;[DONE]indica apenas que o stream terminou, não que o conteúdo está completo.
Confirme isso primeiro; só então toda a discussão seguinte faz sentido. Se o seu fluxo de negócio tem os dois tipos de chamada (por exemplo, processamento em lote no backend e diálogo no frontend compartilhando um mesmo wrapper), recomenda-se marcar explicitamente o caminho no cliente, em vez de distinguir por uma inferência implícita como "tem ou não callback" — isso planta minas de falha de desserialização em futuras refatorações.
Uma regra simples de decisão: use streaming quando precisar exibir ao usuário palavra por palavra ou quando a saída puder ser muito longa; use não streaming quando precisar obter um resultado estruturado de uma só vez e depois gravá-lo no banco ou processá-lo novamente. O código de parsing dos dois caminhos deve ser escrito separadamente; só a construção da requisição e o mapeamento de erros são compartilhados.

Parsing do JSON completo: texto, conteúdo de raciocínio e campos estruturados
A resposta não streaming segue o formato de corpo de resposta do OpenAI Chat Completions, mas há um ponto fácil de ignorar: texto e conteúdo de raciocínio são dois campos diferentes.
O texto fica na posição padrão do conteúdo da mensagem, enquanto o processo de raciocínio do Kimi K3 é entregue pelo campo reasoning_content. Isso significa que sua camada de parsing precisa fazer pelo menos três coisas:
- Extrair do conteúdo da mensagem a resposta final voltada ao usuário;
- Verificar se
reasoning_contentexiste e, quando existir, decidir se registra em log, exibe ao usuário ou descarta diretamente; - Armazenar
usageseparadamente, para cobrança e contabilização de cota.
Exibir reasoning_content como se fosse o texto é um acidente comum: ele é voltado a cenários de depuração e explicabilidade; ir diretamente para textos de produto ou respostas de atendimento ao cliente resulta em tom e conteúdo inadequados. O correto é dar a ele um caminho de consumo independente, por exemplo, gravar em log de depuração ou em uma entrada opcional do tipo "ver processo de raciocínio".
Como usar saída estruturada
O contrato suporta o parâmetro response_format e a capacidade de saída estruturada jsonObject. Você pode exigir que o modelo retorne um objeto JSON, eliminando uma camada frágil de extração por regex. Mas há duas premissas a esclarecer: a capacidade jsonObject não equivale a suportar o modo JSON Schema; e saída estruturada também não é garantia de "sucesso certo".
Só tente fazer o parsing do JSON depois que a resposta for concluída normalmente e o conteúdo estiver completo. Depois do parsing, ainda é preciso tratar três tipos de falha:
- Falha de parsing: o conteúdo retornado não é JSON válido, ou faltam campos, ou os tipos não correspondem. Nesse caso, não se deve lançar a string bruta diretamente ao negócio upstream; deve-se entrar em um ramo de degradação.
- Falha de validação de Schema: o JSON é sintaticamente válido, mas não atende à estrutura que você declarou.
jsonObjectnão garante restrições no nível de JSON Schema; o lado do negócio ainda precisa validar campos, tipos e obrigatoriedade por conta própria. - Truncamento: quando o comprimento da saída atinge o limite de tokens de saída desse modelo (131072),
finish_reasonpode serlengthe o JSON pode terminar no meio. Não se pode tratarlengthcomo sucesso completo de JSON. Um parser de JSON truncado vai dar erro, mas o caso mais perigoso é quando ele "consegue parsear por pouco" e você segue executando lógica de negócio com meio objeto.
Recomenda-se adicionar, após o parsing, uma verificação de integridade dos campos de negócio e de evidências, em vez de depender apenas da validade sintática do JSON. A janela de contexto é 1000000; em cenários de documentos longos a entrada não é o gargalo, mas o truncamento de saída continua sendo um limite real.

Leitura em streaming: [DONE], finish_reason e uso
No modo streaming, o servidor envia chunks em ordem, e o marcador de término de rede do SSE é [DONE]. Essa frase parece banal, mas costuma ser mal interpretada: [DONE] indica apenas que esse stream terminou, não que a geração foi bem-sucedida nem que o conteúdo está completo.
Para determinar o estado final, é preciso olhar o choices[].finish_reason de cada chunk. Atualmente o frontend identifica o estado final por finish_reason não vazio; mesmo que [DONE] tenha sido recebido, a ausência de finish_reason ainda deve ser tratada como interrupção. Um frame error dentro do stream indica falha desta requisição.
O stream pode terminar em vários estados:
- Conclusão normal:
finish_reasoné um estado final de sucesso, seguido do recebimento de[DONE]; o conteúdo acumulado pode ser considerado resultado completo; - Truncamento por comprimento:
finish_reason=length, a saída foi truncada pelo limite de comprimento, o conteúdo pode estar incompleto e não pode ser considerado sucesso completo de JSON; - Outros motivos não bem-sucedidos: como filtragem de conteúdo etc., que precisam ser tratados separadamente e não podem ser considerados conclusão normal;
- Desconexão no meio: fechamento de conexão, timeout ou recebimento de um frame
errordentro do stream; nesse caso há apenas conteúdo parcial e deve-se marcar como falha ou incompleto.
O último caso é o mais facilmente implementado como "o que veio, veio". Para exibição em chat isso pode até ser aceitável (o usuário vê meia frase e pode reenviar), mas para gravação no banco, cobrança e disparo de ações downstream é dado errado. Use "recebeu ou não um estado final de sucesso em finish_reason" como critério de integridade, em vez de olhar apenas [DONE].
O uso é agregado após o fim do stream
No modo streaming, usage pode aparecer em um frame choices:[] após finish_reason. O cliente deve ler o stream inteiro e só então agregar o uso; não se pode garantir que o próprio [DONE] carregue usage.
Isso traz duas restrições diretas de codificação:
- Não faça cobrança nem liquidação de cota já no primeiro chunk. Nesse momento você não sabe o comprimento final da saída nem tem o campo de uso.
- Não acumule uso em blocos intermediários nem trate
[DONE]como portador de uso. Blocos intermediários não têm dados confiáveis de uso; qualquer "estimativa" vai divergir do valor final.
A ordem correta é: durante o streaming, apenas acumular texto e estado; após ler o stream, agregar o uso a partir dos frames choices:[] e fazer uma única liquidação. Se o stream cair no meio e você já tiver exibido conteúdo ao usuário, o estado de uso dessa chamada é desconhecido — você precisa de um estado "incompleto", em vez de registrar por padrão como 0 ou por estimativa.
Também é preciso distinguir metadados internos de campos de rede: response.stream.terminal=done, response.usage.delivery=final_chunk e semelhantes são rótulos de metadados internos da plataforma, não campos de rede do SSE nem strings de término que o cliente deve casar. O cliente deve depender apenas de [DONE], finish_reason, frames error e do próprio campo usage.
Outro detalhe prático: ao acumular texto, use append em lista e depois join, em vez de concatenar strings repetidamente; em saídas longas a diferença de desempenho é evidente.

Por que o retry de POST não é idempotência gratuita
Muitas lógicas de retry são escritas assim: a requisição lança uma exceção de timeout, captura-se, espera-se um pouco e reenvia-se. Este artigo discute apenas a semântica de operações POST de geração como completions de conversa: esse tipo de retry pode causar cobrança duplicada e efeitos colaterais duplicados, e não pode ser tratado como idempotência gratuita.
A razão é simples: o timeout é um julgamento do cliente, não uma promessa do servidor. Quando o timer dispara do seu lado, a requisição pode já ter chegado integralmente ao servidor, já ter começado a inferência, ou até já ter sido concluída e cobrada, e apenas a resposta se perdeu no caminho de volta. O cliente não consegue distinguir essas duas situações apenas pelo tipo de exceção:
- A requisição não chegou ao servidor; o retry não produz uma segunda execução;
- A requisição foi aceita e produziu efeito; o retry é uma segunda chamada.
Os "efeitos" de um completions de conversa normalmente incluem consumo de tokens e cobrança, além de ações que você dispara no lado do negócio com base na resposta (gravar no banco, enviar formulário, enviar mensagem). Reexecutar um POST de resultado incerto equivale a fazer esses efeitos colaterais duas vezes. Não é um risco teórico: oscilação de rede, timeout de gateway e conexão resetada por equipamento intermediário produzem esse tipo de estado ambíguo de forma consistente.
Pior ainda: uma resposta 5xx completa, timeout, desconexão ou falha de parsing de JSON não provam que a requisição não gerou, não cobrou ou não teve efeitos colaterais. O erro que você vê só indica que desta vez o cliente não obteve um resultado utilizável.
Portanto, a premissa correta do retry não é "deu erro", mas "esta requisição comprovadamente não foi executada". Antes de escrever qualquer código de retry, responda essa pergunta; se não conseguir responder, não reexecute automaticamente.
Delimite os limites de retry: em quais casos é possível reexecutar
Transformar o retry em uma tabela de classificação é mais confiável do que escrever um for retry in range(3) uniforme. A seguir, a estratégia de tratamento por tipo de erro.
Comprovadamente não executada: pode tentar novamente
- Falha no estabelecimento da conexão (falha de DNS, conexão recusada): a requisição claramente não chegou ao servidor; trata-se de não envio comprovado, e o retry não produz segunda execução.
- Resposta de rate limit (por exemplo, 429): só faça recuo exponencial com retry conforme essa semântica quando a documentação da API ou a semântica da resposta garantirem explicitamente a rejeição antes da execução; não se deve inferir não execução ou não cobrança apenas com base em 429 ou outro código de status. O recuo deve incluir jitter aleatório para evitar que vários clientes tentem novamente em sincronia.
- Mecanismo de deduplicação explicitamente fornecido pela API e efetivamente usado pelo servidor: só se pode tentar novamente conforme sua semântica quando a documentação da API o descrever claramente e o servidor realmente deduplicar com base nisso. Identificadores de requisição gerados pelo próprio cliente servem apenas para rastreamento; não se deve presumir que algum header ou campo tenha efeito idempotente.
Resultado desconhecido: exige tratamento explícito
- Timeout: esta é a categoria mais perigosa. O timeout não prova que a requisição não foi executada; o reenvio pode gerar uma nova geração cobrada. Identificadores de requisição gerados pelo próprio cliente só podem ser usados para rastreamento; apenas quando o servidor suportar explicitamente e realmente usar um mecanismo de deduplicação é que se pode evitar inferência duplicada e cobrança duplicada. A deduplicação no lado do negócio, no máximo, evita ações downstream duplicadas; não impede que o modelo gere novamente e cobre. Se não for possível confirmar a semântica de deduplicação do servidor, não reexecute automaticamente; retorne erro ao usuário ou entre em um fluxo de compensação manual/assíncrona.
- Resposta 5xx completa: mesmo que o corpo da resposta seja legível por completo, isso não prova que não houve geração, cobrança ou efeito colateral. Só se pode tentar novamente quando for comprovadamente não executada ou quando a documentação da API afirmar explicitamente que o servidor deduplicará de fato pelo identificador de deduplicação; caso contrário, trate como resultado desconhecido.
- Falha de parsing da resposta: inclui falha de parsing de JSON e falha de validação de Schema. A requisição pode ter sido bem-sucedida e já cobrada; falha de parsing não prova que não houve geração. O retry pode causar cobrança duplicada e efeitos colaterais duplicados; recomenda-se marcar explicitamente como resultado desconhecido e registrar, para facilitar conferência posterior de uso.
- Desconexão no meio do streaming ou recebimento de frame
errordentro do stream: o conteúdo já enviado antes não pode ser concatenado ao novo resultado; a reexecução será considerada uma nova geração.
Não faça retry automático
- Erro de parâmetro da requisição (erros de parâmetro entre os 4xx): não importa quantas vezes tente, o resultado será o mesmo; só amplifica o erro.
- Rejeição por moderação de conteúdo: reexecutar não muda a conclusão.
- Qualquer situação em que você não consiga determinar "se já teve efeito" e não haja semântica de deduplicação do servidor.
Escreva os limites no código
Duas restrições de engenharia merecem ser fixadas: definir um limite máximo de tentativas (normalmente 1 a 2 já é suficiente), e só aplicar retry em casos de não envio comprovado ou em situações em que a documentação da API garanta explicitamente a rejeição antes da execução; registrar em cada retry o identificador da requisição, o tipo de erro e o tempo gasto, pois "quantas vezes tentou novamente" determina diretamente sua fatura de uso e o caminho de troubleshooting. O retry de requisições em streaming exige atenção extra: reexecutar após desconexão no meio produz uma nova geração cobrada, e o conteúdo já enviado antes não pode ser concatenado ao novo resultado.
Se você ainda está na fase de escolha de tecnologia, pode começar pela página do modelo Kimi K3 para entender os detalhes do contrato e depois decidir a granularidade da estratégia de retry.
Checklist de implementação
Consolide as regras anteriores em uma lista que possa ser comparada item a item em revisão:
- O cliente distingue explicitamente os dois caminhos de consumo, streaming e não streaming, em vez de depender de inferência implícita?
- O parsing não streaming separa o texto do
reasoning_content, e oreasoning_contentnão entra diretamente em textos visíveis ao usuário? - O
usageé armazenado separadamente e pode ser correlacionado com registros de negócio? - A saída estruturada só é parseada após a resposta ser concluída normalmente e o conteúdo estar completo, e há fallback independente para falha de parsing, falha de validação de Schema, falha de verificação de negócio e evidências, e
finish_reason=length? - A leitura em streaming identifica o estado final por
finish_reasonnão vazio, em vez de esperar apenas por[DONE]? [DONE]é tratado apenas como marcador de fim de stream, e a ausência definish_reasoné marcada como interrupção?- O uso é agregado a partir dos frames
choices:[]após a leitura completa do stream, sem presumir que[DONE]carregue usage? - Frames
errordentro do stream são identificados como falha, e não como término normal? - O retry é classificado por tipo de erro e só se aplica a casos de não envio comprovado ou em que a documentação da API garanta explicitamente a rejeição antes da execução?
- Timeout, desconexão, 5xx completo ou falha de parsing de JSON são tratados explicitamente como "resultado desconhecido", e não se promete segurança de retry?
- O número de tentativas tem limite máximo, e cada retry tem log utilizável para conferir o uso?
- A reexecução após interrupção de streaming é considerada uma nova geração, e não continuação?
Não é necessário atender toda esta lista de uma vez, mas cada item corresponde a um problema real que ocorrerá em produção. Comece pelos dois itens de maior retorno direto: o critério de estado final via finish_reason e os limites de retry.
Artigos relacionados
Ver todos os artigos →-
Guia de uso
Guia de geração de imagens a partir de texto com o Nano Banana Basic: proporção, espaço em branco e uso de prompts
Use os campos aspect_ratio e prompt da API de tarefas para gerar imagens com composição clara para banners e cards sociais
-
Guia de uso
GLM 5.3 na prática: extração estruturada com base textual para cada campo JSON
Extração de campos com o modo de objeto JSON: use valores ausentes, citações e validação de negócio para bloquear erros antes da gravação no banco
-
Guia de uso
Guia de produção de músicas curtas com o MiniMax Music 3: como separar letra, tags de seção e briefing de arranjo
Com base nas duas entradas obrigatórias do contrato atual, projete uma requisição de música curta reproduzível