Appeler un modèle d'IA depuis une application (llm.complete)
Appeler un modèle d'IA depuis une application (llm.complete)
L'application Dokos AI fournit la fonction complete() pour qu'une autre application obtienne une réponse de texte d'un modèle, en un seul échange : un prompt en entrée, le texte du modèle en sortie. La fonction réutilise la configuration du site : niveaux de modèles, connexions aux fournisseurs et clés d'accès sont ceux des paramètres de l'IA. Voir Activer et paramétrer l'IA.
complete() est une API Python. Elle n'est pas exposée en HTTP : on ne peut pas l'appeler depuis l'API REST ni depuis un script client.
Prérequis
- L'application Dokos AI est installée sur le site.
- L'IA est activée sur le site (case Activer les intégrations d'IA des paramètres de l'IA) et un fournisseur de modèles est connecté.
- Votre application importe
dokos_ai: déclarez-la comme dépendance ou protégez l'import si elle peut être absente.
Signature
from dokos_ai.dokos_ai.api.llm import AIDisabledError, complete
complete(
prompt: str,
*,
system: str | None = None,
tier: ModelTier | str = ModelTier.FAST,
max_tokens: int = 800,
purpose: str | None = None,
) -> str
| Paramètre | Rôle |
|---|---|
prompt | Le message de l'utilisateur envoyé au modèle. |
system | Une consigne système facultative. Si elle est renseignée, elle est placée avant le prompt. |
tier | Le niveau de modèle : default, fast ou vision (ou l'énumération ModelTier). Par défaut fast. Le modèle réel est celui que les paramètres de l'IA associent à ce niveau. |
max_tokens | La longueur maximale de la réponse. Par défaut 800. |
purpose | Le nom de la fonctionnalité appelante, repris dans le journal d'audit (par exemple monapp.resume_ticket). |
La fonction renvoie le texte de la réponse, ou une chaîne vide si le modèle ne renvoie aucun contenu. L'appel est synchrone : il attend la réponse du fournisseur.
Chaque niveau correspond à un champ des paramètres de l'IA :
| Niveau | Champ des paramètres de l'IA |
|---|---|
default | Modèle logique et agent (appel de fonction) |
fast | Modèle rapide (tâches simples) |
vision | Modèle OCR et Vision |
complete() envoie seulement du texte : elle ne peut pas transmettre d'image. Avec vision, le prompt texte est envoyé au modèle OCR et Vision. Pour une simple réponse de texte, préférez fast ou default.
Erreurs
- Si l'IA est désactivée sur le site,
complete()lèveAIDisabledError, une sous-classe defrappe.ValidationError. Son message est « L'IA est désactivée dans les paramètres IA. » dans l'interface en français. - Les erreurs du fournisseur (service indisponible, clé refusée…) ne sont pas interceptées : elles remontent telles quelles à l'appelant, après l'écriture de la ligne d'audit.
complete() ne vérifie pas les permissions de l'utilisateur connecté. Contrôlez-les dans votre code avant de l'appeler, surtout si le prompt contient des données du site.
Journal d'audit
Chaque appel écrit une ligne dans le Journal d'audit IA (type d'événement llm_completion), qu'il réussisse ou non :
| Information | Contenu |
|---|---|
| Statut | Success ou Failed. |
| Jetons | La somme des jetons d'entrée et de sortie, si le fournisseur les renvoie. |
| Détails | Le purpose, l'identifiant du modèle, une empreinte du prompt et la durée en millisecondes. |
Le prompt lui-même n'est jamais enregistré : seule son empreinte l'est. L'acteur de la ligne est l'utilisateur de la session.
L'écriture de l'audit ne fait jamais échouer l'appel. La ligne est insérée dans la transaction en cours, sans validation (commit) : si l'appelant annule la transaction, par exemple après une exception, la ligne est annulée avec elle.
Exemple
Exemple fictif : une application monapp résume le texte d'un ticket pour l'afficher dans un champ.
import frappe
from dokos_ai.dokos_ai.api.llm import AIDisabledError, complete
def resumer_ticket(ticket: str) -> str | None:
texte = frappe.db.get_value("Issue", ticket, "description")
try:
return complete(
texte,
system="Résume ce message en deux phrases, en français.",
max_tokens=200,
purpose="monapp.resumer_ticket",
)
except AIDisabledError:
return None
Si l'IA est désactivée, la fonction renvoie None et l'application continue sans résumé. Après un appel réussi, une ligne llm_completion au statut Success apparaît dans le journal d'audit, avec monapp.resumer_ticket dans ses détails.
Voir aussi
- Activer et paramétrer l'IA : activation, connexion d'un fournisseur et choix des modèles.
- Dokos AI