Funzjonijiet personalizzati (sejħa tal-funzjonijiet)
F'din il-paġna
Qabbad lil Grok mas-servizzi tiegħek stess
L-għodod tas-server (web_search, x_search, code_interpreter) huma utli iżda limitati għas-servizzi ta’ xAI. Bl-għodod personalizzati ta’ function, tista’ tikkonnettja lil Grok ma’ kwalunkwe API jew servizz fl-infrastruttura tiegħek.
Kif taħdem
Is-sejħa tal-funzjonijiet issegwi ċiklu ta’ tliet passi:
- Dikjarazzjoni: Tiddeskrivi l-funzjonijiet tiegħek (isem, deskrizzjoni, parametri) fit-talba
- Sejħa: Il-mudell jiġġenera sejħa tal-funzjoni bl-argumenti xierqa u jieqaf il-ġenerazzjoni
- Riżultat: Il-kodiċi tiegħek jesegwixxi l-funzjoni, imbagħad tibgħat ir-riżultat lura lill-mudell biex ikun jista’ jifformula t-tweġiba tiegħu
Iddikjara funzjoni
{
"model": "grok-4.20-0309-reasoning",
"input": "Book me a table for 2 people tonight at 8 PM.",
"tools": [{
"type": "function",
"name": "book_restaurant",
"description": "Books a table at a restaurant",
"parameters": {
"type": "object",
"properties": {
"restaurant_name": {
"type": "string",
"description": "Restaurant name"
},
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format"
},
"time": {
"type": "string",
"description": "Time in HH:MM format"
},
"guests": {
"type": "integer",
"description": "Number of guests"
}
},
"required": ["date", "time", "guests"]
}
}]
}
Id-deskrizzjoni ta’ kull funzjoni u parametru hija kruċjali. Il-mudell jużahom biex jiddeċiedi meta jsejjaħ il-funzjoni u kif jimla l-argumenti.
Irċievi s-sejħa tal-funzjoni
Meta l-mudell jiddeċiedi li jsejjaħ il-funzjoni tiegħek, ir-risposta tkun fiha oġġett function_call:
{
"id": "resp-xyz789",
"status": "completed",
"output": [{
"type": "function_call",
"name": "book_restaurant",
"arguments": "{\"date\": \"2026-04-03\", \"time\": \"20:00\", \"guests\": 2}",
"call_id": "call-abc123"
}]
}
Il-qasam arguments huwa stringa JSON li trid tipparsja. Il-call_id jidentifika din is-sejħa speċifika.
Erġa’ rritorna r-riżultat
Wara li tesegwixxi l-funzjoni fil-kodiċi tiegħek, erġa’ rritorna r-riżultat:
import json
# 1. Talba inizjali
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What's the weather like in Paris?",
tools=[{
"type": "function",
"name": "get_weather",
"description": "Retrieves current weather",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}]
)
# 2. Iċċekkja jekk il-mudell iridx isejjaħ funzjoni
for item in response.output:
if item.type == "function_call":
args = json.loads(item.arguments)
# 3. Esegwixxi l-funzjoni tiegħek
weather_data = get_weather_from_api(args["city"])
# 4. Erġa' rritorna r-riżultat lill-mudell
final = client.responses.create(
model="grok-4.20-0309-reasoning",
input=[{
"type": "function_call_output",
"call_id": item.call_id,
"output": json.dumps(weather_data)
}],
previous_response_id=response.id
)
print(final.output[0].content[0].text)
L-aħjar prattiki għad-deskrizzjonijiet
Il-mudell jiddependi fuq id-deskrizzjonijiet biex jifhem il-funzjonijiet tiegħek. Kun preċiż:
{
"name": "search_products",
"description": "Searches for products in the e-commerce catalog. Returns the top 10 results sorted by relevance. Supports search by name, category, or price range.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search terms (product name, brand, keyword)"
},
"category": {
"type": "string",
"enum": ["electronics", "clothing", "home", "sports"],
"description": "Product category to filter"
},
"max_price": {
"type": "number",
"description": "Maximum price in euros"
}
},
"required": ["query"]
}
}
Uża enum għal valuri predefiniti, description dettaljata għal kull parametru, u mmarka biss il-parametri essenzjali bħala required.
Ġestjoni tal-iżbalji
Jekk il-funzjoni tiegħek tonqos, erġa’ rritorna l-iżball bħala r-riżultat:
try:
result = call_external_api(args)
output = json.dumps(result)
except Exception as e:
output = json.dumps({"error": str(e)})
final = client.responses.create(
model="grok-4.20-0309-reasoning",
input=[{
"type": "function_call_output",
"call_id": call_id,
"output": output
}],
previous_response_id=response.id
)
Il-mudell jinterpreta l-iżball u jista’ jifformula mill-ġdid it-tweġiba tiegħu jew jipprova approċċ differenti.
Punti Ewlenin
- Il-funzjonijiet personalizzati jikkonnettjaw lil Grok mas-servizzi tiegħek stess
- Iċ-ċiklu huwa: iddikjara, irċievi s-sejħa, esegwixxi, erġa’ rritorna r-riżultat
- Id-deskrizzjonijiet tal-funzjoni u tal-parametri jiggwidaw l-għażla tal-mudell
- Il-qasam
argumentshuwa stringa JSON li trid tipparsja fuq in-naħa tal-klijent - Erġa’ rritorna l-iżbalji bħala riżultati biex il-mudell ikun jista’ jadatta