KEPLIN Docs

Utiliser l'IA dans les scripts

Demander du texte, du JSON d'une forme précise et des embeddings aux modèles d'IA de l'app, envoyer des fichiers, traiter les erreurs et savoir ce que fait chaque fournisseur.

Les scripts de l'app appellent l'IA avec le module ai du SDK. Le script choisit le modèle par le nom de l'alias, et la requête part du serveur de la plateforme avec les identifiants du fournisseur. Le script ne voit jamais les clés.

from api_manager import ai


def main(input):
    r = ai.chat("Resume em três frases: " + input["args"]["texto"])
    return {"resumo": r["text"]}

Avant de commencer

  • Le tenant doit avoir un fournisseur d'IA actif, avec des modèles autorisés. Voir Fournisseurs d'IA.
  • L'app doit avoir un alias pour chaque usage que le script demande. Sans model=, le script utilise l'alias par défaut de cet usage. Voir Modèles d'IA de l'application.

Ce que fait chaque fournisseur

Fournisseur Texte, JSON et outils Embeddings Images Transcription Voix Lots
OpenAI Oui Oui Oui Oui Oui Oui
Anthropic Oui Non Non Non Non Oui
Microsoft Foundry Oui Oui Oui Oui Oui Non
Amazon Bedrock Oui Titan et Cohere Nova Canvas, Titan et Stability Non Non Non
Google Cloud Oui Oui Oui Oui Oui Uniquement via la Gemini API
OpenRouter Oui Oui Oui Non Non Non
Compatible OpenAI Oui Selon le serveur Selon le serveur Selon le serveur Selon le serveur Non

Chez un fournisseur qui ne fait pas une opération, l'appel donne l'erreur not_supported. Chez n'importe quel fournisseur, l'opération ne fonctionne qu'avec un modèle qui la fait : un modèle de texte ne génère pas d'images.

Les outils et les lots se trouvent dans Outils et lots, et les images, la transcription et la voix dans Images et audio.

Demander du texte

ai.chat envoie une requête et renvoie la réponse du modèle :

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()}
Paramètre Ce qu'il fait
prompt La question.
system L'instruction système : le rôle et les règles du modèle.
messages Une conversation, au lieu de prompt (voir Une conversation).
model Le nom de l'alias. Sans lui, l'alias de texte par défaut s'applique.
max_tokens La taille maximale de la réponse. Sans lui, la valeur de l'alias s'applique, puis celle de la plateforme.
temperature De 0 à 2. Une valeur basse donne des réponses plus prévisibles. Sans lui, la valeur du modèle s'applique.
files Des fichiers qui accompagnent la question (voir Envoyer des fichiers).
stream Un nom, pour que le texte apparaisse sur l'écran de la personne qui a appelé pendant que le modèle l'écrit (voir Réponses en direct à l'écran).

Le résultat est un dict :

Clé Ce qu'elle contient
text Le texte de la réponse.
stop_reason Pourquoi le modèle s'est arrêté : end, max_tokens, tool_use, refusal ou other.
usage Les tokens consommés, dans input_tokens et output_tokens.
model, provider, alias Qui a répondu.

Un stop_reason égal à max_tokens signifie que la réponse a été coupée. Augmentez max_tokens ou demandez une réponse plus courte.

Une conversation

Pour poursuivre une conversation, passez l'historique dans messages, avec les rôles user et assistant en alternance :

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"]}

Avec messages et prompt en même temps, le prompt entre comme le dernier message de l'utilisateur. La liste peut aussi être passée comme premier argument, sans messages= : ai.chat([...]).

Demander du JSON d'une forme précise

ai.json demande la réponse en JSON, la valide par rapport à un JSON Schema et renvoie le JSON déjà lu :

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}
  • Le schéma décrit la forme : les types, les champs obligatoires et une description pour chaque champ. Meilleure est la description, meilleure est la réponse.
  • Une réponse qui ne respecte pas le schéma donne l'erreur invalid_output. Le script ne reçoit jamais de données de la mauvaise forme.
  • Les fournisseurs qui prennent en charge la sortie structurée reçoivent le schéma dans la requête. Les autres le reçoivent dans l'instruction système, et la réponse est validée de la même façon.

Envoyer des fichiers

