max_turns și instrumentele Server/Client
Pe această pagină
Instrumente Server și Instrumente Client
Platforma xAI distinge două tipuri de instrumente pe care Grok le poate utiliza într-o conversație:
- Instrumente lato-server: căutare web, executare de cod, căutare în X. Aceste instrumente rulează automat pe serverele xAI. Grok le invocă, obține rezultatul și continuă fără nicio intervenție din partea dumneavoastră.
- Instrumente lato-client: funcțiile dumneavoastră personalizate (apel de funcții). Când Grok dorește să apeleze una dintre funcțiile dumneavoastră, API-ul vă returnează un apel de funcție. Codul dumneavoastră îl execută, apoi trimite rezultatul înapoi către API.
Această distincție este esențială pentru înțelegerea comportamentului parametrului max_turns.
Parametrul max_turns
max_turns controlează numărul de cicluri asistent/instrument pe care Grok le poate efectua într-o singură cerere API. Fiecare utilizare a unui instrument lato-server consumă un ciclu.
response = await client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": "Search for the latest news on Python 3.13"}],
tools=[...],
max_turns=5 # Grok can use up to 5 server tools
)
Dacă Grok trebuie să efectueze o căutare web, apoi să execute cod pentru a analiza rezultatele și, în final, să ruleze o a doua căutare pentru a concluziona, acest proces consumă 3 cicluri. Cu max_turns=5, îi mai rămân 2 cicluri.
Resetarea prin instrumente Client
Comportament cheie de reținut: invocările instrumentelor lato-client resetează contorul max_turns. Când codul dumneavoastră gestionează un apel de funcție și returnează rezultatul într-o nouă cerere API, Grok își recuperează alocația completă de cicluri.
# First request: max_turns=3
response = await client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=my_tools,
max_turns=3
)
# Grok requests a client function call
if response.choices[0].message.tool_calls:
# You execute the function locally
tool_result = execute_tool(response.choices[0].message.tool_calls[0])
# Second request: max_turns resets to 3
messages.append(response.choices[0].message)
messages.append({"role": "tool", "content": tool_result, ...})
response = await client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=my_tools,
max_turns=3 # new counter
)
Această resetare este logică: fiecare cerere API este independentă. Contorul max_turns se aplică doar ciclurilor efectuate în cadrul aceleiași cereri.
Fluxuri de lucru hibride
Combinarea instrumentelor server și client permite fluxuri de lucru complexe. De exemplu, Grok poate:
- Să efectueze o căutare web (instrument server, 1 ciclu)
- Să execute cod pentru a analiza rezultatele (instrument server, 1 ciclu)
- Să solicite funcției dumneavoastră personalizate să salveze rezultatele (instrument client, resetare)
- Să efectueze o nouă căutare bazată pe rezultatele salvate (instrument server, 1 ciclu cu noul contor)
async def hybrid_workflow(question: str) -> str:
messages = [{"role": "user", "content": question}]
while True:
response = await client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=server_and_client_tools,
max_turns=5
)
message = response.choices[0].message
# If no client tool call, we have the final answer
if not message.tool_calls:
return message.content
# Process client tool calls
messages.append(message)
for tool_call in message.tool_calls:
result = await execute_local_tool(tool_call)
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": result
})
Acest model de buclă gestionează automat schimbul de date dintre Grok și funcțiile dumneavoastră locale. Bucla continuă atâta timp cât Grok are nevoie să apeleze instrumentele dumneavoastră. Se oprește atunci când oferă un răspuns text final.
Setarea lui max_turns
- max_turns=1: Grok poate utiliza un singur instrument server. Suficient pentru o simplă căutare web.
- max_turns=3-5: echilibru bun pentru majoritatea cazurilor. Grok poate înlănțui căutare + analiză + verificare.
- max_turns=10+: pentru sarcini complexe care necesită multe iterații. Atenție la costurile cu token-ii.
O valoare max_turns prea mare nu costă nimic dacă nu este utilizată, dar o valoare max_turns prea mică poate trunchia raționamentul lui Grok în mijlocul sarcinii.
Puncte cheie
- Instrumentele server (căutare web, executare de cod) consumă cicluri
max_turns - Instrumentele client (funcțiile dumneavoastră) resetează contorul la fiecare nouă cerere
- Modelul de buclă
while Truegestionează schimbul de date până la răspunsul final - Începeți cu
max_turns=5și ajustați în funcție de complexitatea sarcinii dumneavoastră - Fiecare ciclu server consumă token-uri suplimentare (context cumulativ)