Erstellen und Abfragen eines Entitätsdiagramms

Note

Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.

Important

Entitätsdiagramm befindet sich in der öffentlichen Vorschau und unterliegt den ergänzenden Nutzungsbedingungen for Microsoft Azure Previews.

Spezifische Vorschaubedingungen für dieses Feature finden Sie unter Vorschaufunktionen.

Ein Entitätsgraph (Vorschau) stellt Personen, Organisationen, Orte und andere Konzepte als Knoten mit ihren Beziehungen als Kanten dar. Es beantwortet Fragen, die von Verbindungen zwischen Entitäten abhängen, z. B. welche Personen für Organisationen in einer bestimmten Stadt arbeiten.

In Foundry IQ (Azure KI-Suche) wandelt die Graphextraktion Blob-Inhalte in einen Entitätsgraphen um. Erstellen Sie eine graphfähige BLOB-Wissensquelle, und fragen Sie dann den verwalteten Graphen über eine Wissensdatenbank oder direkt mit GQL ab. Im Gegensatz zu einem Themendiagramm erfasst ein Entitätsdiagramm explizite Entitäten und ihre Beziehungen basierend auf einer Ontologie.

Prerequisites

  • Ein Foundry IQ-Dienst, 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.
  • Die Voraussetzungen für Dienst, Modellbereitstellungen, Authentifizierung und Abrechnung für eine Blob-Wissensquelle.
  • Ein Azure Blob Storage Container mit Textinhalt. Dieser Diagramm-Workflow unterstützt keine ADLS Gen2-, ACL-Aufnahme- oder Vertraulichkeitsbezeichnungsaufnahme.
  • Native Blob soft delete muss vor dem ersten Indizierungslauf aktiviert werden. Blob-Versionsverwaltung muss deaktiviert sein.
  • Ein Ingestion-Chat-Completion-Modell. Eine Wissensdatenbank benötigt eine eigene Modellkonfiguration für Natural-Language-Graphabfragen.
  • Berechtigung zum Erstellen und Löschen der Testwissensquelle und -wissensbasis. Konfigurieren Sie die schlüssellose Authentifizierung für diese Beispiele. Informationen zu Abfrageberechtigungen und der Azure Identitätsbibliothek, die von den SDK-Beispielen verwendet werden, finden Sie unter den Voraussetzungen für die Abfrage von Wissensbasen.

Limitations

Für den Abruf von Entitätsgraphen ist eine neue Wissensbasis erforderlich. Sie können den Entity-Graph-Abruf nicht auf einer vorhandenen Wissensbasis aktivieren.

Die Entitätsdiagrammfunktion ist in dieser Version nur über die API verfügbar. Sie können die integrierte Benutzeroberfläche als Teil des Foundry IQ Skills Plug-Ins verwenden.

Optimale Verfahren

  • Verwenden Sie das Foundry IQ skills plugin als empfohlene Methode, um zu beginnen. Führen Sie für die direkte Einrichtung mit der REST-API oder einem SDK die Schritte in diesem Artikel aus.
  • Verwenden Sie die Verwendung gpt-5.6-luna mit geringem Abrufgrund für die beste Qualität und Kostenbilanz.
  • Entwerfen Sie Ihre Ontologie rund um die wichtigsten Fragen, von denen Sie erwarten, dass Benutzer sie an Ihre Wissensdatenbank stellen. Die Qualität der Ontologie bestimmt die Form und den Inhalt des Graphen. Schließen Sie also die Entitätstypen und Beziehungen ein, die zur Beantwortung dieser Fragen erforderlich sind.
  • Beginnen Sie mit einem Schlüsselanwendungsfall und einer kleinen Gruppe von Entitätstypen und Beziehungen. Überprüfen Sie den extrahierten Graphen anhand repräsentativer Abfragen, bevor Sie skalieren.
  • Schätzen Sie die Kosten für den Graphaufbau basierend auf der Korpusgröße und der Anzahl der extrahierten Entitäten und Beziehungen.
  • Während der Vorschau gibt es keine zusätzlichen Kosten für das Entitätsgraph-Feature selbst. Sie zahlen weiterhin für die verwendeten Modelltoken.

Inhalte und eine Ontologie vorbereiten

Eine Ontologie definiert die zu extrahierenden Entitätstypen und Beziehungen. Entwerfen Sie sie in Bezug auf die Fragen, die Benutzer voraussichtlich stellen. In diesem Beispiel werden Menschen, ihre Arbeitgeber und die Städte verwendet, in denen sich diese Arbeitgeber befinden.

  1. Laden Sie den folgenden fiktiven Inhalt in einen Text-Blob mit dem Namen roster.txt in Ihrem Container hoch.

    Avery Chen works for Contoso Robotics.
    Contoso Robotics is located in Seattle.
    Jordan Davis works for Fabrikam Analytics.
    Fabrikam Analytics is located in Austin.
    
  2. Laden Sie ein zweites Text-BLOB mit dem Namen avery.txthoch. Es stellt eine weitere Quell-Assertion für die Seattle-Beziehung bereit.

    Avery Chen is employed by Contoso Robotics, an organization located in Seattle.
    
  3. Definieren Sie die Ontologie als eingeschränktes JSON-LD Dokument. Der Namespace identifiziert Ihre Anwendungsbegriffe; in diesem Beispiel werden Person, Organization, Place, worksFor und locatedIn definiert.

    {
      "@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."
        }
      ]
    }
    

