Konfigurowanie pobierania grafu tematu w usłudze Foundry IQ (Wyszukiwanie AI platformy Azure)

Important

Pobieranie grafu tematów jest w publicznej wersji zapoznawczej i podlega dodatkowemu regulaminowi dotyczącemu wersji zapoznawczych Microsoft Azure. Aby zapoznać się z warunkami wersji zapoznawczej specyficznymi dla tej funkcji, zobacz Funkcjonalność w wersji zapoznawczej.

Graf tematów (wersja zapoznawcza) reprezentuje grupy powiązanej zawartości, nazywane również społecznościami, oraz sposób, w jaki te grupy łączą się w hierarchii tematów. Pomaga ona odpowiedzieć na szerokie pytania dotyczące motywów lub wzorców w kolekcji dokumentów, a nie faktów w jednym fragmencie. Dzięki próbkowaniu dowodów z wielu tematów wyszukiwanie obsługuje odpowiedzi, które odzwierciedlają szerszy zakres motywów zamiast tylko najbliższych dopasowań wektorowych.

Użyj pobierania z grafu tematów, aby rozszerzyć istniejące pobieranie wektorowe o próbkowanie tematów w searchIndex źródle wiedzy. W tym artykule dołączysz źródło do bazy wiedzy, pobierzesz dowody wyodrębnione i zastąpisz przechowywane ustawienia dla poszczególnych żądań.

Prerequisites

  • Usługa Foundry IQ (Wyszukiwanie AI platformy Azure), która obsługuje 2026-11-01-preview interfejs API REST.
  • Python 3.10 lub nowszy dla przykładów w Pythonie lub .NET 8 lub nowszy dla przykładów w C#.
  • W przypadku przykładów zestawu SDK postępuj zgodnie z instrukcjami dotyczącymi pakietu w wersji zapoznawczej z publicznego źródła w temacie Tworzenie bazy wiedzy.
  • Wypełniony indeks tematów przygotowany przez wtyczkę umiejętności Foundry IQ.
  • Istniejący, wypełniony indeks treści w tej samej usłudze Foundry IQ. Jego pole wektorowe do pobierania musi być połączone z przygotowanym indeksem tematów.
  • Poświadczenia autoryzujące zasób i operacje pobierania. Skonfiguruj uwierzytelnianie bez klucza dla tych przykładów. Aby uzyskać uprawnienia, zobacz wymagania wstępne dotyczące tworzenia źródeł wiedzy i wykonywania zapytań dotyczących baz wiedzy.

Limitations

Podczas korzystania z wersji zapoznawczej baza wiedzy nie identyfikuje automatycznie zapytania jako zróżnicowane. W przypadku zapytania o zróżnicowanych wynikach ustaw wartość topicGraph.kind na diverse w żądaniu pobierania.

Konfiguracja żądań

W przypadku przykładów zestawu SDK ustaw wartości SEARCH_ENDPOINT, KNOWLEDGE_SOURCE_NAME, VECTOR_FIELD_NAME, TOPIC_INDEX_NAME, CONTENT_FIELD_NAME, CONTENT_INDEX_NAME, KNOWLEDGE_BASE_NAME i QUESTION w zmiennych środowiskowych procesu.

W przypadku przykładów REST użyj Visual Studio Code z rozszerzeniem klienta REST, aby wysłać żądania z jednego .http pliku.

  1. Ustaw punkt końcowy usługi Foundry IQ i token dostępu. Aby uzyskać token dostępu, zobacz Nawiązywanie połączenia z usługą Foundry IQ. punkt końcowy nie może mieć ukośnika końcowego.

  2. Dodaj następujące zmienne. Zastąp nazwy indeksów i pól nazwami używanymi w Twoim środowisku. Użyj nowych nazw źródła wiedzy i bazy wiedzy, które należą do tego zadania.

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

    Odwołanie:interfejs API REST usługi wyszukiwania.

    W przypadku nazw domyślnych embedding jest polem wektorowym z możliwością wyszukiwania, a content jest tekstem możliwym do pobrania.

  3. Sprawdź definicję indeksu zawartości.

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.

Sprawdź, czy embedding.topicGraphProfile wskazuje oczekiwany profil, na przykład content-topics. Przejdź zgodnie z tym profilem do vectorSearch.topicGraphProfiles[name].indexName, który musi identyfikować sample-topics dla tych wartości domyślnych. Sprawdź również profil wyszukiwania wektorowego pola i konfigurację wektoryzatora wejściowego ciągu.

  1. Sprawdź definicję indeksu tematów.
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.

Nie wysyłaj definicji indeksów zastępczych w ramach tej procedury.

Tworzenie źródła wiedzy

Utwórz oddzielne searchIndex źródło z zapisanymi balanced ustawieniami.

  1. Utwórz źródło z jawnymi polami wyszukiwania, zwracanymi polami danych i ustawieniami tematu.
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
)

Odwołanie:biblioteka kliencka Python.

  1. Przeczytaj definicję źródła, aby zweryfikować przechowywany indeks, pola i topicGraph ustawienia.
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.

Dołącz źródło do bazy wiedzy

  1. Utwórz bazę wiedzy przypisaną do zadania, odwołując się do utworzonego wcześniej źródła.
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
)

Odwołanie:biblioteka kliencka Python.

  1. Sprawdź pasujące odwołanie do źródła, nakład pracy i tryb wyjściowy.

Pobierz przy użyciu zapisanych ustawień

  1. Wyślij następujące żądanie.
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
)

Odwołanie:biblioteka kliencka Python.

Nadpisz wybór tematu dla pojedynczego żądania

  1. Wyślij to samo pytanie z pełnym diverse nadpisaniem.
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
)

Odwołanie:biblioteka kliencka Python.

Wyłączanie próbkowania tematu dla jednego żądania

  1. Wyślij następujące żądanie.
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
)

Odwołanie:biblioteka kliencka Python.

Przeglądanie ustawień i limitów weryfikacji

Użyj tylko kombinacji publicznych w poniższej tabeli.

Setting Wartości i ustawienia domyślne
topicGraph.kind Wymagane, gdy obiekt jest obecny: none, diverse lub balanced.
none Wyłącza próbkowanie tematów. Nie dołączaj diversityFactor ani minDiversityPoolSize.
balanced Używa stałego współczynnika różnorodności , 0.2niezależnie od współczynnika profilu. Nie dołączaj diversityFactor.
diversityFactor Tylko dla diverse. Zakres obejmuje wartości od 0 do 1. Pominięcie używa współczynnika profilu lub 0.2, jeśli żaden nie jest skonfigurowany.
minDiversityPoolSize Tylko dla diverse lub balanced. Zakres obejmuje wartości od 250 do 10000. Pominięcie używa minimalnej wartości profilu lub 1000, jeśli nie skonfigurowano żadnej.

Troubleshooting

Rozwiąż błędy konfiguracji przed interpretacją wyników pobierania.

Problem Action
Brak powiązania tematu Sprawdź efektywnie przeszukiwane pole wektorowe topicGraphProfile, pasujący profil i jego indeks topic indexName.
Brak lub niezgodność wektoryzatora Skonfiguruj wektoryzator w polu wektorowym.