Kohandatud funktsioonid (funktsioonide kutsumine)
Sellel lehel
Ühenda Grok oma teenustega
Serveripoolsed tööriistad (web_search, x_search, code_interpreter) on kasulikud, kuid piirduvad xAI teenustega. Kohandatud function tööriistadega saad ühendada Groki mis tahes API või teenusega oma taristus.
Kuidas see toimib
Funktsioonide kutsumine järgib kolmeastmelist tsüklit:
- Deklareerimine: Kirjeldad oma funktsioone (nimi, kirjeldus, parameetrid) päringus
- Kutsumine: Mudel genereerib funktsioonikutse sobivate argumentidega ja peatab genereerimise
- Tulemus: Sinu kood käivitab funktsiooni, seejärel saadad tulemuse mudelile tagasi, et see saaks vormistada oma vastuse
Funktsiooni deklareerimine
{
"model": "grok-4.20-0309-reasoning",
"input": "Broneeri mulle laud kahele täna õhtul kell 20.00.",
"tools": [{
"type": "function",
"name": "book_restaurant",
"description": "Broneerib laua restoranis",
"parameters": {
"type": "object",
"properties": {
"restaurant_name": {
"type": "string",
"description": "Restorani nimi"
},
"date": {
"type": "string",
"description": "Kuupäev formaadis YYYY-MM-DD"
},
"time": {
"type": "string",
"description": "Kellaaeg formaadis HH:MM"
},
"guests": {
"type": "integer",
"description": "Külaliste arv"
}
},
"required": ["date", "time", "guests"]
}
}]
}
Iga funktsiooni ja parameetri kirjeldus on ülioluline. Mudel kasutab neid otsustamaks, millal funktsiooni kutsuda ja kuidas argumendid täita.
Funktsioonikutse vastuvõtmine
Kui mudel otsustab sinu funktsiooni kutsuda, sisaldab vastus elementi 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"
}]
}
Väli arguments on JSON-string, mille pead parsima. call_id identifitseerib seda konkreetset kutset.
Tulemuse tagastamine
Pärast funktsiooni käivitamist oma koodis tagasta tulemus:
import json
# 1. Esmane päring
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Milline on ilm Pariisis?",
tools=[{
"type": "function",
"name": "get_weather",
"description": "Toob praeguse ilmateate",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}]
)
# 2. Kontrolli, kas mudel tahab funktsiooni kutsuda
for item in response.output:
if item.type == "function_call":
args = json.loads(item.arguments)
# 3. Käivita oma funktsioon
weather_data = get_weather_from_api(args["city"])
# 4. Tagasta tulemus mudelile
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)
Parimad tavad kirjelduste koostamisel
Mudel tugineb funktsioonide mõistmisel kirjeldustele. Ole täpne:
{
"name": "search_products",
"description": "Otsib tooteid e-kaubanduse kataloogist. Tagastab 10 parimat tulemust, sorteerituna asjakohasuse järgi. Toetab otsingut nime, kategooria või hinnavahemiku järgi.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Otsingusõnad (toote nimi, bränd, märksõna)"
},
"category": {
"type": "string",
"enum": ["electronics", "clothing", "home", "sports"],
"description": "Toote kategooria filtreerimiseks"
},
"max_price": {
"type": "number",
"description": "Maksimaalne hind eurodes"
}
},
"required": ["query"]
}
}
Kasuta eelmääratud väärtuste jaoks enum, iga parameetri jaoks üksikasjalikku description ja märgi ainult hädavajalikud parameetrid kui required.
Veakäsitlus
Kui sinu funktsioon ebaõnnestub, tagasta viga tulemusena:
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
)
Mudel tõlgendab viga ja saab oma vastust ümber sõnastada või proovida teistsugust lähenemist.
Peamised punktid
- Kohandatud funktsioonid ühendavad Groki sinu enda teenustega
- Tsükkel on: deklareeri, võta kutse vastu, käivita, tagasta tulemus
- Funktsiooni ja parameetrite kirjeldused juhivad mudeli valikut
- Väli
argumentson JSON-string, mille pead kliendipoolselt parsima - Tagasta vead tulemustena, et mudel saaks kohaneda