Rajoitukset ja parhaat käytännöt
Tällä sivulla
Funktion kutsujen tekniset rajoitukset
Ennen kuin aloitat toteutuksen, sinun on ymmärrettävä järjestelmän rajat. Grokin funktion kutsut ovat tehokkaita, mutta ne toimivat tiettyjen rajoitusten puitteissa, jotka sinun on hallittava rakentaaksesi vakaita sovelluksia.
Enintään 200 työkalua pyyntöä kohden
Grok API hyväksyy enintään 200 työkalumääritystä yhdessä pyynnössä. Tämä raja on antelias – useimmat sovellukset käyttävät vain 5–20 työkalua. Mutta jos rakennat skaalautuvaa järjestelmää (laajennukset, työkalumarkkinapaikka), sinun on otettava tämä huomioon.
Jokainen työkalumääritys vie tilaa konteksti-ikkunasta. Tarkemmin sanottuna:
- Yksinkertainen työkalu (2–3 parametria) kuluttaa noin 50–100 tokenia
- Monimutkainen työkalu (yli 10 parametria, yksityiskohtaiset kuvaukset) voi ylittää 300 tokenia
- 200 monimutkaista työkalua = pelkät määritykset vievät 60 000 tokenia
Siksi sinun on oltava strateginen: määritä vain ne työkalut, jotka ovat merkityksellisiä nykyiselle pyynnölle.
Malli ei takaa argumenttien kelvollisuutta
Grok tekee parhaansa tuottaakseen skeeman mukaisia argumentteja, mutta se ei ole erehtymätön. Malli voi:
- Tuottaa väärän päivämäärämuodon
- Välittää
string-arvon, jossa odotetaaninteger-arvoa - Jättää vaaditun kentän pois harvinaisissa tapauksissa
- Hallusinoida olemattomia enum-arvoja
Koodisi asiakaspuolella täytyy aina validoida vastaanotetut argumentit ennen funktion suorittamista.
import json
def handle_tool_call(tool_call):
args = json.loads(tool_call.function.arguments)
# Validoi ennen suorittamista
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"))
Virheenkäsittely
Kun funktio epäonnistuu, sinun on palautettava virhe mallille sen sijaan, että sovellus kaatuisi hiljaa. Tällöin malli voi:
- Muotoilla pyyntönsä uudelleen korjatuilla parametreilla
- Ilmoittaa käyttäjälle ongelmasta
- Yrittää vaihtoehtoista työkalua
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"
})
Palauta aina jäsennelty JSON, myös virhetilanteissa. Malli ymmärtää virheilmoitukset ja mukauttaa vastauksensa niiden mukaan.
Yksilölliset ja selkeät nimet
Funktioiden nimien on oltava yksilöllisiä työkalulistalla. Jos kahdella työkalulla on sama nimi, käyttäytyminen on määrittelemätöntä – API voi hylätä pyynnön tai ignoroida toisen niistä.
Ota käyttöön johdonmukainen nimeämiskäytäntö:
✅ Parhaat käytännöt:
get_weather → datan haku
search_products → haku
create_ticket → luominen
update_order_status → päivitys
delete_draft → poistaminen
❌ Vältä:
fn1, fn2 → käsittämätön
doStuff → liian epämääräinen
getWeatherData → camelCase (suosi snake_casea)
Kuvaukset: laadun tärkein tekijä
Kuvausten laatu määrittää suoraan funktion kutsujen luotettavuuden. Tässä vertailutaulukko:
| Heikko kuvaus | Tehokas kuvaus |
|---|---|
| "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." |
Työkalujen määrän optimointi
Sen sijaan, että määrittäisit 200 työkalua jokaiseen pyyntöön, valitse dynaamisesti ne, jotka todella ovat merkityksellisiä. Ensimmäinen suodatin on konteksti: jos käyttäjä puhuu säästä, laskutustyökalujen lataaminen lisää vain kohinaa – kevyt reititys ylävirrassa (avainsanojen tai ensimmäisen luokittelukutsun perusteella) riittää esittämään vain asiaankuuluvan ryhmän. Toinen suodatin on rooli: tukiasiakaspalvelijalla ei ole tarvetta ylläpitotyökaluille, ja niiden poistaminen on yhtä paljon tarkkuus- kuin turvallisuuskysymys. Kolmas on vaihe: monivaiheisessa työnkulussa jokaisella vaiheella on omat työkalunsa – niiden lataaminen edetessä pitää mallin keskittyneenä siihen, mitä sen tulee tehdä juuri nyt.
Hyöty on kaksinkertainen ja välitön: vähemmän syöttötokeneita pyyntöä kohden (työkalumääritykset maksavat jokaisessa kutsussa) ja parempi valintatarkkuus – malli, joka valitsee kuuden hyvin kuvatun työkalun joukosta, tekee harvoin virheitä, kun taas sama malli kahdensadan määrityksen edessä päätyy sekoittamaan toisiaan muistuttavia variaatioita.
Turvallisuus: älä luota malliin koskaan
Funktion kutsut ovat potentiaalinen injektiovektori. Pahantahtoinen käyttäjä voi muotoilla pyyntönsä manipuloidakseen funktioille välitettäviä argumentteja. Turvallisuussäännöt:
- Validoi kaikki argumentit palvelinpuolella
- Rajoita oikeuksia: lukufunktion ei pitäisi pystyä kirjoittamaan
- Lokitoi kutsut: jäljitä jokainen funktion kutsu tarkastusta varten
- Puhdista syötteet: escape-erikoismerkit ennen SQL-/shell-kyselyitä
Keskeiset asiat
- Enintään 200 työkalua pyyntöä kohden – mutta tavoittele tehokkuuden vuoksi 5–20:ttä
- Validoi argumentit aina asiakaspuolella ennen suorittamista
- Palauta virheet mallille jäsennellyn JSON-muodossa
- Nimien on oltava yksilöllisiä, snake_case-muodossa ja selkeitä
- Yksityiskohtaiset kuvaukset parantavat luotettavuutta huomattavasti
- Valitse dynaamisesti merkitykselliset työkalut jokaiseen pyyntöön
- Älä luota argumentteihin ilman validointia