Skill AIQ Deploy

Objectif

Utilisez ce skill pour mettre en place et vérifier un serveur NVIDIA AI-Q Blueprint local ou auto-hébergé en vue de son utilisation par aiq-research.

Ce skill gère l'installation, le déploiement, les vérifications opérationnelles, le dépannage et l'arrêt. Il n'exécute pas lui-même de recherche approfondie. Une fois le déploiement sain, transmettez l'URL du serveur vérifiée à aiq-research. Le workflow reste explicite pour que la validation du déploiement et la transmission soient reproductibles sur tous les clients agents supportés.

Prérequis

Les utilisateurs ont besoin :

• D'accès pour cloner ou mettre à jour https://github.com/NVIDIA-AI-Blueprints/aiq.
• De Git disponible dans le shell.
• D'un runtime de déploiement :
  • Docker Engine avec Docker Compose v2 pour le déploiement local durable par défaut.
  • Python 3.11+ et uv pour le mode processus local ou CLI.
  • Node.js 20+ et npm pour le mode développement UI navigateur local.
  • kubectl 1.28+, Helm 3.12+ et accès à un cluster Kubernetes pour le mode Helm.
• D'un accès réseau à GitHub, aux endpoints de modèles hébergés par NVIDIA et à tout fournisseur de recherche sélectionné.
• Des identifiants stockés en dehors du chat. L'utilisation de modèles hébergés nécessite NVIDIA_API_KEY ; la recherche web nécessite au moins une clé de fournisseur de recherche supporté tel que TAVILY_API_KEY, SERPER_API_KEY ou EXA_API_KEY.
• Une capacité système pour le runtime sélectionné. Le mode Docker Compose démarre le backend AI-Q et PostgreSQL par défaut ; le mode UI navigateur utilise également le port frontend 3000. Les déploiements de modèles auto-hébergés ou RAG peuvent nécessiter des ressources GPU.

Avant d'écrire des secrets, vérifiez que deploy/.env est ignoré :

git check-ignore deploy/.env

Résultat attendu : deploy/.env ou une règle d'ignorance correspondante. S'il n'est pas ignoré, arrêtez-vous et corrigez la règle d'ignorance avant de placer des identifiants dans le fichier.

Instructions

1. Localisez ou clonez le référentiel AI-Q.
2. Confirmez que les fichiers du référentiel attendus existent.
3. Sélectionnez le mode de déploiement.
4. Préparez deploy/.env sans écraser les secrets de l'utilisateur.
5. Vérifiez les prérequis runtime pour le chemin sélectionné.
6. Démarrez le déploiement sélectionné.
7. Exécutez la validation de base.
8. Rapportez l'AIQ_SERVER_URL vérifiée pour aiq-research.
9. Demandez si vous devez exécuter la validation optionnelle de fin de recherche approfondie.

Étape 1 - Localisez ou clonez AI-Q

Si aucun checkout AI-Q n'existe, lisez references/locate-or-clone.md avant de cloner. Dans un checkout existant, confirmez les fichiers requis :

pwd
test -f pyproject.toml
test -f deploy/.env.example
test -d configs

Résultat attendu : pwd affiche le chemin du référentiel AI-Q ; les commandes test se terminent avec le statut 0 et aucune sortie.

Étape 2 - Sélectionnez le mode de déploiement

Si l'utilisateur demande d'installer, déployer, configurer ou exécuter AI-Q sans nommer un mode, posez la question :

Comment voulez-vous exécuter AI-Q ?

1. Backend Skill - service backend uniquement pour aiq-research sans UI navigateur.
2. CLI - terminal interactif AI-Q.
3. UI - application AI-Q navigateur avec backend et frontend.
4. Custom - choisissez une configuration AI-Q existante ou passez en revue la documentation de personnalisation avancée avant le déploiement.

Attendez la réponse de l'utilisateur avant de démarrer les services.

Ne posez pas cette question quand l'utilisateur a déjà spécifié un mode, tel que Docker Compose, Helm, UI, CLI ou backend Agent Skill. Ne posez pas la question complète du mode quand aiq-research vous a routé ici parce qu'une demande de recherche approfondie nécessite un backend. Dans ce cas, préférez Agent Skill backend et demandez uniquement la permission de le démarrer si nécessaire.

