Utwórz źródło wiedzy typu blob z Azure Blob Storage lub ADLS Gen2

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.

Źródło wiedzy obiektu blob pobiera zawartość Azure Blob Storage lub ADLS Gen2 do potoku pobierania agenta 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 źródła wiedzy obiektu blob należy określić zewnętrzne źródło danych, modele i właściwości, aby automatycznie wygenerować następujące obiekty IQ usługi Foundry:

  • Źródło danych reprezentujące kontener blobów.
  • Zestaw umiejętności, który fragmentuje i opcjonalnie wektoryzuje zawartość wielomodalną z kontenera.
  • 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 obiektów blob, którego wymagania wstępne, obsługiwane formaty dokumentów i ograniczenia dotyczą również źródeł wiedzy obiektów blob. Więcej informacji znajduje się w dokumentacji indeksatora obiektów blob i limitach 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.

Wsparcie użytkowania

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

Wymagania wstępne

  • Usługa IQ znaleziono w dowolnym regionie, który zapewnia pobieranie agentów.

  • Konto Azure Blob Storage lub Azure Data Lake Storage (ADLS) Gen2.

  • Kontener obiektów blob z obsługiwanymi typami zawartości dla zawartości tekstowej. W przypadku opcjonalnej werbalizacji obrazów obsługiwany typ zawartości zależy od tego, czy model uzupełniania czatu może analizować i opisywać plik obrazu.

  • Jeśli contentExtractionMode to standard, użyj zasobu Microsoft Foundry w regionie obsługiwanym przez funkcję Content Understanding w narzędziach Foundry z https://<resource-name>.services.ai.azure.com punktem końcowym. Zasób musi mieć wdrożenie modelu osadzeń oraz — jeśli włączysz funkcję werbalizacji obrazów — wdrożenie wielomodalnego modelu czatu.

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

  • Tożsamość zarządzana dla usługi IQ usługi Foundry z czytnikiem danych obiektu blob usługi Storage w zakresie źródłowego konta magazynu i użytkownikiem usług Cognitive Services w zasobie Microsoft Foundry. Jeśli skonfigurujesz magazyn zasobów dla innego konta magazynu, przypisz również rolę Współautor danych obiektu blob usługi Storage na poziomie tego konta magazynu. Jeśli kontenery źródłowy i zasobów należą do tego samego konta, Storage Blob Data Contributor zapewnia zarówno dostęp do odczytu ze źródła, jak i dostęp do odczytu i zapisu w magazynie zasobów.

    • W przypadku wywołań tożsamości zarządzanej w celu Azure osadzania lub wdrożeń czatu openAI usług Cognitive Services przypisz użytkownika openAI usług Cognitive Services do wybranej tożsamości w zasobie openAI Azure lub nadrzędnym zasobie Foundry, który jest zgodny resourceUriz . Uprawnienia usługi wyodrębniania są oddzielne. Zobacz Przypisywanie roli.
  • Jeśli ustawisz networkAccessMode na private, upewnij się, że spełniono następujące wymagania:

    • Użyj usługi IQ S2, S3, L1 lub L2 Foundry. Sprawdź kanoniczną macierz obsługi udostępnionego łącza prywatnego pod kątem wymagań dotyczących konfiguracji i warstw.

    • Włącz tożsamość zarządzaną przypisaną przez system lub przypisaną przez użytkownika w usłudze IQ usługi Foundry, przyznaj jej rolę Czytelnik danych obiektu blob usługi Storage na koncie magazynu i użyj ResourceId=/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account> parametry połączenia. W przypadku tożsamości przypisanej przez użytkownika ustaw również wartość ingestionParameters.identity.

    • Utwórz i zatwierdź linki do magazynu wymienione w sekcji obsługiwane typy zasobów. W przypadku usługi ADLS Gen2 wymagane są linki blob i dfs .

    • Utwórz i zatwierdź łącze dla każdego chronionego modelu, wyodrębniania, wzbogacania lub zależności związanej z magazynem zasobów używanych przez konfigurację. Korzystaj z obsługiwanych typów zasobów dla każdego elementu docelowego i identyfikatora grupy.

  • Wymagany pakiet Azure.Search.Documents:

    • Dla funkcji 2026-08-01-preview najnowszy pakiet w wersji zapoznawczej: dotnet add package Azure.Search.Documents --prerelease

    • W przypadku programu 2026-10-01, najnowszy stabilny pakiet: dotnet add package Azure.Search.Documents

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

  • Wymagany pakiet azure-search-documents:

    • Dla funkcji 2026-08-01-preview najnowszy pakiet w wersji zapoznawczej: pip install --pre azure-search-documents

    • W przypadku programu 2026-10-01, najnowszy stabilny pakiet: pip install azure-search-documents

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

  • Wymagana wersja interfejsu API REST usługi wyszukiwania:

    • W przypadku funkcji w wersji zapoznawczej: 2026-11-01-preview

    • W przypadku ogólnie dostępnych funkcji, w tym pozyskiwania prywatnego: 2026-10-01

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

