Konfigurieren des Abrufens von Themendiagrammen in Foundry IQ (Azure KI-Suche)

Ein Themengraph (Vorschau) stellt Gruppen verwandter Inhalte dar, auch Communities genannt, und zeigt, wie sich diese Gruppen innerhalb einer Themenhierarchie verbinden. Es hilft, allgemeine Fragen zu Designs oder Mustern in einer Dokumentsammlung zu beantworten, anstatt Fakten in einer einzigen Passage. Durch das Sampling von Nachweisen aus mehreren Themen unterstützt Retrieval Antworten, die eine breitere Palette von Themen und nicht nur die nächstgelegenen Vektorübereinstimmungen widerspiegeln.

Verwenden Sie den Topic-Graph-Abruf, um vorhandenen Vektorabruf mit Themensampling in einer searchIndex Wissensquelle zu ergänzen. In diesem Artikel fügen Sie die Quelle an eine Wissensbasis an, rufen extraktive Evidenz ab und überschreiben die gespeicherten Einstellungen für einzelne Anfragen.

Important

Das Abrufen von Themendiagrammen befindet sich in der öffentlichen Vorschau und unterliegt den ergänzenden Nutzungsbedingungen für Microsoft Azure Previews.

Die für dieses Feature geltenden Vorschaubedingungen finden Sie unter Previewfunktionalität.

Prerequisites

  • Ein Foundry IQ-Dienst (Azure KI-Suche), der die 2026-11-01-preview REST-API unterstützt.
  • Python 3.10 oder höher für Python Beispiele oder .NET 8 oder höher für C#-Beispiele.
  • Für SDK-Beispiele folgen Sie den Anweisungen für das Vorschaupaket für öffentliche Feeds in Erstellen einer Wissensbasis.
  • Ein befüllter Themenindex, der vom Foundry IQ Skills Plugin vorbereitet wurde.
  • Ein vorhandener, befüllter Inhaltsindex für den gleichen Foundry IQ-Dienst. Das Vektorfeld für den Abruf muss mit dem vorbereiteten Themenindex verknüpft werden.
  • Anmeldeinformationen, die für die Ressourcen- und Abrufvorgänge berechtigt sind. Konfigurieren Sie die schlüssellose Authentifizierung für diese Beispiele. Informationen zu Berechtigungen finden Sie unter den Voraussetzungen für die Erstellung von Wissensquellen und abfragen von Wissensbasen.

Limitations

Während der Vorschau identifiziert eine Wissensdatenbank eine Abfrage nicht automatisch als divers. Setzen Sie für eine vielfältige Abfrage topicGraph.kind in der Abrufanforderung auf diverse.

Anfragen einrichten

Für SDK-Beispiele setzen Sie SEARCH_ENDPOINT, CONTENT_INDEX_NAME, TOPIC_INDEX_NAME, VECTOR_FIELD_NAME, CONTENT_FIELD_NAME, KNOWLEDGE_SOURCE_NAME, KNOWLEDGE_BASE_NAME und QUESTION in Ihrer Prozessumgebung.

Verwenden Sie für REST-Beispiele Visual Studio Code mit der REST-Clienterweiterung, um die Anfragen aus einer .http Datei zu senden.

  1. Legen Sie den Foundry IQ-Dienstendpunkt und das Zugriffstoken fest. Informationen zum Abrufen eines Zugriffstokens finden Sie unter Connect to Foundry IQ. Der Endpunkt darf keinen nachgestellten Schrägstrich aufweisen.

  2. Fügen Sie die folgenden Variablen hinzu: Ersetzen Sie die Index- und Feldnamen durch die Namen Ihrer Umgebung. Verwenden Sie neue Wissensquellen- und Wissensbasisnamen, die zu dieser Aufgabe gehören.

    @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}}')
    

    Referenz:Search Service REST API.

    Für die Standardnamen ist embedding das durchsuchbare Vektorfeld und content der abrufbare Text.

  3. Überprüfen Sie die Inhaltsindexdefinition.

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.

Überprüfen Sie, ob embedding.topicGraphProfile das erwartete Profil angibt, z. B. content-topics. Folgen Sie diesem Profil bis zu vectorSearch.topicGraphProfiles[name].indexName, das für diese Standardwerte sample-topics identifizieren muss. Überprüfen Sie außerdem die Vektorsuchprofil- und Zeichenfolgen-Eingabevektorisierungskonfiguration des Felds.

  1. Überprüfen Sie die Themenindexdefinition.
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.

Senden Sie keine Ersetzungsindexdefinitionen im Rahmen dieses Verfahrens.

Wissensquelle erstellen

Erstellen Sie eine separate searchIndex Quelle mit gespeicherten balanced Einstellungen.

  1. Erstellen Sie die Quelle mit expliziten Suchfeldern, zurückgegebenen Datenfeldern und Themeneinstellungen.
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-Clientbibliothek.

  1. Lesen Sie die Quelldefinition, um den gespeicherten Index, die Felder und topicGraph Einstellungen zu überprüfen.
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"]
    )
)

Referenz:SearchIndexClient.

Anfügen der Quelle an eine Wissensbasis

  1. Erstellen Sie die der Aufgabe zugeordnete Wissensbasis, die auf die zuvor erstellte Quelle verweist.
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
)

Referenz:Python-Clientbibliothek.

  1. Überprüfen Sie die zugehörige Quellenreferenz, den Aufwand und den Ausgabemodus.

Mit gespeicherten Einstellungen abrufen

  1. Senden Sie folgende Anfrage.
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-Clientbibliothek.

Themenauswahl für eine Anfrage überschreiben

  1. Senden Sie dieselbe Frage mit einer vollständigen diverse Überschreibung.
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-Clientbibliothek.

Topic-Sampling für eine Anfrage deaktivieren

  1. Senden Sie folgende Anfrage.
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-Clientbibliothek.

Einstellungen und Verifizierungsgrenzwerte überprüfen

Verwenden Sie nur die öffentlichen Kombinationen in der folgenden Tabelle.

Setting Werte und Standardwerte
topicGraph.kind Erforderlich, wenn das Objekt vorhanden ist: none, , diverse, oder balanced.
none Deaktiviert die Themenstichprobe. diversityFactor oder minDiversityPoolSize nicht einschließen.
balanced Verwendet einen festen Diversitätsfaktor von 0.2, unabhängig vom Faktor des Profils. Nicht diversityFactor einschließen.
diversityFactor Nur für diverse. Inklusiver Bereich: 0 bis 1. Auslassung verwendet den Faktor des Profils oder 0.2, wenn kein Faktor konfiguriert ist.
minDiversityPoolSize Nur für diverse oder balanced. Inklusiver Bereich: 250 bis 10000. Auslassung verwendet den Mindestwert des Profils oder 1000, wenn keiner konfiguriert ist.

Troubleshooting

Beheben Sie Konfigurationsfehler vor der Interpretation von Abrufergebnissen.

Problem Action
Fehlende Themenbindung Überprüfen Sie das effektiv durchsuchte Vektorfeld topicGraphProfile, das übereinstimmende Profil und dessen Themenindex indexName.
Fehlender oder inkompatibler Vektorizer Konfigurieren Sie einen Vektorizer für das Vektorfeld.