Skip to main content
View as Markdown

Chat IA

Le Chat IA est une interface conversationnelle sur les données de votre application. Les utilisateurs posent des questions et émettent des commandes en langage naturel ; la plateforme les traduit en requêtes, mutations et déclenchements d'automatisations autorisés, puis renvoie une réponse structurée. Il est disponible à la fois comme point d'accès REST (POST /api/ai/chat) et comme composant de page intégrable (type: ai-chat).

Le chat est natif une fois AI_PROVIDER configuré — la plateforme détecte automatiquement chaque table et champ, aucun YAML par table n'est donc nécessaire pour la prise en charge des requêtes. Toutes les actions effectuées via le chat sont régies par le RBAC et les permissions au niveau des champs de l'utilisateur demandeur, et sont écrites dans le journal d'activité pour une auditabilité complète.

Ce que le chat peut et ne peut pas faire

Le chat peut Le chat ne peut pas
Interroger des enregistrements à travers les tables en langage naturel Modifier les schémas de table (ajouter/supprimer des champs, changer des types)
Créer, mettre à jour et supprimer des enregistrements (opérations destructrices confirmées) Créer ou modifier des automatisations
Déclencher des automatisations à déclenchement manuel que l'utilisateur peut exécuter Accéder aux enregistrements hors des permissions RBAC de l'utilisateur
Maintenir le contexte conversationnel au sein d'une session Contourner les permissions au niveau des champs

Architecture

Message utilisateur
    │
    ▼
POST /api/ai/chat ──▶ Résoudre l'agent (ou IA par défaut) ──▶ Injecter le contexte
    │                                                            │
    │   ┌────────────────────────────────────────────────────────┘
    ▼   ▼
Fournisseur IA ──▶ Appels d'outils (requête, mutation, déclenchement) ──▶ Vérification RBAC ──▶ Journal d'activité
    │
    ▼
Réponse structurée (texte de réponse + actions effectuées)

Le chat résout un agent (lorsqu'un est nommé) ou revient au fournisseur IA par défaut. Le modèle interagit avec les données exclusivement par appels d'outils — des opérations structurées que Sovrium exécute après une vérification RBAC — plutôt que de fabriquer des données en texte libre.

Utiliser le chat comme composant de page

Le composant ai-chat intègre un panneau de chat dans n'importe quelle page.

pages:
  - name: dashboard
    path: /dashboard
    components:
      - type: ai-chat
        agent: support-agent # optionnel — revient au fournisseur IA par défaut
        placeholder: Posez une question sur vos tickets...
        chatHeight: 600
        showHistory: true
        allowAttachments: false
Propriété Description
agent Nom de l'agent depuis app.agents[]. Omettre pour utiliser le fournisseur IA par défaut.
placeholder Texte d'invite pour le champ de saisie du chat.
chatHeight Hauteur du conteneur de chat en pixels (doit être > 0).
showHistory Si l'historique de conversation précédent doit être affiché au chargement.
allowAttachments Si les pièces jointes de fichiers sont autorisées dans le chat.

Utiliser l'API REST

POST /api/ai/chat
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "message": "How many open tickets are there?",
  "context": { "table": "tickets" },
  "sessionId": "sess_abc123"
}
{
  "reply": "There are 42 open tickets — 5 critical, 12 high, 18 medium, 7 low.",
  "actions": [
    {
      "type": "query",
      "table": "tickets",
      "description": "Counted tickets where status = 'open', grouped by priority"
    }
  ],
  "sessionId": "sess_abc123"
}

Requêtes d'enregistrements

Lorsque AI_PROVIDER est défini, l'API de chat traduit nativement les questions en langage naturel en requêtes SQL/API contre les tables autorisées de l'utilisateur, les exécute, et formate le résultat dans la conversation. Aucune configuration n'est requise — la plateforme introspecte le schéma automatiquement. Les requêtes n'atteignent jamais des tables ou des champs que le rôle demandeur ne peut pas lire.

Mutations d'enregistrements

Le chat peut créer, mettre à jour et supprimer des enregistrements pour le compte de l'utilisateur. Les mutations respectent les permissions au niveau des champs (un rôle qui ne peut pas écrire un champ ne peut pas le définir via le chat), et les opérations destructrices nécessitent une confirmation avant de s'exécuter. Chaque mutation est enregistrée dans le journal d'activité avec l'utilisateur qui l'a initiée.

Déclencher des automatisations

Le chat peut invoquer les automatisations à déclenchement manuel que l'utilisateur est autorisé à exécuter, puis rapporter le résultat dans la conversation. Le chat ne peut pas exécuter des automatisations d'autres types de déclenchement, ni créer ou éditer des définitions d'automatisation.

Appel d'outils

Le chat est construit sur l'appel de fonctions/outils. Sovrium présente au modèle un ensemble de définitions d'outils (requête, mutation, déclenchement) ; le modèle retourne un tool_call ; Sovrium l'exécute après une vérification RBAC et renvoie le résultat au modèle, qui compose alors la réponse finale. L'appel d'outils structuré — plutôt que la génération de données en texte libre — est ce qui maintient le chat ancré et auditable.

Message utilisateur → Fournisseur IA (avec définitions d'outils)
                    │
                    ▼
              L'IA retourne tool_call
                    │
                    ▼
         Sovrium exécute l'outil (RBAC vérifié)
                    │
                    ▼
         Résultat de l'outil renvoyé à l'IA
                    │
                    ▼
              L'IA retourne la réponse textuelle finale

Réponses en streaming

Le chat prend en charge le streaming Server-Sent Events (SSE) afin que les utilisateurs voient la génération de texte progressive au lieu d'attendre la réponse complète.

Comportement Détail
Livraison par fragments Le contenu partiel du message arrive sous forme de fragments SSE, transmis en temps réel à mesure que le fournisseur les émet.
Marqueur d'achèvement L'événement SSE final porte un marqueur [DONE] ; le message complet est assemblé à partir de tous les fragments.
Persistance Les messages diffusés sont persistés dans l'historique de conversation une fois terminés.
Permissions Le streaming applique le même RBAC que le chat non diffusé.
Temps jusqu'au premier fragment Un 504 est retourné lorsque le fournisseur n'envoie aucun premier fragment avant AI_CHAT_STREAM_TIMEOUT.
Coupure de connexion Gérée gracieusement — une réponse partielle est rejetée si la connexion se coupe avant l'achèvement.

Limitation de débit

Les limites de débit par utilisateur protègent le fournisseur IA d'une surcharge et plafonnent le coût. Les limites sont configurées via des variables d'environnement, et non le schéma de l'application.

Variable Description Défaut
AI_CHAT_RATE_LIMIT Messages autorisés par fenêtre, par utilisateur. 60
AI_CHAT_RATE_WINDOW Durée de la fenêtre de limitation de débit. 1 minute
AI_CHAT_STREAM_TIMEOUT Délai pour le temps jusqu'au premier fragment sur les requêtes en streaming. —

Une requête limitée en débit retourne 429 avec un en-tête Retry-After et des informations de quota restant. Chaque utilisateur a un compteur indépendant, et la fenêtre se réinitialise après son expiration. Les appels API d'agent respectent les mêmes limites que le chat utilisateur.

Gestion des erreurs

Lorsque le fournisseur IA échoue, le chat retourne une erreur conviviale plutôt que de divulguer les rouages internes bruts du fournisseur. Lorsque AI_PROVIDER n'est pas défini, le point d'accès du chat répond avec un état désactivé au lieu d'échouer — conformément au contrat « IA dormante jusqu'à configuration » de la plateforme.

Pages connexes