Definirea instrumentelor în JSON
Pe această pagină
De la teorie la practică
Ați înțeles acum conceptul de apelare a funcțiilor și structura schemelor JSON. Este momentul să treceți la implementarea concretă. În această lecție, veți învăța cum să construiți o cerere completă cu definiții de instrumente și cum să gestionați răspunsul modelului.
Structura cererii cu instrumente
Iată o cerere completă adresată API-ului Grok cu un instrument definit:
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
)
Observați structura imbricată: obiectul tools conține un tablou, unde fiecare element are un type și un obiect function cu detaliile necesare.
Cifre cheie ale implementării
Gestionarea răspunsului tool_call
Când modelul decide să apeleze o funcție, răspunsul conține un tablou 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}")
Câmpul tool_call.function.arguments este un șir JSON (nu un obiect Python). Trebuie să îl analizați:
import json
args = json.loads(tool_call.function.arguments)
city = args["city"]
unit = args.get("unit", "celsius")
Executarea și returnarea rezultatului
Odată ce funcția este executată, trimiteți rezultatul înapoi modelului într-o a doua apelare:
import json
# 1. Executați funcția
weather_data = get_weather(city="Paris", unit="celsius")
# 2. Construiți mesajele cu rezultatul
messages = [
{"role": "user", "content": "What's the weather like in Paris?"},
message, # Răspunsul modelului cu tool_calls
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(weather_data)
}
]
# 3. Apelați din nou modelul cu rezultatul
final_response = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools
)
print(final_response.choices[0].message.content)
Mesajul cu rolul tool trebuie să conțină:
tool_call_id: identificatorul unic al tool_call-ului (pentru a-l lega de cerere)content: rezultatul sub formă de șir JSON
Definirea mai multor instrumente
Puteți declara câte instrumente doriți în tabloul 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": { ... }
}
}
]
Modelul va alege automat instrumentul sau instrumentele relevante în funcție de cererea utilizatorului.
Verificarea câmpului finish_reason
Câmpul finish_reason din răspuns indică dacă modelul și-a terminat răspunsul sau dacă așteaptă un rezultat de la un instrument:
finish_reason = response.choices[0].finish_reason
if finish_reason == "tool_calls":
# Modelul așteaptă rezultatul unuia sau mai multor instrumente
handle_tool_calls(response)
elif finish_reason == "stop":
# Modelul și-a terminat răspunsul
print(response.choices[0].message.content)
Puncte cheie
- Cererea conține
messagesșitools(definiții) - Argumentele tool_call sunt un șir JSON care trebuie analizat
- Trimiteți rezultatul într-un mesaj cu rolul
tool, incluzândtool_call_id - Verificați
finish_reasonpentru a ști dacă modelul așteaptă un rezultat - Puteți declara multiple instrumente; modelul le alege automat