Configuration
Fournisseurs du module IA, variables d'environnement, permissions ai.use et ai.view, entrée d'admin, page IA et tuile du tableau de bord.
Le module lit toute sa configuration dans les variables d'environnement, à chaque appel et jamais à l'import : changer de modèle prend effet au prochain appel, et la clé n'est écrite nulle part ailleurs.
Fournisseurs
FRAZA_MODULE_AI_PROVIDER | Fournisseur | Clé | Adresse par défaut |
|---|---|---|---|
anthropic | Anthropic (Claude), API Messages. | Requise. | https://api.anthropic.com |
openai | OpenAI, API Chat Completions. | Requise. | https://api.openai.com/v1 |
google | Google (Gemini), generateContent. | Requise. | https://generativelanguage.googleapis.com/v1beta |
mistral | Mistral, API Chat Completions. | Requise. | https://api.mistral.ai/v1 |
openai-compatible | Un service qui reprend l'API Chat Completions d'OpenAI : OpenRouter, Groq, vLLM, LM Studio. | Facultative. | Aucune : FRAZA_MODULE_AI_BASE_URL est requise. |
ollama | Ollama, sur un serveur du projet ou hébergé. | Facultative. | http://localhost:11434 |
Les six reçoivent la même demande, écrite dans la forme que chacun attend, et rendent la même réponse au code. Un prompt écrit pour un fournisseur marche donc avec un autre, à la qualité du modèle près.
Un service compatible peut ignorer le schéma. Le module lui envoie le schéma de réponse sans le mode strict, que tous ne connaissent pas. Il vérifie de toute façon chaque réponse lui-même, et redemande une fois une réponse hors schéma : la garantie reste la même, au prix d'un appel de plus quand le modèle s'écarte.
Avec Ollama, rien ne quitte le serveur. C'est le seul fournisseur qui peut tourner sur une machine du projet. Les autres reçoivent le texte des prompts, et les images qu'ils portent.
Une clé, quand elle est présente, part pour openai-compatible et ollama dans un en-tête Authorization: Bearer. Un Ollama hébergé en demande une, un Ollama local non.
Variables
| Variable | Requise | Défaut | Effet |
|---|---|---|---|
FRAZA_MODULE_AI | oui | true active le module. Toute autre valeur le laisse ignoré : aucune route, aucune entrée d'admin, aucune intégration. | |
FRAZA_MODULE_AI_PROVIDER | oui | L'un des six fournisseurs du tableau ci-dessus. | |
FRAZA_MODULE_AI_MODEL | oui | Le modèle, tel que le fournisseur le nomme dans sa documentation, ou tel qu'Ollama l'a téléchargé. Aucune valeur par défaut : un nom choisi par le module serait périmé avant sa prochaine version. | |
FRAZA_MODULE_AI_API_KEY | selon le fournisseur | Clé d'API. Requise pour anthropic, openai, google et mistral. Secret. | |
FRAZA_MODULE_AI_BASE_URL | pour openai-compatible | voir les fournisseurs | Adresse de l'API, complète, en https:// ou http://. Remplace aussi l'adresse d'un autre fournisseur, pour passer par un relais. Les / finaux sont retirés. |
FRAZA_MODULE_AI_TIMEOUT_MS | non | 120000 | Attente maximale d'un appel, en millisecondes, de 5 000 à 600 000. |
FRAZA_MODULE_AI_RETENTION_DAYS | non | 90 | Jours d'historique gardés par la tâche ai-retention, de 1 à 3 650. Une valeur illisible est signalée sur la page IA, sans empêcher les appels. |
Une valeur hors bornes n'est pas ramenée dans l'intervalle : elle rend la configuration invalide, et la page IA dit laquelle. Une valeur faite d'espaces compte comme absente.
La clé est un secret. Elle ne va ni dans .env.example ni dans un .env.local suivi par git : fraza-doctor le signale comme bloquant. La page IA ne l'affiche jamais, elle dit seulement si elle est présente.
Le délai couvre un appel, pas un prompt. Une réponse hors schéma redemandée fait deux appels, chacun avec son délai. Un modèle qui raisonne avant de répondre peut prendre plus d'une minute sur un long contenu : les deux minutes par défaut laissent cette marge.
Permissions
| Clé | Nom | Portée |
|---|---|---|
ai.use | Utiliser l'IA | Lancer les boutons d'IA des écrans de l'admin, et voir les propositions de l'IA à côté d'un contenu. |
ai.view | Voir la page IA | Configuration du fournisseur, prompts déclarés, historique des appels, jetons consommés, et le bouton « Tester ». |
Les deux sont groupées sous IA dans /admin/roles. Elles sont attribuées au rôle admin au moment du fraza-db init, et distribuables ensuite à d'autres rôles.
ai.use ne suffit pas toujours. Un prompt peut demander une permission de plus : celui de Posts demande posts.manage, celui de Médias media.upload. Le bouton n'apparaît qu'au compte qui a les deux. Voir Boutons.
Les deux permissions sont distinctes parce qu'elles ne visent pas les mêmes personnes : une rédactrice lance les boutons sans avoir à voir la consommation du site, et qui suit la facture du fournisseur n'a pas besoin de rédiger.
Entrée d'admin
| Propriété | Valeur |
|---|---|
| Section | IA, groupe tools, icône BrainIcon, ordre 90. |
| Item | IA, ordre 1. |
| Chemin | ai, relatif à l'admin (/admin/ai par défaut). |
| Permission | ai.view |
La section ne contient qu'un item : la barre latérale la rend comme une entrée racine cliquable, sous le libellé « Outils ». Voir Étendre l'admin.
La page IA
/admin/ai réunit quatre blocs, de haut en bas.
| Bloc | Contenu |
|---|---|
| Configuration | Fournisseur, modèle, présence de la clé, et l'adresse d'un service compatible ou d'Ollama, puisqu'elle dit où partent les données. Le problème de configuration, s'il y en a un. Les ajustements de ai.js qui ne trouvent aucun prompt. Le bouton « Tester ». |
| Consommation | Jetons envoyés et jetons reçus sur 30 jours, appels en échec sur le total, puis les jetons par prompt. |
| Prompts déclarés | Chaque prompt, par les modules ou par ai.js : son nom, son libellé, son écran ou « Code seulement », sa source, et les marques « Ajusté par ai.js » et « Désactivé ». |
| Historique des appels | Les appels, du plus récent au plus ancien, 25 par page, filtrables en réussis ou en échec : prompt, résultat et message d'erreur, origine (bouton, code, test), modèle, jetons envoyés et reçus, durée, date. |
« Tester » est désactivé tant que la configuration n'est pas complète. Il compte dans le même budget que les boutons, voir Boutons.
Tuile du tableau de bord
| id | Ordre | Largeur | Permission | Contenu |
|---|---|---|---|---|
ai-usage | 80 | 1, jusqu'à 2 | ai.view | Les jetons du mois en cours, depuis le premier jour en UTC, et les appels en échec. Signale une IA non configurée. |
La tuile mène à la page IA. Quand ses chiffres ne peuvent pas être lus, elle disparaît plutôt que d'afficher zéro. Voir Widgets du tableau de bord.
Notes
- La configuration est vérifiée à chaque appel, pas au démarrage : un site démarre même sans fournisseur, et chaque appel rend alors l'erreur
not_configured, avec le nom de la variable en cause. - Changer de fournisseur ne change pas l'historique : chaque ligne garde le fournisseur et le modèle de son appel.
- Une
FRAZA_MODULE_AI_RETENTION_DAYShors bornes compte comme une configuration invalide : la page IA la nomme, « Tester » se désactive etisAiConfigured()rendfalse.