Tworzenie indeksowanego źródła wiedzy SharePoint

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 funkcje lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

Ważna

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.

Indeksowane źródło wiedzy SharePoint pozyskuje zawartość SharePoint do potoku wyszukiwania agentowego w usłudze Foundry IQ (Wyszukiwanie AI platformy Azure). Jest ona ogólnie dostępna w interfejsie 2026-10-01 API REST. Ź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 SharePoint należy określić SharePoint parametry połączenia, modele i właściwości, aby automatycznie wygenerować następujące obiekty IQ usługi Foundry:

  • Źródło danych, które wskazuje na witryny programu SharePoint i używa parametrów połączenia bez zmian. Wygenerowane źródło danych jest zgodne z regułami indeksatora TenantIdSharePoint.
  • Zestaw umiejętności, który fragmentuje i opcjonalnie wektoryzuje zawartość wielomodalną.
  • 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 SharePoint w indeksatorze Microsoft 365, którego wymagania wstępne, obsługiwane formaty dokumentów i ograniczenia dotyczą również indeksowanych źródeł wiedzy SharePoint. Aby uzyskać więcej informacji, zobacz dokumentację indeksatora SharePoint i limity indeksatora. 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.

Użyj contentExtractionMode polecenia , aby wybrać minimal lub standard wyodrębnić zawartość podczas tworzenia źródła wiedzy. Informacje o różnicach między plikami, listami i nowoczesnymi stronami znajdziesz w artykule SharePoint content representations.

Wsparcie użytkowania

Azure portal portal Microsoft Foundry zestaw SDK .NET Python SDK Java SDK JavaScript SDK REST API
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Przykłady REST używają stabilnego 2026-10-01 interfejsu API. Przykłady zestawu SDK nadal podlegają wymaganiom dotyczącym pakietów wymienionym poniżej; dostępność interfejsu REST nie określa stanu wydania pakietu SDK. Funkcje oznaczone etykietą wersja zapoznawcza zachowują swój niezależny stan.

Wymagania wstępne

  • Najnowszy pakiet Azure.Search.Documents wersji zapoznawczej: dotnet add package Azure.Search.Documents --prerelease

  • W przypadku uwierzytelniania bezkluczowego pakiet Azure.Identity: dotnet add package Azure.Identity

  • Najnowszy pakiet azure-search-documents wersji zapoznawczej: pip install --pre azure-search-documents

  • W przypadku uwierzytelniania bezkluczowego pakiet azure-identity: pip install azure-identity

  • Wersja 2026-10-01 interfejsu API REST usługi wyszukiwania.

  • W przypadku uwierzytelniania bez klucza dołącz token Microsoft Entra ID w nagłówku Authorization każdego żądania HTTP.

W przypadku klienta REST ustaw te zmienne w pliku .http. Przykłady zarządzania zasobami w dalszej części tego artykułu używają tego samego punktu końcowego, wersji interfejsu API i nazwy źródła wiedzy.

@search-url = https://<search-service-name>.search.windows.net
@api-version = 2026-10-01
@knowledge-source-name = my-indexed-sharepoint-ks
@knowledge-base-name = <your-knowledge-base-name>
@sharepoint-federated-connection-string = <your-federated-connection-string>
@aoai-endpoint = https://<resource-name>.openai.azure.com

Zastąp symbol zastępczy parametry połączenia skonfigurowanym federacyjnym parametry połączenia. Ustaw aoai-endpoint na zasób Azure OpenAI, który hostuje wdrożenie osadzania. W żądaniu tworzenia zastąp embeddingModel.azureOpenAIParameters.resourceUri ciągiem {{aoai-endpoint}}, zastąp przykładową wartość deploymentId nazwą wdrożenia i ustaw modelName na wdrożony model.

Przykłady usuwania używają również polecenia knowledge-base-name. Ustaw ją na bazę wiedzy, do której są odwołania, którą zamierzasz zaktualizować lub usunąć przed uruchomieniem tych przykładów.

Wybierz właściciela zasobów

W tym artykule użyto interfejsu API źródła wiedzy do zarządzania pozyskiwaniem i tworzenia indeksu bazowego. Skonfiguruj wybór źródła, wyodrębnianie zawartości i inne obsługiwane opcje w źródle wiedzy. Przejrzyj wygenerowane zasoby, ale unikaj ich bezpośredniego edytowania.

Jeśli musisz kontrolować schemat indeksu lub utworzyć niestandardowy potok przetwarzania, skonfiguruj indeksator SharePoint i połącz jego wypełniony indeks za pośrednictwem źródła wiedzy indeksu wyszukiwania. Informacje o alternatywach pobierania zdalnego i niestandardowego pozyskiwania znajdziesz w artykule opcje architektury SharePoint.

Planowanie topologii uprawnień grupa programu SharePoint

