Strumenti e lotti
Lasciare che il modello usi funzioni dello script con ai.run, ed elaborare molte richieste in background con ai.batch.
Due operazioni per un lavoro più grande di una domanda: ai.run lascia che
il modello usi funzioni dello script mentre risponde, e ai.batch elabora
molte richieste in background.
Strumenti (ai.run)
Con ai.run, il modello può chiedere funzioni dello script durante la
risposta: interrogare un database, calcolare un valore o chiamare un'API. L'SDK
esegue la funzione nello script, restituisce il risultato al modello e ripete
finché il modello non dà la risposta finale.
from api_manager import ai, db
def stock(produto: str) -> int:
"""Unidades em armazém de um produto, pelo nome."""
linha = db("Dados CRM").query_one("select quantidade from stock where nome = ?", [produto])
return linha["quantidade"] if linha else 0
def preco(produto: str) -> float:
"""Preço unitário de um produto, em euros."""
return db("Dados CRM").query_one("select preco from produtos where nome = ?", [produto])["preco"]
def main(input):
r = ai.run(input["args"]["pergunta"], tools=[stock, preco])
return {"resposta": r["text"], "passos": r["steps"]}
- Uno strumento è una funzione Python. Il nome, la docstring e le annotazioni di tipo degli argomenti sono ciò che il modello legge per decidere quando usarla, quindi descrivi bene la funzione nella docstring.
- I tipi che diventano JSON Schema sono
str,int,float,bool,listedict. Un argomento con valore predefinito è facoltativo. - Per controllare lo schema degli argomenti, passa un dict al posto della
funzione:
{"name": "stock", "description": "...", "parameters": {...}, "function": stock}, conparametersin JSON Schema. - Il risultato è quello di
ai.chat, con in piùsteps: l'elenco degli strumenti eseguiti, con gli argomenti e il risultato di ciascuno. - Un'eccezione in uno strumento non ferma il compito: va al modello come testo («Erro: …»), e il modello decide cosa fare.
max_steps(10 per impostazione predefinita) è il numero massimo di richieste al modello. Se il modello continua a chiedere strumenti dopo,ai.runsollevaai.Errorcon il codicemax_steps.
Attenzione
È il modello a scegliere gli argomenti. Uno strumento che modifica dati (eliminare, inviare un'email, salvare) viene eseguito con ciò che il modello decide: valida gli argomenti nella funzione e non dare al modello strumenti che non possono essere eseguiti senza supervisione.
ai.run accetta gli stessi parametri di ai.chat: system, messages,
model, max_tokens, temperature e files.
Lotti (ai.batch)
Un lotto elabora molte richieste di testo in background. Il fornitore ha fino a 24 ore per rispondere. Serve per il lavoro senza fretta: riassumere le richieste di supporto della settimana, classificare migliaia di record o tradurre un catalogo.
Un lotto si fa in due tempi. Uno script invia le richieste e conserva l'id:
from api_manager import ai, db
def main(input):
crm = db("Dados CRM")
pedidos = crm.query("select id, texto from pedidos where resumo is null")
lote = ai.batch.submit(
[{"id": str(p["id"]), "prompt": "Resume numa frase: " + p["texto"]} for p in pedidos],
model="texto",
)
crm.query("insert into lotes (id, estado) values (?, 'em curso')", [lote["id"]])
return lote # {"id": "lote-...", "status": "in_progress", "count": 120}
Più tardi, un altro script (per esempio, pianificato ogni ora) controlla lo stato e legge i risultati:
from api_manager import ai, db
def main(input):
crm = db("Dados CRM")
for linha in crm.query("select id from lotes where estado = 'em curso'"):
estado = ai.batch.get(linha["id"])
if estado["status"] == "in_progress":
continue
if estado["status"] == "ended":
for r in ai.batch.results(linha["id"]):
if r["ok"]:
crm.query("update pedidos set resumo = ? where id = ?", [r["text"], int(r["id"])])
crm.query("update lotes set estado = ? where id = ?", [estado["status"], linha["id"]])
return {"ok": True}
| Funzione | Cosa fa |
|---|---|
ai.batch.submit(pedidos, model=None, system=None, max_tokens=None, temperature=None, schema=None) |
Invia il lotto. Ogni richiesta è un testo, o un dict con id, prompt (o messages) e, facoltativo, system. Restituisce id, status e count. |
ai.batch.get(id) |
Lo stato (in_progress, ended, failed, cancelled o expired) e i conteggi (total, succeeded, failed e processing). |
ai.batch.results(id) |
I risultati di un lotto finito: un elenco con id, ok, text, data (con schema), error e usage. |
ai.batch.cancel(id) |
Annulla il lotto e restituisce lo stato. |
- Un lotto ha fino a 10 000 richieste. Gli
idusano lettere, cifre, trattini e trattini bassi, fino a 64 caratteri, senza ripetizioni. Senzaid, le richieste sono numerate da 1. - Con
schema, ogni risultato è validato come inai.json: quelli che non rispettano lo schema arrivano conokfalso e il motivo inerror. - Fanno lotti OpenAI, Anthropic e Google tramite la Gemini API. Con gli altri
fornitori,
ai.batch.submitdà l'errorenot_supported. - L'id di un lotto vale solo nell'app che lo ha inviato.
Domande frequenti
Uno strumento può chiamare un servizio esterno? Sì. Uno strumento è una
funzione Python come un'altra, e può usare http, db o workflow.
Quanto tempo richiede un lotto? Dipende dal fornitore e dal suo carico, e
può arrivare a 24 ore. Un lotto che non finisce in quel tempo diventa
expired.
Posso usare strumenti in un lotto? No. Un lotto fa richieste di testo e di
JSON; per gli strumenti, usa ai.run.