主題圖表(預覽)用來表示相關內容的群組,也稱為社群,以及這些群組在主題階層結構中如何相互連結。 它幫助回答文件集合中主題或模式的廣泛問題,而非單篇文章中的事實。 透過從多個主題抽樣證據,檢索能支持反映更廣泛主題的答案,而非僅僅最接近的向量匹配。
利用主題圖檢索,在知識來源上進行主題抽樣 searchIndex ,來補充現有的向量檢索。 在本文中,您將把來源附加至知識庫、擷取擷取式證據,並針對個別要求覆寫已儲存的設定。
Important
主題圖擷取目前處於公開預覽階段,並受 Microsoft Azure 預覽補充使用條款的約束。
有關此功能專屬的預覽條款,請參閱 「預覽功能」。
Prerequisites
- 支援
2026-11-01-previewREST 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檔案傳送請求。
設定 Foundry IQ 服務端點及存取權杖。 若要取得存取權杖,請參閱 「連接至 Foundry IQ」。 端點不得有尾部斜線。
加入下列變數。 請將索引與欄位名稱替換為您環境的名稱。 使用屬於此任務的新知識來源與知識庫名稱。
@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為可擷取的文字。檢視內容索引定義。
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"]
)
確認該 embedding.topicGraphProfile 名稱是預期的設定檔,例如 content-topics。 沿著該設定檔找到 vectorSearch.topicGraphProfiles[name].indexName,其中必須將 sample-topics 識別為這些預設值。 同時檢查欄位的向量搜尋設定檔及字串輸入向量化器設定。
- 檢查主題索引定義。
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來源。
- 建立包含明確搜尋欄位、回傳資料欄位及主題設定的來源。
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 用戶端函式庫。
- 閱讀來源定義以驗證所儲存的索引、欄位與
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。
將來源附加到知識庫
- 建立由任務擁有的知識庫,並引用先前建立的來源。
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 用戶端函式庫。
- 驗證相符的來源參考、工作量與輸出模式。
使用已儲存的設定擷取
- 請發送以下請求。
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 用戶端函式庫。
覆寫單一請求的主題選擇
- 寄出同樣的問題,並使用完整的
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 用戶端函式庫。
針對單一請求停用主題抽樣
- 請發送以下請求。
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。 |
| 缺少或不相容的向量器 | 在向量欄位上設定向量化器。 |