Vector Retrieval Service for Milvus:Alibaba Cloud Milvus ナレッジベースを使用した開発トラブルシューティングアシスタントの構築

ソリューション概要

このチュートリアルは、Alibaba Cloud Milvus ナレッジベースを使用したインテリジェントなカスタマーサービス Q&A アプリケーションの構築 を基に構築されています。エンドツーエンドのパイプラインは同一です。コンソールでタグを定義 → タグ別にソースファイルをバッチインポート → バージョンを公開 → SDK を通じて取得 (オプションのタグフィルタリング付き) → LLM にソースの引用付きの回答を生成させる → Flask で Q&A ページを配信。そのチュートリアルのエンジニアリングコード (kb_client.py、upload.py、app.py、templates/index.html、start.sh) を再利用し、ステップ 4：再利用コードの修正 で説明する 2 つの変更を加えます。このドキュメントでは、開発トラブルシューティングシナリオのために変更する必要がある点のみを説明します。モジュールタグ、用語の完全一致のための取得パラメーター、HTML ソースファイルの処理、および高リスクコマンドと空の結果に対する制約です。

最初のバージョンでは、単一のシステムから 5〜20 個のソースファイルのみを選択し、検証後に範囲を拡大します。プロセス全体には約 20〜30 分かかり、ドキュメントの解析時間はソースファイルの数とサイズによって異なります。

前提条件

• Milvus ナレッジベースが作成されており、その [Knowledge Base ID] (例：kd-803ae9b10cc31) を記録していること。

• Alibaba Cloud アカウントで RAM ユーザーが作成されており、[Use Permanent AccessKey Access] が選択され、システムポリシー AliyunMilvusFullAccess がアタッチされていること。

• OpenAI chat/completions プロトコルをサポートする LLM エンドポイントとその API キーが準備できていること。

• Python 3.8 以降がローカルにインストールされていること。

• ソリューション概要 で参照されているチュートリアルに従って、プロジェクトディレクトリと 5 つの再利用ファイル (kb_client.py、upload.py、app.py、templates/index.html、start.sh) がセットアップされていること。

• ソースファイルにシークレット、トークン、または内部ネットワークアカウントが含まれていないこと。

ステップ 1：モジュールタグの定義

ナレッジベース詳細ページの [Basic Information] で、[Tags] > [Manage] を選択し、次の 3 つのタグを追加します。各タグのフィールドタイプを string に設定します。タイプのドロップダウンはタグ名入力ボックスの右側にあり、オプションは string、int64、list、float32、bool です。

タグ名 version は、取得リクエストでナレッジベースの公開バージョンを表す version パラメーターと同じ名前ですが、両者は互いに影響しません。タグは tagFilter.field で使用され、取得バージョンはリクエストのトップレベルに配置されます。混乱が懸念される場合は、代わりにタグ名を apiVersion にしてください。

このシナリオでは、module タグが最も重要な設計判断です。異なるシステムでは、まったく同じ名前の API パスを持つことがよくあり、モジュールによるフィルタリングがないと互いに干渉してしまいます。このテストでは、user-service と order-service は両方とも同じパス GET /api/v2/orders/{orderId} を持っています。このパスを検索したとき：

ステップ 2：ソースファイルとインポートマニフェストの準備

このステップでは、ソースファイルを収集し、インポートマニフェストで各ファイルに注釈を付け、ナレッジベースがそれらをどのようにチャンキングするかを設定します。

• ソースファイルを documents/ ディレクトリに配置します。Markdown、HTML、PDF、DOCX、TXT がサポートされています。ソースファイルには完全なエラーコード、API パス、バージョン番号を省略せずに含めてください — テストでは、エラーコードとフルパスの両方を正確に取得できました。

• documents.jsonl を作成し、各ソースファイルにそのモジュール、ドキュメントタイプ、バージョンを注釈として付けます。

  {"path": "documents/order-api.md", "metadata": {"module": "order-service", "docType": "API", "version": "v2"}}
  {"path": "documents/order-timeout-runbook.md", "metadata": {"module": "order-service", "docType": "Runbook", "version": "v2"}}
  {"path": "documents/order-error-codes.html", "metadata": {"module": "order-service", "docType": "ErrorCode", "version": "v2"}}
  {"path": "documents/order-postmortem-2026-06.md", "metadata": {"module": "order-service", "docType": "Postmortem", "version": "v2"}}

• API リファレンス、ランブック、エラーコードテーブル、ポストモーテムをセットとしてインポートし、docType で区別します。テストでは、エラーコードについて質問したところ、4 種類のソースファイルすべてが同時にヒットし、モデルは「意味 → トラブルシューティング手順 → 過去のケース」という完全な回答を生成しました。

ステップ 3：取得パラメーターとプロンプトの設定

開発のトラブルシューティングに関するクエリは、主にエラーコード、API パス、コマンドです。これらは用語の完全一致で検索されるため、パラメーターは他のシナリオと大きく異なります。

