Développeurs

Appeler un modèle d'IA depuis une application (llm.complete)

La fonction Python complete() de Dokos AI envoie un prompt au modèle configuré sur le site et renvoie le texte de la réponse, avec une ligne d'audit par appel.

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ètreRôle
promptLe message de l'utilisateur envoyé au modèle.
systemUne consigne système facultative. Si elle est renseignée, elle est placée avant le prompt.
tierLe 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_tokensLa longueur maximale de la réponse. Par défaut 800.
purposeLe 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 :

NiveauChamp des paramètres de l'IA
defaultModèle logique et agent (appel de fonction)
fastModèle rapide (tâches simples)
visionModè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ève AIDisabledError, une sous-classe de frappe.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 :

InformationContenu
StatutSuccess ou Failed.
JetonsLa somme des jetons d'entrée et de sortie, si le fournisseur les renvoie.
DétailsLe 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