Actif ai functional Revu le 2026-05-22 ai/ai-connectors-backend.md

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