Vector Retrieval Service for Milvus:Alibaba Cloud Milvus ナレッジベースを利用した社内ポリシー Q&A アプリケーションの構築

ソリューション概要

エンドツーエンドのパイプラインは、「Alibaba Cloud Milvus ナレッジベースを利用したインテリジェントなカスタマーサービス Q&A アプリケーションの構築」と同じです。コンソールでタグを定義 → タグごとにドキュメントをバッチインポート → バージョンを公開 → SDK を介してオプションのタグフィルタリングで検索 → 大規模言語モデル (LLM) が出典の引用付きで回答を生成 → Flask が Q&A ページを提供、という流れになります。そのドキュメントのエンジニアリングコード (kb_client.py、upload.py、app.py、templates/index.html、start.sh) を直接再利用してください。このトピックでは、ポリシーシナリオ向けに変更が必要な部分、すなわち部門タグスキーマ、検索パラメーター、ポリシーアシスタントのプロンプト、ポリシーのバージョン管理のみを説明します。

最初のバージョンでは、1 つの部門から 5～20 個のドキュメントのみを選択し、検索品質とプロンプトを検証した後に拡張してください。全プロセスには約 20～30 分かかります。

前提条件

• ナレッジベースを作成し、ナレッジベース ID (例：kd-803ae9b10cc31) を記録しておきます。

• ご利用の Alibaba Cloud アカウントで RAM ユーザーを作成し、[永続的な AccessKey ペアを使用] を選択し、システムポリシー AliyunMilvusFullAccess をアタッチします。

• OpenAI の chat/completions プロトコルをサポートする LLM エンドポイントとその API キー。

• ローカルに Python 3.9 以降がインストールされており、「ソリューション概要」で参照されているチュートリアルに従ってプロジェクトディレクトリがセットアップされていること。

ステップ 1：部門とポリシーのタグ定義

ナレッジベース詳細ページの [基本情報] で、[タグ] > [管理] を選択し、以下の 3 つのタグを追加します。すべてタイプは string です。

タグ値には任意のテキストが使用できるため、部門名やドキュメントタイプ名を直接使用できます。

すでにデータに書き込まれているタグ値は失われません。タグを再追加した後、詳細ページでタグ数を確認してください。

タグ定義は、主に使用可能な値を標準化するために行います。定義されていないタグ名でもデータと共に書き込み、フィルタリングに使用できますが、チームでの共同作業やメンテナンスを容易にするために、インポート前に定義しておくことを推奨します。

ステップ 2：ポリシードキュメントとインポートマニフェストの整理

1. ドキュメントを部門ごとに整理し、documents/ ディレクトリに配置します。回答のソースセクションで各エントリを簡単に識別できるように、各ファイル名にポリシー名とバージョンまたは発効日を含めます。

2. documents.jsonl を作成し、各ドキュメントに部門、タイプ、発効日をアノテーションします。

   {"path": "documents/finance-travel.md", "metadata": {"department": "Finance", "docType": "Policy", "effectiveDate": "2026-01-01"}}
   {"path": "documents/finance-reimbursement.md", "metadata": {"department": "Finance", "docType": "Process", "effectiveDate": "2026-02-01"}}
   {"path": "documents/hr-leave.md", "metadata": {"department": "Administration", "docType": "Policy", "effectiveDate": "2026-01-01"}}
   {"path": "documents/it-troubleshoot.md", "metadata": {"department": "IT", "docType": "Process", "effectiveDate": "2026-03-01"}}

3. 各ポリシードキュメントの本文の冒頭に発効日とポリシーの所有者を記述し、古いバージョンには「バージョン X により廃止」とマークします。デフォルトでは、LLM は検索されたチャンクの本文しか参照しません。effectiveDate タグは自動的にプロンプトに追加されず、ステップ 4 の変更を適用した後にのみ含まれます。

4. チャンク化の粒度を調整します。ポリシードキュメントは通常、短いエントリです。ナレッジベース詳細ページの [処理ポリシー] (ナレッジベースのドキュメント処理とチャンク化の設定) で、[ポリシーの作成] をクリックします。チャンクの最大長の単位は文字 (デフォルトは 512) です。各プロセスのステップが分断されないように、580～770 文字 (約 384～512 トークン) に設定します。

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

config.json で、ポリシーシナリオに合わせて retrieval と scenario を調整します。これら 2 つのセクションのみを変更し、ファイルの残りの部分は変更しないでください。

