--- title: "Connecteurs IA — Configuration et administration" module: ai type: functional status: active updated: 2026-05-22 --- # Connecteurs IA — Configuration et administration ## À quoi ça sert ISI-APP intègre un système de **connecteurs IA modulaire** qui permet à l'application de dialoguer avec différents fournisseurs d'IA (OpenAI, Mistral, et potentiellement d'autres) via une interface unique. Cette page décrit le paramétrage de ces connecteurs côté administrateur. Toute la configuration se fait dans `/admin/ai`, sans intervention dans le code. ## Concepts | Notion | Définition | |--------|------------| | **Provider** | Un fournisseur d'IA (OpenAI, Mistral, etc.). Chaque provider a une URL de base et une famille de modèles. | | **Credential** | Une clé API associée à un provider. On peut avoir plusieurs credentials par provider (par exemple « Production », « Dev »). Les clés sont chiffrées en base. | | **Modèle** | Un modèle IA précis chez un provider (ex. `gpt-4-turbo`, `mistral-large-latest`). Chaque modèle a sa taille de contexte, son type (chat, completion, embedding) et ses paramètres. | | **Prompt système** | Un prompt prêt-à-l'emploi (templating supporté) qu'on peut associer à un contexte (ticket, CRM, cyber, général). | ## Providers supportés en standard ### OpenAI - Endpoint : `https://api.openai.com/v1/chat/completions` - Supporte les modèles classiques (GPT-3.5, GPT-4) et les modèles récents (GPT-4 Turbo, GPT-5, o1). - Header `OpenAI-Organization` géré automatiquement si le credential renseigne une organisation. > ⚠️ Spécificités OpenAI selon le modèle : > - **GPT-3.5 / GPT-4 classique** : supportent `temperature` et `max_tokens`. > - **GPT-4 Turbo** : supportent `temperature` et utilisent `max_completion_tokens`. > - **GPT-5 / o1 (raisonnement)** : utilisent `max_completion_tokens` mais **ne supportent pas** `temperature` ni les system prompts. Ils peuvent être lents (>30s). ### Mistral - Endpoint : `https://api.mistral.ai/v1/chat/completions` - API compatible OpenAI (mêmes formats de requête/réponse). - Supporte `temperature` pour tous les modèles. ### Function calling (tools) Tous les providers compatibles Chat Completions (OpenAI, Mistral, futurs) supportent le **function calling**, c'est-à-dire la capacité pour le modèle d'appeler des outils définis par ISI-APP. Cette fonctionnalité est automatiquement disponible dès qu'un assistant est configuré avec des packs d'outils (voir doc `ai-tool-calling-ui`). ## Configuration côté admin ### 1. Ajouter un credential `/admin/ai` → onglet **Credentials** → **Ajouter** : - Choisir le provider. - Saisir un nom parlant (« Production OpenAI », « Mistral Dev »…). - Coller la clé API — elle sera chiffrée automatiquement à l'enregistrement. - Renseigner éventuellement l'organisation (OpenAI), une URL de base personnalisée (proxy interne par exemple), un timeout (par défaut 30 s). - Cocher **par défaut** si c'est le credential principal du provider. ### 2. Ajouter un modèle `/admin/ai` → onglet **Modèles** → **Ajouter** : - Lier au provider. - Renseigner le nom affiché (« GPT-4 Turbo ») et l'identifiant technique (`gpt-4-turbo`). - Préciser le type (`chat`, `completion`, `embedding`) et la taille du contexte en tokens. - Cocher **par défaut** si c'est le modèle de référence pour ce provider. ### 3. Tester la connexion `/admin/ai` → onglet **Credentials** → menu d'action sur un credential → **Tester la connexion** : - Sélectionne un modèle dans la liste déroulante. - Lance un appel test avec un prompt par défaut. - Affiche le **temps de réponse**, le **modèle utilisé**, les **tokens consommés** et la **réponse de l'IA**. - En cas d'erreur, le message détaille la cause (clé invalide, timeout, modèle inconnu, problème réseau…). C'est le moyen le plus rapide de vérifier qu'un credential fonctionne avant de l'utiliser en production. ## Prompts système Les prompts sont organisés en trois portées : | Portée | Définition | Visibilité | |--------|------------|------------| | **Global** | Pas d'entité associée, pas d'association ciblée | Accessible à tous les tenants | | **Ciblé** | Pas d'entité propriétaire, mais associé à certaines entités | Accessible aux entités listées | | **Privé** | Rattaché à une entité (`_id`) | Accessible uniquement à cette entité | Les prompts supportent des **variables** (`@{{ variable }}`) pour injecter du contexte (utilisateur, date, données métier). ## Variables d'environnement | Variable | Rôle | Défaut | |----------|------|--------| | `AI_DEFAULT_PROVIDER` | Provider utilisé par défaut quand aucun n'est précisé | `openai` | | `AI_LOGGING_ENABLED` | Active le log des requêtes/réponses IA | `true` | | `AI_LOGGING_CHANNEL` | Channel de log dédié | `stack` | > Les clés API ne sont **jamais loggées**, seules les métadonnées (provider, modèle, tokens, durée) le sont. ## Sécurité - **Chiffrement** : toutes les nouvelles clés API sont chiffrées en base via le système de chiffrement Laravel. Une migration progressive est en place pour les clés legacy en clair (le système gère les deux formats). - **Pas de fuite dans les logs** : seules les métadonnées non-sensibles sont écrites. - **Test de connexion isolé** : le test recharge toujours un credential frais depuis la base pour garantir le déchiffrement correct. ## Cas d'usage admin typiques - Ajouter un nouveau provider IA pour un client qui souhaite utiliser son propre compte. - Mettre en place un credential « Dev » distinct du « Prod » pour les tests internes. - Référencer un nouveau modèle qu'OpenAI ou Mistral vient de publier (rien à coder, tout passe par la config). - Ajuster le timeout pour un modèle lent (modèles de raisonnement type o1, GPT-5). - Diagnostiquer un assistant qui ne répond pas : tester directement le credential associé pour isoler le problème. ## Évolutions envisagées - Support des assistants OpenAI (threads / runs). - Streaming des réponses (affichage progressif). - Support des embeddings pour RAG. - Cache de réponses, rate limiting par credential, suivi de consommation par entité. --- > Doc technique : [.claude/technical-docs/ai/ai-connectors-backend.md](../../.claude/technical-docs/ai/ai-connectors-backend.md)