Jeśli aplikacja potrzebuje uprawnień grupy SharePoint, oceń zakres jej witryny przed utworzeniem źródła wiedzy. Każdy wygenerowany indeks, który używa pola oznaczonego jako sharepointSiteUrl: true obsługuje co najwyżej pięć odrębnych wartości adresu URL witryny. Zapisy dla dodatkowego adresu URL witryny są odrzucane. Oddzielny limit agregacji czasu zapytania 100-URL nie zwiększa tego limitu. Zobacz limity witryn dla uprawnień grupa programu SharePoint.

W przypadku większego zakresu witryny oceń następującą topologię:

  1. Podziel zakres witryny na oddzielne indeksowane SharePoint źródła wiedzy, dzięki czemu każdy wygenerowany indeks pozostaje w limicie pięciu wartości. Zachowaj wymagane pola uprawnień i kontekst lokacji źródłowej w każdym indeksie i dokumencie pochodnym.
  2. Przypisz źródła do bazy wiedzy w ramach maksymalnej liczby źródeł na bazę wiedzy. Na przykład S1 obsługuje maksymalnie 10 źródeł na bazę wiedzy. Sprawdź swój plan i datę utworzenia usługi, zamiast zakładać, że ten limit dotyczy każdej usługi.
  3. Jeśli wszystkie wymagane źródła nie mieszczą się w jednej bazie wiedzy, rozważ wiele baz wiedzy. Przed wybraniem tej topologii sprawdź limity poszczególnych usług dotyczące źródeł wiedzy, baz wiedzy, indeksów i indeksatorów.
  4. Zaimplementuj routing lub orkiestrację na poziomie aplikacji dla wielu baz wiedzy. Żądanie pobierania dotyczy jednej bazy wiedzy, a nie wszystkich baz wiedzy w usłudze. Zachowaj kontekst uprawnień użytkownika końcowego w każdym żądaniu i podczas łączenia wyników i cytatów.

Sprawdź również wybór źródła wiedzy podczas wyszukiwania. Liczba źródeł skonfigurowanych w bazie wiedzy i liczba wybrana dla żądania są oddzielnymi zagadnieniami.

Sprawdzanie istniejących źródeł wiedzy

Źródłem wiedzy jest obiekt najwyższego poziomu wielokrotnego użytku. Znajomość istniejących źródeł wiedzy jest przydatna w przypadku ponownego użycia lub nazewnictwa nowych obiektów.

Uruchom następujący kod, aby wyświetlić listę źródeł wiedzy według nazwy i typu.

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

Reference:SearchIndexClient

# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

for ks in index_client.list_knowledge_sources():
    print(f"  - {ks.name} ({ks.kind})")

Reference:SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}

Odwołanie:Źródła wiedzy — lista

Możesz również zwrócić pojedyncze źródło wiedzy według nazwy, aby przejrzeć jego definicję JSON.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

Reference:SearchIndexClient

# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))

Reference:SearchIndexClient

### Get a knowledge source definition
GET {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{token}}

Odwołanie:Źródła wiedzy — pobieranie

Poniższa odpowiedź ukrywa wartości poufne. Przed ponownym użyciem do utworzenia innego źródła wiedzy podaj docelowe ustawienia połączenia i poświadczenia lub skonfiguruj obsługiwane uwierzytelnianie bez użycia wpisów tajnych; zanonimizowane wartości nie są poświadczeniami.

{
  "name": "my-indexed-sharepoint-ks",
  "kind": "indexedSharePoint",
  "description": "A sample indexed SharePoint knowledge source",
  "encryptionKey": null,
  "indexedSharePointParameters": {
    "connectionString": "<redacted>",
    "containerName": "defaultSiteLibrary",
    "query": null,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "minimal",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<redacted>",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large",
          "authIdentity": null
        }
      },
      "chatCompletionModel": null,
      "ingestionSchedule": null,
      "aiServices": null
    },
    "createdResources": {
      "datasource": "my-indexed-sharepoint-ks-datasource",
      "indexer": "my-indexed-sharepoint-ks-indexer",
      "skillset": "my-indexed-sharepoint-ks-skillset",
      "index": "my-indexed-sharepoint-ks-index"
    }
  }
}

Tworzenie źródła wiedzy

Uruchom następujący kod, aby utworzyć indeksowane źródło wiedzy SharePoint.

Przykład wybiera domyślną bibliotekę dokumentów witryny. Aby wybrać inne biblioteki, listy, strony lub witryny, skonfiguruj containerName element i query w obszarze indexedSharePointParameters. Postępuj zgodnie z opcjami wyboru zawartości SharePoint i wymaganiami dotyczącymi wyboru między witrynami.

// Create an IndexedSharePoint knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure.Identity;

var foundryEndpoint = "https://<foundry-resource>.services.ai.azure.com";
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());

var chatCompletionParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(foundryEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var embeddingParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(foundryEndpoint),
    DeploymentName = aoaiEmbeddingDeployment,
    ModelName = aoaiEmbeddingModel
};

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    NetworkAccessMode = KnowledgeSourceNetworkAccessMode.Public,
    DisableImageVerbalization = false,
    ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    }
};

var sharePointParams = new IndexedSharePointKnowledgeSourceParameters(
    connectionString: sharePointConnectionString,
    containerName: "defaultSiteLibrary")
{
    IngestionParameters = ingestionParams
};

