在 Foundry IQ(Azure AI 搜尋服務)中設定主題圖形擷取

主題圖表(預覽)用來表示相關內容的群組,也稱為社群,以及這些群組在主題階層結構中如何相互連結。 它幫助回答文件集合中主題或模式的廣泛問題,而非單篇文章中的事實。 透過從多個主題抽樣證據,檢索能支持反映更廣泛主題的答案,而非僅僅最接近的向量匹配。

利用主題圖檢索,在知識來源上進行主題抽樣 searchIndex ,來補充現有的向量檢索。 在本文中,您將把來源附加至知識庫、擷取擷取式證據,並針對個別要求覆寫已儲存的設定。

Important

主題圖擷取目前處於公開預覽階段,並受 Microsoft Azure 預覽補充使用條款的約束。

有關此功能專屬的預覽條款,請參閱 「預覽功能」。

Prerequisites

  • 支援 2026-11-01-preview REST API 的 Foundry IQ(Azure AI 搜尋服務)服務。
  • Python 範例需 Python 3.10 或更新版本,C# 範例則需 .NET 8 或更新版本。
  • 如需 SDK 範例,請依照 建立知識庫 中的公開資訊預覽套件指示操作。
  • 由 Foundry IQ 技能外掛製作的已有內容的主題索引。
  • 在同一 Foundry IQ 服務中現有且已填入資料的內容索引。 其檢索向量場必須與已準備的主題索引連結。
  • 授權用於資源與擷取作業的憑證。 為這些範例設定 無金鑰驗證 。 有關權限,請參閱 建立知識來源 及 查詢知識庫的先決條件。

Limitations

在預覽期間,知識庫不會自動將查詢識別為多樣化查詢。 對於多樣化的查詢,請在擷取請求中設定topicGraph.kind為diverse。

設定請求

針對 SDK 範例,請在程序環境中設定 SEARCH_ENDPOINT、CONTENT_INDEX_NAME、CONTENT_FIELD_NAME、KNOWLEDGE_BASE_NAME、TOPIC_INDEX_NAME、KNOWLEDGE_SOURCE_NAME、VECTOR_FIELD_NAME 和 QUESTION。

以 REST 範例為例,請使用 Visual Studio Code 搭配 REST Client 副檔名,從單一.http檔案傳送請求。

  1. 設定 Foundry IQ 服務端點及存取權杖。 若要取得存取權杖,請參閱 「連接至 Foundry IQ」。 端點不得有尾部斜線。

  2. 加入下列變數。 請將索引與欄位名稱替換為您環境的名稱。 使用屬於此任務的新知識來源與知識庫名稱。

    @api-version = 2026-11-01-preview
    @search-endpoint = <search-endpoint>
    @access-token = <search-access-token>
    @content-index-name = sample-content
    @topic-index-name = sample-topics
    @vector-field-name = embedding
    @content-field-name = content
    @knowledge-source-name = sample-topic-ks
    @knowledge-base-name = sample-topic-kb
    @question = What are the main themes across the documents in this collection?
    @content-url = {{search-endpoint}}/indexes('{{content-index-name}}')
    @topic-url = {{search-endpoint}}/indexes('{{topic-index-name}}')
    @source-url = {{search-endpoint}}/knowledgesources('{{knowledge-source-name}}')
    @base-url = {{search-endpoint}}/knowledgebases('{{knowledge-base-name}}')
    

    參考:搜尋服務 REST API。

    預設名稱中, embedding 是可搜尋的向量欄位, content 為可擷取的文字。

  3. 檢視內容索引定義。

import os

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

content_index_client = SearchIndexClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
content_index_definition = content_index_client.get_index(
    os.environ["CONTENT_INDEX_NAME"]
)

參考:SearchIndexClient。

確認該 embedding.topicGraphProfile 名稱是預期的設定檔,例如 content-topics。 沿著該設定檔找到 vectorSearch.topicGraphProfiles[name].indexName,其中必須將 sample-topics 識別為這些預設值。 同時檢查欄位的向量搜尋設定檔及字串輸入向量化器設定。

  1. 檢查主題索引定義。
