Note
foundry IQ(Azure AI 검색)는 관리 검색을 위해 고급 기술 자료 및 기술 자료 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.
Important
엔터티 그래프는 공개 미리 보기 상태이며 Microsoft Azure 미리 보기에 대한 추가 사용 약관의 적용을 받습니다.
이 기능과 관련된 미리 보기 용어는 미리 보기 기능을 참조하세요.
엔터티 그래프(미리 보기)는 사람, 조직, 장소 및 기타 개념을 노드로, 이들 간의 관계를 에지로 나타냅니다. 예를 들어 특정 도시의 조직에서 일하는 사람이 누구인지와 같이 엔터티 간의 연결 관계에 의존하는 질문에 답변합니다.
Foundry IQ (Azure AI 검색)에서 그래프 추출은 Blob 콘텐츠를 엔터티 그래프로 바꿉니다. 그래프 사용 Blob 지식 원본을 만든 다음, 기술 자료를 통해 또는 GQL을 사용하여 직접 관리되는 그래프를 쿼리합니다. 토픽 그래프와 달리 엔터티 그래프는 온톨로지 기반의 명시적 엔터티 및 해당 관계를 캡처합니다.
Prerequisites
- REST API를
2026-11-01-preview지원하는 Foundry IQ 서비스입니다. - Python 예제의 경우 Python 3.10 이상, C# 예제의 경우 .NET 8 이상이 필요합니다.
- SDK 예제의 경우 지식 베이스 만들기의 공개 피드 미리 보기 패키지 지침을 따릅니다.
- Blob 지식 원본에 대한 서비스, 모델 배포, 인증 및 청구 필수 구성 요소입니다.
- 텍스트 콘텐츠가 있는 Azure Blob Storage 컨테이너입니다. 이 그래프 워크플로는 ADLS Gen2, ACL 수집 또는 민감도 레이블 수집을 지원하지 않습니다.
- 첫 번째 인덱싱 실행 전에 네이티브 Blob 일시 삭제를 사용하도록 설정됨. Blob 버전 관리 기능을 사용하지 않도록 설정해야 합니다.
- 수집 채팅 완료 모델입니다. 지식 베이스에는 자연어 그래프 쿼리에 대한 자체 모델 구성이 필요합니다.
- 테스트 지식 소스 및 지식 베이스를 만들고 삭제할 수 있는 권한입니다. 이 예제에 사용할 키 없는 인증을 구성합니다. 쿼리 권한 및 SDK 예제에서 사용하는 Azure Identity 라이브러리에 대해서는 지식 베이스 쿼리를 위한 필수 구성 요소를 참조하세요.
Limitations
엔터티 그래프 검색에는 새 기술 자료가 필요합니다. 기존 지식 베이스에서 엔터티 그래프 검색을 사용하도록 설정할 수 없습니다.
엔터티 그래프 기능은 이 릴리스에서 API 전용입니다. 기본 제공 UI를 Foundry IQ skills plugin의 일부로 사용할 수 있습니다.
모범 사례
- Foundry IQ skills plugin을 시작할 때 권장되는 방법으로 사용하세요. REST API 또는 SDK를 사용하여 직접 설정하려면 이 문서의 단계를 따르세요.
- 최상의 품질과 비용의 균형을 위해 를
gpt-5.6-luna과 함께 사용하세요. - 사용자가 지식 베이스에 질문할 것으로 예상되는 주요 질문을 중심으로 온톨로지를 디자인합니다. 온톨로지의 품질은 그래프의 모양과 내용을 결정하므로 해당 질문에 필요한 엔터티 유형과 관계를 포함하세요.
- 하나의 키 사용 사례와 작은 엔터티 형식 및 관계 집합으로 시작합니다. 확장하기 전에 대표 쿼리에 대해 추출된 그래프의 유효성을 검사합니다.
- 코퍼스 크기와 추출된 엔터티 및 관계 수를 기준으로 그래프 구축 비용을 예측합니다.
- 미리 보기 중에는 엔터티 그래프 기능 자체에 대한 추가 요금이 부과되지 않습니다. 모델 토큰 사용량에 대해서는 여전히 비용이 청구됩니다.
콘텐츠와 온톨로지 준비
온톨로지는 추출할 엔터티 형식 및 관계를 정의합니다. 사용자가 할 것으로 예상되는 질문을 중심으로 설계합니다. 이 예제에서는 사람, 그들이 근무하는 회사, 그리고 그 회사들이 위치한 도시를 사용합니다.
컨테이너에 있는
roster.txt라는 이름의 텍스트 Blob에 다음 가상 콘텐츠를 업로드합니다.Avery Chen works for Contoso Robotics. Contoso Robotics is located in Seattle. Jordan Davis works for Fabrikam Analytics. Fabrikam Analytics is located in Austin.avery.txt라는 이름의 두 번째 텍스트 blob을 업로드합니다. 시애틀 관계에 대한 또 다른 소스 어설션을 제공합니다.Avery Chen is employed by Contoso Robotics, an organization located in Seattle.온톨로지를 제약된 JSON-LD 문서로 정의합니다. 네임스페이스는 애플리케이션 용어를 식별합니다. 이 예제에서는
Organization,worksFor,Place,locatedIn및Person를 정의합니다.{ "@context": { "owl": "http://www.w3.org/2002/07/owl#", "rdfs": "http://www.w3.org/2000/01/rdf-schema#", "ex": "https://schema.search.azure.com/entities#" }, "@graph": [ { "@id": "ex:Person", "@type": "owl:Class", "rdfs:comment": "A person." }, { "@id": "ex:Organization", "@type": "owl:Class", "rdfs:comment": "An organization." }, { "@id": "ex:Place", "@type": "owl:Class", "rdfs:comment": "A geographic place." }, { "@id": "ex:worksFor", "@type": "owl:ObjectProperty", "rdfs:domain": {"@id": "ex:Person"}, "rdfs:range": {"@id": "ex:Organization"}, "rdfs:comment": "A person's employer." }, { "@id": "ex:locatedIn", "@type": "owl:ObjectProperty", "rdfs:domain": {"@id": "ex:Organization"}, "rdfs:range": {"@id": "ex:Place"}, "rdfs:comment": "The city where an organization is located." } ] }
그래프 지원 지식 소스 만들기
이 연습에서는 생성 시 온톨로지를 제공하고 수집 캐시는 구성하지 않습니다. 이 원본을 만들기 전에 온톨로지 선택: 캐시가 없으면 나중에 온톨로지 변경이 지원되지 않습니다. 온톨로지 업데이트가 필요한 원본에는 생성 시 구성된 다시 처리 사용 캐시가 필요합니다. 나중에 해당 캐시를 추가하거나 연결된 온톨로지를 제거할 수 없습니다.
REST 예제의 경우 REST 클라이언트에서 다음 변수를 설정합니다. 자리 표시자를 사용자 고유의 리소스 이름 및 액세스 토큰으로 바꿉니다. 액세스 토큰을 가져오려면 Foundry IQ에 연결을 참조하세요.
@search-endpoint = https://<search-service>.search.windows.net @api-version = 2026-11-01-preview @access-token = <search-access-token> @knowledge-source-name = employees-ks @knowledge-base-name = employees-kb @container-name = <blob-container> @storage-resource-id = /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account> @model-endpoint = https://<model-resource>.openai.azure.com @chat-deployment = <chat-completion-deployment> @embedding-deployment = <embedding-deployment>Python, C# 또는 REST를 사용하여 새 지식 원본을 만듭니다.
이
graphExtraction.ontology속성은 XML이 아닌 JSON 개체입니다.inline을(를)kind로 설정하고,value을(를) JSON 문자열로 직렬화된 제한된 JSON-LD 문서로 설정합니다.name속성은 선택 사항입니다. SDK 예제의 경우, 이전 섹션의 온톨로지를ontology.json로 저장하고 다음 환경 변수MODEL_ENDPOINT,KNOWLEDGE_SOURCE_NAME,EMBEDDING_DEPLOYMENT,SEARCH_ENDPOINT,CONTAINER_NAME,STORAGE_RESOURCE_ID및CHAT_DEPLOYMENT를 설정합니다.
import json
import os
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
AzureBlobKnowledgeSource,
AzureBlobKnowledgeSourceParameters,
AzureOpenAIVectorizerParameters,
KnowledgeBaseAzureOpenAIModel,
KnowledgeSourceContentExtractionMode,
KnowledgeSourceGraphExtractionParameters,
KnowledgeSourceGraphOntology,
)
from azure.search.documents.knowledgebases.models import (
KnowledgeSourceAzureOpenAIVectorizer,
KnowledgeSourceIngestionParameters,
)
with open("ontology.json", encoding="utf-8") as ontology_file:
entity_ontology_value = json.dumps(
json.load(ontology_file), separators=(",", ":")
)
entity_model_endpoint = os.environ["MODEL_ENDPOINT"]
entity_ingestion_parameters = KnowledgeSourceIngestionParameters(
content_extraction_mode=KnowledgeSourceContentExtractionMode.MINIMAL,
disable_image_verbalization=True,
chat_completion_model=KnowledgeBaseAzureOpenAIModel(
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
resource_url=entity_model_endpoint,
deployment_name=os.environ["CHAT_DEPLOYMENT"],
model_name="gpt-5.6-luna",
)
),
embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
resource_url=entity_model_endpoint,
deployment_name=os.environ["EMBEDDING_DEPLOYMENT"],
model_name="text-embedding-3-small",
)
),
)
entity_graph_parameters = KnowledgeSourceGraphExtractionParameters(
graph_name="employees",
page_degree_of_parallelism=2,
ontology=KnowledgeSourceGraphOntology(
kind="inline",
name="employees-v1",
value=entity_ontology_value,
),
)
entity_blob_parameters = AzureBlobKnowledgeSourceParameters(
connection_string=f"ResourceId={os.environ['STORAGE_RESOURCE_ID']}",
container_name=os.environ["CONTAINER_NAME"],
ingestion_parameters=entity_ingestion_parameters,
graph_extraction=entity_graph_parameters,
)
entity_knowledge_source = AzureBlobKnowledgeSource(
name=os.environ["KNOWLEDGE_SOURCE_NAME"],
description="Employees, their employers, and employer locations.",
results_processing="none",
azure_blob_parameters=entity_blob_parameters,
)
entity_index_client = SearchIndexClient(
endpoint=os.environ["SEARCH_ENDPOINT"],
credential=DefaultAzureCredential(),
)
entity_index_client.create_or_update_knowledge_source(
entity_knowledge_source
)
참조: Python 클라이언트 라이브러리.
프로비전 후 생성된 리소스 이름을 얻으려면 소스를 다시 조회합니다.
GET {{search-endpoint}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{access-token}}
참조: Knowledge sources REST API.
azureBlobParameters.createdResources.graphIndex가 표시될 때까지 기다립니다. 생성 응답에 azureBlobParameters.createdResources.graphIndex가 없을 수 있습니다. 직접 그래프 쿼리에는 반환된 이름을 사용하고, 원본 청크 조회에는 createdResources.index를 사용합니다. 이러한 속성은 읽기 전용입니다. 원본은 생성된 데이터 원본, 인덱서, 기술 세트, 청크 인덱스 및 그래프 인덱스 등을 소유합니다.
추출이 완료되는지 확인
생성이 인제스트를 시작합니다. 관계는 원본 콘텐츠가 처리될 때 그래프에 표시됩니다.
원본 상태를 가져옵니다.
GET {{search-endpoint}}/knowledgesources('{{knowledge-source-name}}')/status?api-version={{api-version}} Authorization: Bearer {{access-token}}참조: 지식 소스 REST API.
동기화가 완료될 때까지 기다립니다.
lastSynchronizationState.endTime가 존재하는지,lastSynchronizationState.itemsUpdatesFailed이 비어 있는지, 그리고currentSynchronizationState가 0인지 확인합니다. 수집에 실패하면 동기화 오류 및 생성된 인덱서의 상태를 검사합니다.synchronizationStatus: "active"는 원본을 동기화에 사용할 수 있음을 의미하며, 추출이 완료되었다는 뜻은 아닙니다.graphStatistics.triplesWritten가 반환되면 그래프의 총 크기가 아니라 해당 동기화 중의 쓰기 작업을 설명합니다.
지식 베이스를 통해 그래프를 쿼리하세요
지식 베이스는 자연어 관계 질문을 GQL로 변환합니다. 해당 모델 구성은 그래프를 추출하는 데 사용되는 모델과 별개입니다.
Python, C# 또는 REST를 사용하여 그래프 지원 소스를 참조하는 기술 자료를 만듭니다. 적절한 경우 기존 모델 배포를 다시 사용하지만 기술 자료에서 명시적으로 구성합니다.
SDK 예제의 경우 프로세스 환경에서
KNOWLEDGE_BASE_NAME도 설정하세요.
import os
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
AzureOpenAIVectorizerParameters,
KnowledgeBase,
KnowledgeBaseAzureOpenAIModel,
KnowledgeSourceReference,
)
from azure.search.documents.knowledgebases.models import (
KnowledgeRetrievalLowReasoningEffort,
KnowledgeRetrievalOutputMode,
)
entity_kb_model_parameters = AzureOpenAIVectorizerParameters(
resource_url=os.environ["MODEL_ENDPOINT"],
deployment_name=os.environ["CHAT_DEPLOYMENT"],
model_name="gpt-5.6-luna",
)
entity_knowledge_base = KnowledgeBase(
name=os.environ["KNOWLEDGE_BASE_NAME"],
knowledge_sources=[
KnowledgeSourceReference(
name=os.environ["KNOWLEDGE_SOURCE_NAME"]
)
],
models=[
KnowledgeBaseAzureOpenAIModel(
azure_open_ai_parameters=entity_kb_model_parameters
)
],
retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort(),
output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
retrieval_instructions=(
"Use graph_search for entity relationship questions. "
"Answer the relationship question by traversing the graph, "
"rather than using ordinary text search."
),
)
entity_kb_index_client = SearchIndexClient(
endpoint=os.environ["SEARCH_ENDPOINT"],
credential=DefaultAzureCredential(),
)
entity_kb_index_client.create_or_update_knowledge_base(
entity_knowledge_base
)
참조: Python 클라이언트 라이브러리.
Python, C# 또는 REST를 사용하여 다음 쿼리를 실행합니다.
요청은 활동 및 원본 참조를 사용하도록 설정합니다. 또한 생성된 쿼리 공개 및 소스 문서 로드를 사용하도록 설정합니다.
import os
from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
AgentRuntimeGraphHydrateDocumentsParams,
AgentRuntimeGraphParams,
AgentRuntimeGraphProvenanceParams,
AzureBlobKnowledgeSourceParams,
KnowledgeBaseMessage,
KnowledgeBaseMessageTextContent,
KnowledgeBaseRetrievalRequest,
)
source = AzureBlobKnowledgeSourceParams(
knowledge_source_name=os.environ["KNOWLEDGE_SOURCE_NAME"],
include_references=True,
include_reference_source_data=True,
fail_on_error=True,
graph_parameters=AgentRuntimeGraphParams(
include_query=True,
provenance=AgentRuntimeGraphProvenanceParams(
kind="hydrate",
hydrate_documents=AgentRuntimeGraphHydrateDocumentsParams(
select="uid,snippet,snippet_parent_id,blob_url", top=10
),
),
),
)
request = KnowledgeBaseRetrievalRequest(
messages=[
KnowledgeBaseMessage(
role="user",
content=[
KnowledgeBaseMessageTextContent(
text=(
"Which people work for organizations located in Seattle? "
"Return their names, organization names, and city names."
)
)
],
)
],
include_activity=True,
output_mode="extractiveData",
max_runtime_in_seconds=60,
knowledge_source_params=[source],
)
with KnowledgeBaseRetrievalClient(
endpoint=os.environ["SEARCH_ENDPOINT"],
credential=DefaultAzureCredential(),
knowledge_base_name=os.environ["KNOWLEDGE_BASE_NAME"],
) as client:
result = client.retrieve(request)
참조: Python 클라이언트 라이브러리.
그래프 참조는 graphIndexName에서 관리되는 그래프와 activitySource에서 실행 중인 작업을 식별합니다. 하이드레이션을 사용하도록 설정하면 추가 참조에 지원되는 원본 청크가 포함됩니다 sourceData.
해당 snippet_parent_id, blob_url 및 uid를 통해 결과를 해당 청크 및 상위 문서까지 추적할 수 있습니다.
지식 베이스 그래프 출처의 기본값은 none입니다. hydrated 청크 없이 그래프 행을 반환하려면 graphParameters.provenance를 생략합니다. 하이드레이션 top 은 그래프 행 수와 독립적으로 원본 문서를 제한합니다.
GQL을 사용하여 그래프를 직접 쿼리
애플리케이션이 순회 자체를 제공할 때 관리되는 그래프 인덱스를 사용합니다. 직접 search.graph 작업에는 .가 gql필요합니다. 선택적 search 속성은 전체 텍스트 검색에만 적용됩니다.
REST 클라이언트 또는
GRAPH_INDEX_NAMESDK 프로세스 환경에서 반환createdResources.graphIndex된 값으로 설정합니다graph-index-name.사람에서 고용주를 거쳐 도시까지 2홉 순회를 실행합니다. 레이블 및 조건자는 앞에서 정의한 온톨로지와 일치합니다.
import os
from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient
from azure.search.documents.models import (
GraphQueryProvenanceHydrateDocumentsParameters,
GraphQueryProvenanceParameters,
)
gql = (
"MATCH (person:Person)-[job]->(org:Organization)"
"-[location]->(city:Place) "
"WHERE job.predicate = 'worksFor' "
"AND location.predicate = 'locatedIn' "
"AND city.name = 'Seattle' "
"RETURN person.name AS person, org.name AS organization, "
"city.name AS city LIMIT 10"
)
with SearchClient(
os.environ["SEARCH_ENDPOINT"],
os.environ["GRAPH_INDEX_NAME"],
DefaultAzureCredential(),
) as client:
result = client.graph(
gql=gql,
include_statistics=True,
include_diagnostics=True,
provenance=GraphQueryProvenanceParameters(
kind="hydrate",
max_evidence_per_row=10,
hydrate_documents=GraphQueryProvenanceHydrateDocumentsParameters(
select="uid,snippet,snippet_parent_id,blob_url"
),
),
)
참조: Python 클라이언트 라이브러리.
각 행의 @search.graphProvenance에는 지원 edgeId, chunkId, 및 parentId 식별자가 포함됩니다. 그래프 어설션의 edgeId에 id을 조인하고, 생성된 청크 인덱스에서 chunkId를 uid에 조인합니다. 하이드레이션된 청크는 @search.graphProvenanceDocuments의 행 간에 공유됩니다. 이 관리되는 그래프의 경우 맵 키는 청크 ID입니다.
증거 개수를 해석하려면 exact를 사용합니다: evidenceCount.relation는 개수가 완전함을 의미하고, lowerBound는 수집이 제한되었음을 의미하므로 더 많은 지원 증거가 존재할 수 있습니다.
maxEvidencePerRow 는 수집되는 증거의 양을 제한합니다.
문서 하이드레이션이 없는 식별자의 경우 kind: "ids"를 사용하고 hydrateDocuments는 생략합니다. 직접 하이드레이션은 필드 선택을 지원하지만 기술 자료 수화와 달리 top를 허용하지 않습니다.
그래프 쿼리 문제 해결
검색 실패의 경우 최상위 오류를 검사하고, 반환되면 graphSearch 활동을 검사합니다.
| Problem | Action |
|---|---|
| 쿼리 모델 제한 | 검색 요청은 기술 자료의 쿼리 모델이 502(All retrieval tasks failed)을(를) 반환할 때 TooManyRequests와(과) 함께 429을(를) 반환할 수 있습니다. 해당 모델 배포에 대한 토큰 및 요청 속도 제한을 확인하고 요청을 지속적으로 다시 전송하는 대신 속도 제한 재시도 지침을 따릅니다. 이 쿼리 모델 오류는 추출 실패 또는 서버리스 그래프 쿼리에 대한 제한을 의미하지 않습니다. |
| 예상 그래프 행 없음 | 동기화가 완료되었는지 확인한 다음 직접 GQL 순회를 실행하여 저장된 관계를 확인하세요. 빈 쿼리 결과는 추출에 성공했음을 확인하지 않습니다. |
테스트 리소스 정리
이 연습에 대해 만든 기술 자료를 삭제한 다음, 지식 원본을 삭제합니다.
소스를 삭제하면 관리되는 그래프 인덱스를 포함하여 생성된 Search 리소스가 제거되지만 Blob은 삭제되지 않습니다. 테스트 Blob만 제거하거나, 이 연습을 위해 만든 경우에만 컨테이너를 제거합니다. 공유 스토리지 계정 및 모델 배포를 유지합니다.
관련 콘텐츠
기본 수집 설정 및 검색 워크플로는 다음을 참조하세요.