Skill de déploiement AIQ

Objectif

Utilisez ce skill pour démarrer et vérifier un serveur NVIDIA AI-Q Blueprint local ou auto-hébergé pour utilisation par aiq-research.

Ce skill gère la configuration, le déploiement, les vérifications opérationnelles, la résolution de problèmes et l'arrêt. Il n'exécute pas la recherche approfondie lui-même. Une fois le déploiement sain, transmettez l'URL du serveur vérifié à aiq-research.

Prérequis

Les utilisateurs ont besoin de :

• Accès pour cloner ou mettre à jour https://github.com/NVIDIA-AI-Blueprints/aiq.
• Git disponible dans le shell.
• 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 avec interface utilisateur locale.
  • kubectl 1.28+, Helm 3.12+ et accès à un cluster Kubernetes pour le mode Helm.
• Accès réseau à GitHub, aux endpoints de modèles hébergés par NVIDIA et à tout fournisseur de recherche sélectionné.
• 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é telle que TAVILY_API_KEY, SERPER_API_KEY ou EXA_API_KEY.
• 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 interface utilisateur 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 les secrets, vérifiez que deploy/.env est ignoré :

git check-ignore deploy/.env

Sortie attendue : deploy/.env ou une règle d'ignore correspondante. S'il n'est pas ignoré, arrêtez et corrigez la règle d'ignore avant de placer les identifiants dans le fichier.

Instructions

1. Localisez ou clonez le repository AI-Q.
2. Confirmez l'existence des fichiers repository attendus.
3. Sélectionnez le mode de déploiement.
4. Préparez deploy/.env sans écraser les secrets 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 basique.
8. Rapportez l'AIQ_SERVER_URL vérifié pour aiq-research.
9. Demandez si la validation de completion de recherche approfondie optionnelle doit être exécutée.

Étape 1 - Localiser ou cloner AI-Q

Si aucune extraction AI-Q n'existe, lisez references/locate-or-clone.md avant de cloner. Dans une extraction existante, confirmez les fichiers requis :

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

Sortie attendue : pwd affiche le chemin du repository AI-Q ; les commandes test se terminent avec le statut 0 et aucune sortie.

Étape 2 - Sélectionner 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 interface utilisateur navigateur.
2. CLI - assistant terminal interactif AI-Q.
3. UI - application navigateur AI-Q avec backend et frontend.
4. Personnalisé - choisissez une config AI-Q existante ou consultez la documentation d'customisation 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 Agent Skill backend. Ne posez pas la question complète du mode quand aiq-research vous a orienté ici parce qu'une demande de recherche approfondie nécessite un backend. Dans ce cas, privilégiez Agent Skill backend et demandez uniquement la permission de le démarrer si nécessaire.

Étape 3 - Préparer 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

Sortie attendue quand le fichier manque : created deploy/.env from deploy/.env.example. Sortie attendue quand le fichier existe déjà : aucune sortie, et le fichier existant est préservé.

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

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

Faites correspondre la demande utilisateur, puis lisez le fichier référencé avant d'agir :

Étape 5 - Valider et transmettre

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

Sortie attendue : une réponse JSON de santé réussie ou une réponse réussie vide selon la construction 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 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 dans la recherche approfondie ou la validation de completion de recherche approfondie à moins que l'utilisateur ne le demande ou ne confirme l'invite de validation post-déploiement. Le critère de succès de ce skill est un serveur déployé et fondamentalement validé, non la qualité de la génération de rapport.

Compatibilité des versions

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

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

Version du skill : X.Y.Z
Version du 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 de patch n'affecte pas la compatibilité)

Exemples :

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

Si votre version Blueprint n'est pas compatible :

1. Vérifiez la disponibilité d'une version mise à jour du skill correspondant à votre version Blueprint.
2. Utilisez une version Blueprint compatible avec ce skill.
3. Procédez avec prudence seulement 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é

• N'affichez jamais les valeurs de secret. Vérifiez uniquement que 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 quand il existe déjà.
• Demandez avant le nettoyage destructeur 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 si possible.

Limitations

• Ce skill prépare et valide l'infrastructure AI-Q ; il ne juge pas la qualité du rapport de recherche approfondie.
• Il ne peut pas fournir ou inspecter les valeurs de secret. 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 destructeur, 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

Sortie attendue :

deploy/.env
<docker compose démarre aiq-agent et les 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 : Transmettre une URL de backend non-par défaut à aiq-research

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

Sortie attendue : une réponse de santé réussie. Ensuite, dites à l'utilisateur de garder 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à utilisé

Symptômes :

• Docker Compose échoue à se lier au 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 le chat avec support de modèle ou les demandes de recherche échouent.
• Les journaux mentionnent non autorisé, interdit, clé invalide ou configuration de fournisseur manquante.

Causes :

• NVIDIA_API_KEY manque ou est 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 les secrets dans le chat.
3. Réexécutez references/validation.md après que l'utilisateur a mis à jour les identifiants.

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

Symptômes :

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

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 sur la mauvaise config AI-Q.

Solutions :

1. Lisez references/configs.md et confirmez que la config sélectionnée est habilitée à 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 :

• La résolution de problèmes suggère docker compose down -v.
• L'utilisateur peut avoir des données de job ou de checkpoint PostgreSQL locales qu'il souhaite conserver.

Causes :

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

Solutions :

1. Privilégiez 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 la route sélectionnée.