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.
Uwaga
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.
Ważna
Funkcje lub możliwości oznaczone (wersja zapoznawcza) w tym artykule znajdują się w publicznej wersji zapoznawczej i podlegają dodatkowym warunkom użytkowania Microsoft Azure w wersji zapoznawczej. Informacje o warunkach wersji zapoznawczej specyficznych dla Foundry IQ (Wyszukiwanie AI platformy Azure) znajdziesz w artykule Funkcje wersji zapoznawczej. Informacje o terminach stosowanych podczas nawiązywania połączenia z zewnętrznymi źródłami danych znajdziesz w sekcji Zewnętrzne źródła danych.
Utwórz indeksowane źródło wiedzy usługi OneLake przy użyciu interfejsu 2026-11-01-preview API REST w celu pozyskiwania Microsoft plików OneLake i zachowywania uprawnień źródłowych w usłudze Foundry IQ (Wyszukiwanie AI platformy Azure).
Źródła wiedzy są tworzone niezależnie, przywoływane w bazie wiedzy i używane jako dane uziemienia, gdy baza wiedzy jest odpytywane w czasie wykonywania zapytań.
Podczas tworzenia indeksowanego źródła wiedzy usługi OneLake funkcja IQ rozwiązania Foundry automatycznie generuje następujące obiekty:
- Źródło danych reprezentujące jezioro.
- Zestaw umiejętności, który fragmentuje i opcjonalnie wektoryzuje zawartość wielomodalną z jeziora.
- Indeks, który przechowuje wzbogaconą treść i spełnia kryteria odbioru przez system agenta.
- Indeksator, który używa poprzednich obiektów do napędzania potoku indeksowania i wzbogacania.
Wygenerowany indeksator jest zgodny z indeksatorem OneLake. Wymagania wstępne, obsługiwane zadania, formaty dokumentów i ograniczenia dotyczą również źródeł wiedzy OneLake. Zobacz dokumentację indeksatora OneLake i limity indeksatora. Zwykła obsługa pozyskiwania skrótów jest oddzielona od pobierania z rozpoznawaniem uprawnień, która wyklucza zawartość pochodną skrótów w tej wersji zapoznawczej. Jeśli wygenerowany zestaw umiejętności wywołuje usługę zewnętrzną, zastosowanie mają również limity danych wejściowych tej umiejętności i limity usługi.
Wymagania wstępne
Usługa IQ Foundry w chmurze publicznej Azure w regionie oferującym wyszukiwanie agentowe.
Ukończenie wymagań wstępnych indeksatora OneLake i przygotowania danych.
Ukończenie wymagań wstępnych zachowywania uprawnień w usłudze OneLake. Usługa Foundry IQ musi mieć tożsamość zarządzaną przypisaną przez system. Przypisz tej tożsamości rolę Admin w obszarze roboczym Fabric.
Uprawnienie do tworzenia źródeł wiedzy. Skonfiguruj uwierzytelnianie bez klucza przy użyciu ról Współautor usługi wyszukiwania i Współautor danych indeksu wyszukiwania przypisanych do konta użytkownika (zalecane) lub użyj klucza interfejsu API administratora.
Klient REST. Użyj wersji
2026-11-01-previewinterfejsu API REST usługi Wyszukiwania dla żądań w tym artykule. W przypadku uwierzytelniania bez klucza uzyskaj token Microsoft Entra ID do nagłówkaAuthorization.Jeśli skonfigurujesz
contentExtractionModejakostandard, użyj zasobu Microsoft Foundry w regionie obsługiwanym przez usługę Content Understanding w narzędziach Foundry Tools i jegohttps://<resource-name>.services.ai.azure.compunkcie końcowym. Wdróż model embeddingów oraz multimodalny model czatu, jeśli włączysz funkcję opisywania obrazów. W przykładzie w tym artykule użytominimali wyłączono werbalizację obrazów.W przypadku wywołań tożsamości zarządzanej do osadzeń Azure OpenAI lub werbalizacji obrazów przypisz rolę Cognitive Services OpenAI User do wybranej tożsamości w zasobie Azure OpenAI lub nadrzędnym zasobie Foundry odpowiadającym elementowi
resourceUri. Uprawnienia usługi wyodrębniania są oddzielne. Zobacz Przypisz rolę.W przypadku pozyskiwania prywatnego użyj kwalifikującej się usługi S2, S3, L1 lub L2 Dedykowanej, która spełnia wymagania dotyczące obciążenia udostępnionego łącza prywatnego. Utwórz i zatwierdź udostępnione łącze prywatne do obszaru roboczego Fabric, używając elementów
workspacetarget iMicrosoft.Fabric/privateLinkServicesForFabricgroup ID opisanych w temacie Obsługiwane typy zasobów. Skonfiguruj zatwierdzone linki dla wszelkiego chronionego wyodrębniania, modelu lub innych zależności platformy Azure używanych przez potok.
Limitations
Serverless i S3 HD nie obsługują prywatnego wykonywania indeksatora ani udostępnionych prywatnych linków usługi Search dla ruchu wychodzącego. Konfiguracja granicy zabezpieczeń sieciowych kontroluje obsługiwany dostęp do publicznego punktu końcowego; nie włącza wykonywania prywatnego.
Po włączeniu pozyskiwania uprawnień z usługi OneLake pomiń ustawienia magazynu zasobów, pamięci podręcznej wzbogacania i wyodrębniania grafu. Aby uzyskać informacje o obsługiwanych umiejętnościach i innych ograniczeniach dotyczących wersji zapoznawczej, zobacz Ograniczenia zachowania uprawnień usługi OneLake.
Sprawdzanie istniejących źródeł wiedzy
Źródłem wiedzy jest obiekt najwyższego poziomu wielokrotnego użytku. Przed wybraniem nazwy lub utworzenia nowego obiektu sprawdź istniejące źródła wiedzy.
Wyślij GET /knowledgesources?api-version=2026-11-01-preview&$select=name,kind do punktu końcowego wyszukiwania.
Aby przejrzeć pojedynczą definicję, wyślij polecenie GET /knowledgesources/<knowledge-source-name>?api-version=2026-11-01-preview. Uwzględnij nagłówek uwierzytelniania w każdym żądaniu.
Tworzenie źródła wiedzy
Utwórz źródło wiedzy za pomocą następującego żądania REST. W tym przykładzie jest używana minimalna funkcja wyodrębniania zawartości, wyłącza werbalizacja obrazów i włącza zachowywanie uprawnień usługi OneLake.
Zachowywanie uprawnień OneLake (wersja zapoznawcza)
Ustaw zarówno oneLakeParentFolders, jak i oneLakeLakehouseId w indexedOneLakeParameters.ingestionParameters.ingestionPermissionOptions. W przeciwieństwie do indexerPermissionOptions w przypadku bezpośredniego źródła danych OneLake obie wartości są wymagane razem dla zabezpieczonego indeksowanego źródła wiedzy OneLake.
Zastąp nazwę usługi Foundry IQ, token dostępu, identyfikator obszaru roboczego i identyfikator lakehouse własnymi wartościami.
PUT https://<search-service>.search.windows.net/knowledgesources/my-secured-onelake-ks?api-version=2026-11-01-preview
Authorization: Bearer <access-token>
Content-Type: application/json
{
"name": "my-secured-onelake-ks",
"kind": "indexedOneLake",
"indexedOneLakeParameters": {
"fabricWorkspaceId": "<fabric-workspace-id>",
"lakehouseId": "<lakehouse-id>",
"ingestionParameters": {
"contentExtractionMode": "minimal",
"disableImageVerbalization": true,
"ingestionPermissionOptions": [
"oneLakeParentFolders",
"oneLakeLakehouseId"
]
}
}
}
Aby uzyskać informacje o konfiguracji uprawnień i jej ograniczeniach, zobacz Konfigurowanie indeksowanego źródła wiedzy OneLake.
Odpowiedź na utworzenie zawiera listę wygenerowanych obiektów w obszarze indexedOneLakeParameters.createdResources. Źródło wiedzy generuje indeks z włączonymi uprawnieniami, mapowania pól i projekcje fragmentów. Nie trzeba konfigurować tych mapowań oddzielnie. Aby uzyskać informacje o wymaganiach dotyczących pól generowanych i autoryzacji w czasie wykonywania zapytań, zobacz Zachowywanie uprawnień OneLake.
Ustawienia opcjonalne używają następujących ścieżek właściwości:
-
indexedOneLakeParameters.targetPath: Ogranicz pozyskiwanie do folderu w lakehouse. Zawartość pochodna skrótów pozostaje wykluczona z pobierania z rozpoznawania uprawnień. -
indexedOneLakeParameters.ingestionParameters.embeddingModel: Skonfiguruj opcjonalną wektoryzację treści. -
indexedOneLakeParameters.ingestionParameters.chatCompletionModel: Skonfiguruj model do generowania odpowiedzi czatu na potrzeby słowizacji obrazów lub wyodrębniania kontekstu. W przykładzie wyłączono werbalizację obrazu. -
indexedOneLakeParameters.ingestionParameters.ingestionSchedule: Skonfiguruj odpytywanie zmian źródła za pomocąintervaloraz opcjonalnegostartTime. Automatyczna kontynuacja po odpowiednim zatrzymaniu czasu wykonywania jest oddzielona od tego interwału sondowania. Ani planowanie, ani kontynuacja nie ustanawiają aktualności uprawnień.
Zachowaj obie opcje uprawnień podczas dodawania ustawień opcjonalnych. Domyślny tryb dostępu do sieci to public; w przypadku kwalifikujących się konfiguracji dedykowanych zobacz Ograniczanie pozyskiwania do sieci prywatnej.
Ogranicz pozyskiwanie danych do sieci prywatnej
Prywatne ingestowanie dla indeksowanych źródeł wiedzy OneLake jest ogólnie dostępne w interfejsie API REST 2026-10-01 w kwalifikujących się usługach dedykowanych. Zachowanie uprawnień oneLake w przykładzie tego artykułu oddzielnie wymaga 2026-11-01-preview.
Ustaw wartość indexedOneLakeParameters.ingestionParameters.networkAccessMode na private w żądaniu tworzenia.
Ustaw
networkAccessModenaprivatew żądaniu utworzenia źródła wiedzy. Tę właściwość można ustawić tylko podczas tworzenia, w tym w stabilnym2026-10-01interfejsie API. Aby zmienić tryb przechowywania później, usuń i ponownie utwórz źródło wiedzy. Kwalifikujące się źródła obiektów blob, ADLS Gen2 i Azure SQL mogą zamiast tego używać tymczasowego zastąpienia sieci dla tymczasowo wygenerowanego indeksatora. Ten wyjątek nie ma zastosowania do zaindeksowanego SharePoint ani innych rodzajów źródeł.Tworzenie może zakończyć się niepowodzeniem, jeśli warstwa usługi lub środowisko uruchomieniowe nie obsługuje wykonywania prywatnego lub jeśli wymagany udostępniony link prywatny nie istnieje. Serverless i S3 HD nie obsługują prywatnego wykonywania. Konfiguracja granic bezpieczeństwa sieci kontroluje obsługiwany dostęp do publicznego punktu końcowego, a nie uruchamianie prywatne.
Upewnij się, że wygenerowany indeksator
parameters.configuration.executionEnvironmentma wartośćprivate.Upewnij się, że każdy wymagany udostępniony link prywatny jest zatwierdzony, aprowizowany i jest przeznaczony dla prawidłowej zależności. Samo pomyślne utworzenie nie potwierdza zatwierdzenia linku ani kierowania. Jeśli sprawdzenie w portalu nie może zlokalizować zasobu między subskrypcjami, ręcznie zweryfikuj zatwierdzenie i gotowość zasobu docelowego oraz usługi Foundry IQ.
Sonduj stan źródła wiedzy, dopóki
lastSynchronizationState.endTimenie ma wartości. Potwierdź, żeitemsUpdatesFailedto0, a następnie zweryfikuj zawartość źródłową związaną z danym łącznikiem. Synchronizacja kończy się niepowodzeniem, jeśli zależność nie jest osiągalna.
Skonfiguruj ekstrakcję standardową
Aby użyć usługi Content Understanding na potrzeby wyodrębniania układu i fragmentowania semantycznego zamiast wyodrębniania minimal w poprzednich przykładach, ustaw contentExtractionMode na standard i skonfiguruj aiServices za pomocą punktu końcowego zasobu usługi Foundry. Użyj zasobów i wdrożeń opisanych w temacie Wymagania wstępne.
Wyodrębnianie w warstwie Standard powoduje naliczanie opłat za korzystanie z usługi Content Understanding i, gdy włączono werbalizację obrazu, opłat za użycie modelu. Aby uzyskać więcej informacji, zobacz kontrolki rozliczeń i opisu obrazu.
Korzystanie z automatycznych analizatorów dla poszczególnych języków (wersja zapoznawcza)
Aby włączyć automatyczne analizatory dla poszczególnych języków, ustaw wartość indexedOneLakeParameters.ingestionParameters.contentExtractionMode na minimal. Ustaw indexedOneLakeParameters.ingestionParameters.aiServices.uri na punkt końcowy zasobu Microsoft Foundry. Usługa Foundry IQ wykrywa język każdego dokumentu źródłowego i stosuje pasujący analizator języka Microsoft. Nie określasz analizatora w definicji źródła wiedzy ani w zapytaniu.
W przypadku uwierzytelniania bez klucza pomiń element indexedOneLakeParameters.ingestionParameters.aiServices.apiKey. Przypisz rolę Cognitive Services User do tożsamości zarządzanej usługi Foundry IQ w zasobie Microsoft Foundry.
Obsługiwane języki to angielski, japoński, francuski, hiszpański, niemiecki, holenderski, włoski, portugalski brazylijski, portugalski europejski, chiński uproszczony, chiński tradycyjny i koreański.
W przypadku zawartości wielojęzycznej usługa Foundry IQ wybiera analizator oparty na dominującym wykrytym języku. Używa standardowego analizatora, gdy język nie jest obsługiwany lub nie można go jednoznacznie określić.
Po włączeniu tej opcji wygenerowany indeks zawiera pola zawartości specyficzne dla języka dla każdego obsługiwanego języka, nawet jeśli dane nie zawierają tych języków. Podczas importowania danych Foundry IQ kieruje dokumenty do pola odpowiadającego wykrytemu językowi. Nieużywane pola nie zawierają zaindeksowanej zawartości i mają minimalny wpływ na wykorzystanie pamięci, ale nadal wliczają się do limitu pól indeksu. Uwzględnij te pola podczas planowania liczby pól i pojemności pamięci.
Wykrywanie języka jest rozliczane po bezpłatnym limicie wzbogacania AI.
Sprawdź stan importowania danych
Wyślij GET /knowledgesources/my-secured-onelake-ks/status?api-version=2026-11-01-preview do punktu końcowego wyszukiwania przy użyciu nagłówka uwierzytelniania.
Przejrzyj stan synchronizacji, bieżący i poprzedni stan synchronizacji oraz błędy na poziomie dokumentu. Użyj stanu indeksatora i historii wykonywania , aby zbadać błędy pozyskiwania. Pomyślne pozyskanie danych nie potwierdza, że zmiany uprawnień źródłowych zostały rozpropagowane. Zobacz Uprawnienia i świeżość ścieżki.
Przeglądanie wygenerowanych obiektów
Wygenerowane źródło danych, zestaw umiejętności, indeksator i indeks używają nazw na podstawie nazwy źródła wiedzy. Nie można zmienić tych nazw. Unikaj bezpośredniego edytowania obiektów, ponieważ zmiany mogą przerwać potok indeksatora.
Użyj wygenerowanych nazw obiektów z indexedOneLakeParameters.createdResources , aby pobrać każdą definicję. Wyślij GET /<resource-collection>/<generated-object-name>?api-version=2026-11-01-preview do punktu końcowego wyszukiwania przy użyciu nagłówka uwierzytelniania. Kolekcje zasobów to indexers, datasources, skillsetsi indexes.
- Wyślij
GET /indexers/<generated-indexer-name>/status?api-version=2026-11-01-previewprzy użyciu nagłówka uwierzytelniania. SprawdźexecutionHistoryilastResultpod kątem stanu wykonywania i komunikatów o błędach, w tym błędów połączenia lub limitu przydziału. Zobacz Monitorowanie za pomocą Get Indexer Status. - Sprawdź źródło danych, aby zweryfikować połączenie usługi Lakehouse i konfigurację tożsamości zarządzanej.
- Sprawdź zestaw umiejętności, aby zobaczyć, jak zawartość jest fragmentowana i opcjonalnie wektoryzowana.
- Sprawdź pola zawartości i uprawnień indeksu. Sprawdź, czy wygenerowane mapowania pól i projekcje fragmentów zachowują metadane lokalizacji źródłowej.
Przypisywanie do bazy wiedzy
Jeśli źródło wiedzy jest zadowalające, dodaj je do bazy wiedzy.
Dla każdej bazy wiedzy, która określa indeksowane źródło wiedzy OneLake, ustaw wartość includeReferenceSourceData na true. To ustawienie jest niezbędne do ściągnięcia adresu URL dokumentu źródłowego do cytatu.
Wykonywanie zapytań w bazie wiedzy
Po skonfigurowaniu bazy wiedzy wywołaj akcję pobierania lub punkt końcowy MCP , aby wykonać zapytanie względem źródła wiedzy.
Wymuszanie uprawnień na poziomie dokumentu (wersja zapoznawcza)
Użyj 2026-11-01-preview do żądań uwzględniających uprawnienia w usłudze OneLake. Uwzględnij token dostępu żądającego użytkownika w x-ms-query-source-authorization, zgodnie z opisem w temacie Wymuszanie uprawnień w czasie zapytania (wersja zapoznawcza). Postępuj zgodnie ze wskazówkami dotyczącymi zapytań i testowania usługi OneLake, aby sprawdzić użytkowników z dozwolonym i zablokowanym dostępem.
Surface obrazów osadzonych w dokumentach (wersja zapoznawcza)
Wyświetlanie obrazów nie jest obsługiwane, gdy skonfigurowano ingestionPermissionOptions, więc nie należy dodawać assetStore do zabezpieczonego źródła wiedzy w tym artykule. W przypadku scenariuszy bez pozyskiwania uprawnień zobacz Surface obrazy osadzone w dokumentach w agentic retrieval (wersja zapoznawcza)
Usuwanie źródła wiedzy
Przed usunięciem źródła wiedzy usuń dowolną bazę wiedzy, która się do niej odwołuje, lub zaktualizuj definicję bazy wiedzy, aby usunąć odwołanie. Jeśli źródło jest nadal używane, usuwanie kończy się niepowodzeniem i zwraca listę baz wiedzy, których dotyczy problem.
- Wyślij
GET /knowledgebases?api-version=2026-11-01-previewaby wyświetlić listę baz wiedzy. UżyjGET /knowledgebases/<knowledge-base-name>?api-version=2026-11-01-previewpolecenia , aby sprawdzić każdą definicję pod kątem odwołań do źródła wiedzy. -
Zaktualizuj bazę wiedzy, aby usunąć odwołanie. Alternatywnie wyślij,
DELETE /knowledgebases/<knowledge-base-name>?api-version=2026-11-01-previewjeśli nie potrzebujesz już tej bazy wiedzy. - Wyślij
DELETE /knowledgesources/my-secured-onelake-ks?api-version=2026-11-01-preview, aby usunąć źródło wiedzy. Uwzględnij nagłówek uwierzytelniania w każdym żądaniu.
Usunięcie indeksowanego źródła wiedzy OneLake powoduje również usunięcie wygenerowanego źródła danych, zestawu umiejętności, indeksatora i indeksu. Nie usuwa źródła lakehouse ani plików w Microsoft Fabric.