max_turns и инструменти на сървъра/клиента
На тази страница
Инструменти на сървъра и инструменти на клиента
Платформата xAI разграничава два вида инструменти, които Grok може да използва в рамките на един разговор:
- Инструменти от страна на сървъра: уеб търсене, изпълнение на код, търсене в X. Тези инструменти се изпълняват автоматично на сървърите на xAI. Grok ги извиква, получава резултата и продължава без никакво ваше вмешателство.
- Инструменти от страна на клиента: ваши собствени функции (извикване на функции). Когато Grok поиска да извика една от вашите функции, API връща заявка за извикване на функция към вас. Вашият код я изпълнява и след това изпраща резултата обратно към API.
Това разграничение е ключово за разбирането на поведението на max_turns.
Параметърът max_turns
max_turns контролира броя на ходове на асистента/инструмента, които Grok може да извърши в рамките на една единствена заявка към API. Всяко използване на инструмент от страна на сървъра консумира един ход.
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
)
Ако Grok трябва да изпълни уеб търсене, след това да стартира код за анализ на резултатите и накрая да пусне второ търсене за приключване, това консумира 3 хода. При max_turns=5 му остават още 2 хода.
Нулиране чрез инструменти на клиента
Важно правило, което трябва да запомните: извикванията на инструменти от страна на клиента нулират брояча на max_turns. Когато вашият код обработи извикване на функция и върне резултата в нова заявка към API, Grok получава отново пълната си квота от ходове.
# 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
)
Това нулиране е логично: всяка заявка към API е независима. Броячът max_turns важи само за ходове, извършени в рамките на една и съща заявка.
Хибридни работни потоци
Комбинирането на инструменти от сървъра и от клиента позволява създаването на сложни работни потоци. Например, Grok може:
- Да изпълни уеб търсене (инструмент на сървъра, 1 ход)
- Да изпълни код за анализ на резултатите (инструмент на сървъра, 1 ход)
- Да поиска от вашата персонализирана функция да запази резултатите (инструмент на клиента, нулиране)
- Да стартира ново търсене въз основа на запазените резултати (инструмент на сървъра, 1 ход с нов брояч)
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
})
Този шаблон с цикъл автоматично обработва размяната на данни между Grok и вашите локални функции. Цикълът продължава, докато Grok има нужда да извиква ваши инструменти. Той спира, когато моделът предостави окончателен текстов отговор.
Задаване на max_turns
- max_turns=1: Grok може да използва само един инструмент от страна на сървъра. Достатъчно е за просто уеб търсене.
- max_turns=3-5: добър баланс за повечето случаи. Grok може да верижно изпълни търсене + анализ + проверка.
- max_turns=10+: за сложни задачи, изискващи много итерации. Внимавайте с разходите за токени.
Стойност на max_turns, която е твърде висока, не струва нищо, ако не се използва, но стойност, която е твърде ниска, може да прекъсне разсъжденията на Grok по средата на задачата.
Ключови изводи
- Инструментите на сървъра (уеб търсене, изпълнение на код) консумират ходове от
max_turns - Инструментите на клиента (вашите функции) нулират брояча при всяка нова заявка
- Шаблонът с цикъл
while Trueобработва размяната на данни до получаване на окончателния отговор - Започнете със
max_turns=5и коригирайте според сложността на вашата задача - Всеки ход на сървъра консумира допълнителни токени (кумулативен контекст)