Omezení a osvědčené postupy
Na této stránce
Technická omezení volání funkcí
Než začneš s implementací, musíš pochopit limity systému. Volání funkcí v modelu Grok je sice výkonné, ale pracuje v rámci specifických omezení, která musíš zvládnout, abys vybudoval robustní aplikace.
Maximálně 200 nástrojů na požadavek
API Grok přijme v jednom požadavku až 200 definic nástrojů. Tento limit je štědrý – většina aplikací využívá pouze 5 až 20 nástrojů. Pokud však buduješ škálovatelný systém (pluginy, tržiště nástrojů), musíš s tímto limitem počítat.
Každá definice nástroje zabírá místo v kontextovém okně. Konkrétně:
- Jednoduchý nástroj (2–3 parametry) spotřebuje přibližně 50–100 tokenů
- Složitý nástroj (10+ parametrů, podrobné popisy) může překročit 300 tokenů
- 200 složitých nástrojů = 60 000 tokenů jen pro definice
Proto musíš postupovat strategicky: deklaruj pouze nástroje relevantní pro aktuální požadavek.
Model nezaručuje platnost argumentů
Grok se snaží generovat argumenty odpovídající schématu, ale není neomylný. Model může:
- Vygenerovat nesprávný formát data
- Předat
stringtam, kde se očekáváinteger - Ve vzácných případech vynechat povinné pole
- Halucinovat hodnoty výčtu, které neexistují
Tvůj kód na straně klienta musí vždy validovat přijaté argumenty před spuštěním funkce.
import json
def handle_tool_call(tool_call):
args = json.loads(tool_call.function.arguments)
# Validace před spuštěním
if "city" not in args:
return {"error": "Parametr city je povinný"}
if not isinstance(args["city"], str):
return {"error": "city musí být řetězec"}
return get_weather(args["city"], args.get("unit", "celsius"))
Zpracování chyb
Když funkce selže, musíš chybu vrátit modelu, nikoliv tiše spadnout. Model pak může:
- Přeformulovat svůj požadavek s opravenými parametry
- Informovat uživatele o problému
- Zkusit alternativní nástroj
try:
result = search_database(query=args["query"])
return json.dumps(result)
except ConnectionError:
return json.dumps({
"error": "Databáze je nedostupná",
"suggestion": "Zkuste to znovu za několik sekund"
})
Vždy vracej strukturované JSON, a to i v případě chyby. Model rozumí chybovým zprávám a podle nich přizpůsobí svou odpověď.
Unikátní a explicitní názvy
Názvy funkcí musí být v seznamu nástrojů unikátní. Pokud dva nástroje sdílejí stejný název, chování je nedefinované – API může požadavek odmítnout nebo jeden z nástrojů ignorovat.
Přijmi konzistentní konvenci pojmenování:
✅ Osvědčené postupy:
get_weather → získávání dat
search_products → vyhledávání
create_ticket → vytvoření
update_order_status → aktualizace
delete_draft → smazání
❌ Vyvaruj se:
fn1, fn2 → nesrozumitelné
doStuff → příliš vágní
getWeatherData → camelCase (upřednostňuj snake_case)
Popisy: faktor kvality číslo jedna
Kvalita popisů přímo určuje spolehlivost volání funkcí. Zde je srovnávací tabulka:
| Slabý popis | Efektivní popis |
|---|---|
| "Vyhledat" | "Vyhledat produkty podle názvu, kategorie nebo cenového rozpětí v e-commerce katalogu" |
| "Odeslat zprávu" | "Odeslat e-mail příjemci. Vyžaduje předmět a tělo zprávy. Nepodporuje přílohy." |
| "Vypočítat" | "Vypočítat celkovou cenu včetně daně z ceny před zdaněním a sazby DPH. Vrátí částku v eurech se dvěma desetinnými místy." |
Optimalizace počtu nástrojů
Místo deklarování 200 nástrojů při každém požadavku dynamicky vybírej ty, které jsou skutečně důležité. Prvním filtrem je kontext: pokud uživatel mluví o počasí, načítání fakturačních nástrojů jen přidává šum – lehké směrování na úrovni upstream (podle klíčových slov nebo prvního klasifikačního volání) stačí k předložení pouze relevantní rodiny nástrojů. Druhým filtrem je role: agent podpory nepotřebuje administrátorské nástroje a jejich odstranění je otázkou přesnosti stejně jako bezpečnosti. Třetím filtrem je krok: v pracovním postupu s více kroky má každá fáze své vlastní nástroje – jejich načítání podle postupu udržuje model zaměřený na to, co musí udělat právě teď.
Přínos je dvojnásobný a okamžitý: méně vstupních tokenů na požadavek (definice nástrojů tě stojí peníze při každém volání) a lepší přesnost výběru – model vybírající ze šesti dobře popsaných nástrojů se málokdy spletne, zatímco stejný model čelící dvěma stovkám definic si nakonec začne plést blízké varianty.
Bezpečnost: modelu nikdy nedůvěřuj
Volání funkcí je potenciálním vektorem pro injekce. Škodlivý uživatel může formulovat svůj požadavek tak, aby manipuloval s argumenty předávanými funkcím. Bezpečnostní pravidla:
- Validuj všechny argumenty na straně serveru
- Omez oprávnění: funkce určená pouze ke čtení nesmí mít právo zápisu
- Loguj volání: sleduj každé volání funkce pro účely auditu
- Čisti vstupy: escapuj speciální znaky před dotazy SQL/shell
Klíčové poznatky
- Maximálně 200 nástrojů na požadavek – ale pro efektivitu cíl na 5–20
- Vždy validuj argumenty na straně klienta před spuštěním
- Vracej chyby modelu ve strukturovaném JSON
- Názvy musí být unikátní, ve formátu snake_case a explicitní
- Podrobné popisy drasticky zlepšují spolehlivost
- Dynamicky vybírej relevantní nástroje pro každý požadavek
- Nikdy nedůvěřuj argumentům bez validace