Configure topic graph retrieval in Foundry IQ (Azure AI Search)

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-preview REST 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.

  1. 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.

  2. 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, embedding is the searchable vector field and content is retrievable text.

  3. 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.

  1. 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.

  1. 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.

  1. Read the source definition to verify the stored index, fields, and topicGraph settings.
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

  1. 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.

  1. Verify the matching source reference, effort, and output mode.

Retrieve with the stored settings

  1. 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

  1. Send the same question with a complete diverse override.
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

  1. 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.