Streaming și instrumente
Pe această pagină
Streaming cu apeluri de funcții
Streaming-ul vă permite să primiți răspunsul modelului incremental, token cu token. Acest lucru este esențial pentru interfețele de utilizator reactive. Dar cum interacționează streaming-ul cu apelurile de funcții?
Regula fundamentală
Apelurile de funcții sunt returnate într-o singură bucată (chunk), nu sunt transmise progresiv. Aceasta este o diferență majoră față de textul normal, care sosește token cu token.
În practică:
- Textul răspunsului este transmis progresiv
- tool_calls sosesc toate odată, într-un singur eveniment
Această constrângere există dintr-un motiv întemeiat: un apel de instrument trebuie să fie complet (nume + argumente JSON valide) pentru a putea fi executat. Un JSON parțial ar fi inutilizabil.
Implementarea streaming-ului cu instrumente
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
# Text transmis prin streaming
if delta.content:
collected_content += delta.content
print(delta.content, end="", flush=True)
# Apeluri de instrumente (sosesc într-un singur bloc)
if delta.tool_calls:
for tc in delta.tool_calls:
collected_tool_calls.append(tc)
# Verificare sfârșit de stream
if chunk.choices[0].finish_reason == "tool_calls":
# Modelul așteaptă rezultatele instrumentelor
break
elif chunk.choices[0].finish_reason == "stop":
# Răspuns terminat, niciun instrument apelat
break
Reconstrucția apelurilor de instrumente în streaming
În unele cazuri, argumentele apelurilor de instrumente pot sosi în mai multe fragmente în cadrul stream-ului. Trebuie să le reconstruiți:
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
Această abordare bazată pe tampon (buffer) asigură reconstrucția corectă a fiecărui apel de instrument, chiar dacă datele sosesc fragmentat.
Arhitectură pentru streaming cu instrumente
Într-o aplicație reală, trebuie să gestionați două fluxuri simultane:
- Afișare în timp real: afișați textul pe măsură ce sosește
- Acumularea apelurilor de instrumente: colectați apelurile pentru execuție
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":
# Executați instrumentele, apoi reporniți
results = await execute_tools(tool_calls)
yield {"type": "tool_results", "data": results}
Latență și experiența utilizatorului
Streaming-ul cu instrumente implică pauze naturale în flux:
- Utilizatorul pune întrebarea
- Modelul începe să „gândească“ (niciun token vizibil)
- Modelul decide să apeleze un instrument (primiți tool_call)
- Pauză — executați funcția
- Trimiteți rezultatul înapoi
- Modelul generează răspunsul (transmis progresiv)
Pentru experiența utilizatorului, afișați un indicator în timpul pasului 4:
🔍 Se caută vremea în Paris...
Acest lucru împiedică utilizatorul să creadă că aplicația s-a blocat.
Server-Sent Events (SSE) pentru aplicații web
Dacă construiți un API web, utilizați SSE pentru a retransmite stream-ul:
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")
Puncte cheie
- Apelurile de instrumente sosesc într-o singură bucată, nu sunt transmise progresiv
- Textul normal continuă să fie transmis token cu token
- Reconstruiți apelurile de instrumente fragmentate folosind un tampon indexat după
index - Gestionați două fluxuri în paralel: afișarea textului + colectarea apelurilor de instrumente
- Afișați un indicator în timpul execuției instrumentelor pentru o bună experiență a utilizatorului
- Utilizați SSE pentru aplicațiile web