W przypadku pozyskiwania uprawnień użyj interfejsu REST 2026-10-01 , jak pokazano w temacie Wymuszanie uprawnień na poziomie dokumentu. Przykłady stabilnego 2026-04-01 zestawu SDK nie konfigurują pozyskiwania uprawnień. Sprawdź dziennik zmian pakietu pod kątem obsługi wymaganej wersji interfejsu API i właściwości.

Przykłady REST używają najnowszego interfejsu API w wersji zapoznawczej. 2026-11-01-preview Przykłady zestawu SDK w wersji zapoznawczej zachowują udokumentowany 2026-08-01-preview kontrakt. Sprawdź dziennik zmian pakietu przed wybraniem nowszej wersji interfejsu API jako docelowej.

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}}

Dokumentacja:Źródła wiedzy — pobieranie

Poniższa odpowiedź ukrywa poufne wartości i wyświetla wygenerowane obiekty pod createdResources. Przed ponownym korzystaniem z niego w celu utworzenia innego źródła wiedzy podaj poświadczenia docelowe lub skonfiguruj obsługiwaną tożsamość zarządzaną; zanonimizowane wartości nie są poświadczeniami.

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "standard",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<aoai-endpoint>",
          "deploymentId": "gpt-5-mini",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<aoai-endpoint>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-ks-index"
    }
  }
}

Tworzenie źródła wiedzy

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

// Create a blob knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;

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

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

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

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

var blobParams = new AzureBlobKnowledgeSourceParameters(
    connectionString: connectionString,
    containerName: containerName
)
{
    IsAdlsGen2 = false,
    IngestionParameters = ingestionParams
};

var knowledgeSource = new AzureBlobKnowledgeSource(
    name: "my-blob-ks",
    azureBlobParameters: blobParams
)
{
    Description = "This knowledge source pulls from a blob storage container."
};

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

Reference:SearchIndexClient, AzureBlobKnowledgeSource

# Create a blob knowledge source
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import AzureBlobKnowledgeSource, AzureBlobKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters
from azure.search.documents.knowledgebases.models import KnowledgeSourceNetworkAccessMode

index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())

knowledge_source = AzureBlobKnowledgeSource(
    name = "my-blob-ks",
    description = "This knowledge source pulls from a blob storage container.",
    encryption_key = None,
    azure_blob_parameters = AzureBlobKnowledgeSourceParameters(
        connection_string = "blob_connection_string",
        container_name = "blob_container_name",
        folder_path = None,
        is_adls_gen2 = False,
        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 = "<aoai-endpoint>",
                    deployment_name = "<aoai-gpt-deployment>",
                    model_name = "<aoai-gpt-model>",
                )
            ),
            embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
                azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
                    resource_url = "<aoai-endpoint>",
                    deployment_name = "<aoai-embedding-deployment>",
                    model_name = "<aoai-embedding-model>",
                )
            ),
            content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
            ingestion_schedule = None,
            ingestion_permission_options = ["rbacScope"]
        )
    )
)

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

Reference:SearchIndexClient

### Create a blob knowledge source
PUT {{search-endpoint}}/knowledgesources/my-blob-ks?api-version=2026-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "This knowledge source pulls from a blob storage container.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "ResourceId=<storage-resource-id>",
    "containerName": "<blob-container-name>",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
        "networkAccessMode": "public",
        "identity": null,
        "disableImageVerbalization": null,
        "chatCompletionModel": {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{aoai-endpoint}}",
                "deploymentId": "{{aoai-gpt-deployment}}",
                "modelName": "{{aoai-gpt-model}}"
            }
        },
        "embeddingModel": {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{aoai-endpoint}}",
                "deploymentId": "{{aoai-embedding-deployment}}",
                "modelName": "{{aoai-embedding-model}}"
            }
        },
        "contentExtractionMode": "minimal",
        "ingestionSchedule": null,
        "ingestionPermissionOptions": ["rbacScope"]
    }
  }
}

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

Konfigurowanie harmonogramu pozyskiwania

Ustaw ingestionParameters.ingestionSchedule, aby określić, jak często wygenerowany indeksator sprawdza zmiany w źródle danych. Kwalifikujące się niedokończone pozyskiwanie danych może być kontynuowane automatycznie po zatrzymaniu z powodu limitu czasu wykonania bez oczekiwania na następne odpytywanie.

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 ustawienia rozliczeń i opisu obrazu.

Ogranicz pozyskiwanie danych do sieci prywatnej

