KEPLIN Docs

Ferramentas e lotes

Deixar o modelo usar funções do script com ai.run, e processar muitos pedidos em segundo plano com ai.batch.

Duas operações para trabalho maior do que uma pergunta: ai.run deixa o modelo usar funções do script enquanto responde, e ai.batch processa muitos pedidos em segundo plano.

Ferramentas (ai.run)

Com ai.run, o modelo pode pedir funções do script durante a resposta: consultar uma base de dados, calcular um valor ou chamar uma API. O SDK corre a função no script, devolve o resultado ao modelo e repete até o modelo dar a resposta final.

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"]}
  • Uma ferramenta é uma função Python. O nome, a docstring e as anotações de tipo dos argumentos são o que o modelo lê para decidir quando a usar, por isso descreve bem a função na docstring.
  • Os tipos que passam a JSON Schema são str, int, float, bool, list e dict. Um argumento com valor por omissão é opcional.
  • Para controlar o esquema dos argumentos, passa um dict em vez da função: {"name": "stock", "description": "...", "parameters": {...}, "function": stock}, com parameters em JSON Schema.
  • O resultado é o de ai.chat, com mais steps: a lista das ferramentas que correram, com os argumentos e o resultado de cada uma.
  • Uma excepção numa ferramenta não pára a tarefa: vai para o modelo como texto («Erro: …»), e o modelo decide o que fazer.
  • max_steps (10 por omissão) é o número máximo de pedidos ao modelo. Se o modelo continuar a pedir ferramentas depois disso, ai.run lança ai.Error com o código max_steps.

Atenção

É o modelo que escolhe os argumentos. Uma ferramenta que altera dados (apagar, enviar um email, gravar) corre com o que o modelo decidir: valida os argumentos dentro da função e não dês ao modelo ferramentas que não possam correr sem supervisão.

ai.run aceita os mesmos parâmetros de ai.chat: system, messages, model, max_tokens, temperature e files.

Lotes (ai.batch)

Um lote processa muitos pedidos de texto em segundo plano. O fornecedor tem até 24 horas para responder. Serve para trabalho sem pressa: resumir os pedidos de suporte da semana, classificar milhares de registos ou traduzir um catálogo.

Um lote faz-se em dois tempos. Um script submete os pedidos e guarda o 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}

Mais tarde, outro script (por exemplo, agendado de hora a hora) vê o estado e lê os resultados:

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}
Função O que faz
ai.batch.submit(pedidos, model=None, system=None, max_tokens=None, temperature=None, schema=None) Submete o lote. Cada pedido é um texto, ou um dict com id, prompt (ou messages) e, opcional, system. Devolve id, status e count.
ai.batch.get(id) O estado (in_progress, ended, failed, cancelled ou expired) e as contagens (total, succeeded, failed e processing).
ai.batch.results(id) Os resultados de um lote acabado: uma lista com id, ok, text, data (com schema), error e usage.
ai.batch.cancel(id) Cancela o lote e devolve o estado.
  • Um lote tem até 10 000 pedidos. Os id levam letras, algarismos, hífen e underscore, até 64 caracteres, sem repetir. Sem id, os pedidos ficam numerados a partir de 1.
  • Com schema, cada resultado é validado como em ai.json: os que não cumprem o schema vêm com ok a falso e o motivo em error.
  • Fazem lotes a OpenAI, a Anthropic e o Google pela Gemini API. Nos outros fornecedores, ai.batch.submit dá o erro not_supported.
  • O id de um lote só serve na app que o submeteu.

Perguntas frequentes

Uma ferramenta pode chamar um serviço externo? Pode. Uma ferramenta é uma função Python como outra qualquer, e pode usar http, db ou workflow.

Quanto tempo demora um lote? Depende do fornecedor e da carga dele, e pode chegar às 24 horas. Um lote que não acaba nesse prazo fica expired.

Posso usar ferramentas num lote? Não. Um lote faz pedidos de texto e de JSON; para ferramentas, usa ai.run.