import os

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

topic_index_client = SearchIndexClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
topic_index_definition = topic_index_client.get_index(
    os.environ["TOPIC_INDEX_NAME"]
)

參考資料:SearchIndexClient。

請勿在此程序中傳送替換索引定義。

建立知識來源

建立使用已儲存searchIndex設定的個別balanced來源。

  1. 建立包含明確搜尋欄位、回傳資料欄位及主題設定的來源。
import os

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    SearchIndexFieldReference,
    SearchIndexKnowledgeSource,
    SearchIndexKnowledgeSourceParameters,
)
from azure.search.documents.models import BalancedVectorQueryTopicGraph

topic_source_parameters = SearchIndexKnowledgeSourceParameters(
    search_index_name=os.environ["CONTENT_INDEX_NAME"],
    search_fields=[
        SearchIndexFieldReference(
            name=os.environ["VECTOR_FIELD_NAME"]
        )
    ],
    source_data_fields=[
        SearchIndexFieldReference(
            name=os.environ["CONTENT_FIELD_NAME"]
        )
    ],
    topic_graph=BalancedVectorQueryTopicGraph(
        min_diversity_pool_size=1000
    ),
)
topic_knowledge_source = SearchIndexKnowledgeSource(
    name=os.environ["KNOWLEDGE_SOURCE_NAME"],
    results_processing="none",
    search_index_parameters=topic_source_parameters,
)
topic_source_index_client = SearchIndexClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
topic_source_index_client.create_or_update_knowledge_source(
    topic_knowledge_source
)

參考資料:Python 用戶端函式庫。

  1. 閱讀來源定義以驗證所儲存的索引、欄位與 topicGraph 設定。
import os

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

stored_source_index_client = SearchIndexClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
stored_topic_knowledge_source = (
    stored_source_index_client.get_knowledge_source(
        os.environ["KNOWLEDGE_SOURCE_NAME"]
    )
)

參考資料:SearchIndexClient。

將來源附加到知識庫

  1. 建立由任務擁有的知識庫,並引用先前建立的來源。
import os

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    KnowledgeBase,
    KnowledgeSourceReference,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeRetrievalMinimalReasoningEffort,
    KnowledgeRetrievalOutputMode,
)

topic_knowledge_base = KnowledgeBase(
    name=os.environ["KNOWLEDGE_BASE_NAME"],
    knowledge_sources=[
        KnowledgeSourceReference(
            name=os.environ["KNOWLEDGE_SOURCE_NAME"]
        )
    ],
    retrieval_reasoning_effort=(
        KnowledgeRetrievalMinimalReasoningEffort()
    ),
    output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
)
topic_base_index_client = SearchIndexClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
topic_base_index_client.create_or_update_knowledge_base(
    topic_knowledge_base
)

參考資料:Python 用戶端函式庫。

  1. 驗證相符的來源參考、工作量與輸出模式。

使用已儲存的設定擷取

  1. 請發送以下請求。
import os

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import (
    KnowledgeBaseRetrievalClient,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalMinimalReasoningEffort,
    KnowledgeRetrievalOutputMode,
    KnowledgeRetrievalSemanticIntent,
    SearchIndexKnowledgeSourceParams,
)

stored_topic_source = SearchIndexKnowledgeSourceParams(
    knowledge_source_name=os.environ["KNOWLEDGE_SOURCE_NAME"],
    include_references=True,
    include_reference_source_data=True,
)
stored_topic_request = KnowledgeBaseRetrievalRequest(
    intents=[
        KnowledgeRetrievalSemanticIntent(
            search=os.environ["QUESTION"]
        )
    ],
    retrieval_reasoning_effort=(
        KnowledgeRetrievalMinimalReasoningEffort()
    ),
    output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
    include_activity=True,
    knowledge_source_params=[stored_topic_source],
)
stored_topic_client = KnowledgeBaseRetrievalClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    knowledge_base_name=os.environ["KNOWLEDGE_BASE_NAME"],
    credential=DefaultAzureCredential(),
)
stored_topic_response = stored_topic_client.retrieve(
    stored_topic_request
)