var knowledgeSource = new IndexedSharePointKnowledgeSource(
    name: "my-indexed-sharepoint-ks",
    indexedSharePointParameters: sharePointParams)
{
    Description = "A sample indexed SharePoint knowledge source."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

Reference:SearchIndexClient, IndexedSharePointKnowledgeSource

# Create an indexed SharePoint knowledge source
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import IndexedSharePointKnowledgeSource, IndexedSharePointKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceContentExtractionMode
from azure.search.documents.knowledgebases.models import KnowledgeSourceIngestionParameters, KnowledgeSourceNetworkAccessMode, KnowledgeSourceAzureOpenAIVectorizer

foundry_endpoint = "https://<foundry-resource>.services.ai.azure.com"
index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())

knowledge_source = IndexedSharePointKnowledgeSource(
    name = "my-indexed-sharepoint-ks",
    description = "A sample indexed SharePoint knowledge source.",
    encryption_key = None,
    indexed_share_point_parameters = IndexedSharePointKnowledgeSourceParameters(
        connection_string = "connection_string",
        container_name = "defaultSiteLibrary",
        query = None,
        ingestion_parameters = KnowledgeSourceIngestionParameters(
            network_access_mode = KnowledgeSourceNetworkAccessMode.PUBLIC,
            identity = None,
            disable_image_verbalization = False,
            chat_completion_model = KnowledgeBaseAzureOpenAIModel(
                azure_open_ai_parameters = AzureOpenAIVectorizerParameters(
                    resource_url = foundry_endpoint,
                    deployment_name = "<aoai-gpt-deployment>",
                    model_name = "<aoai-gpt-model>",
                )
            ),
            embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
                azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
                    resource_url = foundry_endpoint,
                    deployment_name = "<aoai-embedding-deployment>",
                    model_name = "<aoai-embedding-model>",
                )
            ),
            content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
            ingestion_schedule = None,
            ingestion_permission_options = None
        )
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

Reference:SearchIndexClient

### Create an indexed SharePoint knowledge source
PUT {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "{{knowledge-source-name}}",
    "kind": "indexedSharePoint",
    "description": "A sample indexed SharePoint knowledge source.",
    "encryptionKey": null,
    "indexedSharePointParameters": {
        "connectionString": "{{sharepoint-federated-connection-string}}",
        "containerName": "defaultSiteLibrary",
        "query": null,
        "ingestionParameters": {
            "networkAccessMode": "public",
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "https://<foundry-resource>.services.ai.azure.com"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": false,
            "ingestionSchedule": null,
            "ingestionPermissionOptions": [],
            "contentExtractionMode": "minimal"
        }
    }
}

Odwołanie:Źródła wiedzy — tworzenie lub aktualizowanie

Skonfiguruj ekstrakcję standardową

Standardowe wyodrębnianie korzysta z usługi Content Understanding na potrzeby analizowania układów i semantycznego dzielenia na fragmenty obsługiwanych dokumentów SharePoint z opcjonalnymi opisami obrazów. Używa on zasobu Foundry i wdrożeń opisanych w temacie Wymagania wstępne.

W żądaniu utworzenia lub aktualizacji skonfiguruj indexedSharePointParameters.ingestionParameters:

  1. Ustaw contentExtractionMode na standard i skonfiguruj aiServices za pomocą punktu końcowego zasobu Foundry.
  2. Ustaw ingestionPermissionOptions na ["userIds", "groupIds"], aby zachować uprawnienia dokumentu SharePoint.
  3. Skonfiguruj chatCompletionModel przy użyciu obsługiwanego modelu i wdrożenia w tym zasobie Foundry na potrzeby opisywania obrazów. Pozostaw disableImageVerbalization ustawione na false lub pomiń je.
  4. Skonfiguruj embeddingModel.azureOpenAIParameters przy użyciu punktu końcowego zasobu foundry w resourceUri, na przykład https://<embedding-resource>.services.ai.azure.com. Ustaw modelName i deploymentId dla wdrożenia osadzania i zachowaj wymagane ustawienia połączenia z przykładu tworzenia.

Wygenerowana umiejętność osadzania wysyła zawartość fragmentu usługi Content Understanding, w tym wygenerowane opisy obrazów, do tego punktu końcowego osadzania przed zapisaniem wektorów do indeksu.

Usługa Search generuje źródło danych, indeksator, zestaw umiejętności usługi Content Understanding i zabezpieczony indeks fragmentów. Po pomyślnym zakończeniu pozyskiwania źródło wiedzy jest gotowe do przypisania do bazy wiedzy.

Semantyczne fragmentowanie Content Understanding i opisy obrazów są ogólnie dostępne w interfejsie Search REST API 2026-10-01. Użyj wersji interfejsu API, która obsługuje również łącznik SharePoint i funkcje obsługi uprawnień w konfiguracji.

Używaj plików obsługiwanych zarówno przez indeksator SharePoint, jak i umiejętność Content Understanding. Nie należy stosować konfiguracji przetwarzania plików do elementów listy ani stron witryny analizowanych jako tekst.

