Robežas un labākā prakse
Šajā lapā
Funkciju izsaukšanas tehniskie ierobežojumi
Pirms sāc ieviešanu, tev jāsaprot sistēmas robežas. Grok funkciju izsaukšana ir jaudīga, taču tā darbojas noteiktu ierobežojumu ietvaros, kas tev jāpārzina, lai veidotu stabilas lietotnes.
Maksimums 200 rīki vienā pieprasījumā
Grok API vienā pieprasījumā pieņem līdz 200 rīku definīcijām. Šis limits ir dāsns — lielākā daļa lietotņu izmanto tikai 5 līdz 20. Taču, ja veido mērogojamu sistēmu (spraudņi, rīku tirgus), tev tas jāņem vērā.
Katra rīka definīcija aizņem vietu konteksta logā. Konkrēti:
- Vienkāršs rīks (2–3 parametri) patērē aptuveni 50–100 tokenus
- Sarežģīts rīks (10+ parametri, detalizēti apraksti) var pārsniegt 300 tokenus
- 200 sarežģīti rīki = 60 000 tokeni tikai definīcijām
Tāpēc tev jābūt stratēģiskam: deklarē tikai tos rīkus, kas ir būtiski konkrētajam pieprasījumam.
Modelis negarantē argumentu derīgumu
Grok dara visu iespējamo, lai ģenerētu argumentus, kas atbilst shēmai, taču tas nav nekļūdīgs. Modelis var:
- Ģenerēt nepareizu datuma formātu
- Nodot
string, kur tiek gaidītsinteger - Retos gadījumos izlaist obligātu lauku
- Izdomāt (halucinēt) enum vērtības, kas neeksistē
Tavam klienta puses kodam vienmēr jāvalidē saņemtie argumenti pirms funkcijas izpildes.
import json
def handle_tool_call(tool_call):
args = json.loads(tool_call.function.arguments)
# Validē pirms izpildes
if "city" not in args:
return {"error": "The city parameter is required"}
if not isinstance(args["city"], str):
return {"error": "city must be a string"}
return get_weather(args["city"], args.get("unit", "celsius"))
Kļūdu apstrāde
Ja funkcija neizdodas, tev kļūda jāatgriež modelim, nevis klusām jāļauj sistēmai sabrukt. Tad modelis var:
- Pārformulēt savu pieprasījumu ar labotiem parametriem
- Informēt lietotāju par problēmu
- Izmēģināt alternatīvu rīku
try:
result = search_database(query=args["query"])
return json.dumps(result)
except ConnectionError:
return json.dumps({
"error": "Database unavailable",
"suggestion": "Retry in a few seconds"
})
Vienmēr atgriez strukturētu JSON, pat kļūdas gadījumā. Modelis saprot kļūdu ziņojumus un attiecīgi pielāgo savu atbildi.
Unikāli un skaidri nosaukumi
Funkciju nosaukumiem rīku sarakstā jābūt unikāliem. Ja diviem rīkiem ir vienāds nosaukums, uzvedība ir neparedzama — API var noraidīt pieprasījumu vai ignorēt vienu no tiem.
Ievies konsekventu nosaukumu konvenciju:
✅ Labākā prakse:
get_weather → datu iegūšana
search_products → meklēšana
create_ticket → izveide
update_order_status → atjaunināšana
delete_draft → dzēšana
❌ Izvairies:
fn1, fn2 → nesaprotami
doStuff → pārāk vispārīgi
getWeatherData → camelCase (dod priekšroku snake_case)
Apraksti: galvenais kvalitātes faktors
Aprakstu kvalitāte tieši nosaka funkciju izsaukšanas uzticamību. Lūk, salīdzinošā tabula:
| Vājš apraksts | Efektīvs apraksts |
|---|---|
| "Search" | "Search for products by name, category, or price range in the e-commerce catalog" |
| "Send message" | "Send an email to a recipient. Requires a subject and message body. Does not support attachments." |
| "Calculate" | "Calculate the total price including tax from a pre-tax price and a VAT rate. Returns the amount in euros with 2 decimal places." |
Rīku skaita optimizēšana
Tā vietā, lai katrā pieprasījumā deklarētu 200 rīkus, dinamiski atlasi tikai tos, kas patiešām ir svarīgi. Pirmais filtrs ir konteksts: ja lietotājs runā par laika apstākļiem, rēķinu rīku ielāde tikai rada troksni — pietiek ar vieglu maršrutēšanu augšupplūsmā (pēc atslēgvārdiem vai sākotnēja klasifikācijas izsaukuma), lai piedāvātu tikai attiecīgo saimi. Otrais filtrs ir loma: atbalsta aģentam nav vajadzīgi administratora rīki, un to noņemšana ir gan precizitātes, gan drošības jautājums. Trešais ir solis: daudzsolu darbplūsmā katrai fāzei ir savi rīki — to ielāde, virzoties uz priekšu, notur modeli fokusētu uz to, kas tam jādara tieši tagad.
Ieguvums ir divkāršs un tūlītējs: mazāk ievades tokeni katrā pieprasījumā (rīku definīcijas tev izmaksā katrā izsaukumā) un precīzāka atlase — modelis, izvēloties starp sešiem labi aprakstītiem rīkiem, kļūdās reti, savukārt tas pats modelis, saskaroties ar divsimt definīcijām, beigās sajauc līdzīgus variantus.
Drošība: nekad neuzticies modelim
Funkciju izsaukšana ir potenciāls injicēšanas vektors. Ļaunprātīgs lietotājs varētu formulēt savu pieprasījumu tā, lai manipulētu ar funkcijām nodotajiem argumentiem. Drošības noteikumi:
- Validē visus argumentus servera pusē
- Ierobežo atļaujas: lasīšanas funkcijai nevajadzētu būt iespējai rakstīt
- Reģistrē izsaukumus: izseko katru funkcijas izsaukumu auditam
- Attīri ievades datus: atbrīvojas no speciālajām rakstzīmēm pirms SQL/shell vaicājumiem
Galvenās atziņas
- Maksimums 200 rīki vienā pieprasījumā — taču efektivitātes labad tiecies uz 5–20
- Vienmēr validē argumentus klienta pusē pirms izpildes
- Atgriez kļūdas modelim strukturētā JSON formātā
- Nosaukumiem jābūt unikāliem, snake_case formātā un skaidriem
- Detalizēti apraksti krasi uzlabo uzticamību
- Dinamiski atlasi attiecīgos rīkus katram pieprasījumam
- Nekad neuzticies argumentiem bez validācijas