Foundry IQ(Azure AI 검색)에서 토픽 그래프 검색 구성

토픽 그래프(미리 보기)는 서로 관련된 콘텐츠의 그룹(커뮤니티라고도 함)과 이러한 그룹이 토픽 계층 구조 내에서 어떻게 연결되는지를 나타냅니다. 단일 구절의 팩트보다는 문서 컬렉션 전체의 테마 또는 패턴에 대한 광범위한 질문에 답변하는 데 도움이 됩니다. 검색은 여러 주제의 증거를 샘플링하여 가장 가까운 벡터 일치만이 아니라 더 광범위한 테마를 반영하는 답변을 지원합니다.

searchIndex 지식 원본에 대한 토픽 샘플링으로 기존 벡터 검색을 보강하려면 토픽 그래프 검색을 사용합니다. 이 문서에서는 소스를 지식 베이스에 연결하고, 추출 증거를 검색하고, 개별 요청에 대한 저장된 설정을 재정의합니다.

Important

토픽 그래프 검색은 공개 미리 보기로 제공되며 Microsoft Azure 미리 보기에 대한 추가 사용 약관의 적용을 받습니다.

이 기능에 대한 미리 보기 약관은 미리 보기 기능을 참조하세요.

Prerequisites

  • REST API를 지원하는 2026-11-01-preview foundry IQ(Azure AI 검색) 서비스입니다.
  • Python 예제의 경우 Python 3.10 이상을, C# 예제의 경우 .NET 8 이상을 사용합니다.
  • SDK 예제의 경우 지식 베이스 만들기의 공개 피드 미리 보기 패키지 지침을 따릅니다.
  • Foundry IQ 기술 플러그 인에서 준비한 채워진 토픽 인덱스입니다.
  • 동일한 Foundry IQ 서비스에서 채워진 기존 콘텐츠 인덱스입니다. 검색을 위한 해당 벡터 필드는 준비된 토픽 인덱스로 연결되어야 합니다.
  • 리소스 및 검색 작업에 대한 권한이 있는 자격 증명입니다. 이 예제에 사용할 키 없는 인증을 구성합니다. 사용 권한은 지식 소스를 생성하는 것 및 지식 베이스를 쿼리하는 것에 대한 필수 조건을 참조하세요.

Limitations

미리 보기 중에 지식 베이스는 쿼리가 다양한지 자동으로 식별하지 않습니다. 다양한 쿼리의 경우 검색 요청에서 topicGraph.kind를 diverse로 설정합니다.

요청 설정하기

SDK 예제의 경우 프로세스 환경에서 CONTENT_INDEX_NAME, TOPIC_INDEX_NAME, VECTOR_FIELD_NAME, CONTENT_FIELD_NAME, KNOWLEDGE_SOURCE_NAME, KNOWLEDGE_BASE_NAME, QUESTION, SEARCH_ENDPOINT을 설정합니다.

REST 예제의 경우 REST 클라이언트 확장과 함께 Visual Studio Code 사용하여 한 .http 파일에서 요청을 보냅니다.

  1. Foundry IQ 서비스 엔드포인트 및 액세스 토큰을 설정합니다. 액세스 토큰을 가져오려면 Foundry IQ에 연결을 참조하세요. 엔드포인트에 후행 슬래시가 없어야 합니다.

  2. 다음 변수를 추가합니다. 인덱스 및 필드 이름을 사용자 환경의 이름으로 바꿉니다. 이 작업에 속하는 새 지식 원본 이름과 기술 자료 이름을 사용합니다.

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

    참조:Search Service REST API.

    기본 이름의 경우 embedding는 검색 가능한 벡터 필드이며 content는 검색 결과로 반환 가능한 텍스트입니다.

  3. 콘텐츠 인덱스 정의를 검사합니다.

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"]
)

참조:SearchIndexClient.

content-topics에 예상한 프로필 이름(예: embedding.topicGraphProfile)이 표시되는지 확인합니다. vectorSearch.topicGraphProfiles[name].indexName까지 해당 프로필을 따라가서, 이러한 기본값에 대해 sample-topics을 식별해야 합니다. 필드의 벡터 검색 프로필 및 문자열 입력 벡터라이저 구성도 확인합니다.

  1. 토픽 인덱스 정의를 검사합니다.
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"]
)

참조:SearchIndexClient.

이 절차의 일부로 대체 인덱스 정의를 보내지 마세요.

지식 소스 만들기

저장된 balanced 설정이 있는 별도의 searchIndex 원본을 만듭니다.

  1. 명시적 검색 필드, 반환된 데이터 필드 및 토픽 설정을 사용하여 소스를 만듭니다.
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
)

참조:Python 클라이언트 라이브러리.

  1. 원본 정의를 읽어 저장된 인덱스, 필드 및 topicGraph 설정을 확인합니다.
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"]
    )
)

참조:SearchIndexClient.

소스를 지식 베이스에 연결

  1. 이전에 만든 원본을 참조하여 작업 소유 기술 자료를 만듭니다.
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
)

참조:Python 클라이언트 라이브러리.

  1. 일치하는 원본 참조, 노력 및 출력 모드를 확인합니다.

저장된 설정을 사용하여 가져오기

  1. 다음 요청을 보내세요.
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
)

참조:Python 클라이언트 라이브러리.

하나의 요청에 대한 토픽 선택 재정의

  1. 전체 diverse 재정의를 사용하여 동일한 질문을 보냅니다.
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
)

참조:Python 클라이언트 라이브러리.

한 요청에 대한 토픽 샘플링 사용 안 함

  1. 다음 요청을 보내세요.
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
)

참조:Python 클라이언트 라이브러리.

설정 및 확인 한도 검토

다음 표의 공개된 조합만 사용합니다.

설정 값 및 기본값
topicGraph.kind 개체가 있는 경우 필요: none, diverse또는 balanced.
none 토픽 샘플링을 사용하지 않도록 설정합니다. diversityFactor 및 minDiversityPoolSize을 포함하지 마세요.
balanced 프로필의 계수와 무관하게 고정된 다양성 계수 0.2를 사용합니다. diversityFactor를 포함하지 마세요.
diversityFactor diverse에만 해당합니다. 포함 범위: 0 ~ 1. 누락은 프로필의 계수를 사용하거나, 구성된 것이 없으면 0.2를 사용합니다.
minDiversityPoolSize diverse 또는 balanced에만 해당합니다. 포함 범위: 250 ~ 10000. 누락은 프로필의 최소값을 사용하거나, 구성된 값이 없으면 1000를 사용합니다.

Troubleshooting

검색 결과를 해석하기 전에 구성 오류를 해결합니다.

Problem Action
토픽 바인딩 누락 유효한 검색 벡터 필드의 topicGraphProfile, 일치하는 프로필 및 해당 토픽 인덱스 indexName를 확인하세요.
누락되거나 호환되지 않는 벡터라이저 벡터 필드에 벡터라이저를 구성합니다.