{
  "retrieval": {
    "page_size": 6,
    "candidate_count": 48,
    "min_score": 0.35,
    "semantic_weight": 0.6,
    "enable_query_expansion": true,
    "rerank_model_name": "",
    "tag_filter": {
      "relation": "and",
      "conditions": []
    }
  },
  "scenario": {
    "title": "Enterprise policy and process Q&A",
    "system_prompt": "You are an internal policy assistant. Answer only based on the retrieved published policies. Organize processes into steps, state the applicable conditions and required materials, and cite sources as [Source N]. When the materials conflict or are insufficient, clearly tell the user to contact the policy owner.",
    "image_enabled": false,
    "sample_questions": [
      "What materials are required for travel expense reimbursement?",
      "Who approves leave requests longer than three days?",
      "What is the process for reporting an issue when my computer cannot connect to the network?"
    ]
  }
}

例にある他のパラメーター (page_size、candidate_count、enable_query_expansion、rerank_model_name) は、参照元のチュートリアルの値を維持します。min_score、semantic_weight、tag_filter パラメーターは、シナリオ固有の選択が必要です。

• min_score — コーパス全体で普遍的に推奨される値はありません。実際の質問を使って、ご自身のコーパスに対してしきい値を調整してください。

  1. min_score を 0 に設定し、結果のバッチを取得します。

  2. 結果の関連性を手動でラベリングします。

  3. 再現率と偽陽性のディストリビューションに基づいてしきい値を選択します。

     このようなキャリブレーションデータがない場合は、このトピックのコーパスで測定された値である 0.35 から始めてください。そのコーパスでは、0.2 の場合、質問とは全く無関係なポリシー (スコア 0.36～0.43) が LLM のコンテキストに入力され、コストと誤答のリスクが増加しました。0.35 にすると、これらの結果は除外されました。コーパスを変更したり、再ランキングモデルを切り替えたり、semantic_weight を調整したりした場合は、常に再調整してください。

• semantic_weight=0.6 — ポリシーに関する質問では、固有名詞と口語表現が混在することが多いため、セマンティックマッチングとキーワードマッチングのバランスを取ります。

  このパラメーターは最終スコアの重み付け係数で、score ≈ (1-semantic_weight) × keywordScore + semantic_weight × semanticScore として計算されます (ランク特徴量も追加される場合があります)。min_score は、この計算後の最終スコアでフィルタリングします。

  再ランキングなしの場合、semanticScore はベクトル類似度です。再ランキングを有効にすると、再ランキングモデルのスコアになります。両者はスケールが異なるため、重みを変更したり、再ランキングを切り替えたりした後は、scoreDetails と一緒にしきい値を再調整してください。重みを下げても必ずしも合計スコアが下がるわけではありません。スコアが下がるのは、バッチに対して semanticScore が keywordScore よりも高い場合のみです。

• tag_filter — デフォルトでは conditions を空のままにして、すべての部門から検索します。エントリポイントを単一の部門に限定したい場合にのみ、フィルター条件を設定します。「ステップ 5：検索範囲の特定部門への限定」で、設定方法と知っておくべき演算子の動作について説明します。

ステップ 4：回答への部門と発効日の追加

ポリシーに関する Q&A では、どのバージョンが有効で、どの部門に適用されるかを判断する必要があるため、タグ値を LLM のコンテキストに含める必要があります。検索結果の tags フィールドは、書き込んだタグ値を返しません。これは、サービスの内部的なチャンクタグ拡張機能に由来するものであり、AddDocuments によって書き込まれた MetaFields とは異なるフィールドです。その返却を有効にするリクエストパラメーターはないため、値が空であってもアップロードの失敗やタグの損失を意味するわけではありません。

クライアント側でマッピングを維持します。ローカルのインポートマニフェストをファイル名でインデックス化し、各検索結果をその documentName でルックアップし、タグ値を LLM のコンテキストに追加します。

app.py の app = Flask(__name__) の後に、マッピングを追加します。

META_BY_NAME: dict[str, dict[str, Any]] = {}
_manifest = Path("documents.jsonl")
if _manifest.is_file():
    for _line in _manifest.read_text(encoding="utf-8").splitlines():
        if _line.strip():
            _entry = json.loads(_line)
            META_BY_NAME[Path(str(_entry["path"])).name] = _entry.get("metadata") or {}

次に、llm_answer() を変更して、コンテキストを構築する際にタグ値を含め、質問に現在の日付を提供するようにします。

