Ribos ir geriausios praktikos
Šiame puslapyje
Techniniai funkcijų iškvietimo apribojimai
Prieš pradėdamas diegimą, turi suprasti sistemos ribas. Grok funkcijų iškvietimas yra galingas, tačiau veikia pagal specifinius apribojimus, kuriuos privalai įvaldyti, kad sukurtum patikimas programas.
Daugiausia 200 įrankių vienam užklausimui
Grok API viename užklausime priima iki 200 įrankių apibrėžimų. Ši riba yra dosni – dauguma programų naudoja tik 5–20 įrankių. Tačiau jei kuriate mastelį turinčią sistemą (įskiepius, įrankių turgavietę), turite į tai atsižvelgti.
Kiekvienas įrankio apibrėžimas užima vietos konteksto lange. Visų pirma:
- Paprastas įrankis (2–3 parametrai) sunaudoja apie 50–100 tokenų
- Sudėtingas įrankis (10+ parametrų, išsamūs aprašymai) gali viršyti 300 tokenų
- 200 sudėtingų įrankių = 60 000 tokenų vien apibrėžimams
Štai kodėl turi būti strategiškai nusiteikęs: deklaruok tik tuos įrankius, kurie yra aktualūs dabartiniam užklausimui.
Modelis negarantuoja argumentų galiojimo
Grok stengiasi sugeneruoti argumentus, atitinkančius schemą, tačiau nėra neklystantis. Modelis gali:
- Sugeneruoti neteisingą datos formatą
- Perdavoti
string, kai tikimasiinteger - Retais atvejais praleisti privalomą lauką
- Haliucinuoti enum reikšmes, kurių nėra
Tavo kliento pusės kodas privalo visada patikrinti gautus argumentus prieš vykdydamas funkciją.
import json
def handle_tool_call(tool_call):
args = json.loads(tool_call.function.arguments)
# Patikrinkite prieš vykdymą
if "city" not in args:
return {"error": "Miesto parametras yra privalomas"}
if not isinstance(args["city"], str):
return {"error": "miestas turi būti eilutė"}
return get_weather(args["city"], args.get("unit", "celsius"))
Klaidų valdymas
Kai funkcija nepavyksta, turite grąžinti klaidą modeliui, o ne tyliai „lūžti“. Tada modelis gali:
- Performuluoti savo užklausą su pataisytais parametrais
- Informuoti vartotoją apie problemą
- Pabandyti alternatyvų įrankį
try:
result = search_database(query=args["query"])
return json.dumps(result)
except ConnectionError:
return json.dumps({
"error": "Duomenų bazė nepasiekiama",
"suggestion": "Bandykite po kelių sekundžių"
})
Visada grąžinkite struktūrizuotą JSON, net ir įvykus klaidai. Modelis supranta klaidų pranešimus ir atitinkamai pritaiko savo atsakymą.
Unikalūs ir aiškūs pavadinimai
Funkcijų pavadinimai įrankių sąraše turi būti unikalūs. Jei du įrankiai turi tą patį pavadinimą, elgsena yra neapibrėžta – API gali atmesti užklausą arba ignoruoti vieną iš jų.
Laikykitės nuoseklaus pavadinimų kūrimo konvencijos:
✅ Geriausios praktikos:
get_weather → duomenų gavimas
search_products → paieška
create_ticket → kūrimas
update_order_status → atnaujinimas
delete_draft → ištrynimas
❌ Venkite:
fn1, fn2 → nesuprantama
doStuff → per daug miglota
getWeatherData → camelCase (geriau rinktis snake_case)
Aprašymai: svarbiausias kokybės veiksnys
Aprašymų kokybė tiesiogiai lemia funkcijų iškvietimo patikimumą. Štai palyginimo lentelė:
| Silpnas aprašymas | Efektyvus aprašymas |
|---|---|
| "Paieška" | "Ieškoti produktų pagal pavadinimą, kategoriją ar kainų diapazoną el. prekybos kataloge" |
| "Siųsti žinutę" | "Siųsti el. laišką gavėjui. Reikalauja temos ir žinutės teksto. Nepalaiko priedų." |
| "Skaičiuoti" | "Apskaičiuoti bendrą kainą įskaitant mokestį iš kainos be mokesčio ir PVM tarifo. Grąžina sumą eurais su 2 skaitmenimis po kablelio." |
Įrankių skaičiaus optimizavimas
Užuot deklaruojant 200 įrankių kiekvienam užklausimui, dinamiškai pasirinkite tik tuos, kurie iš tikrųjų svarbūs. Pirmasis filtras yra kontekstas: jei vartotojas kalba apie orus, mokesčių įrankių įkėlimas tik pridės triukšmo – pakanka lengvo maršrutizavimo aukštesniame lygmenyje (pagal raktažodžius ar pirmąjį klasifikavimo iškvietimą), kad būtų pateikta tik aktuali grupė. Antrasis filtras yra vaidmuo: palaikymo agentui nereikia administratoriaus įrankių, o jų pašalinimas yra tiek tikslumo, tiek saugumo klausimas. Trečiasis yra žingsnis: daugiapakopėje darbo eigoje kiekvienas etapas turi savo įrankius – jų įkėlimas progresuojant leidžia modeliui sutelkti dėmesį į tai, ką jis turi daryti dabar.
Naudą galima suskirstyti į dvi dalis, ir ji yra momentali: mažiau įvesties tokenų vienam užklausimui (įrankių apibrėžimai kainuoja kiekvieno iškvietimo metu) ir geresnis pasirinkimo tikslumas – modelis, renkantis iš šešių gerai aprašytų įrankių, retai klysta, tuo tarpu tas pats modelis, susidūręs su dviem šimtais apibrėžimų, galiausiai supainioja panašias variacijas.
Saugumas: niekada nepasitikėkite modeliu
Funkcijų iškvietimas yra potencialus injekcijos vektorius. Piktavališkas vartotojas galėtų suformuluoti savo užklausą taip, kad manipuliuotų funkcijoms perduodamais argumentais. Saugumo taisyklės:
- Patikrinkite visus argumentus serverio pusėje
- Apribokite leidimus: skaitymo funkcija neturėtų galėti rašyti
- Registruokite iškvietimus: fiksuokite kiekvieną funkcijos iškvietimą audito tikslais
- Valykite įvestis: prieš SQL/shell užklausas pabėkite specialiuosius simbolius
Svarbiausi punktai
- Daugiausia 200 įrankių vienam užklausimui – tačiau efektyvumui siekite 5–20
- Prieš vykdymą visada patikrinkite argumentus kliento pusėje
- Grąžinkite klaidas modeliui struktūrizuotu JSON formatu
- Pavadinimai turi būti unikalūs, naudoti snake_case ir būti aiškūs
- Išsamūs aprašymai drastiškai pagerina patikimumą
- Dinamiškai pasirinkite aktualius įrankius kiekvienam užklausimui
- Niekada nepasitikėkite argumentais be patikrinimo