Erstellen der graphfähigen Wissensquelle

Diese exemplarische Vorgehensweise stellt die Ontologie beim Erstellen und konfiguriert keinen Aufnahmecache. Wählen Sie die Ontologie aus, bevor Sie diese Quelle erstellen: Ohne Cache werden spätere Ontologieänderungen nicht unterstützt. Quellen, die Ontologieupdates benötigen, erfordern einen beim Erstellen konfigurierten für die Neuverarbeitung aktivierten Cache; Sie können diesen Cache nicht später hinzufügen oder eine angefügte Ontologie entfernen.

  1. Legen Sie für das REST-Beispiel die folgenden Variablen in Ihrem REST-Client fest. Ersetzen Sie die Platzhalter durch Ihre eigenen Ressourcennamen und das Zugriffstoken. Informationen zum Abrufen eines Zugriffstokens finden Sie unter Connect to 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>
    
  2. Erstellen Sie eine neue Wissensquelle mit Python, C# oder REST.

    Die graphExtraction.ontology Eigenschaft ist ein JSON-Objekt, nicht XML. Setzen Sie kind auf inline und value auf das eingeschränkte JSON-LD-Dokument, das als JSON-Zeichenfolge serialisiert wurde. Die name-Eigenschaft ist optional. Speichern Sie für die SDK-Beispiele die Ontologie aus dem vorherigen Abschnitt als ontology.json, und legen Sie die folgenden Umgebungsvariablen fest: SEARCH_ENDPOINT, KNOWLEDGE_SOURCE_NAME, CONTAINER_NAME, STORAGE_RESOURCE_ID, MODEL_ENDPOINT, CHAT_DEPLOYMENT und EMBEDDING_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
)

Referenz: Python Clientbibliothek.

Rufen Sie die Quelle erneut ab, um die generierten Ressourcennamen nach der Bereitstellung abzurufen.

GET {{search-endpoint}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{access-token}}

Referenz: REST-API für Wissensquellen.

Warten Sie, bis azureBlobParameters.createdResources.graphIndex angezeigt wird; es kann in der Erstellungsantwort fehlen. Verwenden Sie diesen zurückgegebenen Namen für Direkte Graph-Abfragen und createdResources.index für Quellabschnitts-Nachschlagevorgänge. Diese Eigenschaften sind schreibgeschützt. Die Quelle besitzt die generierte Datenquelle, den Indexer, das Skillset, den Blockindex und den Graphindex.

Überprüfen, ob die Extraktion abgeschlossen ist

Die Erstellung startet die Ingestion. Beziehungen werden im Diagramm angezeigt, während der Quellinhalt verarbeitet wird.

  1. Rufen Sie den Quellstatus ab.

    GET {{search-endpoint}}/knowledgesources('{{knowledge-source-name}}')/status?api-version={{api-version}}
    Authorization: Bearer {{access-token}}
    

    Referenz: REST-API für Wissensquellen.

  2. Warten Sie, bis die Synchronisierung abgeschlossen ist. Überprüfen Sie, ob lastSynchronizationState.endTime vorhanden ist, currentSynchronizationState leer ist und lastSynchronizationState.itemsUpdatesFailed null ist. Überprüfen Sie Synchronisierungsfehler und den Status des generierten Indexers, wenn die Aufnahme fehlschlägt.

    synchronizationStatus: "active" bedeutet, dass die Quelle für die Synchronisierung verfügbar ist, und nicht, dass die Extraktion abgeschlossen ist. Bei Rückgabe beschreibt graphStatistics.triplesWritten Schreibvorgänge während dieser Synchronisierung und nicht die Gesamtgröße des Diagramms.

Fragen Sie den Graphen über eine Wissensbasis ab

Eine Wissensbasis übersetzt eine Frage zu Beziehungen in natürlicher Sprache in GQL. Die Modellkonfiguration ist vom Modell getrennt, das zum Extrahieren des Graphen verwendet wird.

  1. Erstellen Sie eine Wissensdatenbank, die auf die graphfähige Quelle mit Python, C# oder REST verweist. Verwenden Sie ggf. eine vorhandene Modellbereitstellung wieder, konfigurieren Sie sie jedoch explizit in der Wissensdatenbank.

    Legen Sie für SDK-Beispiele auch KNOWLEDGE_BASE_NAME in Ihrer Prozessumgebung fest.

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
)

