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.
Note
Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.
Important
Graf encji jest dostępny w publicznej wersji zapoznawczej i podlega dodatkowym warunkom użytkowania dotyczącym wersji zapoznawczych Microsoft Azure. Aby zapoznać się z warunkami wersji zapoznawczej dotyczącymi tej funkcji, zobacz sekcję Funkcje w wersji zapoznawczej.
Graf encji (wersja zapoznawcza) przedstawia osoby, organizacje, miejsca i inne pojęcia w postaci węzłów, a relacje między nimi w postaci krawędzi. Odpowiada na pytania, które zależą od połączeń między jednostkami, na przykład od tego, które osoby pracują dla organizacji w określonym mieście.
W Foundry IQ (Wyszukiwanie AI platformy Azure) ekstrakcja grafu przekształca zawartość obiektu Blob w graf encji. Utwórz źródło wiedzy z obsługą grafów obiektów blob, a następnie wykonaj zapytanie względem zarządzanego grafu za pomocą bazy wiedzy lub bezpośrednio przy użyciu języka GQL. W przeciwieństwie do grafu tematycznego, graf encji przedstawia jawne encje i ich relacje na podstawie ontologii.
Prerequisites
- Usługa IQ usługi Foundry, 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 z publicznego źródła w wersji zapoznawczej w temacie Tworzenie bazy wiedzy.
- Usługa, wdrożenia modelu, uwierzytelnianie i wymagania wstępne dotyczące rozliczeń dla źródła wiedzy Blob.
- Kontener Azure Blob Storage z zawartością tekstową. Ten przepływ pracy grafu nie obsługuje ADLS Gen2, pozyskiwania list ACL ani pozyskiwania etykiet wrażliwości.
- Natywne usuwanie miękkie obiektów blob jest włączone przed pierwszym uruchomieniem indeksowania. Przechowywanie wersji obiektów blob musi być wyłączone.
- Model uzupełniania czatu do pozyskiwania danych. Baza wiedzy wymaga własnej konfiguracji modelu dla zapytań grafowych w języku naturalnym.
- Uprawnienie do tworzenia i usuwania testowego źródła wiedzy i bazy wiedzy. Skonfiguruj uwierzytelnianie bez klucza dla tych przykładów. Informacje o uprawnieniach do wykonywania zapytań i bibliotece Azure Identity używanej w przykładach zestawu SDK znajdziesz w wymaganiach wstępnych dotyczących wykonywania zapytań dotyczących baz wiedzy.
Limitations
Pobieranie grafu encji wymaga nowej bazy wiedzy. Nie można włączyć pobierania grafu encji w istniejącej bazie wiedzy.
Funkcja grafu jednostek jest dostępna wyłącznie przez interfejs API w tej wersji. Możesz użyć wbudowanego interfejsu użytkownika w ramach wtyczki umiejętności Foundry IQ.
Najlepsze praktyki
- Użyj wtyczki umiejętności Foundry IQ jako zalecanego sposobu rozpoczęcia pracy. Aby uzyskać bezpośrednią konfigurację za pomocą interfejsu API REST lub zestawu SDK, wykonaj kroki opisane w tym artykule.
- Używaj
gpt-5.6-lunaz niskim nakładem rozumowania przy wyszukiwaniu, aby uzyskać najlepszą jakość i równowagę kosztów. - Zaprojektuj swoją ontologię w oparciu o kluczowe pytania, które użytkownicy będą zadawać Twojej bazie wiedzy. Jakość ontologii określa kształt i zawartość grafu, dlatego obejmują typy jednostek i relacje, których te pytania wymagają.
- Zacznij od jednego kluczowego przypadku użycia i małego zestawu typów jednostek i relacji. Przed skalowaniem w górę zweryfikuj wyodrębniony graf względem reprezentatywnych zapytań.
- Oszacuj koszty tworzenia grafu na podstawie zarówno rozmiaru korpusu, jak i liczby wyodrębnionych jednostek i relacji.
- W trakcie korzystania z wersji zapoznawczej nie są naliczane dodatkowe opłaty za samą funkcję grafu encji. Nadal płacisz za używane tokeny modelu.
Przygotuj treść i ontologię
Ontologia definiuje typy jednostek i relacje do wyodrębnienia. Zaprojektuj je wokół pytań, których, jak oczekujesz, będą zadawać użytkownicy. W tym przykładzie użyto ludzi, ich pracodawców i miast, w których znajdują się ci pracodawcy.
Prześlij następującą fikcyjną zawartość do obiektu blob tekstowego o nazwie
roster.txtw kontenerze.Avery Chen works for Contoso Robotics. Contoso Robotics is located in Seattle. Jordan Davis works for Fabrikam Analytics. Fabrikam Analytics is located in Austin.Przekaż drugi tekstowy obiekt blob o nazwie
avery.txt. Zapewnia inną asercję źródłową dla relacji Seattle.Avery Chen is employed by Contoso Robotics, an organization located in Seattle.Zdefiniuj ontologię jako ograniczony dokument JSON-LD. Przestrzeń nazw identyfikuje terminy aplikacji; w tym przykładzie zdefiniowano
Person,Organization,Place,worksForilocatedIn.{ "@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." } ] }
Tworzenie źródła wiedzy z obsługą grafu
Ten przewodnik określa ontologię podczas tworzenia i nie konfiguruje pamięci podręcznej ingestii. Wybierz ontologię przed utworzeniem tego źródła: bez pamięci podręcznej późniejsze zmiany ontologii nie są obsługiwane. Źródła wymagające aktualizacji ontologii wymagają pamięci podręcznej z obsługą ponownego przetwarzania skonfigurowanej podczas tworzenia; Nie można dodać tej pamięci podręcznej później ani usunąć dołączonej ontologii.
W przykładzie REST ustaw następujące zmienne w kliencie REST. Zastąp symbole zastępcze własnymi nazwami zasobów i tokenem dostępu. Aby uzyskać token dostępu, zobacz Łączenie z usługą 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>Utwórz nowe źródło wiedzy przy użyciu Python, C# lub REST.
Właściwość
graphExtraction.ontologyjest obiektem JSON, a nie XML. Ustawkindnainlinei ustawvaluena ograniczony dokument JSON-LD serializowany jako ciąg JSON. Właściwośćnamejest opcjonalna. W przykładach zestawu SDK zapisz ontologię z poprzedniej sekcji jakoontology.jsoni ustaw następujące zmienne środowiskowe:SEARCH_ENDPOINT,KNOWLEDGE_SOURCE_NAME,MODEL_ENDPOINT,CHAT_DEPLOYMENT,CONTAINER_NAME,STORAGE_RESOURCE_IDiEMBEDDING_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
)
Dokumentacja: biblioteki klienta Python.
Ponownie odczytaj źródło, aby pobrać wygenerowane nazwy zasobów po aprowizacji.
GET {{search-endpoint}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{access-token}}
Dokumentacja: Interfejs API REST źródeł wiedzy.
Poczekaj, aż pojawi się azureBlobParameters.createdResources.graphIndex; może być nieobecne w odpowiedzi tworzenia. Użyj tej zwracanej nazwy do bezpośrednich zapytań grafowych oraz createdResources.index do wyszukiwania fragmentów źródłowych. Te właściwości są tylko do odczytu. Źródło ma własne wygenerowane źródło danych, indeksator, zestaw umiejętności, indeks fragmentów i indeks grafu.
Sprawdź, czy wyodrębnianie zostało zakończone
Utworzenie rozpoczyna import danych. Relacje są wyświetlane na grafie podczas przetwarzania zawartości źródłowej.
Pobierz stan źródła.
GET {{search-endpoint}}/knowledgesources('{{knowledge-source-name}}')/status?api-version={{api-version}} Authorization: Bearer {{access-token}}Dokumentacja: Interfejs API REST źródeł wiedzy.
Poczekaj na zakończenie synchronizacji. Sprawdź, czy
lastSynchronizationState.endTimejest obecny,currentSynchronizationStatejest pusty ilastSynchronizationState.itemsUpdatesFailedma wartość zero. Sprawdź błędy synchronizacji i stan wygenerowanego indeksatora, jeśli pozyskiwanie nie powiedzie się.synchronizationStatus: "active"oznacza, że źródło jest dostępne do synchronizacji, a nie, że wyodrębnianie zostało ukończone. Po zwróceniugraphStatistics.triplesWrittenopisuje zapisy podczas tej synchronizacji, a nie całkowity rozmiar grafu.
Wysyłanie zapytań do grafu przez bazę wiedzy
Baza wiedzy tłumaczy pytanie o relacje zadane w języku naturalnym na język GQL. Jego konfiguracja modelu jest oddzielona od modelu używanego do wyodrębniania grafu.
Utwórz bazę wiedzy, która odwołuje się do źródła z obsługą grafów przy użyciu Python, C# lub REST. W razie potrzeby ponownie użyj istniejącego wdrożenia modelu, ale skonfiguruj je jawnie w bazie wiedzy.
W przypadku przykładów zestawu SDK również ustaw
KNOWLEDGE_BASE_NAMEw środowisku procesu.
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
)
Dokumentacja: biblioteki klienta Python.
Uruchom następujące zapytanie z Python, C# lub REST.
Żądanie włącza odwołania do działań i dokumentów źródłowych. Włącza również ujawnienie generowanych zapytań i hydrację dokumentu źródłowego.
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)
Dokumentacja: biblioteki klienta Python.
Odwołania do grafu identyfikują zarządzany graf w graphIndexName i wykonywane działanie w activitySource. Przy włączonej hydracji dodatkowe odwołania zawierają powiązane fragmenty źródłowe w sourceData. Ich uid, snippet_parent_id i blob_url umożliwiają prześledzenie wyniku do jego fragmentu i dokumentu nadrzędnego.
Wartością domyślną pochodzenia grafu bazy wiedzy jest none. Aby zwrócić wiersze grafu bez zhydratowanych fragmentów, pomiń element graphParameters.provenance. Hydration top ogranicza dokumenty źródłowe niezależnie od liczby wierszy grafu.
Wykonywanie zapytań względem grafu bezpośrednio za pomocą języka GQL
Użyj zarządzanego indeksu grafu, gdy aplikacja sama realizuje przechodzenie. Operacja bezpośrednia search.graph wymaga gql. Jego opcjonalna search właściwość ma zastosowanie tylko do wyszukiwania pełnotekstowego.
Ustaw
graph-index-namew kliencie REST lubGRAPH_INDEX_NAMEw środowisku procesu SDK na zwróconą wartośćcreatedResources.graphIndex.Uruchom trawersowanie dwuprzeskokowe od osoby do pracodawcy, a następnie do miasta. Etykiety i predykaty są zgodne ze zdefiniowaną wcześniej ontologią.
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"
),
),
)
Dokumentacja: biblioteki klienta Python.
Pole @search.graphProvenance każdego wiersza zawiera uzasadniające identyfikatory edgeId, chunkId i parentId. Dołącz edgeId do id asercji grafu, a chunkId do uid w wygenerowanym indeksie fragmentów. Zmaterializowane fragmenty są współużytkowane między wierszami w elemencie @search.graphProvenanceDocuments. W przypadku tego zarządzanego grafu klucze mapy są identyfikatorami fragmentów.
Użyj evidenceCount.relation, aby zinterpretować liczbę danych dowodowych: exact oznacza, że liczba jest kompletna, a lowerBound oznacza, że zbieranie było ograniczone, więc może istnieć więcej danych dowodowych pomocniczych.
maxEvidencePerRow ogranicza ilość zebranych danych dowodowych.
W przypadku identyfikatorów bez nawodnienia dokumentu użyj polecenia kind: "ids" i pomiń hydrateDocumentselement . Bezpośrednie hydration obsługuje wybór pól, ale w przeciwieństwie do hydration bazy wiedzy nie akceptuje top.
Rozwiązywanie problemów z zapytaniami grafu
W przypadku niepowodzeń pobierania sprawdź błąd najwyższego poziomu i, jeśli zostanie zwrócona, aktywność graphSearch.
| Problem | Action |
|---|---|
| Ograniczanie przepustowości modelu zapytań | Żądanie pobrania może zwracać 502 z All retrieval tasks failed, gdy model zapytań bazy wiedzy zwraca 429 wartość (TooManyRequests). Sprawdź limity tokenów i liczby żądań dla tego wdrożenia modelu, a następnie postępuj zgodnie ze wskazówkami dotyczącymi ponawiania żądań po osiągnięciu limitu, a nie ciągłym wysyłaniem żądań. Ten błąd modelu zapytań nie oznacza błędu wyodrębniania ani ograniczenia dotyczącego bezserwerowych zapytań grafowych. |
| Brak oczekiwanych wierszy grafu | Sprawdź, czy synchronizacja została ukończona, a następnie uruchom bezpośrednie przejście GQL, aby sprawdzić przechowywane relacje. Pusty wynik zapytania nie potwierdza, że wyodrębnianie powiodło się. |
Czyszczenie zasobów testowych
Usuń bazę wiedzy utworzoną na potrzeby tego ćwiczenia, a następnie usuń źródło danych.
Usunięcie źródła powoduje usunięcie wygenerowanych zasobów wyszukiwania, w tym zarządzanego indeksu grafu, ale nie powoduje usunięcia obiektów blob. Usuń tylko testowe obiekty blob lub kontener, jeśli został utworzony na potrzeby tego ćwiczenia. Zachowaj współużytkowane konta magazynu danych i wdrożenia modelu.
Treści powiązane
Aby zapoznać się z bazową konfiguracją pozyskiwania i przepływem pracy pobierania, zobacz: