Tworzenie indeksowanego źródła wiedzy usługi OneLake

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

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ą interval oraz opcjonalnego startTime. 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.

  1. Wypełnij wymagania wstępne dotyczące sieci prywatnej.

  2. Ustaw networkAccessMode na private w żądaniu utworzenia źródła wiedzy. Tę właściwość można ustawić tylko podczas tworzenia, w tym w stabilnym 2026-10-01 interfejsie 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.

  3. Upewnij się, że wygenerowany indeksator parameters.configuration.executionEnvironment ma wartość private.

  4. 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.

  5. Sonduj stan źródła wiedzy, dopóki lastSynchronizationState.endTime nie ma wartości. Potwierdź, że itemsUpdatesFailed to 0, 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.

  1. Wyślij GET /indexers/<generated-indexer-name>/status?api-version=2026-11-01-preview przy użyciu nagłówka uwierzytelniania. Sprawdź executionHistory i lastResult pod 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.
  2. Sprawdź źródło danych, aby zweryfikować połączenie usługi Lakehouse i konfigurację tożsamości zarządzanej.
  3. Sprawdź zestaw umiejętności, aby zobaczyć, jak zawartość jest fragmentowana i opcjonalnie wektoryzowana.
  4. 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.

  1. Wyślij GET /knowledgebases?api-version=2026-11-01-preview aby wyświetlić listę baz wiedzy. Użyj GET /knowledgebases/<knowledge-base-name>?api-version=2026-11-01-preview polecenia , aby sprawdzić każdą definicję pod kątem odwołań do źródła wiedzy.
  2. Zaktualizuj bazę wiedzy, aby usunąć odwołanie. Alternatywnie wyślij, DELETE /knowledgebases/<knowledge-base-name>?api-version=2026-11-01-preview jeśli nie potrzebujesz już tej bazy wiedzy.
  3. 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.