Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Streaming e Ferramentas

Aula 9 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Streaming com Chamada de Funções
  2. A Regra Fundamental
  3. Implementar Streaming com Ferramentas
  4. Reconstruir Chamadas de Ferramentas em Streaming
  5. Arquitetura para Streaming com Ferramentas
  6. Latência e Experiência do Utilizador
  7. Server-Sent Events (SSE) para Aplicações Web
  8. Pontos-chave

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:

  1. Exibição em tempo real: mostrar o texto à medida que chega
  2. 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:

  1. O utilizador faz a sua pergunta
  2. O modelo começa a pensar (sem tokens visíveis)
  3. O modelo decide chamar uma ferramenta (recebe a tool_call)
  4. Pausa — executa a função
  5. Envia o resultado de volta
  6. 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