Étape 3 - Préparez l'environnement et les secrets

Lisez references/env-and-secrets.md avant de modifier deploy/.env.

if [ ! -f deploy/.env ]; then
  cp deploy/.env.example deploy/.env
  echo "created deploy/.env from deploy/.env.example"
fi

Résultat attendu quand le fichier est manquant : created deploy/.env from deploy/.env.example. Résultat attendu quand le fichier existe déjà : pas de sortie, et le fichier existant est préservé.

Ne jamais afficher les valeurs de secret. Si des identifiants manquent, demandez à l'utilisateur de mettre à jour deploy/.env ; ne lui demandez pas de coller des valeurs secrètes dans le chat.

Étape 4 - Routez vers le chemin de déploiement sélectionné

Faites correspondre l'intention de l'utilisateur, puis lisez le fichier référencé avant d'agir :

Étape 5 - Validez et transmettez

Après le démarrage, lisez references/validation.md et exécutez les vérifications appropriées pour le mode sélectionné. Pour le backend local par défaut, vérifiez la santé :

curl -sf http://localhost:8000/health

Résultat attendu : une réponse JSON de santé réussie ou une réponse réussie vide selon la compilation du serveur. Si la commande échoue, lisez references/troubleshooting.md et diagnostiquez avant de prétendre que le backend est prêt.

aiq-research a besoin d'une URL de serveur AI-Q accessible. Si le backend est sur le port par défaut, aucune configuration supplémentaire n'est nécessaire :

AIQ_SERVER_URL=http://localhost:8000

Si le backend s'exécute ailleurs, dites à l'utilisateur de définir :

export AIQ_SERVER_URL="http://localhost:<PORT>"

Ne continuez pas vers la recherche approfondie ou la validation de fin de recherche approfondie sauf si l'utilisateur le demande ou confirme l'invite de validation post-déploiement. Le critère de succès de ce skill est un serveur déployé et validé de manière basique, pas la qualité de génération de rapports.

Compatibilité des versions

IMPORTANT : Ce skill est conçu pour la version 2.1.0 du NVIDIA AI-Q Blueprint.

Règles de compatibilité du versioning sémantique :

Version Skill : X.Y.Z
Version Blueprint : A.B.C

Compatible SI :
1. A == X (les versions majeures DOIVENT correspondre)
2. B >= Y (la version mineure doit être égale ou supérieure)
3. C peut être n'importe quoi (la version correctif n'affecte pas la compatibilité)

Exemples :

• La version Skill 2.1.0 est compatible avec la version Blueprint 2.1.0.
• La version Skill 2.1.0 est compatible avec la version Blueprint 2.2.0.
• La version Skill 2.1.0 est compatible avec la version Blueprint 2.1.5.
• La version Skill 2.1.0 n'est pas compatible avec la version Blueprint 3.0.0.
• La version Skill 2.1.0 n'est pas compatible avec la version Blueprint 2.0.0.

Si votre version Blueprint n'est pas compatible :

1. Vérifiez s'il existe une version de skill mise à jour correspondant à votre version Blueprint.
2. Utilisez une version Blueprint compatible avec ce skill.
3. Continuez avec prudence uniquement quand l'utilisateur accepte le risque de compatibilité ; les commandes de déploiement ou les noms de config peuvent avoir changé.

Bonnes pratiques de sécurité

• Ne jamais afficher les valeurs secrètes. Vérifiez uniquement si les variables d'environnement requises sont définies.
• Stockez les identifiants dans deploy/.env ou les variables d'environnement, pas dans les transcriptions de chat, l'historique du shell, les fichiers validés ou les commandes d'exemple.
• N'écrasez pas deploy/.env s'il existe déjà.
• Demandez avant tout nettoyage destructif tel que la suppression de volumes Docker avec down -v.
• Ne prétendez pas que FRAG est prêt sauf si RAG_SERVER_URL et RAG_INGEST_URL sont configurés et accessibles.
• Exécutez les commandes de vérification vous-même quand c'est possible.

Limitations

• Ce skill prépare et valide l'infrastructure AI-Q ; il ne juge pas la qualité des rapports de recherche approfondie.
• Il ne peut pas fournir ou inspecter les valeurs secrètes. Les utilisateurs doivent configurer les identifiants en dehors du chat.
• Les chemins Helm, FRAG, config personnalisée et modèle auto-hébergé dépendent de l'infrastructure que l'utilisateur contrôle.
• Le nettoyage destructif, tel que la suppression de volumes Docker, nécessite l'approbation explicite de l'utilisateur.

