Apibrėžkite įrankius JSON formatu
Šiame puslapyje
Nuo teorijos prie praktikos
Dabar supranti funkcijų kvietimo koncepciją ir JSON schemų struktūrą. Metas pereiti prie konkrečios implementacijos. Šioje pamokoje išmoksi sudaryti pilną užklausą su įrankių apibrėžimais ir apdoroti modelio atsakymą.
Užklausos struktūra su įrankiais
Štai pilna užklausa Grok API su apibrėžtu įrankiu:
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
)
Atkreipk dėmesį į įdėtą struktūrą: objektas tools yra masyvas, kurio kiekvienas elementas turi lauką type ir objektą function su išsamia informacija.
Pagrindiniai implementacijos skaičiai
tool_call atsakymo apdorojimas
Kai modelis nusprendžia iškviesti funkciją, atsakyme atsiranda masyvas 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}")
Laukas tool_call.function.arguments yra JSON eilutė (ne Python objektas). Jį reikia išanalizuoti (parse):
import json
args = json.loads(tool_call.function.arguments)
city = args["city"]
unit = args.get("unit", "celsius")
Vykdykite ir grąžinkite rezultatą
Įvykdžius funkciją, rezultatą siunčiate modeliui atgal antruoju kvietimu:
import json
# 1. Vykdykite funkciją
weather_data = get_weather(city="Paris", unit="celsius")
# 2. Sukurkite žinučių sąrašą su rezultatu
messages = [
{"role": "user", "content": "What's the weather like in Paris?"},
message, # Modelio atsakymas su tool_calls
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(weather_data)
}
]
# 3. Dar kartą iškvieskite modelį su rezultatu
final_response = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools
)
print(final_response.choices[0].message.content)
Žinutė su vaidmeniu tool privalo turėti:
tool_call_id: unikalųtool_callidentifikatorių (susiejimui su užklausa)content: rezultatą kaip JSON eilutę
Apibrėžkite kelis įrankius
Masyve tools galite deklaruoti tiek įrankių, kiek reikia:
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": { ... }
}
}
]
Modelis automatiškai pasirinks tinkamą (-us) įrankį (-ius) pagal vartotojo užklausą.
Tikrinkite finish_reason
Laukas finish_reason atsakyme nurodo, ar modelis baigė savo atsakymą, ar laukia įrankio rezultato:
finish_reason = response.choices[0].finish_reason
if finish_reason == "tool_calls":
# Modelis laukia vieno ar kelių įrankių rezultatų
handle_tool_calls(response)
elif finish_reason == "stop":
# Modelis baigė savo atsakymą
print(response.choices[0].message.content)
Svarbiausi punktai
- Užklausa turi
messagesirtools(apibrėžimus) tool_callargumentai yra JSON eilutė, kurią reikia išanalizuoti- Siųskite rezultatą žinutėje su vaidmeniu
tool, įtraukdamitool_call_id - Tikrinkite
finish_reason, kad sužinotumėte, ar modelis laukia rezultato - Galite deklaruoti kelis įrankius – modelis pasirenka automatiškai