W stabilnym interfejsie API 2026-10-01 element networkAccessMode steruje środowiskiem sieciowym, w którym działa wygenerowany indeksator dla źródła wiedzy typu blob. To ustawienie wpływa tylko na indeksowanie i nie zmienia żądań ani odpowiedzi pobierania z bazy wiedzy. Zapoznaj się z macierzą obsługi udostępnionego łącza prywatnego pod kątem kwalifikujących się konfiguracji. Niezależne funkcje w wersji zapoznawczej, takie jak automatyczne analizatory dla poszczególnych języków i udostępnianie obrazów, mają własne wymagania dotyczące interfejsu API.

networkAccessMode wartość domyślna to public, która zachowuje istniejące zachowanie sieci publicznej. Gdy parametr networkAccessMode ma wartość private, wygenerowany indeksator działa w prywatnym środowisku wykonywania. Używa zatwierdzonych współużytkowanych łączy prywatnych do uzyskiwania dostępu do źródłowego połączenia z usługą Azure Blob Storage lub ADLS Gen2 oraz do obsługiwanych zależności platformy Azure, takich jak modele usługi Azure OpenAI i zasoby Microsoft Foundry.

Aby skonfigurować i zweryfikować dostęp do sieci prywatnej:

  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.

Korzystanie z automatycznych analizatorów dla poszczególnych języków (wersja zapoznawcza)

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ę Cognitive Services User w zasobie Microsoft Foundry do tożsamości zarządzanej usługi Foundry IQ. 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 na podstawie dominującego wykrytego języka. 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 Foundry IQ 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.

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.

Traktuj wygenerowane źródło danych, indeksator, indeks i zestaw umiejętności, jeśli istnieje, jako jedną konfigurację pozyskiwania. Ogranicz, kto może zmienić konfigurację lub publikować dokumenty do tego indeksu. Wygenerowane identyfikatory i nazwy pól uprawnień nie ustanawiają własności dokumentów ani nie czynią zwykłej zawartości autoryzowanym źródłem uprawnień. Postępuj zgodnie ze wskazówkami dotyczącymi zapobiegawczego przetwarzania i udokumentowanymi ograniczeniami dotyczącymi dostosowywania; nie używaj dowolnych bezpośrednich zmian wygenerowanych kluczy ani mapowań jako mechanizmu kontroli własności.

Przypisywanie do bazy wiedzy

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

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

Użyj domyślnej opcji wyodrębniania (contentExtractionMode: "minimal") lub standardowego wyodrębniania opartego na rozwiązaniu 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.

Ustaw ingestionPermissionOptions podczas tworzenia źródła wiedzy przy użyciu interfejsu API 2026-10-01REST:

  • W przypadku standardowych Blob Storage ustaw isADLSGen2 na false i zażądaj rbacScope. Zobacz pełną konfigurację REST obiektów blob.
  • W przypadku usługi ADLS Gen2 ustaw wartość isADLSGen2 i zażądaj trueuserIds, groupIdsi rbacScope. Rozpocznij od konfiguracji REST usługi ADLS i dodaj rbacScope do tablicy ingestionPermissionOptions , aby pozyskać zarówno listy ACL, jak i zakresy kontroli dostępu opartej na rolach kontenera.

Wygenerowany indeks zawiera metadata_storage_path i skonfigurowane pola uprawnień z mapowaniami na rzutowanych fragmentach. Ścieżka jest wymagana do pozyskiwania uprawnień usługi ADLS, w tym pozyskiwania uprawnień wyłącznie przy użyciu mechanizmu RBAC. Jego obecność w wygenerowanym standardowym schemacie obiektów blob nie czyni go wymogiem przy obliczaniu zakresu kontenera bezpośredniego indeksatora obiektów blob.

Przejrzyj wygenerowany indeks, projekcje zestawu umiejętności i indeksator razem. Zachowaj kontekst ścieżki źródłowej i mapowania uprawnień autorytatywnych dla każdego chronionego fragmentu. W przypadku istniejących rekordów z brakującymi wartościami poprawianie samego schematu nie powoduje wypełniania metadanych; postępuj zgodnie z korektą schematu i projekcji.

Wygenerowane indeksatory usługi ADLS są zgodne z ustawieniami i cyklem automatycznego odświeżania listy ACL. Skonfiguruj parameters.configuration.refreshAllAcls na wygenerowanym indeksatorze. W przypadku odświeżania na żądanie użyj nazwy tego indeksatora w procedurze ponownej synchronizacji uprawnień.

Uwzględnij token dostępu delegowanego użytkownika w żądaniu pobierania. Informacje o nagłówkach żądania znajdziesz w Wymuszanie uprawnień w czasie zapytania.

Wyświetlanie obrazów osadzonych w dokumentach (wersja zapoznawcza)

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