Verweis: Python Client-Bibliothek.

  1. Führen Sie die folgende Abfrage mit Python, C# oder REST aus.

    Die Anforderung aktiviert Aktivitäts- und Quellverweise. Außerdem aktiviert dies die Offenlegung generierter Abfragen und die Hydratation von Quelldokumenten.

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)

Referenz: Python Clientbibliothek.

Graph-Verweise identifizieren den verwalteten Graphen in graphIndexName und die Ausführungsaktivität in activitySource. Wenn die Hydratation aktiviert ist, enthalten zusätzliche Verweise unterstützende Quellblöcke in sourceData. Sie uidkönnen snippet_parent_idblob_url das Ergebnis auf den zugehörigen Block und das übergeordnete Dokument nachverfolgen.

Die Graph-Provenienz der Wissensdatenbank ist standardmäßig auf none gesetzt. Wenn Sie Graphzeilen ohne hydratisierte Blöcke zurückgeben möchten, lassen Sie graphParameters.provenance aus. Die Hydrierung schränkt top Quelldokumente unabhängig von der Anzahl der Graphzeilen ein.

Fragen Sie den Graphen direkt mit GQL ab

Verwenden Sie den verwalteten Diagrammindex, wenn Ihre Anwendung die Traversale selbst bereitstellt. Der direkte search.graph Vorgang erfordert gql. Die optionale search Eigenschaft gilt nur für die Volltextsuche.

  1. Setzen Sie graph-index-name in Ihrem REST-Client oder GRAPH_INDEX_NAME in der Prozessumgebung Ihres SDK auf den zurückgegebenen Wert createdResources.graphIndex.

  2. Führen Sie einen Zwei-Hop-Traversal von einer Person zu einem Arbeitgeber und dann einer Stadt durch. Die Bezeichnungen und Prädikate entsprechen der zuvor definierten Ontologie.

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

Referenz: Python Clientbibliothek.

@search.graphProvenance jeder Zeile enthält unterstützende edgeId, chunkId und parentId-Bezeichner. Verbinden Sie edgeId mit dem id der Graph-Assertion und chunkId mit uid im generierten Chunk-Index. Hydratierte Chunks werden über Zeilen hinweg geteilt in @search.graphProvenanceDocuments; für dieses verwaltete Diagramm sind die Kartenschlüssel Chunk-IDs.

Wird evidenceCount.relation verwendet, um die Anzahl der Nachweise zu interpretieren: exact bedeutet, dass die Anzahl vollständig ist und lowerBound bedeutet, dass die Sammlung begrenzt wurde, sodass mehr unterstützende Nachweise vorhanden sein können. maxEvidencePerRow begrenzt, wie viele Belege erfasst werden.

Verwenden Sie hydrateDocuments und lassen Sie kind: "ids" für Bezeichner ohne Dokumenthydratation weg. Direkte Hydrierung unterstützt die Feldauswahl, aber im Gegensatz zur Wissensbasis-Hydrierung akzeptiert sie top nicht.

Problembehandlung bei Graphabfragen

Überprüfen Sie bei Abruffehlern den Fehler der obersten Ebene, und überprüfen Sie, wenn sie zurückgegeben wird, die graphSearch Aktivität.

Problem Action
Drosselung des Abfragemodells Eine Abrufanforderung kann TooManyRequests mit 429 zurückgeben, wenn das Abfragemodell der Knowledge Base 502 zurückgibt (All retrieval tasks failed). Überprüfen Sie die Token- und Anforderungsratenbeschränkungen für diese Modellbereitstellung, und befolgen Sie die Hinweise zu Wiederholungen bei Ratenbegrenzung, anstatt Anforderungen kontinuierlich erneut zu senden. Bei diesem Abfragemodellfehler wird kein Extraktionsfehler oder eine Einschränkung für serverlose Diagrammabfragen hergestellt.
Keine erwarteten Graphzeilen Überprüfen Sie, ob die Synchronisierung abgeschlossen ist, und führen Sie dann die direkte GQL-Traversal aus, um die gespeicherten Beziehungen zu überprüfen. Ein leeres Abfrageergebnis bestätigt nicht, dass die Extraktion erfolgreich war.

Bereinigen von Testressourcen

Löschen Sie die wissensbasis, die Sie für diese Übung erstellt haben, und löschen Sie dann die Wissensquelle.

Durch das Löschen der Quelle werden die generierten Suchressourcen entfernt, einschließlich des verwalteten Diagrammindexes, aber ihre BLOBs werden nicht gelöscht. Entfernen Sie nur die Test-BLOBs oder den Container, wenn Sie ihn für diese Übung erstellt haben. Behalten Sie freigegebene Speicherkonten und Modellbereitstellungen bei.

Informationen zum zugrunde liegenden Setup- und Abrufworkflow finden Sie unter: