Obmedzenia a osvedčené postupy
Na tejto strane
Technické obmedzenia volania funkcií
Predtým, než začneš s implementáciou, musíš pochopiť limity systému. Volanie funkcií v modeli Grok je síce výkonné, ale funguje v rámci špecifických obmedzení, ktoré musíš ovládať, aby si vybudoval robustné aplikácie.
Maximálne 200 nástrojov na požiadavku
API modelu Grok akceptuje až 200 definícií nástrojov v jednej požiadavke. Tento limit je štedrý – väčšina aplikácií využíva len 5 až 20 nástrojov. Ak však buduješ škálovateľný systém (pluginy, trh s nástrojmi), musíš s týmto limitom počítať.
Každá definícia nástroja zaberá miesto v kontextovom okne. Konkrétne:
- Jednoduchý nástroj (2 – 3 parametre) spotrebuje približne 50 – 100 tokenov
- Zložitý nástroj (10+ parametrov, podrobné popisy) môže presiahnuť 300 tokenov
- 200 zložitých nástrojov = 60 000 tokenov len pre definície
Preto musíš postupovať strategicky: deklaruj iba nástroje relevantné pre aktuálnu požiadavku.
Model nezaručuje platnosť argumentov
Grok sa snaží generovať argumenty, ktoré zodpovedajú schéme, ale nie je neomylný. Model môže:
- Vygenerovať nesprávny formát dátumu
- Poslať
stringtam, kde sa očakávainteger - V zriedkavých prípadoch vynechať povinné pole
- Halucinovať hodnoty enum, ktoré neexistujú
Tvoj kód na strane klienta musí vždy validovať prijaté argumenty pred vykonaním funkcie.
import json
def handle_tool_call(tool_call):
args = json.loads(tool_call.function.arguments)
# Validácia pred vykonaním
if "city" not in args:
return {"error": "Parameter city je povinný"}
if not isinstance(args["city"], str):
return {"error": "city musí byť reťazec"}
return get_weather(args["city"], args.get("unit", "celsius"))
Spracovanie chýb
Keď funkcia zlyhá, musíš vrátiť chybu modelu, namiesto toho, aby aplikácia ticho zlyhala. Model potom môže:
- Preformulovať svoju požiadavku s opravenými parametrami
- Informovať používateľa o probléme
- Skúsiť alternatívny nástroj
try:
result = search_database(query=args["query"])
return json.dumps(result)
except ConnectionError:
return json.dumps({
"error": "Databáza je nedostupná",
"suggestion": "Skús to znova o niekoľko sekúnd"
})
Vždy vráť štruktúrovaný JSON, aj v prípade chyby. Model rozumie chybovým hlášeniam a podľa toho prispôsobí svoju odpoveď.
Jedinečné a explicitné názvy
Názvy funkcií musia byť v zozname nástrojov jedinečné. Ak dva nástroje zdieľajú rovnaký názov, správanie je nedefinované – API môže požiadavku odmietnuť alebo jeden z nástrojov ignorovať.
Prijmi konzistentnú konvenciu pomenovania:
✅ Osvedčené postupy:
get_weather → získavanie dát
search_products → vyhľadávanie
create_ticket → vytváranie
update_order_status → aktualizácia
delete_draft → vymazanie
❌ Vyvaruj sa:
fn1, fn2 → nezrozumiteľné
doStuff → príliš vágne
getWeatherData → camelCase (uprednostni snake_case)
Popisy: faktor kvality číslo 1
Kvalita popisov priamo určuje spoľahlivosť volania funkcií. Tu je porovnávacia tabuľka:
| Slabý popis | Efektívny popis |
|---|---|
| "Vyhľadať" | "Vyhľadaj produkty podľa názvu, kategórie alebo cenového rozpätia v e-commerce katalógu" |
| "Odoslať správu" | "Odošli e-mail príjemcovi. Vyžaduje predmet a telo správy. Nepodporuje prílohy." |
| "Vypočítať" | "Vypočítaj celkovú cenu vrátane dane z ceny bez dane a sadzby DPH. Vrátia sumu v eurách s dvoma desatinnými miestami." |
Optimalizácia počtu nástrojov
Namiesto deklarovania 200 nástrojov pri každej požiadavke dynamicky vyberaj tie, ktoré sú skutočne dôležité. Prvým filtrom je kontext: ak používateľ hovorí o počasí, načítanie fakturačných nástrojov len pridáva šum – na prezentáciu iba relevantnej rodiny stačí jednoduché smerovanie na začiatku (podľa kľúčových slov alebo prvého klasifikačného volania). Druhým filtrom je rola: agent podpory nepotrebuje administrátorské nástroje a ich odstránenie je otázkou presnosti rovnako ako bezpečnosti. Tretím faktorom je krok: vo viacstupňovom pracovnom postupe má každá fáza svoje vlastné nástroje – ich načítavaním podľa postupu udržuješ model sústredený na to, čo má robiť práve teraz.
Výhod je hneď niekoľko a sú okamžité: menej vstupných tokenov na požiadavku (definície nástrojov ťa stoja pri každom volaní) a lepšia presnosť výberu – model vyberajúci zo šiestich dobre popísaných nástrojov sa málokedy pomýli, zatiaľ čo ten istý model confronted so dvesto definíciami si nakoniec pomýli podobné varianty.
Bezpečnosť: modelu nikdy nedôveruj
Volanie funkcií je potenciálnym vektorom injekcie. Škodlivý používateľ by mohol formulovať svoju požiadavku tak, aby manipuloval s argumentmi odovzdanými funkciám. Bezpečnostné pravidlá:
- Validuj všetky argumenty na strane servera
- Obmedz oprávnenia: funkcia na čítanie by nemala mať právo zapisovať
- Loguj volania: sleduj každé volanie funkcie kvôli auditu
- Čisti vstupy: escapuj špeciálne znaky pred SQL/shell dotazmi
Kľúčové poznatky
- Maximálne 200 nástrojov na požiadavku – ale pre efektivitu sa zameraj na 5 – 20
- Vždy validuj argumenty na strane klienta pred vykonaním
- Vracaj chyby modelu v štruktúrovanom JSON
- Názvy musia byť jedinečné, vo formáte snake_case a explicitné
- Podrobné popisy drasticky zlepšujú spoľahlivosť
- Dynamicky vyberaj relevantné nástroje pre každú požiadavku
- Nikdy nedôveruj argumentom bez validácie