KEPLIN Docs

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, list en dict. 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}, met parameters in JSON Schema.
  • Het resultaat is dat van ai.chat, met daarbij steps: 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, gooit ai.run ai.Error met de code max_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. Zonder id worden de verzoeken genummerd vanaf 1.
  • Met schema wordt elk resultaat gevalideerd zoals bij ai.json: resultaten die niet aan het schema voldoen, komen met ok onwaar en de reden in error.
  • Batches doen OpenAI, Anthropic en Google via de Gemini API. Bij de andere providers geeft ai.batch.submit de fout not_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.