Дефиниране на инструменти в JSON
На тази страница
От теория към практика
Сега разбирате концепцията за извикване на функции и структурата на JSON схемите. Време е да преминете към конкретна реализация. В този урок ще научите как да изградите пълна заявка с дефиниции на инструменти и как да обработите отговора на модела.
Структура на заявката с инструменти
Ето пълна заявка към Grok API с дефиниран инструмент:
from openai import OpenAI
client = OpenAI(
api_key="your-api-key",
base_url="https://api.x.ai/v1"
)
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"default": "celsius"
}
},
"required": ["city"]
}
}
}
]
response = client.chat.completions.create(
model="grok-4.5",
messages=[
{"role": "user", "content": "What's the weather like in Paris?"}
],
tools=tools
)
Обърнете внимание на вложената структура: обектът tools съдържа масив, където всеки елемент има поле type и обект function с детайлите.
Ключови фигури за реализацията
Обработка на отговора tool_call
Когато моделът реши да извика функция, отговорът съдържа масив tool_calls:
message = response.choices[0].message
if message.tool_calls:
for tool_call in message.tool_calls:
print(f"Function: {tool_call.function.name}")
print(f"Arguments: {tool_call.function.arguments}")
print(f"ID: {tool_call.id}")
Полето tool_call.function.arguments е JSON низ (не Python обект). Трябва да го анализирате:
import json
args = json.loads(tool_call.function.arguments)
city = args["city"]
unit = args.get("unit", "celsius")
Изпълнение и връщане на резултата
След изпълнението на функцията, изпращате резултата обратно към модела във второ извикване:
import json
# 1. Изпълнете функцията
weather_data = get_weather(city="Paris", unit="celsius")
# 2. Изградете съобщенията с резултата
messages = [
{"role": "user", "content": "What's the weather like in Paris?"},
message, # Отговорът на модела с tool_calls
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(weather_data)
}
]
# 3. Извикайте модела отново с резултата
final_response = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools
)
print(final_response.choices[0].message.content)
Съобщението с роля tool трябва да съдържа:
tool_call_id: уникалният идентификатор на tool_call (за свързване със заявката)content: резултатът като JSON низ
Дефиниране на множество инструменти
Можете да декларирате толкова инструменти, колкото е необходимо, в масива tools:
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city",
"parameters": { ... }
}
},
{
"type": "function",
"function": {
"name": "search_restaurants",
"description": "Search for restaurants by city and cuisine type",
"parameters": { ... }
}
},
{
"type": "function",
"function": {
"name": "book_table",
"description": "Book a table at a restaurant",
"parameters": { ... }
}
}
]
Моделът автоматично ще избере подходящия инструмент (или инструменти) въз основа на потребителската заявка.
Проверка на finish_reason
Полето finish_reason в отговора показва дали моделът е завършил отговора си или очаква резултат от инструмент:
finish_reason = response.choices[0].finish_reason
if finish_reason == "tool_calls":
# Моделът очаква резултат от един или повече инструменти
handle_tool_calls(response)
elif finish_reason == "stop":
# Моделът е завършил своя отговор
print(response.choices[0].message.content)
Ключови изводи
- Заявката съдържа
messagesиtools(дефиниции) - Аргументите на tool_call са JSON низ, който трябва да се анализира
- Изпратете резултата в съобщение с роля
tool, включващоtool_call_id - Проверете
finish_reason, за да разберете дали моделът очаква резултат - Можете да декларирате множество инструменти – моделът избира автоматично