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,listydict. 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}, conparametersen JSON Schema. - El resultado es el de
ai.chat, consteps: 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.runlanzaai.Errorcon el códigomax_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
idllevan letras, dígitos, guion y guion bajo, hasta 64 caracteres, sin repetir. Sinid, las peticiones se numeran a partir de 1. - Con
schema, cada resultado se valida como enai.json: los que no cumplen el schema vienen conoken falso y el motivo enerror. - Hacen lotes OpenAI, Anthropic y Google por la Gemini API. En los demás
proveedores,
ai.batch.submitda el errornot_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.