Tutoriais de VPS
API de IA não transmite: SSE, buffering Nginx e leitura no frontend
Compare eventos no backend, Nginx e domínio; diferencie formato SSE, buffering, consumo no frontend e timeout com quatro comparações históricas.

A resposta de IA chega inteira no final depois da implantação, mesmo com streaming ativo. Compare a mesma requisição no backend, no Nginx e no domínio público para localizar onde os eventos se acumulam. Trocar modelo ou adicionar memória não identifica essa camada.
O guia trata de fluxos HTTP, SSE, buffering e leitura no frontend. Para conexão bidirecional com handshake 101, veja WebSocket.
| Observação | O que conferir | Próximo passo |
|---|---|---|
| Backend direto espera até terminar | Aplicação, SDK e modelo | Geração e flush |
| Backend transmite, Nginx agrupa | Buffering, compressão e location | Configuração do endpoint |
| Origem transmite, CDN demora | Cache, conversão ou políticas | Tempos por camada |
| curl transmite, página atualiza no final | response.text, parser e UI | Consumo no frontend |
| Abre e cai após silêncio | Heartbeat e timeout | Último evento e limites |
200 não comprova entrega em tempo real. Separe primeiro token lento de dados posteriores retidos: desativar buffering não produz um token que ainda não existe.
Use um endpoint que realmente emita eventos pequenos em intervalos. /events/test é um caminho ilustrativo que precisa ser implementado. Compare backend local e domínio:
curl -sS -N -i --max-time 10 \
-H 'Accept: text/event-stream' \
http://127.0.0.1:3000/events/test
curl -sS -N -i --max-time 10 \
-H 'Accept: text/event-stream' \
https://api.example.com/events/test
Adapte porta e domínio. -N desativa o buffer do curl, não o servidor. Preserve POST, autenticação e corpo da API real. Não coloque chaves na URL ou logs públicos. Timeout após dez segundos pode ser apenas o limite de observação.
Registre a chegada de cada evento. Se o backend gera a cada meio segundo e o cliente recebe tudo junto, investigue intermediários.
O guia do Nginx explica que receber do upstream e entregar ao cliente podem seguir ritmos distintos.
Com caminho /events/ e backend local 3000, integre ao servidor HTTPS existente:
location /events/ {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Accept-Encoding "";
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 90s;
gzip off;
}
Mantenha TLS, autenticação, limites e outras rotas. proxy_pass não tem barra final e preserva /events/.... Se o endpoint é /api/chat, configure-o; um /events/ nunca utilizado não altera nada.
O trecho separa buffering, cache e compressão. Limpar Accept-Encoding evita negociar compressão upstream. gzip off a desativa neste Nginx, mas não descomprime respostas arbitrárias. Compare sem compressão primeiro e avalie depois.
proxy_request_buffering controla o corpo enviado pelo cliente, não a resposta. Desativá-lo não é a correção principal de SSE e texto não exige aumentar uploads.
A aplicação pode retornar X-Accel-Buffering: no na resposta upstream para controlar buffering, salvo quando Nginx ignora esse cabeçalho. Veja as diretivas proxy. Vê-lo no navegador não comprova o resultado: meça a chegada.
Valide antes de carregar:
sudo nginx -t
sudo systemctl reload nginx
Confirme que painel, contêiner ou script usa o arquivo. Confira os outros proxies da cadeia.
SSE utiliza text/event-stream e linhas vazias entre eventos, conforme a MDN:
data: {"text":"你好"}
data: {"text":",世界"}
O servidor precisa enviar e fazer flush a tempo. Acumular uma string e retornar no fim não transmite incrementalmente, mesmo com Content-Type correto. Middleware, compressão ou SDK podem agrupar antes.
Chunks e eventos não coincidem: uma leitura pode trazer meio evento ou vários. Guarde fragmentos incompletos e use o parser adequado; não suponha JSON completo em cada chunk. JSON, NDJSON e SSE são protocolos diferentes.
Ative streaming conforme a API. Um proxy não transforma JSON completo em tokens reais. Preserve status e tipo dos erros, sem disfarçar todos como 200 SSE.
Este padrão espera até encerrar:
const text = await response.text();
Response.text lê até o fim antes de entregar texto. Atualizar depois esconde o streaming.
Use reader do corpo ou cliente SSE adequado; veja ReadableStream.getReader. Decodifique UTF-8 preservando caracteres divididos entre chunks, inclusive texto chinês e acentos. Atualize após analisar eventos completos.
EventSource nativo atende GET compatível, mas não substitui diretamente API com corpo POST ou Authorization personalizado. Mantenha autenticação sem mover chaves para parâmetros. Para bloqueio entre origens, veja CORS.
Se chega tudo no final, confira agrupamento. Se a conexão cai e faltam eventos, confira timeout. O limite de leitura normalmente mede silêncio entre leituras upstream, não a duração inteira.
Os 90 segundos ilustrativos devem combinar com espera inicial, heartbeat e gateways. Em SSE, o servidor pode enviar comentário como : ping seguido de linha vazia. Não é evento de negócio; não insira em JSON comum ou outro protocolo.
Heartbeat não evita todo limite total nem acelera o modelo. Defina erros, marcador final e recuperação se um fluxo aberto falhar, para a UI não ficar gerando indefinidamente.
Compare backend, Nginx e domínio para primeiro evento e seguintes. Teste requisição autenticada e erro controlado, incluindo encerramento correto da UI.
O artigo original comparou quatro casos com Nginx 1.19.6 e o mesmo backend simulado, emitindo em 0, 0.5 e 1 segundos. O conteúdo foi completo e idêntico:
| Acesso | Chegada dos eventos 1 / 2 / 3, segundos desde o início |
|---|---|
| Backend direto | 0.038 / 0.541 / 1.045 |
| Nginx com buffering | 1.006 / 1.006 / 1.006 |
| Nginx sem buffering | 0.002 / 0.505 / 1.007 |
| Buffering ativo, cabeçalho upstream desativa | 0.002 / 0.506 / 1.007 |
Nessas condições, buffering agrupou eventos; desativá-lo por configuração ou cabeçalho manteve o ritmo. Não são medidas de velocidade do modelo ou latência de produção e não cobrem TLS, CDN, UI do navegador ou timeouts longos.