{
  "retrieval": {
    "page_size": 6,
    "candidate_count": 64,
    "min_score": 0.05,
    "semantic_weight": 0.15,
    "enable_query_expansion": false,
    "rerank_model_name": "",
    "tag_filter": {
      "relation": "and",
      "conditions": [
        {"field": "module", "op": "=", "value": "order-service"}
      ]
    }
  },
  "scenario": {
    "title": "開発ドキュメントとトラブルシューティングアシスタント",
    "system_prompt": "あなたは開発ドキュメントアシスタントです。取得した資料にのみ基づいて回答してください。API 名、エラーコード、コマンド、コードはそのまま保持してください。トラブルシューティング手順を順にリストアップし、[Source N] として引用してください。書き込み操作や高リスクのコマンドが含まれる場合は、リスクレベルを明記し、手動での確認を促してください。取得した資料が空の場合は、資料が不十分であることのみを返信し、いかなる変更操作も行わないように警告してください。",
    "image_enabled": false,
    "sample_questions": [
      "注文クエリ API の必須パラメーターは何ですか？",
      "接続タイムアウトのトラブルシューティングはどのような順序で行うべきですか？",
      "このエラーコードはどのドキュメントに記載されていますか？"
    ]
  }
}

以下に、このシナリオに合わせて調整したパラメーターを説明します。例の残りのフィールドは、参照元のチュートリアルから引き継がれています。

• semantic_weight: 0.15：最終スコアの重み付け係数。スコアは score ≈ (1 - semantic_weight) × keywordScore + semantic_weight × semanticScore (ランク特徴量も追加される場合があります) として計算され、min_score はこの最終スコアに対して事後フィルタリングを実行します。このシナリオでは 0.15 を使用して、エラーコードや API パスなどの用語の完全一致のキーワードスコアがランキングを支配するようにします。semantic_weight は min_score と相互作用するため、semantic_weight と min_score の同時調整 で説明されているように、両方を一緒に調整してください。

• enable_query_expansion: false：クエリ拡張は無効になっており、エラーコードや API 名が書き換えられないようにします。テストでは、これを有効にすると、クエリ ORD-50021 の keywordScore が 0.283 から 0.226 に低下し、クエリ ORD-42901 でリコールされた結果の数が 2 から 1 に減少しました。用語の完全一致の取得では無効にしておいてください。

• tag_filter が module を固定：これにより、異なるシステムの同名 API が互いに干渉するのを防ぎます。効果については ステップ 1：モジュールタグの定義をご参照ください。1 つのエントリポイントで複数のモジュールをカバーする必要がある場合は、{"field": "module", "op": "in", "value": ["order-service", "user-service"]} を使用します。

• rerank_model_name が空の場合は、再ランキングが有効になっていないことを意味します。エラーコードの完全一致はキーワードスコアに依存するため、再ランキングによるメリットは限定的です。

• op は =、in、および not in のみをサポートします。テストでは、≠、>、≥、<、≤、empty、not empty、start with、end with はサイレントに無視され、すべてのデータが返されます (エラーは報告されません)。contains および not contains は、部分文字列の一致を意味するものではなく、単に in/not in のエイリアスです。文字列の断片を渡すと、結果は 0 件となります。eq、==、like などのエイリアスは 400 Unsupported tag filter operator を返し、すべてのクエリが失敗します。フィルター条件を設定した後、結果の総数をフィルター適用前の結果と比較し、フィルターが実際に有効になっていることを確認してください。

score ≈ semantic_weight × semanticScore + (1 - semantic_weight) × keywordScore

ステップ 4：再利用コードの修正

再利用するプロジェクトは、アシスタントを検証する前に 2 つの修正が必要です。app.py での空の結果に対するフォールバックと、kb_client.py での戻りコードの修正です。

app.py における空の取得結果のインターセプト

再利用する app.py では、取得結果が空の場合でも llm_answer() は LLM を呼び出します。その時点ではコンテキストは空の文字列であり、モデルは完全に自身の知識から回答します。テストで、ナレッジベースがカバーしていない「Redis クラスターのスプリットブレインから回復する方法は？」と質問したところ、モデルはパラメーター付きの完全な操作計画を出力し、警告を一切表示しませんでした。トラブルシューティングのシナリオでは、ユーザーがコマンドをコピーして本番環境で直接実行する可能性があるため、これはコードレベルでインターセプトする必要があります。

def llm_answer(question: str, results: list[dict[str, Any]]) -> str:
    if not LLM.get("enabled", True):
        return "LLM が有効になっていません。以下の取得結果を確認してください。"
    if not results:
        return "ナレッジベースから関連ドキュメントが取得されなかったため、トラブルシューティング手順を提供できません。これに基づいていかなる変更操作も行わないでください。モジュールの所有者に連絡することを推奨します。"
    ...

これをプロンプトだけで制約するのは信頼できません — 「資料が質問をカバーしていない場合は明示的に通知する」と記述しても、モデルは回答してしまいます。