Ekstrakcja standardowa 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.

Aby uzyskać większą kontrolę nad umiejętnościami, fragmentowaniem i zabezpieczonymi projekcjami, zobacz Konfigurowanie indeksatora SharePoint i zestawu umiejętności usługi Content Understanding.

Konfigurowanie harmonogramu pozyskiwania

Bez skonfigurowanego harmonogramu pozyskiwania indeksowany SharePoint źródło wiedzy domyślnie uruchamia wygenerowany indeksator co 24 godziny. Aby użyć krótszego interwału cyklicznego odświeżania uprawnień, należy ustawić indexedSharePointParameters.ingestionParameters.ingestionSchedule podczas tworzenia lub aktualizowania źródła wiedzy. Ustaw wartość interval na czas trwania XSD, na przykład PT5M dla pięciu minut, minimalnego obsługiwanego interwału.

Aby uzyskać informacje o właściwościach harmonogramu, zobacz Schedule definition. Postępuj zgodnie z zaleceniem dotyczącym odświeżania uprawnień w SharePoint, aby uzyskać informacje o ograniczeniach czasowych. Interwał nie jest terminem ukończenia ani umową SLA cofnięcia uprawnień.

Ta wartość domyślna źródła wiedzy różni się od indeksatora utworzonego bezpośrednio bez schedule, który jest uruchamiany na żądanie, a nie zgodnie z harmonogramem cyklicznym.

Używanie automatycznych analizatorów dla poszczególnych języków

Automatyczne analizatory poszczególnych języków są w wersji zapoznawczej. Wykonaj kroki konfiguracji i weryfikacji w poniższych sekcjach. Nie musisz konfigurować analizatorów dla wygenerowanego indeksu samodzielnie. Informacje o rozróżnieniu między analizą języka zarządzaną i bezpośrednio skonfigurowaną można znaleźć w sekcji automatyczne analizatory dla poszczególnych języków.

Od wersji interfejsu API 2026-08-01-preview automatyczne analizatory specyficzne dla języka są dostępne dla obiektów blob, indeksowanych źródeł wiedzy usługi OneLake oraz indeksowanych źródeł wiedzy programu SharePoint. Po włączeniu funkcji Foundry IQ (Wyszukiwanie AI platformy Azure) wykrywa język każdego dokumentu źródłowego i automatycznie stosuje pasujący analizator języka Microsoft. Nie określasz analizatora w definicji źródła wiedzy ani w zapytaniu.

Aby włączyć automatyczne analizatory dla każdego języka, ustaw element contentExtractionMode na minimal i skonfiguruj ingestionParameters.aiServices w definicji źródła wiedzy.

W przypadku uwierzytelniania bez klucza pomiń aiServices.apiKey i przypisz rolę użytkownika usług Cognitive Services w zasobie Microsoft Foundry do tożsamości zarządzanej usługi IQ usługi Foundry. W przypadku uwierzytelniania opartego na kluczach ustaw wartość aiServices.apiKey na prawidłowy klucz dla zasobu Foundry.

Obsługiwane są następujące języki:

  • angielski
  • Japoński
  • Francuski
  • Hiszpański
  • Niemiecki
  • Niderlandzki
  • Włoski
  • Portugalski (Brazylia)
  • portugalski (europejski)
  • Chiński (uproszczony)
  • Chiński tradycyjny
  • 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 automatycznych analizatorów językowych funkcja Foundry IQ dodaje w wygenerowanym schemacie indeksu pola zawartości właściwe dla każdego obsługiwanego języka, niezależnie od tego, czy dane zawierają dokumenty w tych językach. Podczas przetwarzania dokumenty są kierowane do odpowiedniego pola właściwego dla danego języka na podstawie wykrytego języka.

Nieużywane pola języka nie zawierają indeksowanej zawartości i mają minimalny wpływ na magazyn, ale pozostają częścią schematu indeksu i są liczone do limitu pól indeksu. Podczas planowania projektu indeksu, liczby pól i wymagań dotyczących magazynu należy wziąć pod uwagę dodatkowe pola. Aby uzyskać więcej informacji, zobacz Limity indeksów i Szacowanie pojemności usługi IQ usługi Foundry i zarządzanie nią.

Wykrywanie języka jest płatne po przekroczeniu bezpłatnego przydziału wzbogacania AI. Aby uzyskać więcej informacji, zobacz Bezpłatne wzbogacania.

Po pozyskaniu sprawdź routing języka bez edytowania wygenerowanych obiektów:

  1. Sprawdź wygenerowany schemat indeksu. Upewnij się, że pola specyficzne dla języka mają zgodne analizatory, takie jak snippet_en z en.microsoft, oraz że snippet_default zapewnia standardowy analizator rezerwowy.
  2. Upewnij się, że wygenerowana konfiguracja semantyczna zawiera listę pól zawartości specyficznych dla języka i snippet_default.
  3. Sprawdź indeksowane fragmenty dokumentu wykrytego jako napisanego w obsługiwanym języku. Tekst każdego fragmentu powinien znajdować się w odpowiednim polu języka. Nieobsługiwane lub niepewne wykrywanie kieruje tekst do snippet_default.
  4. Odczytywanie zawartości z wypełnionego pola języka lub pola rezerwowego. W tym trybie wygenerowany schemat nie zawiera oddzielnego snippet pola.

