Werkzeuge und Batches
Das Modell mit ai.run Funktionen des Skripts nutzen lassen und mit ai.batch viele Anfragen im Hintergrund verarbeiten.
Zwei Operationen für Arbeit, die größer ist als eine Frage: ai.run lässt
das Modell beim Antworten Funktionen des Skripts nutzen, und ai.batch
verarbeitet viele Anfragen im Hintergrund.
Werkzeuge (ai.run)
Mit ai.run kann das Modell während der Antwort Funktionen des Skripts
anfordern: eine Datenbank abfragen, einen Wert berechnen oder eine API
aufrufen. Das SDK führt die Funktion im Skript aus, gibt dem Modell das
Ergebnis zurück und wiederholt das, bis das Modell die endgültige Antwort
gibt.
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"]}
- Ein Werkzeug ist eine Python-Funktion. Name, Docstring und die Typannotationen der Argumente sind das, was das Modell liest, um zu entscheiden, wann es sie nutzt; beschreiben Sie die Funktion also gut im Docstring.
- Die Typen, die zu JSON Schema werden, sind
str,int,float,bool,listunddict. Ein Argument mit Standardwert ist optional. - Um das Schema der Argumente selbst zu bestimmen, übergeben Sie statt der
Funktion ein Dict:
{"name": "stock", "description": "...", "parameters": {...}, "function": stock}, mitparametersals JSON Schema. - Das Ergebnis ist das von
ai.chat, zusätzlich mitsteps: der Liste der ausgeführten Werkzeuge, jeweils mit Argumenten und Ergebnis. - Eine Ausnahme in einem Werkzeug stoppt die Aufgabe nicht: Sie geht als Text an das Modell („Erro: …“), und das Modell entscheidet, was zu tun ist.
max_steps(standardmäßig 10) ist die maximale Anzahl Anfragen an das Modell. Fordert das Modell danach weiter Werkzeuge an, löstai.runai.Errormit dem Codemax_stepsaus.
Achtung
Das Modell wählt die Argumente. Ein Werkzeug, das Daten ändert (löschen, eine E-Mail senden, speichern), läuft mit dem, was das Modell entscheidet: Prüfen Sie die Argumente in der Funktion und geben Sie dem Modell keine Werkzeuge, die nicht unbeaufsichtigt laufen dürfen.
ai.run nimmt dieselben Parameter wie ai.chat: system, messages,
model, max_tokens, temperature und files.
Batches (ai.batch)
Ein Batch verarbeitet viele Textanfragen im Hintergrund. Der Anbieter hat bis zu 24 Stunden Zeit für die Antwort. Er eignet sich für Arbeit ohne Eile: die Supportanfragen der Woche zusammenfassen, Tausende Datensätze klassifizieren oder einen Katalog übersetzen.
Ein Batch läuft in zwei Schritten. Ein Skript reicht die Anfragen ein und behält die 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}
Später prüft ein anderes Skript (zum Beispiel stündlich geplant) den Status und liest die Ergebnisse:
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}
| Funktion | Was sie macht |
|---|---|
ai.batch.submit(pedidos, model=None, system=None, max_tokens=None, temperature=None, schema=None) |
Reicht den Batch ein. Jede Anfrage ist ein Text oder ein Dict mit id, prompt (oder messages) und optional system. Gibt id, status und count zurück. |
ai.batch.get(id) |
Den Status (in_progress, ended, failed, cancelled oder expired) und die Zählungen (total, succeeded, failed und processing). |
ai.batch.results(id) |
Die Ergebnisse eines fertigen Batches: eine Liste mit id, ok, text, data (mit schema), error und usage. |
ai.batch.cancel(id) |
Bricht den Batch ab und gibt den Status zurück. |
- Ein Batch hat bis zu 10 000 Anfragen. Die
id-Werte bestehen aus Buchstaben, Ziffern, Bindestrichen und Unterstrichen, höchstens 64 Zeichen, ohne Wiederholung. Ohneidwerden die Anfragen ab 1 nummeriert. - Mit
schemawird jedes Ergebnis wie beiai.jsongeprüft: Ergebnisse, die das Schema nicht erfüllen, kommen mitokgleich falsch und dem Grund inerror. - Batches bieten OpenAI, Anthropic und Google über die Gemini API. Bei den
anderen Anbietern gibt
ai.batch.submitden Fehlernot_supported. - Die ID eines Batches gilt nur in der App, die ihn eingereicht hat.
Häufige Fragen
Kann ein Werkzeug einen externen Dienst aufrufen? Ja. Ein Werkzeug ist
eine Python-Funktion wie jede andere und kann http, db oder workflow
nutzen.
Wie lange dauert ein Batch? Das hängt vom Anbieter und seiner Auslastung
ab und kann bis zu 24 Stunden dauern. Ein Batch, der in dieser Zeit nicht
fertig wird, endet als expired.
Kann ich in einem Batch Werkzeuge nutzen? Nein. Ein Batch stellt Text- und
JSON-Anfragen; für Werkzeuge nutzen Sie ai.run.