KEPLIN Docs

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 description en 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.
PDF 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.