Ograničenja i najbolje prakse
Na ovoj stranici
Tehnička ograničenja pozivanja funkcija
Prije nego što kreneš s implementacijom, moraš razumjeti ograničenja sustava. Grokovo pozivanje funkcija je moćno, ali radi unutar specifičnih okvira koje moraš savladati kako bi izgradio/la robustne aplikacije.
Maksimalno 200 alata po zahtjevu
Grok API prihvaća do 200 definicija alata u jednom zahtjevu. Ovo ograničenje je velikodušno – većina aplikacija koristi samo 5 do 20. No, ako gradiš skalabilan sustav (pluginovi, tržište alata), moraš računati na ovo.
Svaka definicija alata zauzima prostor u prozoru konteksta. Konkretno:
- Jednostavan alat (2-3 parametra) troši oko 50-100 tokena
- Složen alat (10+ parametara, detaljni opisi) može premašiti 300 tokena
- 200 složenih alata = 60 000 tokena samo za definicije
Zato moraš biti strateški nastrojen/a: deklariraj samo alate relevantne za trenutni zahtjev.
Model ne jamči valjanost argumenata
Grok se trudi generirati argumente koji odgovaraju shemi, ali nije nepogrešiv. Model može:
- Generirati netočan format datuma
- Proslijediti
stringtamo gdje se očekujeinteger - U rijetkim slučajevima izostaviti obavezno polje
- Halucinirati enum vrijednosti koje ne postoje
Tvoj kôd na strani klijenta mora uvijek validirati primljene argumente prije izvršavanja funkcije.
import json
def handle_tool_call(tool_call):
args = json.loads(tool_call.function.arguments)
# Validiraj prije izvršavanja
if "city" not in args:
return {"error": "Parametar city je obavezan"}
if not isinstance(args["city"], str):
return {"error": "city mora biti string"}
return get_weather(args["city"], args.get("unit", "celsius"))
Rukovanje greškama
Kada funkcija zakaže, moraš vratiti grešku modelu umjesto da tiho padneš. Model tada može:
- Preformulirati svoj zahtjev s ispravljenim parametrima
- Obavijestiti korisnika o problemu
- Pokušati alternativni alat
try:
result = search_database(query=args["query"])
return json.dumps(result)
except ConnectionError:
return json.dumps({
"error": "Baza podataka nije dostupna",
"suggestion": "Pokušaj ponovno za nekoliko sekundi"
})
Uvijek vrati strukturirani JSON, čak i kod greške. Model razumije poruke o greškama i sukladno tome prilagođava svoj odgovor.
Jedinstvena i eksplicitna imena
Imena funkcija moraju biti jedinstvena na popisu alata. Ako dva alata dijele isto ime, ponašanje je nedefinirano – API može odbiti zahtjev ili ignorirati jedan od njih.
Usvoji dosljednu konvenciju imenovanja:
✅ Najbolje prakse:
get_weather → dohvat podataka
search_products → pretraživanje
create_ticket → kreiranje
update_order_status → ažuriranje
delete_draft → brisanje
❌ Izbjegavaj:
fn1, fn2 → nerazumljivo
doStuff → previše neodređeno
getWeatherData → camelCase (preferiraj snake_case)
Opisi: faktor kvalitete broj 1
Kvaliteta opisa izravno određuje pouzdanost pozivanja funkcija. Evo usporedne tablice:
| Slab opis | Učinkovit opis |
|---|---|
| "Pretraži" | "Pretraži proizvode po nazivu, kategoriji ili cjenovnom rangu u e-trgovini" |
| "Pošalji poruku" | "Pošalji e-mail primatelju. Zahtijeva naslov i tijelo poruke. Ne podržava privitke." |
| "Izračunaj" | "Izračunaj ukupnu cijenu uključujući porez na temelju cijene bez poreza i stope PDV-a. Vraća iznos u eurima s 2 decimalna mjesta." |
Optimizacija broja alata
Umjesto da deklariraš 200 alata pri svakom zahtjevu, dinamički odaberi one koji su stvarno bitni. Prvi filtar je kontekst: ako korisnik govori o vremenu, učitavanje alata za naplatu samo dodaje šum – lagano usmjeravanje na početku (po ključnim riječima ili prvim pozivom klasifikacije) dovoljno je da se prikaže samo relevantna obitelj. Drugi filtar je uloga: agent za podršku ne treba administrativne alate, a njihovo uklanjanje je pitanje preciznosti koliko i sigurnosti. Treći je korak: u višekoračnom tijeku rada, svaka faza ima svoje alate – njihovo učitavanje kako napreduješ drži model fokusiranim na ono što sada treba učiniti.
Prednost je dvostruka i trenutna: manje ulaznih tokena po zahtjevu (definicije alata te koštaju pri svakom pozivu) i bolja točnost odabira – model koji bira između šest dobro opisanih alata rijetko griješi, dok isti model suočen s dvjesto definicija završava miješajući slične varijante.
Sigurnost: nikada ne vjeruj modelu
Pozivanje funkcija je potencijalni vektor za injekcije. Zlonamjerni korisnik mogao bi formulirati svoj zahtjev kako bi manipulirao argumentima proslijeđenim funkcijama. Pravila sigurnosti:
- Validiraj sve argumente na strani poslužitelja
- Ograniči dopuštenja: funkcija za čitanje ne smije moći pisati
- Bilježi pozive: prati svaki poziv funkcije radi revizije
- Čisti ulaze: escapeaj posebne znakove prije SQL/shell upita
Ključne točke
- Maksimalno 200 alata po zahtjevu – ali ciljaj na 5-20 radi učinkovitosti
- Uvijek validiraj argumente na strani klijenta prije izvršavanja
- Vrati greške modelu u strukturiranom JSON-u
- Imena moraju biti jedinstvena, u snake_case formatu i eksplicitna
- Detaljni opisi drastično poboljšavaju pouzdanost
- Dinamički odaberi relevantne alate za svaki zahtjev
- Nikada ne vjeruj argumentima bez validacije