Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
A topic graph (preview) represents groups of related content, also called communities, and how those groups connect within a topic hierarchy. It helps answer broad questions about themes or patterns across a document collection, rather than facts in a single passage. By sampling evidence from multiple topics, retrieval supports answers that reflect a broader range of themes instead of only the closest vector matches.
Use topic graph retrieval to augment existing vector retrieval with topic sampling on a searchIndex knowledge source. In this article, you attach the source to a knowledge base, retrieve extractive evidence, and override the stored settings for individual requests.
Important
Topic graph retrieval is in Public Preview and is subject to the Supplemental Terms of Use for Microsoft Azure Previews.
For preview terms specific to this feature, see Preview functionality.
Prerequisites
- A Foundry IQ (Azure AI Search) service that supports the
2026-11-01-previewREST API. - Python 3.10 or later for Python examples, or .NET 8 or later for C# examples.
- For SDK examples, follow the public-feed preview package instructions in Create a knowledge base.
- A populated topic index prepared by the Foundry IQ skills plugin.
- An existing, populated content index on the same Foundry IQ service. Its vector field for retrieval must be linked to the prepared topic index.
- Credentials authorized for the resource and retrieval operations. Configure keyless authentication for these examples. For permissions, see the prerequisites for creating knowledge sources and querying knowledge bases.
Limitations
During preview, a knowledge base doesn't automatically identify a query as diverse. For a diverse query, set topicGraph.kind to diverse in the retrieval request.
Set up requests
For SDK examples, set SEARCH_ENDPOINT, CONTENT_INDEX_NAME,
TOPIC_INDEX_NAME, VECTOR_FIELD_NAME, CONTENT_FIELD_NAME,
KNOWLEDGE_SOURCE_NAME, KNOWLEDGE_BASE_NAME, and QUESTION in your
process environment.
For REST examples, use Visual Studio Code with the REST Client extension to send the requests from one .http file.
Set the Foundry IQ service endpoint and access token. To get an access token, see Connect to Foundry IQ. The endpoint must not have a trailing slash.
Add the following variables. Replace the index and field names with your environment's names. Use new knowledge source and knowledge base names that belong to this task.
@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}}')Reference: Search Service REST API.
For the default names,
embeddingis the searchable vector field andcontentis retrievable text.Inspect the content index definition.
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"]
)
Reference: SearchIndexClient.
Check that embedding.topicGraphProfile names the expected profile, such as content-topics. Follow that profile to vectorSearch.topicGraphProfiles[name].indexName, which must identify sample-topics for these defaults. Also check the field's vector search profile and string-input vectorizer configuration.
- Inspect the topic index definition.
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"]
)
Reference: SearchIndexClient.
Don't send replacement index definitions as part of this procedure.
Create the knowledge source
Create a separate searchIndex source with stored balanced settings.
- Create the source with explicit search fields, returned data fields, and topic settings.
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
)
Reference: Python client library.
- Read the source definition to verify the stored index, fields, and
topicGraphsettings.
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"]
)
)
Reference: SearchIndexClient.
Attach the source to a knowledge base
- Create the task-owned knowledge base, referencing the source created earlier.
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
)
Reference: Python client library.
- Verify the matching source reference, effort, and output mode.
Retrieve with the stored settings
- Send the following request.
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
)
Reference: Python client library.
Override topic selection for one request
- Send the same question with a complete
diverseoverride.
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
)
Reference: Python client library.
Disable topic sampling for one request
- Send the following request.
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
)
Reference: Python client library.
Review settings and verification limits
Use only the public combinations in the following table.
| Setting | Values and defaults |
|---|---|
topicGraph.kind |
Required when the object is present: none, diverse, or balanced. |
none |
Disables topic sampling. Don't include diversityFactor or minDiversityPoolSize. |
balanced |
Uses a fixed diversity factor of 0.2, independent of the profile's factor. Don't include diversityFactor. |
diversityFactor |
Only for diverse. Inclusive range: 0 through 1. Omission uses the profile's factor, or 0.2 if none is configured. |
minDiversityPoolSize |
Only for diverse or balanced. Inclusive range: 250 through 10000. Omission uses the profile's minimum, or 1000 if none is configured. |
Troubleshooting
Resolve configuration errors before interpreting retrieval results.
| Problem | Action |
|---|---|
| Missing topic binding | Check the effective searched vector field's topicGraphProfile, the matching profile, and its topic-index indexName. |
| Missing or incompatible vectorizer | Configure a vectorizer on the vector field. |