Outils et lots
Laisser le modèle utiliser des fonctions du script avec ai.run, et traiter de nombreuses requêtes en arrière-plan avec ai.batch.
Deux opérations pour un travail plus grand qu'une question : ai.run laisse
le modèle utiliser des fonctions du script pendant qu'il répond, et
ai.batch traite de nombreuses requêtes en arrière-plan.
Outils (ai.run)
Avec ai.run, le modèle peut demander des fonctions du script pendant sa
réponse : interroger une base de données, calculer une valeur ou appeler une
API. Le SDK exécute la fonction dans le script, renvoie le résultat au modèle
et recommence jusqu'à ce que le modèle donne la réponse 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"]}
- Un outil est une fonction Python. Son nom, sa docstring et les annotations de type de ses arguments sont ce que le modèle lit pour décider quand l'utiliser : décrivez donc bien la fonction dans la docstring.
- Les types qui deviennent du JSON Schema sont
str,int,float,bool,listetdict. Un argument avec une valeur par défaut est facultatif. - Pour contrôler le schéma des arguments, passez un dict au lieu de la
fonction :
{"name": "stock", "description": "...", "parameters": {...}, "function": stock}, avecparametersen JSON Schema. - Le résultat est celui de
ai.chat, avec en plussteps: la liste des outils exécutés, avec les arguments et le résultat de chacun. - Une exception dans un outil n'arrête pas la tâche : elle part vers le modèle sous forme de texte (« Erro: … »), et le modèle décide quoi faire.
max_steps(10 par défaut) est le nombre maximal de requêtes au modèle. Si le modèle continue à demander des outils au-delà,ai.runlèveai.Erroravec le codemax_steps.
Attention
C'est le modèle qui choisit les arguments. Un outil qui modifie des données (supprimer, envoyer un e-mail, enregistrer) s'exécute avec ce que le modèle décide : validez les arguments dans la fonction et ne donnez pas au modèle des outils qui ne peuvent pas s'exécuter sans supervision.
ai.run accepte les mêmes paramètres que ai.chat : system, messages,
model, max_tokens, temperature et files.
Lots (ai.batch)
Un lot traite de nombreuses requêtes de texte en arrière-plan. Le fournisseur a jusqu'à 24 heures pour répondre. Il convient au travail qui n'est pas urgent : résumer les demandes de support de la semaine, classer des milliers d'enregistrements ou traduire un catalogue.
Un lot se fait en deux temps. Un script soumet les requêtes et garde 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}
Plus tard, un autre script (par exemple, planifié toutes les heures) consulte l'état et lit les résultats :
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}
| Fonction | Ce qu'elle fait |
|---|---|
ai.batch.submit(pedidos, model=None, system=None, max_tokens=None, temperature=None, schema=None) |
Soumet le lot. Chaque requête est un texte, ou un dict avec id, prompt (ou messages) et, facultatif, system. Renvoie id, status et count. |
ai.batch.get(id) |
L'état (in_progress, ended, failed, cancelled ou expired) et les décomptes (total, succeeded, failed et processing). |
ai.batch.results(id) |
Les résultats d'un lot terminé : une liste avec id, ok, text, data (avec schema), error et usage. |
ai.batch.cancel(id) |
Annule le lot et renvoie l'état. |
- Un lot compte jusqu'à 10 000 requêtes. Les
idutilisent des lettres, des chiffres, des tirets et des tirets bas, jusqu'à 64 caractères, sans répétition. Sansid, les requêtes sont numérotées à partir de 1. - Avec
schema, chaque résultat est validé comme dansai.json: ceux qui ne respectent pas le schéma arrivent avecokà faux et la raison danserror. - OpenAI, Anthropic et Google via la Gemini API font des lots. Chez les autres
fournisseurs,
ai.batch.submitdonne l'erreurnot_supported. - L'id d'un lot ne sert que dans l'app qui l'a soumis.
Questions fréquentes
Un outil peut-il appeler un service externe ? Oui. Un outil est une
fonction Python comme une autre, et il peut utiliser http, db ou
workflow.
Combien de temps prend un lot ? Cela dépend du fournisseur et de sa
charge, et cela peut aller jusqu'à 24 heures. Un lot qui ne termine pas dans
ce délai passe à expired.
Puis-je utiliser des outils dans un lot ? Non. Un lot fait des requêtes de
texte et de JSON ; pour les outils, utilisez ai.run.