def llm_answer(question: str, results: list[dict[str, Any]]) -> str:
    if not LLM.get("enabled", True):
        return "The LLM is disabled. Review the retrieval results below."
    if not results:
        return "The current policy materials contain no relevant provisions. Contact the corresponding policy owner for confirmation."
    blocks = []
    for index, item in enumerate(results, 1):
        title = field(item, "documentName", "DocumentName")
        meta = META_BY_NAME.get(title) or {}
        label = ", ".join(f"{key}={value}" for key, value in meta.items())
        header = f"[Source {index}] {title}" + (f" ({label})" if label else "")
        blocks.append(f"{header}\n{field(item, 'content', 'Content')}")
    context = "\n\n".join(blocks)
    today = datetime.date.today().isoformat()
    url = str(LLM["base_url"]).rstrip("/") + "/chat/completions"
    response = requests.post(
        url,
        headers={"Authorization": f"Bearer {LLM['api_key']}"},
        json={
            "model": LLM["model"],
            "temperature": 0.1,
            "messages": [
                {"role": "system", "content": SCENARIO.get("system_prompt", "Answer only based on the provided materials.")},
                {"role": "user", "content": f"Current date: {today}\nQuestion: {question}\n\nRetrieved materials:\n{context}"},
            ],
        },
        timeout=90,
    )
    response.raise_for_status()
    return response.json()["choices"][0]["message"]["content"].strip()

ファイルのヘッダーに import datetime を追加します。

ステップ 5：検索範囲の特定部門への限定

ある部門専用のエントリポイントを提供するには、対応するフィルター条件を設定します。

"tag_filter": {
  "relation": "and",
  "conditions": [
    {"field": "department", "op": "=", "value": "Finance"}
  ]
}

複数の条件を組み合わせることもできます。例えば、Finance 部門のプロセスドキュメントのみを検索する場合：

"conditions": [
  {"field": "department", "op": "=", "value": "Finance"},
  {"field": "docType", "op": "=", "value": "Process"}
]

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

ドキュメントのアップロード

MetaFields はバッチ全体に適用されます。スクリプトはまずドキュメントをタグでグループ化し、バッチで送信します。

python upload.py --manifest documents.jsonl

処理結果の確認

コンソールの [データ管理] ページで、ドキュメントのステータスが [処理完了] であり、タグ列に書き込まれたタグ (例：docType=Process, department=IT +1) が表示されていることを確認します。

バージョンの公開

[バージョン管理] ページで、[バージョンの公開] をクリックします。3 ステップのウィザードを完了した後、新しいバージョンのステータスが [公開済み] になっていることを確認します。

ポリシーを更新した後は、バージョンを再公開する必要があります。アプリケーションは LATEST_PUBLISHED を使用している場合にのみ、新しいコンテンツを取得します。

バージョンクォータ：デフォルトでは、同時に最大 3 つの公開済みバージョンが存在できます。この制限はテナントごとにカウントされ、インスタンスの CU 仕様を上げても増加しません。制限に達すると、[バージョンの公開] ボタンがグレーアウトしますが、ページにはまだ公開待ちの変更が N 件あると表示されます。ポリシーナレッジベースは頻繁に更新されます。現在の有効なバージョンと最新の履歴バージョンのみを保持し、新しいバージョンを公開する前に古いバージョンをクリーンアップしてください。この制限はサーバー側で調整できますが、現在ユーザー向けのセルフサービスのクォータ申請エントリはありません。評価のためにチケットを起票してください。

サービスの開始と検証

python app.py

テスト質問を送信します。

curl -sS http://127.0.0.1:7860/api/ask \
  -H 'Content-Type: application/json' \
  -d '{"question":"What materials are required for travel expense reimbursement?"}'

以下の基準を満たしていることを確認します。

• ページが正常に表示され、質問を送信すると、回答と取得ソースの両方が返されます。

• 回答内の各 [Source N] に、下のソースセクションに対応するポリシーチャンクがあること。

• [Source N] のヘッダーに、department=、docType=、effectiveDate= などのタグのラベルが付与されていること。ラベルがない場合は、検索によって返された documentName が documents.jsonl のファイル名と一致しているか確認してください。

• ポリシーでカバーされていない内容について質問した場合、回答には関連する規定がないことが明確に示され、ポリシーの所有者に連絡するよう指示されること。

• ポリシーが更新され、バージョンが再公開された後、ページが新しいバージョンのコンテンツを検索すること。これには、アプリケーションが LATEST_PUBLISHED を使用している必要があります。

ポリシーシナリオにおける考慮事項

• 古いポリシーバージョン — トレーサビリティのために履歴バージョンを保持する場合は、本文に「バージョン X により廃止」とマークし、effectiveDate でバージョンを区別します。トレーサビリティが不要な場合は、[データ管理] ページで古いバージョンを削除して再公開し、モデルがバージョン間で揺れ動かないようにします。

• 手動フォールバック — 重要なポリシーに関する Q&A では、手動のフォールバックエントリポイントを維持し、従業員には公式に公開されているポリシードキュメントに従うよう指示します。

よくある質問

以下の表は、一般的な現象とその原因および解決策をまとめたものです。