Streaming

Receba respostas em tempo real com Server-Sent Events (SSE) para menor latência percebida.

Visão Geral

Streaming permite receber a resposta do modelo token por token em tempo real, em vez de aguardar a resposta completa. Isso reduz drasticamente a latência percebida pelo usuário. A Polar usa o protocolo Server-Sent Events (SSE), compatível com o formato OpenAI.

Como Ativar

Defina stream: true na requisição de Chat Completions ou Text Completions:

{
  "model": "urso-base",
  "messages": [{"role": "user", "content": "Olá!"}],
  "stream": true
}

Exemplos

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.polar-ai.com/v1",
    api_key="pk-your-key-here"
)

# Streaming básico
stream = client.chat.completions.create(
    model="urso-base",
    messages=[
        {"role": "user", "content": "Explique o que é o SUS em 3 parágrafos."}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="", flush=True)

print()  # Nova linha ao final

# Streaming com informações de uso (token count)
stream = client.chat.completions.create(
    model="urso-pro",
    messages=[
        {"role": "user", "content": "Quais são os princípios da LGPD?"}
    ],
    stream=True,
    stream_options={"include_usage": True}
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

    # O último chunk contém usage
    if chunk.usage:
        print(f"\n\nTokens: {chunk.usage.prompt_tokens} prompt + {chunk.usage.completion_tokens} completion = {chunk.usage.total_tokens} total")

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.polar-ai.com/v1",
  apiKey: "pk-your-key-here",
});

// Streaming básico
const stream = await client.chat.completions.create({
  model: "urso-base",
  messages: [
    { role: "user", content: "Explique o que é o SUS em 3 parágrafos." },
  ],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}

console.log();

// Streaming com usage
const stream2 = await client.chat.completions.create({
  model: "urso-pro",
  messages: [
    { role: "user", content: "Quais são os princípios da LGPD?" },
  ],
  stream: true,
  stream_options: { include_usage: true },
});

for await (const chunk of stream2) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
  if (chunk.usage) {
    console.log(`\nTokens: ${chunk.usage.total_tokens}`);
  }
}

curl

curl -X POST https://api.polar-ai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pk-your-key-here" \
  -N \
  -d '{
    "model": "urso-base",
    "messages": [
      {"role": "user", "content": "Explique o que é o SUS em 3 parágrafos."}
    ],
    "stream": true
  }'

# Com usage no stream
curl -X POST https://api.polar-ai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pk-your-key-here" \
  -N \
  -d '{
    "model": "urso-base",
    "messages": [
      {"role": "user", "content": "Explique a LGPD."}
    ],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Formato dos Eventos SSE

Cada evento SSE contém um chunk delta:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"urso-base","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"urso-base","choices":[{"index":0,"delta":{"content":"O"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"urso-base","choices":[{"index":0,"delta":{"content":" SUS"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"urso-base","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Estrutura do Delta

Campo	Descrição
`delta.role`	Presente no primeiro chunk (`"assistant"`)
`delta.content`	Conteúdo parcial do texto
`delta.tool_calls`	Chamadas de ferramenta parciais
`finish_reason`	`null` durante a geração, `"stop"` ao terminar

Streaming com Usage

Ative stream_options.include_usage para receber contagem de tokens no último chunk:

{
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

O último chunk antes de [DONE] incluirá:

{
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

Streaming com Tool Calls

Quando o modelo chama ferramentas durante streaming, os tool calls são enviados incrementalmente:

stream = client.chat.completions.create(
    model="urso-base",
    messages=[{"role": "user", "content": "Qual o endereço do CEP 01001-000?"}],
    tools=tools,
    stream=True
)

tool_calls = {}
for chunk in stream:
    delta = chunk.choices[0].delta

    if delta.tool_calls:
        for tc in delta.tool_calls:
            if tc.id:
                tool_calls[tc.index] = {"id": tc.id, "name": tc.function.name, "arguments": ""}
            if tc.function and tc.function.arguments:
                tool_calls[tc.index]["arguments"] += tc.function.arguments

Dicas de Uso

Use a flag -N no curl para desabilitar buffering
No navegador, use EventSource ou a SDK OpenAI para consumir SSE
Para modelos -think, os tokens de pensamento são enviados primeiro
stream_options.include_usage não adiciona latência extra

Próximos Passos

Chat Completions — referência completa da API
Reasoning — streaming com modelos think
Function Calling — tool calls com streaming

On this page