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
descriptionpour 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. |
| 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.