Usar la IA en los scripts
Pedir texto, JSON con una forma fija y embeddings a los modelos de IA de la app, enviar archivos, tratar los errores y saber qué hace cada proveedor.
Los scripts de la app llaman a la IA con el módulo ai del SDK. El script
elige el modelo por el nombre del alias, y la petición sale del servidor de la
plataforma con las credenciales del proveedor. El script nunca ve las claves.
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 empezar
- El tenant tiene que tener un proveedor de IA activo, con modelos autorizados. Ver Proveedores de IA.
- La app tiene que tener un alias para cada uso que pide el script. Sin
model=, el script usa el alias predeterminado de ese uso. Ver Modelos de IA de la app.
Qué hace cada proveedor
| Proveedor | Texto, JSON y herramientas | Embeddings | Imágenes | Transcripción | Voz | Lotes |
|---|---|---|---|---|---|---|
| OpenAI | Sí | Sí | Sí | Sí | Sí | Sí |
| Anthropic | Sí | No | No | No | No | Sí |
| Microsoft Foundry | Sí | Sí | Sí | Sí | Sí | No |
| Amazon Bedrock | Sí | Titan y Cohere | Nova Canvas, Titan y Stability | No | No | No |
| Google Cloud | Sí | Sí | Sí | Sí | Sí | Solo por la Gemini API |
| OpenRouter | Sí | Sí | Sí | No | No | No |
| Compatible con OpenAI | Sí | Según el servidor | Según el servidor | Según el servidor | Según el servidor | No |
En un proveedor que no hace una operación, la llamada da el error
not_supported. En cualquier proveedor, la operación solo funciona con un
modelo que la haga: un modelo de texto no genera imágenes.
Las herramientas y los lotes están en Herramientas y lotes, y las imágenes, la transcripción y la voz en Imágenes y audio.
Pedir texto
ai.chat envía una petición y devuelve la respuesta del 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 | Qué hace |
|---|---|
prompt |
La pregunta. |
system |
La instrucción de sistema: el papel y las reglas del modelo. |
messages |
Una conversación, en lugar de prompt (ver Una conversación). |
model |
El nombre del alias. Sin él, vale el alias de texto predeterminado. |
max_tokens |
El tamaño máximo de la respuesta. Sin él, vale el del alias y, después, el de la plataforma. |
temperature |
De 0 a 2. Un valor bajo da respuestas más previsibles. Sin él, vale el del modelo. |
files |
Archivos que van con la pregunta (ver Enviar archivos). |
stream |
Un nombre, para que el texto aparezca en la pantalla de quien llamó mientras el modelo lo escribe (ver Respuestas en directo en la pantalla). |
El resultado es un dict:
| Clave | Qué contiene |
|---|---|
text |
El texto de la respuesta. |
stop_reason |
Por qué paró el modelo: end, max_tokens, tool_use, refusal u other. |
usage |
Los tokens gastados, en input_tokens y output_tokens. |
model, provider, alias |
Quién respondió. |
Un stop_reason igual a max_tokens quiere decir que la respuesta se cortó.
Sube el max_tokens o pide una respuesta más corta.
Una conversación
Para continuar una conversación, pasa el historial en messages, con los
papeles user y 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"]}
Con messages y prompt a la vez, el prompt entra como el último mensaje
del usuario. La lista también puede ir como primer argumento, sin messages=:
ai.chat([...]).
Pedir JSON con una forma fija
ai.json pide la respuesta en JSON, la valida contra un JSON Schema y
devuelve el JSON ya leído:
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}
- El schema describe la forma: los tipos, los campos obligatorios y una
descriptionen cada campo. Cuanto mejor la descripción, mejor la respuesta. - Una respuesta que no cumple el schema da el error
invalid_output. El script nunca recibe datos con la forma equivocada. - Los proveedores que admiten salida estructurada reciben el schema en la petición. Los demás lo reciben en la instrucción de sistema, y la respuesta se valida igualmente.
Enviar archivos
files= lleva archivos de la app con la petición, en ai.chat y en
ai.json. Acepta los argumentos de tipo Upload tal como llegan en
input["args"], o lo que devuelve files.store:
from api_manager import ai, files
def main(input):
# un argumento de tipo Upload de una API
foto = input["args"]["foto"]
estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])
# un archivo creado por el propio 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 | Cómo va |
|---|---|
| Imágenes PNG, JPEG, GIF y WebP | Como imagen, para modelos que ven imágenes. |
| Como documento, para modelos que leen PDF. | |
| Texto (txt, csv, json, md, xml y yaml) | Como texto, antes de la pregunta. |
Cada archivo puede tener hasta 20 MB, y una petición hasta 40 MB. Un modelo
solo de texto rechaza imágenes y PDF con el error invalid_request.
Embeddings
ai.embed convierte texto en vectores, para buscar por significado y no
solo por palabras iguales:
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"]) # un vector
artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
vectores = ai.embed(artigos) # un vector por texto
melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
return {"artigo": artigos[melhor]}
Un texto devuelve un vector. Una lista devuelve una lista de vectores, en el
mismo orden, hasta 2048 textos por llamada. Sin model=, vale el alias de
embeddings predeterminado.
Los aliases de la app
ai.models() devuelve los aliases de la app, cada uno con el nombre, el
uso, la marca de predeterminado, el proveedor y el modelo. Sirve para que un
script elija el modelo durante la ejecución o explique por qué falta un
alias.
Errores
Una llamada que falla lanza ai.Error. El atributo code es igual en
todos los proveedores, y el mensaje dice lo que pasó:
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 | Qué quiere decir |
|---|---|
not_configured |
Falta el alias, el proveedor está desactivado o el modelo dejó de estar autorizado. |
rate_limited |
El proveedor rechazó por exceso de peticiones. |
timeout |
El proveedor no respondió dentro del tiempo máximo. |
unavailable, connection |
El proveedor está caído o no fue posible conectar. |
auth, permission |
La clave fue rechazada o no tiene permiso. |
invalid_request |
La petición no es válida para este proveedor o modelo. |
invalid_output |
El JSON de la respuesta no cumple el schema. |
refused |
El modelo se negó a responder. |
not_supported |
El proveedor no hace esta operación, o el archivo es de un tipo que no se envía. |
cancelled |
La ejecución terminó antes de la respuesta. |
max_steps |
ai.run llegó al máximo de pasos sin respuesta final. |
not_found, unknown |
El modelo o la dirección no existe, u ocurrió otro error. |
Tiempo límite y registros
- Una respuesta puede tardar decenas de segundos. El Tiempo límite del script tiene que bastar para todas las llamadas: en un script con varias, súbelo.
- Cuando la ejecución termina, por tiempo límite o por cancelación, las peticiones que aún esperan se cancelan en el proveedor.
- Cada llamada escribe una línea en los logs de la ejecución, con el alias, el
modelo y la duración, por ejemplo
[ai] texto (local/qwen2.5:0.5b): 1840 ms. - La plataforma no guarda el texto de las peticiones ni de las respuestas, salvo que la app active la depuración (ver Modelos de IA de la app). La petición va al proveedor de IA de la app, así que no le envíes datos personales sin necesidad.
Preguntas frecuentes
¿Puedo usar la IA desde un widget o desde el navegador? No. La IA solo existe en los scripts, que corren en el servidor, y así las claves nunca llegan al navegador. Una pantalla que necesita IA llama a una API que ejecuta un script.
El script dice not_configured y el alias existe. Confirma que el alias
es del uso correcto (un alias de embeddings no sirve para ai.chat), que el
proveedor está activo y que el modelo sigue autorizado en él.
¿Puedo usar la biblioteca de OpenAI o de Anthropic directamente? Puedes
instalarla desde el panel pip, pero la clave tendría que quedar en un
secreto de la app, y el script perdería los aliases y los códigos de
error comunes. El módulo ai existe para eso.