KEPLIN Docs

Strumenti e lotti

Lasciare che il modello usi funzioni dello script con ai.run, ed elaborare molte richieste in background con ai.batch.

Due operazioni per un lavoro più grande di una domanda: ai.run lascia che il modello usi funzioni dello script mentre risponde, e ai.batch elabora molte richieste in background.

Strumenti (ai.run)

Con ai.run, il modello può chiedere funzioni dello script durante la risposta: interrogare un database, calcolare un valore o chiamare un'API. L'SDK esegue la funzione nello script, restituisce il risultato al modello e ripete finché il modello non dà la risposta 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"]}
  • Uno strumento è una funzione Python. Il nome, la docstring e le annotazioni di tipo degli argomenti sono ciò che il modello legge per decidere quando usarla, quindi descrivi bene la funzione nella docstring.
  • I tipi che diventano JSON Schema sono str, int, float, bool, list e dict. Un argomento con valore predefinito è facoltativo.
  • Per controllare lo schema degli argomenti, passa un dict al posto della funzione: {"name": "stock", "description": "...", "parameters": {...}, "function": stock}, con parameters in JSON Schema.
  • Il risultato è quello di ai.chat, con in più steps: l'elenco degli strumenti eseguiti, con gli argomenti e il risultato di ciascuno.
  • Un'eccezione in uno strumento non ferma il compito: va al modello come testo («Erro: …»), e il modello decide cosa fare.
  • max_steps (10 per impostazione predefinita) è il numero massimo di richieste al modello. Se il modello continua a chiedere strumenti dopo, ai.run solleva ai.Error con il codice max_steps.

Attenzione

È il modello a scegliere gli argomenti. Uno strumento che modifica dati (eliminare, inviare un'email, salvare) viene eseguito con ciò che il modello decide: valida gli argomenti nella funzione e non dare al modello strumenti che non possono essere eseguiti senza supervisione.

ai.run accetta gli stessi parametri di ai.chat: system, messages, model, max_tokens, temperature e files.

Lotti (ai.batch)

Un lotto elabora molte richieste di testo in background. Il fornitore ha fino a 24 ore per rispondere. Serve per il lavoro senza fretta: riassumere le richieste di supporto della settimana, classificare migliaia di record o tradurre un catalogo.

Un lotto si fa in due tempi. Uno script invia le richieste e conserva 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}

Più tardi, un altro script (per esempio, pianificato ogni ora) controlla lo stato e legge i risultati:

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}
Funzione Cosa fa
ai.batch.submit(pedidos, model=None, system=None, max_tokens=None, temperature=None, schema=None) Invia il lotto. Ogni richiesta è un testo, o un dict con id, prompt (o messages) e, facoltativo, system. Restituisce id, status e count.
ai.batch.get(id) Lo stato (in_progress, ended, failed, cancelled o expired) e i conteggi (total, succeeded, failed e processing).
ai.batch.results(id) I risultati di un lotto finito: un elenco con id, ok, text, data (con schema), error e usage.
ai.batch.cancel(id) Annulla il lotto e restituisce lo stato.
  • Un lotto ha fino a 10 000 richieste. Gli id usano lettere, cifre, trattini e trattini bassi, fino a 64 caratteri, senza ripetizioni. Senza id, le richieste sono numerate da 1.
  • Con schema, ogni risultato è validato come in ai.json: quelli che non rispettano lo schema arrivano con ok falso e il motivo in error.
  • Fanno lotti OpenAI, Anthropic e Google tramite la Gemini API. Con gli altri fornitori, ai.batch.submit dà l'errore not_supported.
  • L'id di un lotto vale solo nell'app che lo ha inviato.

Domande frequenti

Uno strumento può chiamare un servizio esterno? Sì. Uno strumento è una funzione Python come un'altra, e può usare http, db o workflow.

Quanto tempo richiede un lotto? Dipende dal fornitore e dal suo carico, e può arrivare a 24 ore. Un lotto che non finisce in quel tempo diventa expired.

Posso usare strumenti in un lotto? No. Un lotto fa richieste di testo e di JSON; per gli strumenti, usa ai.run.