Étendre avec un fournisseur d’IA personnalisé

Ceci est une référence pour développeurs pour ajouter un nouvel adaptateur de fournisseur d’IA (modèle texte, modèle image ou les deux) au moteur d’IA de Structura. Si vous essayez juste de choisir un fournisseur dans wp-admin, voir Paramètres d’IA.

Le moteur d’IA de Structura utilise un motif d’adaptateur : le pipeline (recherche → rédaction → image) parle à un petit ensemble d’interfaces agnostiques au fournisseur, et chaque fournisseur concret — OpenAI, Gemini, Anthropic, Cloud — les implémente. Ajouter un nouveau fournisseur signifie écrire un adaptateur qui satisfait ces interfaces et l’enregistrer auprès du moteur.

Source de vérité : functions/src/ai/engine.ts, specs/ai-provider-refactor-plan.md.

Ce que vous écrirez

Pour un fournisseur texte :

Une classe implémentant TextProviderAdapter, avec :
- id, displayName, supportedModels.
- generate(request): Promise<GenerationResult> — l’appel central.
- estimateCost(request): Promise<CostEstimate> — utilisé pour le suivi de quota Cloud et la ligne de coût post-génération sur la page Journaux.
- validateKey(key) — utilisé par Structura → Paramètres → Moteur d’IA pour confirmer qu’une clé collée est valide avant de sauvegarder.

Pour un fournisseur image :

Une classe implémentant ImageProviderAdapter, avec :
- id, displayName, supportedSizes.
- generateImage(request): Promise<ImageResult>.
- validateKey(key).

La plupart des adaptateurs finissent à 150–300 lignes chacun. Regardez les OpenAIAdapter, GeminiAdapter et AnthropicAdapter existants pour la forme.

Enregistrer l’adaptateur

Ajoutez l’adaptateur à la liste d’export dans functions/src/ai/providers/index.ts.
Ajoutez-le au registre de fournisseurs du moteur pour qu’il soit visible par le pipeline.
Ajoutez une entrée correspondante dans le paquet de types partagé (packages/types) pour que la page de paramètres Moteur d’IA du client puisse rendre les bons champs de formulaire.
Faites remonter toute config spécifique au fournisseur (par ex. un override d’URL de base pour modèles auto-hébergés) dans le formulaire de paramètres.

Tests

Le motif adaptateur rend les adaptateurs éminemment testables :

Testez votre adaptateur unitairement contre des fixtures enregistrés — pas d’appels API réels en CI.
Ajoutez des tests d’intégration contre une clé de dev si possible ; protégez-les derrière une variable d’environnement pour que CI sans clés puisse les sauter.

Voir functions/src/ai/__tests__/ pour les motifs de tests existants.

Ce que le moteur passe à votre adaptateur

Une GenerationRequest ressemble à :

prompt — les prompts système + utilisateur assemblés pour cette étape du pipeline.
model — le modèle préféré de l’appelant (votre adaptateur peut opposer un veto).
temperature, maxTokens, etc.
context — métadonnées structurées (ID de campagne, nom d’étape) pour vos journaux, jamais alimentés au modèle.

Votre adaptateur renvoie un GenerationResult avec :

content — la sortie du modèle.
usage — jetons (ou équivalent) consommés.
costUsd — votre coût calculé, pour que le moteur puisse journaliser et facturer avec précision.

Gestion des erreurs

Les adaptateurs lèvent des erreurs typées :

AIAuthError — mauvaise clé, identifiant révoqué.
AIRateLimitError — limitation transitoire.
AIQuotaError — quota épuisé / problème de facturation.
AIProviderError — fourre-tout pour autres 4xx/5xx.

Le moteur utilise le type pour décider s’il réessaie, fait échouer l’exécution ou fait remonter un message spécifique sur la page Journaux.

Livrer

Une fois votre adaptateur en place et testé :

Coupez un commit feat:. Le changelog nommera le fournisseur automatiquement.
Mettez à jour Paramètres d’IA avec les étapes de configuration du nouveau fournisseur (à ce stade, vous écrivez pour les utilisateurs finaux, pas les développeurs).