Usar a IA nos scripts
Pedir texto, JSON com uma forma certa e embeddings aos modelos de IA da app, enviar ficheiros, tratar os erros e saber o que cada fornecedor faz.
Os scripts da app chamam a IA pelo módulo ai do SDK. O script escolhe o
modelo pelo nome do alias, e o pedido sai do servidor da plataforma com as
credenciais do fornecedor. O script nunca vê as chaves.
from api_manager import ai
def main(input):
r = ai.chat("Resume em três frases: " + input["args"]["texto"])
return {"resumo": r["text"]}
Antes de começar
- O tenant tem de ter um fornecedor de IA activo, com modelos autorizados. Ver Fornecedores de IA.
- A app tem de ter um alias para cada uso que o script pede. Sem
model=, o script usa o alias predefinido desse uso. Ver Modelos de IA da app.
O que cada fornecedor faz
| Fornecedor | Texto, JSON e ferramentas | Embeddings | Imagens | Transcrição | Voz | Lotes |
|---|---|---|---|---|---|---|
| OpenAI | Sim | Sim | Sim | Sim | Sim | Sim |
| Anthropic | Sim | Não | Não | Não | Não | Sim |
| Microsoft Foundry | Sim | Sim | Sim | Sim | Sim | Não |
| Amazon Bedrock | Sim | Titan e Cohere | Nova Canvas, Titan e Stability | Não | Não | Não |
| Google Cloud | Sim | Sim | Sim | Sim | Sim | Só pela Gemini API |
| OpenRouter | Sim | Sim | Sim | Não | Não | Não |
| Compatível com OpenAI | Sim | Conforme o servidor | Conforme o servidor | Conforme o servidor | Conforme o servidor | Não |
Num fornecedor que não faz uma operação, a chamada dá o erro
not_supported. Em qualquer fornecedor, a operação só funciona com um modelo
que a faça: um modelo de texto não gera imagens.
As ferramentas e os lotes estão em Ferramentas e lotes, e as imagens, a transcrição e a voz em Imagens e áudio.
Pedir texto
ai.chat envia um pedido e devolve a resposta do modelo:
from api_manager import ai, log
def main(input):
r = ai.chat(
"Classifica este pedido de suporte: " + input["args"]["pedido"],
system="És um assistente de apoio ao cliente. Respondes numa palavra: urgente, normal ou baixo.",
model="texto",
max_tokens=10,
temperature=0,
)
log("classificação:", r["text"], r["usage"])
return {"prioridade": r["text"].strip().lower()}
| Parâmetro | O que faz |
|---|---|
prompt |
A pergunta. |
system |
A instrução de sistema: o papel e as regras do modelo. |
messages |
Uma conversa, em vez de prompt (ver Uma conversa). |
model |
O nome do alias. Sem ele, vale o alias de texto predefinido. |
max_tokens |
O tamanho máximo da resposta. Sem ele, vale o do alias e, depois, o da plataforma. |
temperature |
De 0 a 2. Um valor baixo dá respostas mais previsíveis. Sem ele, vale o do modelo. |
files |
Ficheiros que vão com a pergunta (ver Enviar ficheiros). |
stream |
Um nome, para o texto aparecer no ecrã de quem chamou enquanto o modelo o escreve (ver Respostas em directo no ecrã). |
O resultado é um dict:
| Chave | O que tem |
|---|---|
text |
O texto da resposta. |
stop_reason |
Porque parou o modelo: end, max_tokens, tool_use, refusal ou other. |
usage |
Os tokens gastos, em input_tokens e output_tokens. |
model, provider, alias |
Quem respondeu. |
Um stop_reason igual a max_tokens quer dizer que a resposta foi cortada.
Sobe o max_tokens ou pede uma resposta mais curta.
Uma conversa
Para continuar uma conversa, passa o histórico em messages, com os papéis
user e assistant alternados:
from api_manager import ai
def main(input):
r = ai.chat(
messages=[
{"role": "user", "content": "O meu nome é Ana."},
{"role": "assistant", "content": "Olá, Ana!"},
{"role": "user", "content": "Como me chamo?"},
],
)
return {"resposta": r["text"]}
Com messages e prompt ao mesmo tempo, o prompt entra como a última
mensagem do utilizador. A lista também pode ir como primeiro argumento, sem messages=:
ai.chat([...]).
Pedir JSON com uma forma certa
ai.json pede a resposta em JSON, valida-a contra um JSON Schema e devolve
o JSON já lido:
from api_manager import ai
ESQUEMA = {
"type": "object",
"properties": {
"nif": {"type": "string", "description": "NIF do cliente, 9 algarismos"},
"total": {"type": "number", "description": "Total com IVA, em euros"},
},
"required": ["nif", "total"],
}
def main(input):
factura = ai.json(
"Extrai o NIF do cliente e o total desta factura.",
schema=ESQUEMA,
files=[input["args"]["factura"]],
)
return factura # {"nif": "...", "total": 123.45}
- O schema descreve a forma: os tipos, os campos obrigatórios e uma
descriptionem cada campo. Quanto melhor a descrição, melhor a resposta. - Uma resposta que não cumpre o schema dá o erro
invalid_output. O script nunca recebe dados com a forma errada. - Os fornecedores que suportam saída estruturada recebem o schema no pedido. Os outros recebem-no na instrução de sistema, e a resposta é validada na mesma.
Enviar ficheiros
files= leva ficheiros da app com o pedido, em ai.chat e em ai.json.
Aceita os argumentos do tipo Upload tal como chegam em input["args"],
ou o que files.store devolve:
from api_manager import ai, files
def main(input):
# um argumento do tipo Upload de uma API
foto = input["args"]["foto"]
estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])
# um ficheiro criado pelo próprio script
vendas = files.store(b"produto;quantidade\nCadeira;12\nMesa;30\n", "vendas.csv", "text/csv")
melhor = ai.chat("Que produto vendeu mais? Responde só com o nome.", files=[vendas])
return {"estado": estado["text"], "mais_vendido": melhor["text"]}
| Tipo | Como segue |
|---|---|
| Imagens PNG, JPEG, GIF e WebP | Como imagem, para modelos que vêem imagens. |
| Como documento, para modelos que lêem PDF. | |
| Texto (txt, csv, json, md, xml e yaml) | Como texto, antes da pergunta. |
Cada ficheiro pode ter até 20 MB, e um pedido até 40 MB. Um modelo só de
texto recusa imagens e PDF com o erro invalid_request.
Embeddings
ai.embed transforma texto em vectores, para procurar por significado e não
só por palavras iguais:
from api_manager import ai
def semelhanca(a, b):
produto = sum(x * y for x, y in zip(a, b))
normas = (sum(x * x for x in a) ** 0.5) * (sum(y * y for y in b) ** 0.5)
return produto / normas
def main(input):
pergunta = ai.embed(input["args"]["pergunta"]) # um vector
artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
vectores = ai.embed(artigos) # um vector por texto
melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
return {"artigo": artigos[melhor]}
Um texto devolve um vector. Uma lista devolve uma lista de vectores, pela
mesma ordem, até 2048 textos por chamada. Sem model=, vale o alias de
embeddings predefinido.
Os aliases da app
ai.models() devolve os aliases da app, cada um com o nome, o uso, a marca
de predefinido, o fornecedor e o modelo. Serve para um script escolher o
modelo durante a execução ou explicar porque é que falta um alias.
Erros
Uma chamada que falha lança ai.Error. O atributo code é igual em todos
os fornecedores, e a mensagem diz o que aconteceu:
from api_manager import ai, log
def main(input):
try:
r = ai.chat(input["args"]["pergunta"])
except ai.Error as e:
log("IA:", e.code, str(e))
if e.code in ("rate_limited", "unavailable", "timeout", "connection"):
return {"tentar_mais_tarde": True}
raise
return {"resposta": r["text"]}
| Código | O que quer dizer |
|---|---|
not_configured |
Falta o alias, o fornecedor está desactivado ou o modelo deixou de estar autorizado. |
rate_limited |
O fornecedor recusou por excesso de pedidos. |
timeout |
O fornecedor não respondeu dentro do tempo máximo. |
unavailable, connection |
O fornecedor está em baixo ou não foi possível ligar. |
auth, permission |
A chave foi recusada ou não tem permissão. |
invalid_request |
O pedido não é válido para este fornecedor ou modelo. |
invalid_output |
O JSON da resposta não cumpre o schema. |
refused |
O modelo recusou responder. |
not_supported |
O fornecedor não faz esta operação, ou o ficheiro é de um tipo que não segue. |
cancelled |
A execução acabou antes da resposta. |
max_steps |
O ai.run chegou ao máximo de passos sem resposta final. |
not_found, unknown |
O modelo ou o endereço não existe, ou aconteceu outro erro. |
Tempo limite e registos
- Uma resposta pode demorar dezenas de segundos. O Tempo limite do script tem de chegar para todas as chamadas: num script com várias, sobe-o.
- Quando a execução acaba, por tempo limite ou por cancelamento, os pedidos ainda à espera são cancelados no fornecedor.
- Cada chamada escreve uma linha nos logs da execução, com o alias, o modelo
e a duração, por exemplo
[ai] texto (local/qwen2.5:0.5b): 1840 ms. - A plataforma não guarda o texto dos pedidos nem das respostas, a não ser que a app ligue a depuração (ver Modelos de IA da app). O pedido segue para o fornecedor de IA da app, por isso não lhe envies dados pessoais sem necessidade.
Perguntas frequentes
Posso usar a IA a partir de um widget ou do browser? Não. A IA só existe nos scripts, que correm no servidor, e assim as chaves nunca chegam ao browser. Um ecrã que precisa de IA chama uma API que corre um script.
O script diz not_configured e o alias existe. Confirma que o alias é
do uso certo (um alias de embeddings não serve para ai.chat), que o
fornecedor está activo e que o modelo continua autorizado nele.
Posso usar a biblioteca da OpenAI ou da Anthropic directamente? Podes
instalá-la pelo painel pip, mas a chave teria de ficar num segredo da
app, e o script perdia os aliases e os códigos de erro comuns. O módulo
ai existe para isso.