Ορισμός Εργαλείων σε JSON
Σε αυτήν τη σελίδα
Από τη θεωρία στην πράξη
Τώρα που κατανοείτε την έννοια της κλήσης συναρτήσεων (function calling) και τη δομή των σχημάτων JSON, είναι ώρα να προχωρήσετε στην πρακτική υλοποίηση. Σε αυτό το μάθημα, θα μάθετε πώς να κατασκευάζετε ένα πλήρες αίτημα με ορισμούς εργαλείων και πώς να διαχειρίζεστε την απάντηση του μοντέλου.
Δομή αιτήματος με εργαλεία
Ακολουθεί ένα πλήρες αίτημα προς το API του Grok με ένα καθορισμένο εργαλείο:
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για να μάθετε αν το μοντέλο περιμένει αποτέλεσμα - Μπορείτε να δηλώσετε πολλαπλά εργαλεία· το μοντέλο επιλέγει αυτόματα