Jeśli schemat lub wyniki nie są zgodne, przejrzyj powyższe ustawienia aktywacji oraz błędy indeksatora. Te testy nie definiują procedury aktualizacji ani migracji dla istniejącego wygenerowanego indeksu.

Sprawdź stan importowania danych

Uruchom następujący kod, aby monitorować postęp przetwarzania danych i kondycję, w tym rodzaj źródła wiedzy i szczegółowe błędy indeksowania dla źródeł wiedzy, które generują potok indeksatora i tworzą indeks wyszukiwania.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

// Get knowledge source ingestion status
var statusResponse = await indexClient.GetKnowledgeSourceStatusAsync(knowledgeSourceName);
var status = statusResponse.Value;

// Serialize to JSON for display
var json = JsonSerializer.Serialize(status, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

Reference:SearchIndexClient

# Check knowledge source ingestion status
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint="search_url", credential=AzureKeyCredential("api_key"))

status = index_client.get_knowledge_source_status("knowledge_source_name")
print(json.dumps(status.as_dict(), indent=2))

Reference:SearchIndexClient

### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version={{api-version}}
Authorization: Bearer {{token}}
Content-Type: application/json 

Odwołanie:Źródła wiedzy — pobieranie stanu

Odpowiedź na żądanie, która zawiera parametry pozyskiwania i aktywnie pozyskuje zawartość, może wyglądać jak poniższy przykład.

{
  "kind": "azureBlob",
  "synchronizationStatus": "active",
  "synchronizationInterval": "1d",
  "currentSynchronizationState": {
    "startTime": "2026-04-10T19:30:00Z",
    "itemUpdatesProcessed": 1100,
    "itemsUpdatesFailed": 100,
    "itemsSkipped": 1100,
    "errors": [
      {
        "key": "Item id 1",
        "docURL": "https://contoso.blob.core.windows.net/contracts/2024/Q4/doc-00023.csv",
        "statusCode": 400,
        "componentName": "DocumentExtraction.AzureBlob.MyDataSource",
        "errorMessage": "Could not read the value of column 'foo' at index '0'.",
        "details": "The file could not be parsed.",
        "documentationLink": "https://go.microsoft.com/fwlink/?linkid=2049388"
      }
    ]
  },
  "lastSynchronizationState": {
    "status": "partialSuccess",
    "startTime": "2026-04-09T19:30:00Z",
    "endTime": "2026-04-09T19:40:01Z",
    "itemUpdatesProcessed": 1100,
    "itemsUpdatesFailed": 100,
    "itemsSkipped": 1100,
    "errors": null
  },
  "statistics": {
    "totalSynchronizations": 25,
    "averageSynchronizationDuration": "00:15:20",
    "averageItemsProcessedPerSynchronization": 500
  }
}

Uwaga

Właściwość kind i tablica currentSynchronizationState.errors[] ze szczegółami błędów na poziomie dokumentu są dostępne począwszy od wersji interfejsu API 2026-04-01. W przypadku wcześniejszych wersji interfejsu API te pola nie są zwracane. Pole lastSynchronizationState.status jest również nowe w 2026-04-01.

Po zakończeniu pierwszej synchronizacji sprawdź, czy lastSynchronizationState.endTime ma wartość i itemsUpdatesFailed to 0. Jeśli przetwarzanie elementów nie powiodło się, sprawdź zgłoszone błędy i historię wykonywania wygenerowanego indeksatora przed wykonaniem zapytania do bazy wiedzy.

Przeglądanie wygenerowanych obiektów

Podczas tworzenia tego źródła wiedzy usługa Foundry IQ (Wyszukiwanie AI platformy Azure) automatycznie generuje źródło danych, indeksator i indeks oraz zestaw umiejętności, gdy potok pozyskiwania wymaga. Odpowiedź na żądanie utworzenia wymienia każdy obiekt pod elementem createdResources.

Te obiekty są generowane zgodnie z ustalonym szablonem, a ich nazwy są oparte na nazwie źródła wiedzy. Nie można zmienić nazw obiektów. Unikaj bezpośredniego edytowania tych obiektów, ponieważ zmiany mogą powodować błędy lub niezgodności, które przerywają potok indeksatora.

Wyłącznie w przypadku kwalifikujących się źródeł Blob, ADLS Gen2 i Azure SQL tymczasowe obejście ustawień sieciowych umożliwia zmianę środowiska wykonywania wygenerowanego indeksatora. Ten wyjątek nie ma zastosowania do zindeksowanych elementów SharePoint ani OneLake i nie zezwala na zmiany innych wygenerowanych obiektów. Późniejsze aktualizacje źródła wiedzy lub ponowne generowanie mogą nadpisać to nadpisanie.

