KEPLIN Docs

Herramientas y lotes

Dejar que el modelo use funciones del script con ai.run, y procesar muchas peticiones en segundo plano con ai.batch.

Dos operaciones para trabajo mayor que una pregunta: ai.run deja que el modelo use funciones del script mientras responde, y ai.batch procesa muchas peticiones en segundo plano.

Herramientas (ai.run)

Con ai.run, el modelo puede pedir funciones del script durante la respuesta: consultar una base de datos, calcular un valor o llamar a una API. El SDK ejecuta la función en el script, devuelve el resultado al modelo y repite hasta que el modelo da la respuesta 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"]}
  • Una herramienta es una función Python. El nombre, la docstring y las anotaciones de tipo de los argumentos son lo que el modelo lee para decidir cuándo usarla, así que describe bien la función en la docstring.
  • Los tipos que pasan a JSON Schema son str, int, float, bool, list y dict. Un argumento con valor predeterminado es opcional.
  • Para controlar el esquema de los argumentos, pasa un dict en lugar de la función: {"name": "stock", "description": "...", "parameters": {...}, "function": stock}, con parameters en JSON Schema.
  • El resultado es el de ai.chat, con steps: la lista de las herramientas que se ejecutaron, con los argumentos y el resultado de cada una.
  • Una excepción en una herramienta no detiene la tarea: va al modelo como texto («Erro: …»), y el modelo decide qué hacer.
  • max_steps (10 por defecto) es el número máximo de peticiones al modelo. Si el modelo sigue pidiendo herramientas después de eso, ai.run lanza ai.Error con el código max_steps.

Atención

Es el modelo quien elige los argumentos. Una herramienta que cambia datos (borrar, enviar un email, guardar) se ejecuta con lo que el modelo decida: valida los argumentos dentro de la función y no des al modelo herramientas que no puedan ejecutarse sin supervisión.

ai.run acepta los mismos parámetros que ai.chat: system, messages, model, max_tokens, temperature y files.

Lotes (ai.batch)

Un lote procesa muchas peticiones de texto en segundo plano. El proveedor tiene hasta 24 horas para responder. Sirve para trabajo sin prisa: resumir las peticiones de soporte de la semana, clasificar miles de registros o traducir un catálogo.

Un lote se hace en dos tiempos. Un script envía las peticiones y guarda el 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}

Más tarde, otro script (por ejemplo, programado cada hora) consulta el estado y lee los 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}
Función Qué hace
ai.batch.submit(pedidos, model=None, system=None, max_tokens=None, temperature=None, schema=None) Envía el lote. Cada petición es un texto, o un dict con id, prompt (o messages) y, opcional, system. Devuelve id, status y count.
ai.batch.get(id) El estado (in_progress, ended, failed, cancelled o expired) y los recuentos (total, succeeded, failed y processing).
ai.batch.results(id) Los resultados de un lote terminado: una lista con id, ok, text, data (con schema), error y usage.
ai.batch.cancel(id) Cancela el lote y devuelve el estado.
  • Un lote tiene hasta 10 000 peticiones. Los id llevan letras, dígitos, guion y guion bajo, hasta 64 caracteres, sin repetir. Sin id, las peticiones se numeran a partir de 1.
  • Con schema, cada resultado se valida como en ai.json: los que no cumplen el schema vienen con ok en falso y el motivo en error.
  • Hacen lotes OpenAI, Anthropic y Google por la Gemini API. En los demás proveedores, ai.batch.submit da el error not_supported.
  • El id de un lote solo sirve en la app que lo envió.

Preguntas frecuentes

¿Una herramienta puede llamar a un servicio externo? Sí. Una herramienta es una función Python como cualquier otra, y puede usar http, db o workflow.

¿Cuánto tarda un lote? Depende del proveedor y de su carga, y puede llegar a 24 horas. Un lote que no termina en ese plazo queda expired.

¿Puedo usar herramientas en un lote? No. Un lote hace peticiones de texto y de JSON; para herramientas, usa ai.run.