KEPLIN Docs

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, list et dict. 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}, avec parameters en JSON Schema.
  • Le résultat est celui de ai.chat, avec en plus steps : 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.run lève ai.Error avec le code max_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 id utilisent des lettres, des chiffres, des tirets et des tirets bas, jusqu'à 64 caractères, sans répétition. Sans id, les requêtes sont numérotées à partir de 1.
  • Avec schema, chaque résultat est validé comme dans ai.json : ceux qui ne respectent pas le schéma arrivent avec ok à faux et la raison dans error.
  • OpenAI, Anthropic et Google via la Gemini API font des lots. Chez les autres fournisseurs, ai.batch.submit donne l'erreur not_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.