Iddefinixxi l-Għodod f'JSON
F'din il-paġna
Mit-teorija għall-prattika
Issa fhimt il-kunċett tas-sejħa tal-funzjonijiet u l-istruttura tal-iskemi JSON. Wasal iż-żmien li tgħaddi għall-implimentazzjoni konkreta. F’din il-lezzjoni, se titgħallem kif tibni talba sħiħa b’definizzjonijiet tal-għodod u kif timmaniġġja r-risposta tal-mudell.
Struttura tat-talba bl-għodod
Hawnhekk hawn talba sħiħa lill-API ta’ Grok b’għodda definita:
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
)
Innota l-istruttura mbejjna: l-oġġett tools fih array, fejn kull element għandu type u oġġett function bid-dettalji.
Ċifri ewlenin tal-implimentazzjoni
Immaniġġja r-risposta tool_call
Meta l-mudell jiddeċiedi li jsejjaħ funzjoni, ir-risposta tkun fiha array 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}")
Il-qasam tool_call.function.arguments huwa stringa JSON (mhux oġġett Python). Trid tanalizzaha (parse):
import json
args = json.loads(tool_call.function.arguments)
city = args["city"]
unit = args.get("unit", "celsius")
Eżegwixxi u rritorna r-riżultat
Ladarba l-funzjoni tiġi eżegwita, tibgħat ir-riżultat lura lill-mudell f’tieni sejħa:
import json
# 1. Eżegwixxi l-funzjoni
weather_data = get_weather(city="Paris", unit="celsius")
# 2. Ibni l-messaġġi bir-riżultat
messages = [
{"role": "user", "content": "What's the weather like in Paris?"},
message, # Ir-risposta tal-mudell b'tool_calls
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(weather_data)
}
]
# 3. Sejjaħ il-mudell mill-ġdid bir-riżultat
final_response = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools
)
print(final_response.choices[0].message.content)
Il-messaġġ bir-rwol tool irid ikun fih:
tool_call_id: l-identifikatur uniku tat-tool_call (biex torbtu mat-talba)content: ir-riżultat bħala stringa JSON
Iddefinixxi għodod multipli
Tista’ tiddikjara kemm-il għodda trid fl-array 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": { ... }
}
}
]
Il-mudell jagħżel awtomatikament l-għodda/għodod rilevanti abbażi tat-talba tal-utent.
Iċċekkja finish_reason
Il-qasam finish_reason fir-risposta jindika jekk il-mudellx temm ir-risposta tiegħu jew jekk qed jistenna riżultat ta’ għodda:
finish_reason = response.choices[0].finish_reason
if finish_reason == "tool_calls":
# Il-mudell qed jistenna r-riżultat ta' għodda waħda jew aktar
handle_tool_calls(response)
elif finish_reason == "stop":
# Il-mudell temm ir-risposta tiegħu
print(response.choices[0].message.content)
Punti Ewlenin
- It-talba fiha
messagesutools(definizzjonijiet) - L-argumenti ta’ tool_call huma stringa JSON li trid tiġi analizzata
- Ibgħat ir-riżultat f’messaġġ bir-rwol
toolli jinkludi l-tool_call_id - Iċċekkja
finish_reasonbiex tkun taf jekk il-mudellx qed jistenna riżultat - Tista’ tiddikjara għodod multipli—il-mudell jagħżel awtomatikament