Uma resposta de IA em streaming precisa distinguir texto recebido de resposta concluída. A conexão pode cair depois de vários parágrafos, e o usuário pode clicar em parar enquanto o servidor continua gerando. Para tratar esses casos, defina estados explícitos, um evento de conclusão e um caminho de cancelamento que alcance a execução no servidor.
O desenho abaixo se concentra no comportamento de aplicações web: como apresentar conteúdo parcial, reconhecer interrupções, evitar duplicação ao retomar e testar falhas reais de rede. Não é um benchmark de inferência. O objetivo é garantir que a interface diga com precisão o que aconteceu, mesmo quando o transporte falha no meio de uma resposta aparentemente normal.
Resumo rápido
- HTTP 200 e conexão encerrada não comprovam conclusão.
- Use um identificador de execução e estados terminais explícitos.
- Cancelar a leitura no navegador não prova que a geração parou.
- Reconexão exige política de retomada e deduplicação.
- Teste quedas, caracteres fragmentados e eventos finais ausentes.
Defina o contrato antes de animar o texto
Streaming é a entrega gradual de dados. Ele permite mostrar partes da resposta antes de receber o resultado inteiro, mas transfere responsabilidades para a aplicação. O cliente precisa reconhecer quais mensagens são conteúdo, quais são controle e qual delas indica que o trabalho terminou. Um parágrafo bem escrito não funciona como protocolo de conclusão.
Adote um identificador de execução diferente do identificador da conversa. Uma conversa pode conter várias tentativas, inclusive uma cancelada e outra reiniciada. Acrescente um número de sequência aos eventos quando houver necessidade de retomada. Esse número ajuda a detectar repetição, lacunas e mensagens atrasadas que pertencem a uma tentativa anterior.
Um contrato próprio pode enviar eventos como inicio, trecho, concluido, cancelado e falha. Esses nomes são uma proposta de aplicação, não campos universais de APIs de modelos. O backend deve traduzir o protocolo do fornecedor para esse contrato e preservar a distinção entre conclusão normal, limite de geração e interrupção inesperada.
| Estado | Significado | Comportamento da interface |
|---|---|---|
| Conectando | Pedido enviado sem conteúdo | Mostrar espera e permitir parar |
| Recebendo | Chegaram partes válidas | Exibir texto como provisório |
| Concluído | Evento terminal válido recebido | Liberar ações de resultado final |
| Cancelado | Parada solicitada e estado confirmado | Identificar conteúdo parcial |
| Interrompido | Fluxo acabou sem conclusão válida | Oferecer recuperação explícita |
Não permita que um evento atrasado substitua o estado de uma execução mais recente na tela. Ao trocar de conversa ou iniciar outra resposta, compare o identificador recebido com o identificador ativo. Essa checagem simples evita misturar trechos de duas gerações quando o usuário navega rapidamente.
Escolha o transporte e faça parsing incremental
Server-sent events, ou SSE, é um formato de eventos enviados pelo servidor. A documentação da MDN descreve mensagens em texto UTF-8, com campos e separação por linha em branco. O navegador oferece EventSource para consumir esse protocolo. Também é possível ler um corpo de resposta com fetch, mas nesse caso o aplicativo precisa implementar o processamento do formato recebido.
Um bloco entregue pela rede não corresponde necessariamente a um evento completo. Um JSON pode chegar em várias leituras, e uma leitura pode conter diversos eventos. Caracteres acentuados também podem ser divididos entre blocos de bytes. Use um decodificador incremental, como TextDecoderStream, e mantenha um buffer para montar as mensagens completas antes de interpretá-las.
Evite usar JSON.parse diretamente sobre cada bloco retornado pelo leitor. Primeiro decodifique, depois identifique os limites do protocolo e só então interprete o conteúdo. Para SSE, preserve as regras de campos e linhas do formato escolhido; se adotar outro enquadramento, documente-o no contrato e nos testes. Um parser parcial costuma funcionar em rede rápida e falhar em condições menos favoráveis.
Com fetch, confira o status da resposta antes de consumir o corpo. A API não transforma automaticamente todo status HTTP de erro em rejeição da promessa. A aplicação deve diferenciar um erro recebido antes do streaming de uma falha ocorrida depois de iniciar a exibição. Essa distinção orienta o texto de recuperação apresentado ao usuário.
Estabeleça limites de tamanho para mensagens e buffers. Se o servidor envia bytes continuamente sem finalizar um evento válido, o cliente não deve acumular memória indefinidamente. Registre a falha de protocolo sem copiar o conteúdo inteiro para os logs. O objetivo é diagnosticar o problema preservando os limites operacionais da interface.
Implemente o botão parar de ponta a ponta
No navegador, AbortController permite interromper uma operação fetch e o consumo de seu corpo, conforme a documentação da MDN. Associe um controlador a cada execução. Ao receber uma nova tentativa, não reutilize um sinal que já foi abortado. O cancelamento local deve atualizar a interface imediatamente, sem esperar que uma nova palavra apareça.
Interromper a conexão do navegador não comprova que o servidor ou o provedor encerrou o trabalho. Implemente a propagação do cancelamento no backend e observe o resultado. Um caminho possível é uma rota autenticada de cancelamento por identificador de execução. Outro é detectar a desconexão e cancelar o processamento associado, quando a infraestrutura suporta esse comportamento.
A proposta de controle no cliente pode ser expressa assim, em pseudocódigo:
iniciar execucao com identificador unico
criar controlador de cancelamento
abrir fluxo associado ao identificador
para cada evento completo:
validar identificador e sequencia
atualizar conteudo ou estado terminal
ao clicar em parar:
interromper leitura local
solicitar cancelamento autenticado ao servidor
consultar estado ate prazo definido
se fluxo acabar sem evento terminal:
marcar resposta como interrompidaO servidor deve validar que a execução pertence ao usuário e à empresa da sessão. Conhecer um identificador não pode autorizar o cancelamento do trabalho de outra pessoa. Também deve aceitar a repetição segura do pedido de parada: se o trabalho já terminou, a resposta informa seu estado em vez de gerar uma segunda operação incompatível.
Existe uma corrida legítima entre concluir e cancelar. O usuário pode clicar em parar quando o último evento já saiu do servidor. Escolha uma regra determinística baseada no estado persistido da execução. Se o cancelamento não foi confirmado, mostre essa condição com clareza; não afirme que o consumo de recursos cessou apenas porque a animação parou.
Trate reconexão, conteúdo parcial e efeitos externos
A especificação HTML descreve reconexão do EventSource e o mecanismo Last-Event-ID. Esse recurso ajuda o cliente a informar a última identificação recebida, mas o servidor precisa manter e reenviar os eventos adequados. O protocolo não reconstrói sozinho uma geração perdida nem garante que o histórico necessário continue disponível.
Defina se a aplicação oferece retomar ou gerar novamente. Retomar significa continuar a mesma execução a partir de eventos persistidos. Gerar novamente cria uma nova tentativa, potencialmente com outro texto. Os botões devem refletir essa diferença. Reenviar silenciosamente o pedido original pode duplicar consumo e confundir o usuário sobre qual resposta foi concluída.
Quando houver retomada, descarte sequências já exibidas e detecte lacunas. Se os eventos expiraram, informe que aquela execução não pode ser reconstruída e ofereça nova tentativa. Não una o começo de uma geração com o final de outra como se formassem uma resposta única. Preserve o identificador no registro que será usado para suporte e auditoria.
Texto parcial merece apresentação explícita. Use um aviso de interrupção e mantenha ações de resultado final condicionadas à conclusão. Se a resposta contém JSON, código ou uma proposta comercial, um fragmento pode ser inválido ou omitir ressalvas. Para Markdown, revise também como o renderizador trata blocos ainda abertos e conteúdo externo.
Se a execução chama ferramentas que escrevem em sistemas, o cancelamento precisa de uma política adicional. Parar o texto não desfaz um pedido já enviado ao ERP. Consulte o estado da ação pelo seu identificador e evite repetir efeitos em uma retomada. O guia de function calling e saídas estruturadas ajuda a separar geração de conteúdo e execução de ferramentas.
Exemplo: portal de atendimento em Recife
Imagine uma empresa fictícia de software em Recife que oferece um assistente para preparar respostas de suporte. Os atendentes acessam o portal por conexões diferentes e podem trocar de chamado enquanto a IA escreve. Este cenário é ilustrativo; não representa um resultado medido em uma empresa real.
A equipe cria uma execução por rascunho. Enquanto chegam trechos, a tela mostra que o texto está sendo preparado. O botão para enviar ao cliente só é liberado após a conclusão e a revisão do atendente. Se a internet cai, o rascunho permanece visível com o aviso de que está incompleto, sem ser tratado como uma resposta aprovada.
Ao voltar à conexão, o portal consulta o estado da execução. Se o servidor terminou e preservou os eventos, recupera o restante sem repetir os trechos já mostrados. Se a execução falhou ou seus eventos expiraram, oferece gerar novamente. A nova tentativa recebe outro identificador, e o histórico conserva a distinção entre elas.
Quando o atendente clica em parar, o navegador interrompe a leitura e o backend recebe a solicitação de cancelamento. A equipe verifica se o processamento realmente terminou e registra eventuais atrasos. Nenhuma mensagem é enviada automaticamente ao cliente nessa etapa; preparar um rascunho e efetuar um envio são ações diferentes no fluxo do produto.
Monte testes que quebrem o fluxo de propósito
Um teste útil precisa controlar o servidor de ensaio. Faça-o enviar eventos com acentos divididos entre blocos, juntar várias mensagens numa leitura e encerrar sem evento terminal. Simule também um JSON inválido, uma sequência repetida e uma lacuna. Cada caso deve resultar em um estado previsível, sem duplicar texto nem deixar o indicador de espera preso.
No navegador, teste parar antes do primeiro conteúdo, parar no meio, trocar de conversa e voltar. Interrompa a rede e restaure a conexão. Observe se a interface corresponde ao estado persistido. Um encerramento limpo do leitor, indicado pelo campo done, significa fim do fluxo de leitura; a aplicação ainda precisa verificar seu próprio evento de conclusão.
Separe prazo de primeira resposta, prazo de inatividade e prazo total. Uma conexão que envia sinais de manutenção pode estar viva sem entregar conteúdo útil. Escolha os limites segundo o produto e registre qual deles foi atingido. Nenhum valor universal serve para todos os comprimentos de geração e tipos de tarefa.
O guia de latência e tempo até o primeiro token complementa a medição. Para esta implementação, registre também interrupções, cancelamentos confirmados e tentativas duplicadas. Relacione navegador e backend pelo identificador, seguindo a organização do artigo sobre tracing de chamadas de modelos.
Erros comuns
- Confundir HTTP 200 com sucesso completo. Exija o evento terminal do contrato.
- Processar cada bloco como JSON independente. Preserve buffer e decodificação incremental.
- Mostrar cancelado sem confirmação. Diferencie parada local de encerramento no servidor.
- Reiniciar automaticamente uma operação com efeitos externos. Confira sua identidade e situação antes de repetir.
- Ignorar mensagens de tentativas antigas. Valide a execução ativa antes de alterar a tela.
Perguntas frequentes
Preciso usar WebSocket para receber texto aos poucos?
Não necessariamente. SSE ou leitura incremental com fetch podem atender fluxos de entrega do servidor ao cliente. Escolha o transporte conforme o contrato, a autenticação e a infraestrutura da aplicação.
AbortController interrompe a cobrança do modelo?
Ele controla a operação no cliente. O efeito sobre processamento e consumo depende de como o cancelamento é propagado e tratado no backend e no provedor. Verifique essas etapas separadamente.
Posso salvar uma resposta incompleta?
Sim, se o produto precisa preservar o rascunho e o estado acompanhar o conteúdo. Não registre o fragmento como resposta final nem permita ações que pressupõem conclusão sem a verificação correspondente.
Reconectar significa continuar do mesmo ponto?
Somente se o servidor oferece retomada daquela execução e ainda possui os eventos necessários. Caso contrário, uma nova geração deve ser apresentada como outra tentativa.
