max_turns oraz narzędzia serwerowe i klienckie
Na tej stronie
Narzędzia serwerowe i klienckie
Platforma xAI rozróżnia dwa rodzaje narzędzi, z których Grok może korzystać podczas rozmowy:
- Narzędzia serwerowe: wyszukiwanie w sieci, wykonywanie kodu, wyszukiwanie w serwisie X. Narzędzia te działają automatycznie na serwerach xAI. Grok wywołuje je, otrzymuje wynik i kontynuuje pracę bez Twojej ingerencji.
- Narzędzia klienckie: Twoje własne funkcje (wywoływanie funkcji). Gdy Grok chce wywołać jedną z Twoich funkcji, API zwraca Ci żądanie wywołania funkcji. Twój kod ją wykonuje, a następnie odsyła wynik z powrotem do API.
To rozróżnienie jest kluczowe dla zrozumienia działania parametru max_turns.
Parametr max_turns
max_turns kontroluje liczbę tur asystenta/narzędzia, które Grok może wykonać w ramach pojedynczego żądania API. Każde użycie narzędzia serwerowego zużywa jedną turę.
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 może użyć do 5 narzędzi serwerowych
)
Jeśli Grok musi przeprowadzić wyszukiwanie w sieci, następnie wykonać kod analizujący wyniki, a na końcu przeprowadzić drugie wyszukiwanie, aby podsumować sprawę, zużywa to 3 tury. Przy max_turns=5 zostają mu jeszcze 2 tury.
Resetowanie przez narzędzia klienckie
Zapamiętaj kluczową zasadę: wywołania narzędzi klienckich resetują licznik max_turns. Gdy Twój kod obsłuży wywołanie funkcji i zwróci wynik w nowym żądaniu API, Grok odzyskuje pełny przydział tur.
# Pierwsze żądanie: max_turns=3
response = await client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=my_tools,
max_turns=3
)
# Grok żąda wywołania funkcji klienckiej
if response.choices[0].message.tool_calls:
# Wykonujesz funkcję lokalnie
tool_result = execute_tool(response.choices[0].message.tool_calls[0])
# Drugie żądanie: max_turns resetuje się do 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 # nowy licznik
)
Ten reset ma sens: każde żądanie API jest niezależne. Licznik max_turns dotyczy wyłącznie tur wykonanych w ramach tego samego żądania.
Przepływy pracy hybrydowej
Łączenie narzędzi serwerowych i klienckich umożliwia realizację złożonych przepływów pracy. Na przykład Grok może:
- Przeprowadzić wyszukiwanie w sieci (narzędzie serwerowe, 1 tura)
- Wykonać kod analizujący wyniki (narzędzie serwerowe, 1 tura)
- Poprosić Twoją własną funkcję o zapisanie wyników (narzędzie klienckie, reset)
- Przeprowadzić nowe wyszukiwanie na podstawie zapisanych wyników (narzędzie serwerowe, 1 tura z nowym licznikiem)
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
# Jeśli nie ma wywołania narzędzia klienckiego, mamy ostateczną odpowiedź
if not message.tool_calls:
return message.content
# Przetwarzanie wywołań narzędzi klienckich
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
})
Ten wzorzec pętli automatycznie obsługuje wymianę danych między Grokiem a Twoimi lokalnymi funkcjami. Pętla trwa tak długo, jak długo Grok potrzebuje wywołać Twoje narzędzia. Kończy się, gdy model dostarcza ostateczną odpowiedź tekstową.
Ustawianie max_turns
- max_turns=1: Grok może użyć tylko jednego narzędzia serwerowego. Wystarczające do prostego wyszukiwania w sieci.
- max_turns=3-5: dobry balans dla większości przypadków. Grok może połączyć wyszukiwanie, analizę i weryfikację.
- max_turns=10+: dla złożonych zadań wymagających wielu iteracji. Uważaj na koszty tokenów.
Zbyt wysoka wartość max_turns nic nie kosztuje, jeśli nie zostanie wykorzystana, ale zbyt niska wartość może przerwać rozumowanie Groka w trakcie zadania.
Kluczowe wnioski
- Narzędzia serwerowe (wyszukiwanie w sieci, wykonywanie kodu) zużywają tury
max_turns - Narzędzia klienckie (Twoje funkcje) resetują licznik przy każdym nowym żądaniu
- Wzorzec pętli
while Trueobsługuje wymianę danych aż do uzyskania ostatecznej odpowiedzi - Zacznij od
max_turns=5i dostosuj wartość w zależności od złożoności zadania - Każda tura serwerowa zużywa dodatkowe tokeny (kumulujący się kontekst)