Streaming

Defina stream: true para receber a resposta como eventos enviados pelo servidor (SSE) enquanto ela é gerada. Cada evento é uma linha data: contendo um chat.completion.chunk em JSON, e o stream termina com data: [DONE]. SDKs compatíveis com OpenAI analisam esse formato diretamente.

Use streaming para chats voltados ao usuário, para que ele veja o progresso enquanto o raciocínio e as ferramentas são executados. O streaming também mantém os dados fluindo, de modo que solicitações longas raramente atingem os limites de tempo (timeouts) do proxy.

Tipos de eventos #

Cada chunk inclui id, o ID da mensagem AIVAX (aivx_...), model e provider. O último chunk antes de [DONE] também inclui conversation_token. Armazene ambos para continuar a conversa; consulte Reutilização de sessão.

Preserve a ordem em que os eventos chegam. Raciocínio, eventos de ferramentas e texto da resposta de uma única virada do assistente podem ser intercalados.

Eventos de ferramentas no lado do servidor #

Enquanto o AIVAX executa uma ferramenta integrada, uma ferramenta MCP ou uma função de protocolo, ele envia chunks com um objeto servertool:

{
    "object": "chat.completion.chunk",
    "choices": [],
    "servertool": {
        "name": "web_search",
        "id": "call-example-id-0",
        "contents": "{\"query\":\"weather forecast today\"}",
        "state": "Created",
        "explanation": null
    }
}

Para receber o raciocínio e a atividade das ferramentas como blocos de texto dentro de delta.content em vez de campos separados, use rendering_mode: "textual_blocks"; consulte Diretrizes de apresentação de chat.

Chunk de uso #

O último chunk antes de [DONE] possui delta vazio, o finish_reason final e usage:

{
    "object": "chat.completion.chunk",
    "choices": [
        { "index": 0, "finish_reason": "stop", "delta": {} }
    ],
    "usage": {
        "prompt_tokens": 412,
        "completion_tokens": 96,
        "total_tokens": 4604,
        "prompt_tokens_details": { "cached_tokens": 4096, "audio_tokens": 0 }
    },
    "conversation_token": "support-ticket-1042"
}

prompt_tokens exclui a entrada em cache; consulte Cache.

Keep-alive #

Enquanto um stream está aberto, o AIVAX envia um evento keep-alive com o dado %ping% a cada 15 segundos, para que proxies não fechem uma conexão ociosa durante chamadas de ferramentas longas. Ignore eventos cujos dados sejam %ping%. Se seu analisador SSE esperar JSON em cada evento, ignore esses eventos ou desative o keep-alive.

Para desativar o keep-alive, envie o cabeçalho de solicitação:

Sse-Stream-Options: no-ping

Desative-o apenas quando nada entre seu cliente e o AIVAX fechar conexões ociosas.

Erros durante um stream #

Uma vez que o stream começa, o status HTTP já é 200. Uma falha é enviada como um chunk com finish_reason: "error" e um objeto error, seguido por [DONE]:

{
    "object": "chat.completion.chunk",
    "choices": [
        { "index": 0, "finish_reason": "error", "delta": { "content": "" } }
    ],
    "error": {
        "code": "service_unavailable",
        "message": "The inference provider is unavailable right now. Please, try again later."
    }
}

Verifique cada chunk quanto a error e trate-o como uma solicitação falha. O texto já recebido pertence a uma resposta incompleta; descarte-o ou marque-o como incompleto. Para modelos integrados, os detalhes do erro do provedor não são retornados; para gateways que usam sua própria chave de provedor, a mensagem do provedor é retornada conforme está.

Quando um provedor falha antes que qualquer dado tenha sido enviado, o AIVAX retrya a solicitação em outro provedor elegível, de modo que o cliente não vê nenhum erro.

Streaming com json_only #

Com json_only: true, o AIVAX gera o JSON completo primeiro e o envia como um único evento SSE contendo o JSON bruto, seguido por [DONE]. O evento não é um chat.completion.chunk. Consulte Apenas JSON.