KEPLIN Docs

Verktyg och batcher

Låt modellen använda skriptets funktioner med ai.run, och bearbeta många förfrågningar i bakgrunden med ai.batch.

Två åtgärder för arbete som är större än en fråga: med ai.run använder modellen skriptets funktioner medan den svarar, och ai.batch bearbetar många förfrågningar i bakgrunden.

Verktyg (ai.run)

Med ai.run kan modellen be om skriptets funktioner under svaret: fråga en databas, räkna ut ett värde eller anropa ett API. SDK:n kör funktionen i skriptet, ger tillbaka resultatet till modellen och upprepar tills modellen ger det slutliga svaret.

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"]}
  • Ett verktyg är en Python-funktion. Namnet, docstringen och argumentens typannoteringar är det som modellen läser för att avgöra när den ska använda funktionen, så beskriv funktionen väl i docstringen.
  • Typerna som blir JSON Schema är str, int, float, bool, list och dict. Ett argument med standardvärde är valfritt.
  • För att styra argumentens schema skickar du en dict i stället för funktionen: {"name": "stock", "description": "...", "parameters": {...}, "function": stock}, med parameters i JSON Schema.
  • Resultatet är det från ai.chat, plus steps: listan över verktygen som kördes, med argumenten och resultatet för vart och ett.
  • Ett undantag i ett verktyg stoppar inte uppgiften: det går till modellen som text (”Erro: …”), och modellen bestämmer vad den gör.
  • max_steps (10 som standard) är det högsta antalet förfrågningar till modellen. Om modellen fortsätter att be om verktyg efter det kastar ai.run ai.Error med koden max_steps.

Varning

Det är modellen som väljer argumenten. Ett verktyg som ändrar data (radera, skicka ett mejl, spara) körs med det som modellen bestämmer: validera argumenten i funktionen och ge inte modellen verktyg som inte kan köras utan tillsyn.

ai.run tar samma parametrar som ai.chat: system, messages, model, max_tokens, temperature och files.

Batcher (ai.batch)

En batch bearbetar många textförfrågningar i bakgrunden. Leverantören har upp till 24 timmar på sig att svara. Den passar arbete som inte är bråttom: sammanfatta veckans supportärenden, klassificera tusentals poster eller översätta en katalog.

En batch görs i två steg. Ett skript skickar in förfrågningarna och sparar id:t:

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}

Senare kontrollerar ett annat skript (till exempel schemalagt varje timme) statusen och läser 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}
Funktion Vad den gör
ai.batch.submit(pedidos, model=None, system=None, max_tokens=None, temperature=None, schema=None) Skickar in batchen. Varje förfrågan är en text, eller en dict med id, prompt (eller messages) och, valfritt, system. Returnerar id, status och count.
ai.batch.get(id) Statusen (in_progress, ended, failed, cancelled eller expired) och antalen (total, succeeded, failed och processing).
ai.batch.results(id) Resultaten för en färdig batch: en lista med id, ok, text, data (med schema), error och usage.
ai.batch.cancel(id) Avbryter batchen och returnerar statusen.
  • En batch har upp till 10 000 förfrågningar. Värdena i id består av bokstäver, siffror, bindestreck och understreck, högst 64 tecken, utan upprepning. Utan id numreras förfrågningarna från 1.
  • Med schema valideras varje resultat som i ai.json: de som inte följer schemat kommer med ok falskt och orsaken i error.
  • Batcher görs av OpenAI, Anthropic och Google via Gemini API. Hos andra leverantörer ger ai.batch.submit felet not_supported.
  • En batchs id fungerar bara i appen som skickade in den.

Vanliga frågor

Kan ett verktyg anropa en extern tjänst? Ja. Ett verktyg är en Python-funktion som vilken annan som helst, och kan använda http, db eller workflow.

Hur lång tid tar en batch? Det beror på leverantören och dess belastning, och kan ta upp till 24 timmar. En batch som inte blir klar inom den tiden får statusen expired.

Kan jag använda verktyg i en batch? Nej. En batch gör text- och JSON-förfrågningar; för verktyg använder du ai.run.