Piirangud ja parimad tavad
Sellel lehel
Funktsioonide kutsumise tehnilised piirangud
Enne rakendamise alustamist pead mõistma süsteemi piiranguid. Groki funktsioonide kutsumine on võimas, kuid see toimib kindlate raamistike sees, mille valdamine on hädavajalik töökindlate rakenduste loomiseks.
Maksimaalselt 200 tööriista päringu kohta
Grok API aktsepteerib ühes päringus kuni 200 tööriista definitsiooni. See limiit on helde – enamik rakendusi kasutab vaid 5 kuni 20. Kui aga ehidad skaleeruvat süsteemi (pistikprogrammid, tööriistade turg), pead seda arvesse võtma.
Iga tööriista definitsioon võtab kontekstiaknas ruumi. Täpsemalt:
- Lihtne tööriist (2–3 parameetrit) tarbib umbes 50–100 tokenit
- Kompleksne tööriist (10+ parameetrit, üksikasjalikud kirjeldused) võib ületada 300 tokenit
- 200 kompleksset tööriista = 60 000 tokenit ainult definitsioonide jaoks
Seetõttu pead olema strateegiline: deklareeri ainult need tööriistad, mis on konkreetse päringu jaoks asjakohased.
Mudel ei garanteeri argumentide kehtivust
Grok teeb oma parima, et genereerida skeemile vastavaid argumente, kuid see ei ole eksimatu. Mudel võib:
- Genereerida vale kuupäevaformaat
- Edastada
string-i seal, kus oodatakseinteger-it - Harvadel juhtudel jätta nõutud välja täitmata
- Hallutsineerida olematuid enum-väärtusi
Sinu kliendipoolne kood peab saadud argumendid enne funktsiooni käivitamist alati valideerima.
import json
def handle_tool_call(tool_call):
args = json.loads(tool_call.function.arguments)
# Valideeri enne käivitamist
if "city" not in args:
return {"error": "Linn on nõutud parameeter"}
if not isinstance(args["city"], str):
return {"error": "linn peab olema string"}
return get_weather(args["city"], args.get("unit", "celsius"))
Veakäsitlus
Kui funktsioon ebaõnnestub, pead vea mudelile tagastama, mitte vaikimisi kokku jooksma. Seejärel saab mudel:
- Oma päringut parandatud parameetritega ümber sõnastada
- Kasutajat probleemist teavitada
- Proovida alternatiivset tööriista
try:
result = search_database(query=args["query"])
return json.dumps(result)
except ConnectionError:
return json.dumps({
"error": "Andmebaas pole kättesaadav",
"suggestion": "Proovi mõne sekundi pärast uuesti"
})
Tagasta alati struktureeritud JSON, isegi vea korral. Mudel mõistab veateateid ja kohandab oma vastust sellele vastavalt.
Unikaalsed ja selged nimed
Funktsioonide nimed peavad tööriistade loendis olema unikaalsed. Kui kahel tööriistal on sama nimi, on käitumine määratlemata – API võib päringu tagasi lükata või ühe neist ignoreerida.
Kasuta järjekindlat nimede konventsiooni:
✅ Parimad tavad:
get_weather → andmete pärimine
search_products → otsing
create_ticket → loomine
update_order_status → uuendamine
delete_draft → kustutamine
❌ Vältida:
fn1, fn2 → arusaamatu
doStuff → liiga ebamäärane
getWeatherData → camelCase (eelista snake_case'i)
Kirjeldused: kvaliteedi number üks tegur
Kirjelduste kvaliteet määrab otseselt funktsioonide kutsumise usaldusväärsuse. Siin on võrdlustabel:
| Nõrk kirjeldus | Tõhus kirjeldus |
|---|---|
| "Otsing" | "Otsi tooteid nime, kategooria või hinnavahemiku järgi e-kaubanduse kataloogist" |
| "Saada sõnum" | "Saada e-kiri adressaadile. Nõuab teemat ja sõnumi teksti. Manuseid ei toeta." |
| "Arvuta" | "Arvuta käibemaksuga lõpphind eelhinnast ja käibemaksumäärast. Tagastab summa eurodes kahe komakohaga." |
Tööriistade arvu optimeerimine
Selle asemel, et deklareerida igas päringus 200 tööriista, vali dünaamiliselt need, mis tegelikult loevad. Esimene filter on kontekst: kui kasutaja räägib ilmast, lisavad arveldustööriistad ainult müra – piisab kergest ülesvoosu suunamisest (märksõnade või esmase klassifitseerimispäringu abil), et esitada ainult asjakohane perekond. Teine filter on roll: tugiteenuse operaator ei vaja administraatori tööriistu ja nende eemaldamine on täpsuse kui ka turvalisuse küsimus. Kolmas on samm: mitmeastmelises töövoos on igal etapil oma tööriistad – nende laadimine edenemise käigus hoiab mudeli fokuseerituna sellele, mida ta praegu tegema peab.
Kasu on kahekordne ja kohene: vähem sisendtokeneid päringu kohta (tööriistade definitsioonid maksavad iga kutse korral) ja parem valiku täpsus – mudel, mis valib kuue hästi kirjeldatud tööriista seast, teeb harva vigu, samas kui sama mudel kahe saja definitsiooni ees lõpetab sarnaste variantide segiajamisega.
Turvalisus: ära kunagi usalda mudelit
Funktsioonide kutsumine on potentsiaalne süstimisvektor. Pahatahtlik kasutaja võib oma päringu sõnastada nii, et manipuleerida funktsioonidele edastatavate argumentidega. Turvareeglid:
- Valideeri kõik argumendid serveripoolselt
- Piira õigusi: lugemisfunktsioon ei tohi kirjutada
- Logi kutsed: jälita iga funktsioonikutset auditeerimiseks
- Puhasta sisendid: escape’i erimärgid enne SQL-i või shelli päringuid
Peamised punktid
- Maksimaalselt 200 tööriista päringu kohta – kuid efektiivsuse huvides püüa jääda 5–20 juurde
- Valideeri argumendid enne käivitamist alati kliendipoolselt
- Tagasta vead mudelile struktureeritud JSON-formaadis
- Nimed peavad olema unikaalsed, snake_case-formaadis ja selged
- Üksikasjalikud kirjeldused parandavad drastiliselt usaldusväärsust
- Vali iga päringu jaoks dünaamiliselt asjakohased tööriistad
- Ära kunagi usalda argumente ilma valideerimiseta