Streaming e Ferramentas
Nesta página
Streaming com Chamada de Funções
O streaming permite receber a resposta do modelo incrementalmente, token por token. Isto é essencial para interfaces de utilizador responsivas. Mas como é que o streaming interage com a chamada de funções?
A Regra Fundamental
As chamadas de funções são devolvidas num único bloco, não sendo transmitidas progressivamente. Esta é uma grande diferença em relação ao texto normal, que chega token por token.
Na prática:
- O texto da resposta é transmitido progressivamente
- As tool_calls chegam todas de uma vez num único evento
Esta restrição existe por uma boa razão: uma chamada de ferramenta deve estar completa (nome + argumentos JSON válidos) para que a possa executar. Um JSON parcial seria inutilizável.
Implementar Streaming com Ferramentas
stream = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools,
stream=True
)
collected_tool_calls = []
collected_content = ""
for chunk in stream:
delta = chunk.choices[0].delta
# Texto em streaming
if delta.content:
collected_content += delta.content
print(delta.content, end="", flush=True)
# Chamadas de ferramentas (chegam num único bloco)
if delta.tool_calls:
for tc in delta.tool_calls:
collected_tool_calls.append(tc)
# Verificar o fim do stream
if chunk.choices[0].finish_reason == "tool_calls":
# O modelo espera resultados das ferramentas
break
elif chunk.choices[0].finish_reason == "stop":
# Resposta terminada, nenhuma ferramenta chamada
break
Reconstruir Chamadas de Ferramentas em Streaming
Em alguns casos, os argumentos da chamada de ferramenta podem chegar em várias partes dentro do stream. Precisa de os reconstruir:
tool_calls_buffer = {}
for chunk in stream:
delta = chunk.choices[0].delta
if delta.tool_calls:
for tc_chunk in delta.tool_calls:
idx = tc_chunk.index
if idx not in tool_calls_buffer:
tool_calls_buffer[idx] = {
"id": tc_chunk.id,
"function": {
"name": tc_chunk.function.name or "",
"arguments": ""
}
}
if tc_chunk.function.name:
tool_calls_buffer[idx]["function"]["name"] = tc_chunk.function.name
if tc_chunk.function.arguments:
tool_calls_buffer[idx]["function"]["arguments"] += tc_chunk.function.arguments
Esta abordagem de buffering garante que reconstrói corretamente cada chamada de ferramenta, mesmo que os dados cheguem fragmentados.
Arquitetura para Streaming com Ferramentas
Numa aplicação real, precisa de gerir dois streams simultâneos:
- Exibição em tempo real: mostrar o texto à medida que chega
- Acumulação de chamadas de ferramentas: recolher as chamadas para execução
async def handle_streaming_response(stream):
content_parts = []
tool_calls = []
current_tool = None
async for chunk in stream:
delta = chunk.choices[0].delta
if delta.content:
content_parts.append(delta.content)
yield {"type": "text", "data": delta.content}
if delta.tool_calls:
for tc in delta.tool_calls:
tool_calls.append(tc)
if chunk.choices[0].finish_reason == "tool_calls":
# Executar ferramentas e reiniciar
results = await execute_tools(tool_calls)
yield {"type": "tool_results", "data": results}
Latência e Experiência do Utilizador
O streaming com ferramentas envolve pausas naturais no fluxo:
- O utilizador faz a sua pergunta
- O modelo começa a pensar (sem tokens visíveis)
- O modelo decide chamar uma ferramenta (recebe a tool_call)
- Pausa — executa a função
- Envia o resultado de volta
- O modelo gera a sua resposta (transmitida progressivamente)
Para a experiência do utilizador, apresente um indicador durante o passo 4:
🔍 A procurar o tempo em Paris...
Isto impede que o utilizador pense que a aplicação está bloqueada.
Server-Sent Events (SSE) para Aplicações Web
Se estiver a construir uma API web, utilize SSE para retransmitir o stream:
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
app = FastAPI()
@app.get("/chat")
async def chat(message: str):
async def event_stream():
stream = client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": message}],
tools=tools,
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
yield f"data: {chunk.choices[0].delta.content}\n\n"
return StreamingResponse(event_stream(), media_type="text/event-stream")
Pontos-chave
- As chamadas de ferramentas chegam num único bloco, não sendo transmitidas progressivamente
- O texto normal continua a ser transmitido token por token
- Reconstrua chamadas de ferramentas fragmentadas com um buffer indexado por
index - Gerir dois streams em paralelo: exibição de texto + recolha de chamadas de ferramentas
- Apresente um indicador durante a execução da ferramenta para melhorar a UX
- Utilize SSE para aplicações web