qdrant-advisor

Qdrant のトラブルシューティングとアドバイス

基本原則

Qdrant に関する質問に、記憶だけを頼りに回答してはいけません。Qdrant は急速に進化しており（新しいエンドポイント、メトリクス、デフォルト設定、デプロイパターンが頻繁に追加されます）、最新かつ信頼できるガイダンスは、エージェントスキルの階層として skills.qdrant.tech にあります。あなたの役割は、関連するスキルのコンテキストをその場で読み込み、それに基づいて診断することです。問題に合致するブランチだけを読み込み、ツリー全体を読み込んではいけません。

これらのスキルは、コンテキストとして利用します。インストールするものではなく、何もインストールする必要はありません。

情報源

• 検索：https://skills.qdrant.tech/search?query=your+query+here
• 構造は階層型です。トップレベルのスキル SKILL.md → サブスキル SKILL.md → リンク先のドキュメントページという構成です。各階層で対象範囲が絞られます。症状に合致するブランチだけをたどり、深さ優先で進めてください。

ワークフロー

1. 問題を整理する

情報を取得する前に、具体的な詳細を抜き出してください。

• ユーザーの言葉で表された症状（例：「メモリ使用量が増え続ける」「一括アップロード後にクエリが遅くなった」「結果に関連性がない」）。
• デプロイの種類（ローカル、Docker、セルフホスト、Cloud、組み込み）と、分かる場合はバージョン。
• 最近の変更点（アップグレード、新しいインデックス、トラフィックの急増、モデルの切り替え）。

これらを、短い検索フレーズ1～3個にまとめてください。

2. 適切なスキルを見つける

検索を使います（適切なスキルを最速で見つける方法です）。 https://skills.qdrant.tech/search?query=<your query> を取得し、your+query+here を検索フレーズに置き換えてください（スペースは + または %20 でエンコードします）。最も関連性の高いトップレベルスキルの SKILL.md が1つ返されます。複数の要素を含む問題の場合は、複数回検索してください（例：メモリの症状で1回、スケーリングの質問で1回）。

3. 階層をたどる（深く、横にも）

読み込んだ SKILL.md には、サブスキル（および関連するスキルやドキュメント）へのリンクが記載されています。階層は2段とは限りません。スキルは複数階層にわたってネストすることがあり、スキル同士が横断的に参照し合うこともあります。決まった深さで止めず、リンクをたどってください。

下へ進む（さらに深くたどる）。 SKILL.md を取得したからといって、必ずしもそれが末端とは限りません。セクション内にさらに別の SKILL.md へのリンクがある場合は、症状に合致するブランチを引き続きたどってください。トップレベル → サブスキル → サブサブスキル → …と進み、具体的な対処ができるレベル（順序立てた診断手順、正確なエンドポイント／メトリクス、明示的な「してはいけないこと」の一覧）に到達するまで続けます。次のスキルへの案内しか示していない中間スキルで早々に止めないでください。

横に進む（横方向にもたどる）。 実際の問題は複数の領域にまたがることがよくあります。次のような場合は、リンクから同階層または関連するスキルに進んでください。

• 現在のスキルが別のスキルを明示的に参照している（例：デバッグスキルで、「実際には容量の問題である場合は scaling を参照」と案内している）。
• 症状の原因として、複数のトップレベルスキルにまたがるものが考えられる（例：クエリが遅い場合、モニタリング／オプティマイザー、パフォーマンス最適化、またはスケーリングの問題が考えられる）。
• 手順2で複数回検索し、それぞれ問題の一部を扱う異なるスキルが見つかった。

関連する各ブランチを読み込んでから、手順4で内容を整理してください。

関連性を保ってください。 問題に応じて深く、横にもたどることは推奨されますが、症状に関係するブランチだけを読み込んでください。無関係な同階層のスキルまで調べず、根拠に基づいた完全な回答ができる時点で展開を止めてください。目標は「関連するコンテキストをすべて、余計な情報は含めずに」です。「ツリー全体」ではありません。

ドキュメントページ。 スキルから、正規のドキュメント（例：…/md/documentation/…、qdrant.tech/documentation/…、qdrant.tech/articles/…）へリンクされていることがあります。これらのリンクは、SKILL.md に記載されたとおりのURLで取得してください。リンク先はそのまま整ったMarkdownとして表示されます。SKILL.md が参照している詳細を含んでいない場合に限り、ドキュメントページを取得してください。

4. 診断してアドバイスする

読み込んだコンテキストのみに基づいて回答をまとめます。

• 最も可能性の高い原因を優先順位順に示します。スキルでは、最初に確認すべき項目（例：「検索の遅延を疑う前に、オプティマイザーの状態を確認する」）が示されることがよくあります。その順序を維持してください。
• 具体的な手順を順序立てて示します。アクセスするエンドポイント、確認するメトリクスとそのしきい値、変更する設定を記載してください。
• スキルにある**「してはいけないこと」の警告**を明示してください。よくある、自ら問題を悪化させる行為を防ぐためのものです。
• 参照したQdrant の公式ドキュメント URLを記載し、ユーザーが詳しく調べられるようにしてください。
• 読み込んだコンテキストでケースを扱っていない場合は、その旨を明確に伝え、別の検索を実行するかカタログを参照してください。記憶に基づく推測で空白を埋めないでください。

運用上の注意

• **毎回、必ず最新の情報を取得してください。**以前キャッシュしたスキルを再利用しないでください。レジストリは更新されるため、この方法で古い情報を避けられます。
• **何もインストールしないでください。**コンテキストの読み込みのみを行います。
• **取得について：**必要な URL はすべて、このスキル（ルートインデックス、検索ベース URL）に含まれているか、すでに取得したページ（SKILL.md 内のリンクまたはルートインデックス）に記載されています。そのため、それぞれそのまま取得できます。構築した検索クエリ URL が拒否された場合は、ルートインデックスを取得し、絶対リンクをたどってください。

ワークフローの例

1. 症状：「Qdrant ノードの RAM 使用量が増え続け、昨夜 OOM によってプロセスが強制終了されました。特に何も変えていません。」
2. 検索：skills.qdrant.tech/search?query=qdrant+memory+growing+OOM
3. 返されたページにメモリまたはデバッグに関するサブスキルへのリンクがあれば、そのリンクをたどります。
4. 容量が原因として考えられる場合は、関連するスケーリングスキルへ横断的に移動します。
5. 読み込んだ内容に基づいて回答をまとめ、ドキュメント URL を記載します。該当する内容が読み込めなかった場合は、その旨を伝えてください。記憶で補わないでください。