參考資料:Python 用戶端函式庫。

覆寫單一請求的主題選擇

  1. 寄出同樣的問題,並使用完整的 diverse 覆寫。
import os

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import (
    KnowledgeBaseRetrievalClient,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalMinimalReasoningEffort,
    KnowledgeRetrievalOutputMode,
    KnowledgeRetrievalSemanticIntent,
    SearchIndexKnowledgeSourceParams,
)
from azure.search.documents.models import DiverseVectorQueryTopicGraph

diverse_topic_source = SearchIndexKnowledgeSourceParams(
    knowledge_source_name=os.environ["KNOWLEDGE_SOURCE_NAME"],
    include_references=True,
    include_reference_source_data=True,
    topic_graph=DiverseVectorQueryTopicGraph(
        diversity_factor=0.1,
        min_diversity_pool_size=1000,
    ),
)
diverse_topic_request = KnowledgeBaseRetrievalRequest(
    intents=[
        KnowledgeRetrievalSemanticIntent(
            search=os.environ["QUESTION"]
        )
    ],
    retrieval_reasoning_effort=(
        KnowledgeRetrievalMinimalReasoningEffort()
    ),
    output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
    include_activity=True,
    knowledge_source_params=[diverse_topic_source],
)
diverse_topic_client = KnowledgeBaseRetrievalClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    knowledge_base_name=os.environ["KNOWLEDGE_BASE_NAME"],
    credential=DefaultAzureCredential(),
)
diverse_topic_response = diverse_topic_client.retrieve(
    diverse_topic_request
)

參考資料:Python 用戶端函式庫。

針對單一請求停用主題抽樣

  1. 請發送以下請求。
import os

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import (
    KnowledgeBaseRetrievalClient,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalMinimalReasoningEffort,
    KnowledgeRetrievalOutputMode,
    KnowledgeRetrievalSemanticIntent,
    SearchIndexKnowledgeSourceParams,
)
from azure.search.documents.models import NoneVectorQueryTopicGraph

none_topic_source = SearchIndexKnowledgeSourceParams(
    knowledge_source_name=os.environ["KNOWLEDGE_SOURCE_NAME"],
    include_references=True,
    include_reference_source_data=True,
    topic_graph=NoneVectorQueryTopicGraph(),
)
none_topic_request = KnowledgeBaseRetrievalRequest(
    intents=[
        KnowledgeRetrievalSemanticIntent(
            search=os.environ["QUESTION"]
        )
    ],
    retrieval_reasoning_effort=(
        KnowledgeRetrievalMinimalReasoningEffort()
    ),
    output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
    include_activity=True,
    knowledge_source_params=[none_topic_source],
)
none_topic_client = KnowledgeBaseRetrievalClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    knowledge_base_name=os.environ["KNOWLEDGE_BASE_NAME"],
    credential=DefaultAzureCredential(),
)
none_topic_response = none_topic_client.retrieve(
    none_topic_request
)

參考資料:Python 用戶端函式庫。

檢視設定與驗證限制

請僅使用下表中的公開組合。

Setting 數值與預設值
topicGraph.kind 當物件存在時,必須為下列其中之一:none、diverse 或 balanced。
none 停用主題抽樣。 不要包含 diversityFactor 或 minDiversityPoolSize。
balanced 使用固定的多樣性因子 0.2,與剖面因子無關。 不要包含 diversityFactor。
diversityFactor 僅適用於 diverse。 包容範圍:0 至 1。 省略會使用設定檔的因子,若未設定則使用 0.2。
minDiversityPoolSize 僅適用於 diverse 或 balanced。 包容範圍:250 到 10000。 省略時使用設定檔的最小值;若未設定最小值,則使用 1000。

Troubleshooting

在解讀擷取結果之前,請先解決設定錯誤。

Problem Action
缺少主題綁定 檢查有效搜尋向量欄位 topicGraphProfile、相符的設定檔及其主題索引 indexName。
缺少或不相容的向量器 在向量欄位上設定向量化器。