KEPLIN Docs

Verktøy og batcher

La modellen bruke funksjoner i skriptet med ai.run, og behandle mange forespørsler i bakgrunnen med ai.batch.

To operasjoner for arbeid som er større enn ett spørsmål: med ai.run bruker modellen funksjoner i skriptet mens den svarer, og ai.batch behandler mange forespørsler i bakgrunnen.

Verktøy (ai.run)

Med ai.run kan modellen be om funksjoner i skriptet underveis i svaret: slå opp i en database, regne ut en verdi eller kalle et API. SDK-en kjører funksjonen i skriptet, gir resultatet tilbake til modellen og gjentar til modellen gir det endelige 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"]}
  • Et verktøy er en Python-funksjon. Navnet, docstringen og typeannotasjonene på argumentene er det modellen leser for å avgjøre når den skal bruke funksjonen, så beskriv funksjonen godt i docstringen.
  • Typene som blir JSON Schema, er str, int, float, bool, list og dict. Et argument med standardverdi er valgfritt.
  • For å styre skjemaet for argumentene sender du en dict i stedet for funksjonen: {"name": "stock", "description": "...", "parameters": {...}, "function": stock}, med parameters i JSON Schema.
  • Resultatet er det fra ai.chat, pluss steps: listen over verktøyene som kjørte, med argumentene og resultatet for hvert av dem.
  • Et unntak i et verktøy stopper ikke oppgaven: det går til modellen som tekst («Erro: …»), og modellen bestemmer hva den gjør.
  • max_steps (10 som standard) er det høyeste antallet forespørsler til modellen. Hvis modellen fortsetter å be om verktøy etter det, kaster ai.run ai.Error med koden max_steps.

Advarsel

Det er modellen som velger argumentene. Et verktøy som endrer data (slette, sende en e-post, lagre) kjører med det modellen bestemmer: valider argumentene inne i funksjonen, og ikke gi modellen verktøy som ikke kan kjøre uten tilsyn.

ai.run tar de samme parameterne som ai.chat: system, messages, model, max_tokens, temperature og files.

Batcher (ai.batch)

En batch behandler mange tekstforespørsler i bakgrunnen. Leverandøren har opptil 24 timer på seg til å svare. Den passer for arbeid som ikke haster: oppsummere ukens supporthenvendelser, klassifisere tusenvis av poster eller oversette en katalog.

En batch gjøres i to steg. Ett skript sender inn forespørslene og tar vare på ID-en:

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}

Senere sjekker et annet skript (for eksempel planlagt hver time) statusen og leser resultatene:

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}
Funksjon Hva den gjør
ai.batch.submit(pedidos, model=None, system=None, max_tokens=None, temperature=None, schema=None) Sender inn batchen. Hver forespørsel er en tekst, eller en dict med id, prompt (eller messages) og, valgfritt, system. Returnerer id, status og count.
ai.batch.get(id) Statusen (in_progress, ended, failed, cancelled eller expired) og tellingene (total, succeeded, failed og processing).
ai.batch.results(id) Resultatene for en ferdig batch: en liste med id, ok, text, data (med schema), error og usage.
ai.batch.cancel(id) Avbryter batchen og returnerer statusen.
  • En batch har opptil 10 000 forespørsler. Verdiene i id består av bokstaver, sifre, bindestrek og understrek, opptil 64 tegn, uten gjentakelse. Uten id nummereres forespørslene fra 1.
  • Med schema valideres hvert resultat som i ai.json: de som ikke følger skjemaet, kommer med ok usann og årsaken i error.
  • Batcher gjøres av OpenAI, Anthropic og Google via Gemini API. Hos andre leverandører gir ai.batch.submit feilen not_supported.
  • ID-en til en batch virker bare i appen som sendte den inn.

Vanlige spørsmål

Kan et verktøy kalle en ekstern tjeneste? Ja. Et verktøy er en Python-funksjon som alle andre, og kan bruke http, db eller workflow.

Hvor lang tid tar en batch? Det avhenger av leverandøren og belastningen der, og kan ta opptil 24 timer. En batch som ikke blir ferdig innen den tiden, får statusen expired.

Kan jeg bruke verktøy i en batch? Nei. En batch gjør tekst- og JSON-forespørsler; for verktøy bruker du ai.run.