Aby zweryfikować tworzenie obiektów, możesz użyć portalu Azure. Przepływ pracy to:

  1. Sprawdź indeksator pod kątem komunikatów o powodzeniu lub niepowodzeniu. Błędy połączenia lub limitu przydziału są wyświetlane tutaj.

  2. Sprawdź źródło danych, aby zweryfikować połączenie z magazynem danych. Połączenie używa albo parametru połączenia, albo tożsamości zarządzanej, w zależności od tego, jak skonfigurowano źródło wiedzy.

  3. Jeśli zostanie wygenerowany zestaw umiejętności, sprawdź jego ustawienia wzbogacania i wektoryzacji. Źródła wiedzy SQL generują zestaw umiejętności tylko wtedy, gdy określisz embeddingColumns.

  4. Sprawdź indeks, aby zobaczyć, jak zawartość jest indeksowana i uwidoczniona na potrzeby pobierania, w tym pola, które można przeszukiwać i filtrować oraz które pola przechowują wektory na potrzeby wyszukiwania podobieństwa. Użyj Eksploratora wyszukiwania, aby uruchamiać zapytania względem wygenerowanego indeksu.

Upewnij się, że wygenerowane źródło danych wybiera zamierzone witryny i zawartość SharePoint. Sprawdź wypełniony indeks dla znanego elementu źródłowego, a następnie zweryfikuj możliwość pobrania i cytat źródłowy za pośrednictwem bazy wiedzy. Pomyślne utworzenie zasobu nie potwierdza, że pozyskiwanie danych zostało ukończone.

Przypisywanie do bazy wiedzy

Jeśli źródło wiedzy jest zadowalające, dodaj je do bazy wiedzy.

W przypadku każdej bazy wiedzy określającej indeksowane źródło wiedzy SharePoint należy ustawić includeReferenceSourceData na wartość true. Ten krok jest niezbędny 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. Wybierz konfigurację zgodną ze scenariuszem.

Wymuszanie uprawnień na poziomie dokumentu

Filtrowanie uprawnień ACL w SharePoint jest ogólnie dostępne za pomocą interfejsu API REST 2026-10-01. Aby uzyskać szczegółowe informacje, zobacz Wymuszanie listy ACL i kontroli dostępu opartej na rolach w czasie wykonywania zapytań.

Aby pozyskać jawne przypisania użytkowników i grup, ustaw wartość indexedSharePointParameters.ingestionParameters.ingestionPermissionOptions na ["userIds", "groupIds"]. Dołącz token dostępu użytkownika do żądania pobierania zgodnie z opisem w sekcji Autoryzacja w czasie wykonywania zapytań.

Użyj domyślnej opcji wyodrębniania (contentExtractionMode: "minimal") lub standardowego wyodrębniania opartego na Content Understanding (contentExtractionMode: "standard"), jeśli jest obsługiwane. Każdy wygenerowany fragment zachowuje metadane uprawnień elementu źródłowego i kontekst źródłowy. Uprawnienia na poziomie dokumentu nie obsługują specjalnych trybów analizowania wybieranych przez klientów. Zobacz Obsługiwane analizowanie i wyodrębnianie zawartości na potrzeby importu uprawnień. Skonfiguruj te opcje w źródle wiedzy; nie zmieniaj wygenerowanych ustawień analizatora.

Wybierz opcje uwierzytelniania i uprawnień dla potrzebnych typów grup:

Authentication groupIds uwzględniono Zaimportowane uprawnienia grupy
Uwierzytelnianie federacyjne Yes Microsoft Entra i natywne grupy witryn SharePoint.
Tajemnica klienta Yes Tylko grupy Microsoft Entra.
Dowolna z metod No Brak importowania grupowych list ACL. Skonfiguruj userIds oddzielnie dla jawnych przypisań użytkowników.

Obsługa grup federacyjnych wymaga uprawnień Microsoft Graph i SharePoint dla scenariusza ACL. W wygenerowanym indeksie identyfikatorem używanym przez sharePointConnectorAppRegistration.federatedCredentialId jest identyfikator aplikacji wybranej tożsamości zarządzanej, a nie identyfikator obiektu poświadczeń federacyjnych.

Sprawdź wygenerowane obiekty, zanim zaczniesz polegać na pobieraniu filtrowanym uprawnieniami:

  1. Upewnij się, że wygenerowane źródło danych indexerPermissionOptions jest zgodne z żądanymi opcjami pozyskiwania użytkowników i grup.
  2. Upewnij się, że indeks włącza permissionFilterOption i zawiera pola oznaczone żądanymi permissionFilter wartościami oraz wymagane metadata_spo_item_path pole ścieżki źródłowej. W przypadku istniejących rekordów bez wypełnionych ścieżek postępuj zgodnie ze wskazówkami dotyczącymi wypełniania danych; dodanie samego pola nie powoduje ich wypełnienia.
  3. W przypadku federacyjnych groupIdssprawdź sharePointConnectorAppRegistrationidentyfikatory aplikacji i pole oznaczone jako sharepointSiteUrl: true. Sprawdź, czy mapowanie lokacji używa identyfikatora metadata_spo_site_url każdego elementu, w tym wyborów między lokacjami.
  4. Sprawdź projekcje zestawu umiejętności dla ścieżki źródłowej, żądanych wpisów ACL użytkowników i grup oraz odpowiedniego adresu URL witryny we wszystkich fragmentach. Pozostaw niezamapowane klucze generowane przez projekcję i tożsamość nadrzędną.
  5. Sprawdź wyniki wykonywania indeksatora, a następnie sprawdź reprezentatywne dokumenty i fragmenty przy użyciu weryfikacji listy ACL. Porównaj dozwolone wyniki i wyniki, do których odmówiono dostępu, dla użytkownika testowego po zaimportowaniu danych lub odświeżeniu uprawnień.

