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,listedict. 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}, comparametersem JSON Schema. - O resultado é o de
ai.chat, com maissteps: 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.runlançaai.Errorcom o códigomax_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
idlevam letras, algarismos, hífen e underscore, até 64 caracteres, sem repetir. Semid, os pedidos ficam numerados a partir de 1. - Com
schema, cada resultado é validado como emai.json: os que não cumprem o schema vêm comoka falso e o motivo emerror. - Fazem lotes a OpenAI, a Anthropic e o Google pela Gemini API. Nos outros
fornecedores,
ai.batch.submitdá o erronot_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.