ステップ 5：アップロード、公開、検証の最後の受け入れ基準は、この修正をカバーしています。

kb_client.py のリターンコードチェックの修正

再利用する kb_client.py では、_check() は getattr(body, "code", 0) != 0 を評価します。成功したレスポンスの code は None であるため、成功した取得は「Failed: None」と報告されます。チェックを getattr(body, "code", None) not in (None, 0, "0") に変更します。修正後、成功した取得は「Failed: None」と報告されなくなります。

ステップ 5：アップロード、公開、検証

1. ソースファイルをアップロードします。MetaFields はバッチ全体に適用されます。スクリプトはまずタグでグループ化し、次にバッチで送信します。

   python upload.py --manifest documents.jsonl

2. コンソールの [Data Management] ページで、ソースファイルのステータスが [Completed] であることを確認します。アップロード API からの成功レスポンスは、非同期解析が送信されたことのみを意味します。

3. [Version Management] ページで、[Publish Version] をクリックします。ウィザードを完了した後、新しいバージョンのステータスが [Published] であることを確認します。

   重要

   同時に存在できる公開済みバージョンは最大 3 つです。上限に達すると、[Publish Version] ボタンはグレーアウトされますが、ページには「There are currently N pending changes to publish」と表示され続けます。まず、バージョン履歴から不要になった古いバージョンを削除してください。開発ドキュメントは頻繁に変更されるため (リリースごとに API リファレンスやランブックが更新される可能性があります)、「現在のバージョン + 最新の履歴バージョン」のみを保持するようにしてください。

4. サービスを起動します。

   python app.py

5. テスト用の質問を送信します。

   curl -sS http://127.0.0.1:7860/api/ask \
     -H 'Content-Type: application/json' \
     -d '{"question":"接続タイムアウトのトラブルシューティングはどのような順序で行うべきですか？"}'

6. 次の 5 つの受け入れ基準に対して検証します。

   • ページが正常に開き、質問を送信すると、回答と取得ソースが一緒に返されます。

   • 回答内の各 [Source N] が、下のソースセクションにある対応するソースファイルチャンクと一致します。

   • 完全なエラーコードで質問すると、そのエラーコードが出現するすべてのソースファイルがリストアップされます。テストでは、ORD-50021 をクエリすると、エラーコードテーブル、API リファレンス、ランブック、ポストモーテムの 4 つのソースファイルが、それぞれの場所とともに正しくリストアップされました。

   • リスクの高い操作について質問すると、回答にリスクレベルと手動での確認要件が含まれます。

   • ナレッジベースがカバーしていない内容について質問すると、「materials are insufficient」という応答と、いかなる変更操作も行わないようにという警告が返され、捏造されたコマンドは表示されません。このケースを実際にテストしてください。

開発シナリオに関する注意事項

• モジュールごとのエントリポイント — tag_filter が module を固定すると、エントリポイントはそのモジュールに関する質問にのみ回答します。サンプル質問も同じモジュール内に留めてください。

• 完全一致用語の完全性 — ソースファイルには、完全なエラーコード、API パス、コマンド、バージョン番号を保持してください。これらの完全一致用語は、このシナリオにおける主要な取得エントリポイントです。

• リスクのマーキング — ソースファイルにリスクレベルと確認要件をマークしてください。どのコマンドが危険かをモデルに判断させないでください。

• アップロードにシークレットを含めない — シークレット、トークン、内部ネットワークアカウント、または本番データベースの接続文字列をアップロードしないでください。チャンクのコンテンツはコンテキストとして LLM に送信されます。

• 非推奨 API の説明 — 非推奨になった API 操作の説明は保持してください。テストでは、API リファレンスに「the v1 API is deprecated and its parameter names are incompatible」と記載した後、新しい API のパラメーターに関する質問に回答する際に、モデルは古いパラメーターを混在させませんでした。

• 取得結果の tags フィールドは、書き込まれたモジュールとバージョンをエコーバックしません。これは AddDocuments の MetaFields とは異なるフィールドであり、その返却を有効にするパラメーターはありません。値が空でもアップロードが失敗したわけではありません。 回答にモジュールとバージョンを注釈付けする必要がある場合は、取得結果を documentId で documents.jsonl と結合し、その情報をコンテキストに追加します。

• 本番環境へのデプロイ — オンラインデプロイに Flask 開発サーバーを使い続けないでください。本番用の WSGI サーバーに切り替え、シークレット管理、認証、監査、レート制限を追加してください。

よくある質問

次のステップ

• モジュールごとにカバレッジを拡大する：各 module の値に対して独立したエントリポイントを作成し、サンプル質問を同じモジュール内に留めます。

• 本番環境への準備：Flask 開発サーバーから本番用の WSGI サーバーに切り替え、シークレット管理、認証、監査、レート制限を追加します。

• ドキュメントの変更に合わせてバージョンを管理する：API リファレンスやランブックが更新されたときに新しいバージョンを公開し、現在のバージョンと最新の履歴バージョンのみを保持します。