files= envoie des fichiers de l'app avec la requête, dans ai.chat et dans ai.json. Il accepte les arguments de type Upload tels qu'ils arrivent dans input["args"], ou ce que renvoie files.store :

from api_manager import ai, files


def main(input):
    # un argument de type Upload d'une API
    foto = input["args"]["foto"]
    estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])

    # un fichier créé par le script lui-même
    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"]}
Type Comment il part
Images PNG, JPEG, GIF et WebP Comme image, pour les modèles qui voient les images.
PDF Comme document, pour les modèles qui lisent le PDF.
Texte (txt, csv, json, md, xml et yaml) Comme texte, avant la question.

Chaque fichier peut faire jusqu'à 20 Mo, et une requête jusqu'à 40 Mo. Un modèle uniquement textuel refuse les images et le PDF avec l'erreur invalid_request.

Embeddings

ai.embed transforme du texte en vecteurs, pour chercher par le sens et pas seulement par les mots identiques :

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 vecteur
    artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
    vectores = ai.embed(artigos)  # un vecteur por texto
    melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
    return {"artigo": artigos[melhor]}

Un texte renvoie un vecteur. Une liste renvoie une liste de vecteurs, dans le même ordre, jusqu'à 2048 textes par appel. Sans model=, l'alias d'embeddings par défaut s'applique.

Les alias de l'app

ai.models() renvoie les alias de l'app, chacun avec son nom, son usage, la marque de défaut, le fournisseur et le modèle. Un script peut s'en servir pour choisir le modèle pendant l'exécution ou pour expliquer pourquoi un alias manque.

Erreurs

Un appel qui échoue lève ai.Error. L'attribut code est le même pour tous les fournisseurs, et le message dit ce qui s'est passé :

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"]}
Code Ce qu'il signifie
not_configured L'alias manque, le fournisseur est désactivé ou le modèle n'est plus autorisé.
rate_limited Le fournisseur a refusé pour excès de requêtes.
timeout Le fournisseur n'a pas répondu dans la durée maximale.
unavailable, connection Le fournisseur est hors service ou injoignable.
auth, permission La clé a été refusée ou n'a pas l'autorisation.
invalid_request La requête n'est pas valide pour ce fournisseur ou ce modèle.
invalid_output Le JSON de la réponse ne respecte pas le schéma.
refused Le modèle a refusé de répondre.
not_supported Le fournisseur ne fait pas cette opération, ou le fichier est d'un type qui ne part pas.
cancelled L'exécution s'est terminée avant la réponse.
max_steps ai.run a atteint le nombre maximal d'étapes sans réponse finale.
not_found, unknown Le modèle ou l'adresse n'existe pas, ou une autre erreur s'est produite.

Temps limite et journaux

  • Une réponse peut prendre des dizaines de secondes. Le Temps limite du script doit suffire pour tous les appels : dans un script qui en fait plusieurs, augmentez-le.
  • Quand l'exécution se termine, par le temps limite ou par une annulation, les requêtes encore en attente sont annulées chez le fournisseur.
  • Chaque appel écrit une ligne dans les logs de l'exécution, avec l'alias, le modèle et la durée, par exemple [ai] texto (local/qwen2.5:0.5b): 1840 ms.
  • La plateforme ne garde pas le texte des requêtes ni des réponses, sauf si l'app active le débogage (voir Modèles d'IA de l'application). La requête part vers le fournisseur d'IA de l'app : n'y envoyez donc pas de données personnelles sans nécessité.

Questions fréquentes

Puis-je utiliser l'IA depuis un widget ou depuis le navigateur ? Non. L'IA n'existe que dans les scripts, qui s'exécutent sur le serveur, et ainsi les clés n'arrivent jamais au navigateur. Un écran qui a besoin d'IA appelle une API qui exécute un script.

Le script dit not_configured alors que l'alias existe. Vérifiez que l'alias est du bon usage (un alias d'embeddings ne sert pas pour ai.chat), que le fournisseur est actif et que le modèle y est toujours autorisé.

Puis-je utiliser directement la bibliothèque d'OpenAI ou d'Anthropic ? Vous pouvez l'installer depuis le panneau pip, mais la clé devrait alors rester dans un secret de l'app, et le script perdrait les alias et les codes d'erreur communs. Le module ai existe pour cela.