Exemples

Exemple 1 : Déployer un serveur Skill backend uniquement avec Docker Compose

test -f deploy/.env || cp deploy/.env.example deploy/.env
git check-ignore deploy/.env
cd deploy/compose
BUILD_TARGET=release docker compose --env-file ../.env -f docker-compose.yaml config --quiet
BUILD_TARGET=release docker compose --env-file ../.env -f docker-compose.yaml up -d --build aiq-agent
curl -sf http://localhost:8000/health

Résultat attendu :

deploy/.env
<docker compose démarre aiq-agent et ses dépendances>
<l'endpoint de santé retourne une réponse réussie>

Si Docker, les ports, les identifiants ou les vérifications de santé échouent, lisez references/troubleshooting.md avant de réessayer.

Exemple 2 : Transmettez une URL de backend non par défaut à aiq-research

export AIQ_SERVER_URL="http://localhost:8100"
curl -sf "$AIQ_SERVER_URL/health"

Résultat attendu : une réponse de santé réussie. Alors dites à l'utilisateur de maintenir AIQ_SERVER_URL défini avant d'invoquer aiq-research.

Références

Problèmes courants

Problème : Le port du backend est déjà en usage

Symptômes :

• Docker Compose échoue à lier le port 8000.
• curl -sf http://localhost:8000/health atteint un service inattendu ou échoue.

Causes :

• Un autre backend AI-Q ou serveur de développement local s'exécute déjà.
• PORT dans deploy/.env entre en conflit avec un processus existant.

Solutions :

1. Identifiez le processus :

   lsof -nP -iTCP:8000 -sTCP:LISTEN

2. Soit arrêtez le processus en conflit avec l'approbation de l'utilisateur, soit définissez un port différent dans deploy/.env, tel que PORT=8100.
3. Redémarrez le chemin de déploiement sélectionné et vérifiez :

   curl -sf http://localhost:8100/health

Problème : Les identifiants requis manquent

Symptômes :

• L'infrastructure démarre, mais les demandes de chat ou de recherche s'appuyant sur un modèle échouent.
• Les logs mentionnent unauthorized, forbidden, invalid key ou missing provider configuration.

Causes :

• NVIDIA_API_KEY est manquant ou vide.
• Aucune clé de fournisseur de recherche supporté n'est configurée pour la recherche web.

Solutions :

1. Vérifiez la présence sans afficher les valeurs en suivant references/env-and-secrets.md.
2. Demandez à l'utilisateur de mettre à jour deploy/.env ; ne lui demandez pas de coller des secrets dans le chat.
3. Réexécutez references/validation.md après que l'utilisateur mette à jour les identifiants.

Problème : Le backend est sain mais incompatible avec aiq-research

Symptômes :

• /health réussit, mais /chat ou /v1/jobs/async/agents échoue.
• aiq-research rapporte que les agents asynchrones ne sont pas disponibles.

Causes :

• La config sélectionnée est CLI uniquement ou n'expose pas le backend web/API attendu par le skill.
• BACKEND_CONFIG ou CONFIG_FILE pointe vers la mauvaise config AI-Q.

Solutions :

1. Lisez references/configs.md et confirmez que la config sélectionnée est activée pour l'API.
2. Pour le backend Skill par défaut, utilisez configs/config_web_default_llamaindex.yml.
3. Redémarrez le backend et réexécutez references/validation.md.

Problème : Le nettoyage Docker supprimerait un état utile

Symptômes :

• Le dépannage suggère docker compose down -v.
• L'utilisateur peut avoir des données de job ou de checkpoint PostgreSQL locales qu'il veut conserver.

Causes :

• down -v supprime les volumes Docker.
• Les redémarrages et reconstructions sont souvent suffisants pour les changements de config ou d'image.

Solutions :

1. Préférez un redémarrage normal depuis references/shutdown.md.
2. Demandez l'approbation explicite avant d'exécuter la suppression de volumes.
3. Après le nettoyage, réexécutez le déploiement et la validation depuis l'itinéraire sélectionné.