Configurer l'IA

Configuration et paramètres

Avant toute étape, lisez Avant de commencer et Principes de base du terminal. Ces instructions supposent que vous avez ouvert le monorepo supastack complet dans VS Code ; sa racine package.json marque la racine du référentiel. Dans les commandes pnpm, un package d'espace de travail est une application ou un dossier de code partagé ; dans le produit, un espace de travail est le conteneur de données et la limite de sécurité d'une équipe. corepack pnpm --filter ... sélectionne un package dans le monorepo tandis que les commandes sont exécutées à partir de sa racine. Si vous avez ouvert uniquement un dossier mobile ou de bureau synchronisé, il ne contient pas le backend Web, la configuration Docker ou les scripts racine : exécutez le backend à partir de ce monorepo ou d'un serveur hébergé accessible et utilisez les propres scripts du dossier de plateforme. Une variable d'environnement est un paramètre nommé stocké dans un fichier .env local ou dans votre tableau de bord d'hébergement ; redémarrez l'application concernée après l'avoir modifiée et conservez les secrets du serveur en dehors des valeurs NEXT_PUBLIC_ et EXPO_PUBLIC_.

1. Ouvrez apps/web/.env.local pour le serveur Web local et apps/web/src/agent-runtime.ts pour la sélection du fournisseur ; .env.example est la liste des noms de paramètres pris en charge.

2. Conservez AI_PROVIDER=fake pour le travail d'interface locale, sauf si vous disposez de votre propre compte fournisseur et souhaitez tester la génération réelle ; ne placez jamais les clés du fournisseur dans un paramètre NEXT_PUBLIC_ ou EXPO_PUBLIC_.

3. Démarrez l'application Web à partir de la racine du référentiel avec le corepack pnpm --filter @supastack/web dev. Attendu : les écrans locaux peuvent être explorés sans configurer de fournisseur payant ; la génération réelle nécessite un fournisseur de serveur valide et des choix de modèles activés dans le catalogue de base de données.

Le paramètre par défaut AI_PROVIDER=fake permet des opérations locales déterministes. Configurez les vrais fournisseurs dans l’environnement serveur. Les clés des fournisseurs indiquées dans .env.example couvrent OpenAI, Anthropic et un point de terminaison compatible avec OpenAI.

AI_MODEL_POLICY contient les identifiants de modèles ordonnés pour les alias cheap, fast et smart. Une liste d’alias vide désactive ce choix. Chaque identifiant de modèle doit correspondre à une entrée activée du catalogue de la base de données avec un tarif effectif immuable.

AI_MODEL_POLICY='{"cheap":[],"fast":["catalog-model-id"],"smart":["catalog-model-id"]}'
AGENT_FRAMEWORK=ai-sdk    # ai-sdk | mastra | langgraph | openai-agents

Commandes à copier

Suivez les commentaires pour voir dans quel dossier une commande s'exécute. Si deux terminaux sont étiquetés, ouvrez deux fenêtres de terminal et laissez la première commande s'exécuter pendant que vous utilisez la seconde.

corepack pnpm --filter @supastack/web dev

Processus d’implémentation

Configurez le catalogue et la politique de l’espace de travail avant d’accepter des tâches de production. Le navigateur reçoit les alias activés ; la correspondance des capacités, le choix du modèle, la vérification des droits et le contrôle du budget restent côté serveur.

Ne placez pas les identifiants dans les variables NEXT_PUBLIC_ ou EXPO_PUBLIC_. Pour le mode d’utilisation de clés personnelles, conservez l’enveloppe chiffrée existante et le déchiffrement côté serveur ; ne renvoyez jamais à l’interface une clé de fournisseur enregistrée.

Vérification et dépannage

Si l'application signale qu'aucun modèle d'IA n'est disponible, vérifiez le AI_PROVIDER du serveur, les modèles et les prix activés dans le catalogue d'administration, ainsi que la politique d'alias bon marché/rapide/intelligent. Si un vrai fournisseur renvoie une erreur d'authentification, vérifiez sa clé dans apps/web/.env.local et redémarrez le serveur. Une clé préfixée NEXT_PUBLIC_ serait visible par les navigateurs et devra être supprimée.

Vérifiez les alias désactivés, les capacités manquantes, les droits inactifs et les budgets épuisés. Réservez les essais réels auprès d’un fournisseur à une exécution autorisée séparément. Si aucun alias n’est disponible, inspectez la politique serveur et la configuration du catalogue au lieu d’exposer un sélecteur brut de modèles.