Tools en batches
Het model functies van het script laten gebruiken met ai.run, en veel verzoeken op de achtergrond verwerken met ai.batch.
Twee bewerkingen voor werk dat groter is dan één vraag: met ai.run gebruikt
het model functies van het script terwijl het antwoordt, en ai.batch
verwerkt veel verzoeken op de achtergrond.
Tools (ai.run)
Met ai.run kan het model tijdens het antwoord om functies van het script
vragen: een database raadplegen, een waarde berekenen of een API aanroepen.
De SDK voert de functie uit in het script, geeft het resultaat terug aan het
model en herhaalt dat tot het model het definitieve antwoord geeft.
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"]}
- Een tool is een Python-functie. De naam, de docstring en de typeannotaties van de argumenten zijn wat het model leest om te beslissen wanneer het de functie gebruikt; beschrijf de functie dus goed in de docstring.
- De typen die JSON Schema worden, zijn
str,int,float,bool,listendict. Een argument met een standaardwaarde is optioneel. - Om het schema van de argumenten zelf te bepalen, geeft u een dict in plaats
van de functie:
{"name": "stock", "description": "...", "parameters": {...}, "function": stock}, metparametersin JSON Schema. - Het resultaat is dat van
ai.chat, met daarbijsteps: de lijst van de tools die zijn uitgevoerd, elk met de argumenten en het resultaat. - Een uitzondering in een tool stopt de taak niet: die gaat als tekst naar het model („Erro: …”), en het model beslist wat het doet.
max_steps(standaard 10) is het maximum aantal verzoeken aan het model. Als het model daarna nog om tools vraagt, gooitai.runai.Errormet de codemax_steps.
Let op
Het model kiest de argumenten. Een tool die gegevens wijzigt (verwijderen, een e-mail versturen, opslaan) draait met wat het model beslist: controleer de argumenten in de functie en geef het model geen tools die niet zonder toezicht mogen draaien.
ai.run accepteert dezelfde parameters als ai.chat: system, messages,
model, max_tokens, temperature en files.
Batches (ai.batch)
Een batch verwerkt veel tekstverzoeken op de achtergrond. De provider heeft tot 24 uur om te antwoorden. Een batch is bedoeld voor werk zonder haast: de supportverzoeken van de week samenvatten, duizenden records classificeren of een catalogus vertalen.
Een batch gaat in twee stappen. Een script dient de verzoeken in en bewaart de 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}
Later controleert een ander script (bijvoorbeeld elk uur gepland) de status en leest de resultaten:
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}
| Functie | Wat die doet |
|---|---|
ai.batch.submit(pedidos, model=None, system=None, max_tokens=None, temperature=None, schema=None) |
Dient de batch in. Elk verzoek is een tekst, of een dict met id, prompt (of messages) en, optioneel, system. Geeft id, status en count terug. |
ai.batch.get(id) |
De status (in_progress, ended, failed, cancelled of expired) en de tellingen (total, succeeded, failed en processing). |
ai.batch.results(id) |
De resultaten van een afgeronde batch: een lijst met id, ok, text, data (met schema), error en usage. |
ai.batch.cancel(id) |
Annuleert de batch en geeft de status terug. |
- Een batch heeft tot 10 000 verzoeken. De
id's bestaan uit letters, cijfers, koppeltekens en underscores, tot 64 tekens, zonder herhaling. Zonderidworden de verzoeken genummerd vanaf 1. - Met
schemawordt elk resultaat gevalideerd zoals bijai.json: resultaten die niet aan het schema voldoen, komen metokonwaar en de reden inerror. - Batches doen OpenAI, Anthropic en Google via de Gemini API. Bij de andere
providers geeft
ai.batch.submitde foutnot_supported. - De id van een batch werkt alleen in de app die hem heeft ingediend.
Veelgestelde vragen
Kan een tool een externe dienst aanroepen? Ja. Een tool is een
Python-functie zoals elke andere en kan http, db of workflow gebruiken.
Hoe lang duurt een batch? Dat hangt af van de provider en de drukte daar,
en kan tot 24 uur duren. Een batch die niet binnen die tijd klaar is, eindigt
als expired.
Kan ik tools gebruiken in een batch? Nee. Een batch doet tekst- en
JSON-verzoeken; gebruik voor tools ai.run.