Użyj pola SharePoint i wymagań dotyczących mapowania, aby odróżnić ścieżkę źródłową, kontekst witryny i bibliotekę w przeciwieństwie do tożsamości zasobu i elementu.

Obsługiwany model uprawnień obejmuje dziedziczone przypisania i zagnieżdżanie grup w ciągu pięciu poziomów, z zastrzeżeniem limitu rozpoznawania zagnieżdżonego na poziomie witryny. Linki do udostępniania w całej organizacji („Osoby w organizacji”) nie są obsługiwane na potrzeby pozyskiwania list ACL w SharePoint ani wymuszania uprawnień w czasie wykonywania zapytań. Wymuszanie wygaśnięcia łącza udostępniania nie jest obsługiwane. Wygenerowane zasoby nie wymuszają wygaśnięcia. Oddzielne obsługiwane jawnie przyznane uprawnienie jest niezależne od wygaśnięcia linku.

To źródło wiedzy ocenia zreplikowany podzbiór uprawnień SharePoint, z różnicami względem modelu uprawnień SharePoint oraz ograniczeniami dziedziczonymi z łącznika, w tym ograniczenia dostępu warunkowego. Aby uzyskać informacje o zaletach i wadach podejść zdalnego, indeksowanego i Push API, zobacz Wybieranie podejścia pobierania pod kątem świeżości. Aktualizacje uprawnień wynikają z zachowania synchronizacji SharePoint wygenerowanego indeksatora.

Aby uzyskać brakujące, nieoczekiwane lub nieudane wyniki z indeksowanego zapytania uprawnień SharePoint, zobacz Rozwiązywanie problemów z filtrowaniem uprawnień SharePoint.

W przypadku istniejącego źródła wiedzy nie można bezpośrednio w nim zmienić ustawień parametry połączenia ani opcji uprawnień pozyskiwania. Aby zmienić te ustawienia:

  1. Utwórz zastępcze źródło wiedzy z wymaganym uwierzytelnianiem, uprawnieniami witryn i opcjami uprawnień.
  2. Ukończ pozyskiwanie i sprawdź wygenerowane obiekty, korzystając z kontroli opisanych w poprzednich krokach.
  3. Przed zaktualizowaniem bazy wiedzy, aby używać zamiennika, sprawdź dozwolone i odrzucone wyniki użytkownika. Resetowanie lub ponowne synchronizowanie starego indeksatora nie zmienia opcji uprawnień jego źródła wiedzy.

Wyodrębnij obrazy osadzone w dokumencie

Obsługa obrazów jest dostępna w wersji zapoznawczej i wymaga obsługiwanego interfejsu API w wersji zapoznawczej.

Aby uwzględniać obrazy osadzone w dokumentach (takie jak diagramy lub skany) w odpowiedziach generowanych przez syntezę odpowiedzi, skonfiguruj assetStore w tym źródle wiedzy, a następnie włącz udostępnianie obrazów w bazie wiedzy. Dostarczanie obrazów nie jest obsługiwane, gdy skonfigurowano ingestionPermissionOptions. Aby uzyskać więcej informacji, zobacz Wyświetlanie obrazów osadzonych w dokumentach w wyszukiwaniu agentowym (wersja zapoznawcza).

Usuwanie źródła wiedzy

Aby można było usunąć źródło wiedzy, należy usunąć dowolną bazę wiedzy, która odwołuje się do źródła wiedzy, lub zaktualizować definicję bazy wiedzy, aby usunąć odwołanie. W przypadku źródeł wiedzy, które generują potok indeksu i indeksatora, wszystkie wygenerowane obiekty również są usuwane. Jeśli jednak użyto istniejącego indeksu do utworzenia źródła wiedzy, indeks nie zostanie usunięty.

Jeśli spróbujesz usunąć używane źródło wiedzy, akcja zakończy się niepowodzeniem i zwróci listę baz wiedzy, których dotyczy problem.

