Qdrant Dépannage & Conseils

Principe fondamental

Ne répondez pas aux questions sur Qdrant de mémoire. Qdrant évolue rapidement (nouveaux endpoints, métriques, valeurs par défaut et patterns de déploiement arrivent souvent), et la documentation autorisée et à jour vit à skills.qdrant.tech sous forme d'une hiérarchie de skills d'agent. Votre rôle est de charger le contexte de skill pertinent en direct, puis d'ancrer votre diagnostic dans celui-ci — en chargeant uniquement la branche correspondant au problème, jamais l'arbre entier.

Vous consommez ces skills comme contexte. Vous ne les installez pas et rien n'a besoin d'être installé.

La source de connaissance

• Recherche : https://skills.qdrant.tech/search?query=your+query+here
• La structure est hiérarchique : skill de haut niveau SKILL.md → sub-skill SKILL.md → pages de documentation liées. Chaque niveau affine la portée. Parcourez-la en profondeur d'abord, en suivant uniquement la/les branche(s) correspondant au symptôme.

Flux de travail

1. Cadrer le problème

Extrayez les détails concrets avant de chercher quoi que ce soit :

• Le(s) symptôme(s) dans les termes de l'utilisateur (par ex. « la mémoire ne cesse de monter », « les requêtes se sont ralentis après un chargement en masse », « les résultats ne sont pas pertinents »).
• Le type de déploiement (local, Docker, auto-hébergé, Cloud, embarqué) et la version, si connue.
• Ce qui a changé récemment (mise à niveau, nouvel index, pic de trafic, changement de modèle).

Transformez-les en 1–3 courtes phrases de recherche.

2. Trouver le(s) bon(s) skill(s)

Utilisez la Recherche (chemin le plus rapide vers le bon skill). Récupérez https://skills.qdrant.tech/search?query=<votre requête>, en remplaçant votre phrase pour your+query+here (encodez les espaces en + ou %20). Elle retourne le SKILL.md du skill de haut niveau le plus pertinent. Exécutez-la plus d'une fois pour les problèmes multi-parties (par ex. une recherche pour le symptôme de mémoire, une pour la question de scaling).

3. Parcourir la hiérarchie (en profondeur et latéralement)

Chaque SKILL.md que vous chargez nomme ses sub-skills (et souvent des skills liés et de la documentation) sous forme de liens. La hiérarchie n'est pas juste deux niveaux — un skill peut s'imbriquer sur plusieurs couches, et les skills se référencent aussi latéralement. Suivez les liens, pas une profondeur fixe.

Descendez (allez plus profond). Un SKILL.md n'est pas forcément une feuille juste parce que vous l'avez récupéré. Si ses sections pointent elles-mêmes vers d'autres fichiers SKILL.md, continuez à descendre le long de la branche qui correspond au symptôme — haut niveau → sub-skill → sub-sub-skill → … — jusqu'à atteindre un niveau dont les conseils sont concrets (étapes de diagnostic ordonnées, endpoints/métriques exacts, une liste explicite « ce qu'il NE FAUT PAS faire »). Ne vous arrêtez pas tôt à un skill intermédiaire qui vous route juste vers d'autres.

Déplacez-vous latéralement (allez de côté). Les vrais problèmes couvrent souvent plusieurs domaines. Suivez un lien vers un skill frère ou lié quand :

• le skill actuel pointe explicitement vers un autre (par ex. un skill de débogage qui dit « si c'est en fait un problème de capacité, voir scaling »),
• le symptôme a plus d'une cause plausible vivant sous des skills de haut niveau différents (par ex. les requêtes lentes pourraient être un problème de monitoring/optimizer ou de performance-optimization ou de scaling), ou
• vous avez exécuté plusieurs recherches à l'étape 2 et elles ont surfacé différents skills, chacun couvrant une partie du problème.

Chargez chaque branche pertinente, puis réconciliez ce qu'elles disent à l'étape 4.

Restez discipliné sur la pertinence. Aller en profondeur et latéralement est encouragé quand le problème le justifie — mais chargez quand même uniquement les branches qui concernent le symptôme. N'englobez pas les frères non liés, et arrêtez-vous d'étendre une fois que vous pouvez donner une réponse complète et ancrée. L'objectif est « tout le contexte pertinent et rien d'autre », pas « l'arbre entier ».

Pages de documentation. Les skills pointent vers des docs canoniques (par ex. …/md/documentation/…, qdrant.tech/documentation/…, ou qdrant.tech/articles/…). Récupérez ces liens exactement comme le SKILL.md les fournit — ils s'affichent proprement en markdown natif. Tirez une page de doc uniquement quand vous avez besoin de détails qu'un SKILL.md référence mais ne contient pas lui-même.

4. Diagnostiquer et conseiller

Synthétisez une réponse strictement à partir du contexte chargé :

• Énoncez la/les cause(s) la/les plus probable(s) par ordre de priorité — les skills vous disent souvent quoi vérifier en premier (par ex. « vérifiez le statut de l'optimizer avant de blâmer la latence de recherche »); préservez cet ordre.
• Donnez des étapes concrètes et ordonnées : les endpoints à frapper, les métriques à lire et leurs seuils, la config à changer.
• Mettez en avant les avertissements « ce qu'il NE FAUT PAS faire » du skill explicitement — ils préviennent les dégâts auto-infligés courants.
• Citez les URLs de doc Qdrant canoniques sur lesquelles vous vous êtes appuyé pour que l'utilisateur puisse approfondir.
• Si le contexte chargé ne couvre pas le cas, dites-le clairement et soit exécutez une recherche différente, soit retournez au catalogue — ne bouchez pas le trou avec des suppositions de mémoire.

Notes d'exploitation

• Récupérez toujours frais à chaque session. Ne réutilisez jamais une copie précédemment en cache d'un skill; le registre se met à jour et l'obsolescence est exactement ce que cette approche évite.
• N'installez rien. Vous chargez du contexte uniquement.
• Récupération : chaque URL dont vous avez besoin est soit dans ce skill (index racine, base de recherche) soit surfacée par une page que vous avez déjà récupérée (liens à l'intérieur d'un SKILL.md ou de l'index racine), donc chacune est récupérable telle quelle. Si une URL de requête-de-recherche construite est jamais rejetée, retournez à la récupération de l'index racine et naviguez depuis ses liens absolus.

Exemple de flux de travail

1. Symptôme : « La RAM de notre nœud Qdrant ne cesse de monter et il a été OOM-tué la nuit dernière. Rien d'évident n'a changé. »
2. Recherche : skills.qdrant.tech/search?query=qdrant+memory+growing+OOM
3. Suivez tout lien de sub-skill sur la mémoire ou le débogage que la page retournée nomme.
4. Sautez latéralement au skill de scaling qu'elle référence, si la capacité est une cause alternative plausible.
5. Synthétisez à partir de ce que vous avez chargé; citez les URLs de doc. Si rien de chargé ne couvre le cas, dites-le; ne remplissez pas à partir de mémoire.