Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
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-previewinterfejs 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.
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.
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
embeddingjest polem wektorowym z możliwością wyszukiwania, acontentjest tekstem możliwym do pobrania.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.
- 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.
- 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.
- Przeczytaj definicję źródła, aby zweryfikować przechowywany indeks, pola i
topicGraphustawienia.
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
- 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.
- Sprawdź pasujące odwołanie do źródła, nakład pracy i tryb wyjściowy.
Pobierz przy użyciu zapisanych ustawień
- 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
- Wyślij to samo pytanie z pełnym
diversenadpisaniem.
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
- 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. |