Aby usunąć źródło wiedzy:

  1. Pobierz listę wszystkich baz wiedzy w usłudze Foundry IQ.

    using Azure.Search.Documents.Indexes;
    
    var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
    var knowledgeBases = indexClient.GetKnowledgeBasesAsync();
    
    Console.WriteLine("Knowledge Bases:");
    
    await foreach (var kb in knowledgeBases)
    {
        Console.WriteLine($"  - {kb.Name}");
    }
    

    Reference:SearchIndexClient

    Przykładowa odpowiedź może wyglądać następująco:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Uzyskaj pojedynczą definicję bazy wiedzy, aby sprawdzić odwołania do źródeł wiedzy.

    using Azure.Search.Documents.Indexes;
    using System.Text.Json;
    
    var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
    
    // Specify the knowledge base name to retrieve
    string kbNameToGet = "earth-knowledge-base";
    
    // Get a specific knowledge base definition
    var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
    var kb = knowledgeBaseResponse.Value;
    
    // Serialize to JSON for display
    string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
    Console.WriteLine(json);
    

    Reference:SearchIndexClient

    Przykładowa odpowiedź może wyglądać następująco:

     {
       "Name": "earth-knowledge-base",
       "KnowledgeSources": [
         {
           "Name": "earth-knowledge-source"
         }
       ],
       "Models": [
         {}
       ],
       "RetrievalReasoningEffort": {},
       "OutputMode": {},
       "ETag": "\u00220x8DE278629D782B3\u0022",
       "EncryptionKey": null,
       "Description": null,
       "RetrievalInstructions": null,
       "AnswerInstructions": null
     }
    
  3. Usuń bazę wiedzy lub, jeśli masz wiele źródeł wiedzy, zaktualizuj bazę wiedzy, aby usunąć źródło. W tym przykładzie pokazano usunięcie.

    using Azure.Search.Documents.Indexes;
    var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
    
    await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
    System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");
    

    Reference:SearchIndexClient

  4. Usuń źródło wiedzy.

    await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
    System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
    

    Reference:SearchIndexClient

  1. Pobierz listę wszystkich baz wiedzy w usłudze Foundry IQ.

    # Get knowledge bases
    from azure.core.credentials import AzureKeyCredential
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    
    print("Knowledge Bases:")
    for kb in index_client.list_knowledge_bases():
        print(f"  - {kb.name}")
    

    Reference:SearchIndexClient

    Przykładowa odpowiedź może wyglądać następująco:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Uzyskaj pojedynczą definicję bazy wiedzy, aby sprawdzić odwołania do źródeł wiedzy.

    # Get a knowledge base definition
    from azure.core.credentials import AzureKeyCredential
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    kb = index_client.get_knowledge_base("knowledge_base_name")
    print(kb)
    

    Reference:SearchIndexClient

    Przykładowa odpowiedź może wyglądać następująco:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Usuń bazę wiedzy lub, jeśli masz wiele źródeł wiedzy, zaktualizuj bazę wiedzy, aby usunąć źródło. W tym przykładzie pokazano usunięcie.

    # Delete a knowledge base
    from azure.core.credentials import AzureKeyCredential 
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    index_client.delete_knowledge_base("knowledge_base_name")
    print(f"Knowledge base deleted successfully.")
    

    Reference:SearchIndexClient

  4. Usuń źródło wiedzy.

    # Delete a knowledge source
    from azure.core.credentials import AzureKeyCredential 
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    index_client.delete_knowledge_source("knowledge_source_name")
    print(f"Knowledge source deleted successfully.")
    

    Reference:SearchIndexClient

  1. Pobierz listę wszystkich baz wiedzy w usłudze Foundry IQ.

    ### Get knowledge bases
    GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
    Authorization: Bearer {{token}}
    

    Dokumentacja:Bazy wiedzy — lista

    Przykładowa odpowiedź może wyglądać następująco:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Uzyskaj pojedynczą definicję bazy wiedzy, aby sprawdzić odwołania do źródeł wiedzy.

    ### Get a knowledge base definition
    GET {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Odwołanie:Bazy wiedzy — pobieranie

    Przykładowa odpowiedź może wyglądać następująco:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Usuń bazę wiedzy lub, jeśli masz wiele źródeł wiedzy, zaktualizuj bazę wiedzy, aby usunąć źródło. W tym przykładzie pokazano usunięcie.

    ### Delete a knowledge base
    DELETE {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Odwołanie:Bazy wiedzy — usuwanie

  4. Usuń źródło wiedzy.

    ### Delete a knowledge source
    DELETE {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Odwołanie:Źródła wiedzy — usuwanie

Znane błędy

Wygenerowane źródło danych SharePoint i indeksator korzystają z tego samego sposobu weryfikacji dzierżawy i uwierzytelniania Microsoft Entra, jak bezpośrednio skonfigurowane indeksatory SharePoint. W przypadku błędów związanych z dzierżawcą przejrzyj stan oraz historię wykonywania wygenerowanego indeksatora, a następnie postępuj zgodnie z Invalid AAD tenant instrukcjami naprawy.

W przypadku innych błędów uwierzytelniania, łączności lub uprawnień zidentyfikuj niedziałające połączenie. Rozróżnij dostęp do usługi Foundry IQ, pozyskiwanie z SharePoint, ustalanie uprawnień w czasie wykonywania zapytania oraz wywołania do punktów końcowych modelu lub rozwiązania Foundry.