Määritä työkalut JSON-muodossa
Tällä sivulla
Teoriasta käytäntöön
Ymmärrät nyt funktion kutsumisen käsitteen ja JSON-skeemojen rakenteen. On aika siirtyä konkreettiseen toteutukseen. Tässä oppitunnissa opit rakentamaan täydellisen pyynnön työkalumäärityksineen ja käsittelemään mallin vastauksen.
Pyynnön rakenne työkalujen kanssa
Tässä on täydellinen pyyntö Grok API:lle määritellyllä työkalulla:
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
)
Huomaa sisäkkäinen rakenne: tools-objekti sisältää taulukon, jossa jokaisella alkiolla on type ja function-objekti, joka sisältää yksityiskohdat.
Toteutuksen avainluvut
Käsittele tool_call-vastaus
Kun malli päättää kutsua funktion, vastaus sisältää tool_calls-taulukon:
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}")
Kenttä tool_call.function.arguments on JSON-merkkijono (ei Python-objekti). Sinun on jäsennettävä se:
import json
args = json.loads(tool_call.function.arguments)
city = args["city"]
unit = args.get("unit", "celsius")
Suorita ja palauta tulos
Kun funktio on suoritettu, lähetät tuloksen takaisin mallille toisessa pyynnössä:
import json
# 1. Suorita funktio
weather_data = get_weather(city="Paris", unit="celsius")
# 2. Rakenna viestit tuloksen kanssa
messages = [
{"role": "user", "content": "What's the weather like in Paris?"},
message, # Mallin vastaus, jossa on tool_calls
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(weather_data)
}
]
# 3. Kutsu mallia uudelleen tuloksen kanssa
final_response = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools
)
print(final_response.choices[0].message.content)
Viestin, jonka rooli on tool, on sisällettävä:
tool_call_id: työkalukutsun yksilöllinen tunniste (sen linkittämiseksi pyyntöön)content: tulos JSON-merkkijonona
Määritä useita työkaluja
Voit määrittää tarvittavan määrän työkaluja tools-taulukkoon:
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": { ... }
}
}
]
Malli valitsee automaattisesti asiaankuuluvat työkalut käyttäjän pyynnön perusteella.
Tarkista finish_reason
Vastauksen finish_reason-kenttä ilmoittaa, onko malli päättänyt vastauksensa vai odottaako se työkalun tulosta:
finish_reason = response.choices[0].finish_reason
if finish_reason == "tool_calls":
# Malli odottaa yhden tai useamman työkalun tulosta
handle_tool_calls(response)
elif finish_reason == "stop":
# Malli on päättänyt vastauksensa
print(response.choices[0].message.content)
Keskeiset asiat
- Pyyntö sisältää
messages- jatools-osat (määritykset) - tool_call-argumentit ovat jäsennettävä JSON-merkkijono
- Lähetä tulos viestissä, jonka rooli on
toolja joka sisältäätool_call_id:n - Tarkista
finish_reasonselvittääksesi, odottaako malli tulosta - Voit määrittää useita työkaluja – malli valitsee ne automaattisesti