Limiti e migliori pratiche
In questa pagina
Vincoli tecnici del function calling
Prima di iniziare l’implementazione, devi comprendere i limiti del sistema. Il function calling di Grok è potente, ma opera entro vincoli specifici che devi padroneggiare per costruire applicazioni robuste.
Massimo 200 strumenti per richiesta
L’API di Grok accetta fino a 200 definizioni di strumenti in una singola richiesta. Questo limite è generoso: la maggior parte delle applicazioni ne utilizza solo da 5 a 20. Tuttavia, se costruisci un sistema scalabile (plugin, marketplace di strumenti), devi tenerne conto.
Ogni definizione di strumento occupa spazio nella finestra di contesto. Nello specifico:
- Uno strumento semplice (2-3 parametri) consuma circa 50-100 token
- Uno strumento complesso (10+ parametri, descrizioni dettagliate) può superare i 300 token
- 200 strumenti complessi = 60.000 token solo per le definizioni
Ecco perché devi essere strategico: dichiara solo gli strumenti rilevanti per la richiesta corrente.
Il modello non garantisce la validità degli argomenti
Grok fa del suo meglio per generare argomenti che corrispondano allo schema, ma non è infallibile. Il modello può:
- Generare un formato data errato
- Passare una
stringdove ci si aspetta uninteger - Omettere un campo obbligatorio in rari casi
- Allucinare valori enum inesistenti
Il tuo codice lato client deve sempre convalidare gli argomenti ricevuti prima di eseguire la funzione.
import json
def handle_tool_call(tool_call):
args = json.loads(tool_call.function.arguments)
# Validate before execution
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"))
Gestione degli errori
Quando una funzione fallisce, devi restituire l’errore al modello invece di bloccarti silenziosamente. Il modello può quindi:
- Riformulare la sua richiesta con parametri corretti
- Informare l’utente del problema
- Provare uno strumento alternativo
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"
})
Restituisci sempre JSON strutturato, anche in caso di errore. Il modello comprende i messaggi di errore e adatta la sua risposta di conseguenza.
Nomi unici ed espliciti
I nomi delle funzioni devono essere unici nell’elenco degli strumenti. Se due strumenti condividono lo stesso nome, il comportamento è indefinito: l’API potrebbe rifiutare la richiesta o ignorarne uno.
Adotta una convenzione di denominazione coerente:
✅ Migliori pratiche:
get_weather → recupero dati
search_products → ricerca
create_ticket → creazione
update_order_status → aggiornamento
delete_draft → eliminazione
❌ Da evitare:
fn1, fn2 → incomprensibili
doStuff → troppo vaghi
getWeatherData → camelCase (preferisci snake_case)
Descrizioni: il fattore di qualità numero 1
La qualità della descrizione determina direttamente l’affidabilità del function calling. Ecco una tabella comparativa:
| Descrizione debole | Descrizione efficace |
|---|---|
| "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." |
Ottimizzazione del numero di strumenti
Invece di dichiarare 200 strumenti per ogni richiesta, seleziona dinamicamente quelli che contano davvero. Il primo filtro è il contesto: se l’utente parla di meteo, caricare strumenti di fatturazione aggiunge solo rumore; un routing leggero a monte (per parole chiave o una prima chiamata di classificazione) è sufficiente per presentare solo la famiglia rilevante. Il secondo filtro è il ruolo: un agente di supporto non ha bisogno di strumenti amministrativi e rimuoverli è una questione di precisione tanto quanto di sicurezza. Il terzo è il passaggio: in un flusso di lavoro multi-step, ogni fase ha i suoi strumenti; caricarli man mano che si procede mantiene il modello focalizzato su ciò che deve fare ora.
Il vantaggio è duplice e immediato: meno token di input per richiesta (le definizioni degli strumenti hanno un costo per ogni chiamata) e una migliore accuratezza nella selezione: un modello che sceglie tra sei strumenti ben descritti raramente sbaglia, mentre lo stesso modello di fronte a duecento definizioni finisce per confondere varianti simili.
Sicurezza: non fidarti mai del modello
Il function calling è un potenziale vettore di iniezione. Un utente malintenzionato potrebbe formulare la sua richiesta per manipolare gli argomenti passati alle funzioni. Regole di sicurezza:
- Convalida tutti gli argomenti lato server
- Limita i permessi: una funzione di lettura non deve poter scrivere
- Registra le chiamate: traccia ogni chiamata di funzione per l’audit
- Sanifica gli input: esegui l’escape dei caratteri speciali prima delle query SQL/shell
Punti chiave
- Massimo 200 strumenti per richiesta, ma punta a 5-20 per efficienza
- Convalida sempre gli argomenti lato client prima dell’esecuzione
- Restituisci gli errori al modello in JSON strutturato
- I nomi devono essere unici, in snake_case ed espliciti
- Descrizioni dettagliate migliorano drasticamente l’affidabilità
- Seleziona dinamicamente gli strumenti rilevanti per ogni richiesta
- Non fidarti mai degli argomenti senza convalida