Создать файловый источник знаний (предварительная версия)

Note

Поиск с использованием ИИ Azure доступна через портал Azure, REST API и Azure SDKs. Он также лежит в основе Foundry IQ — управляемого слоя знаний, который преобразует корпоративный контент в многократно используемые базы знаний с учетом разрешений доступа для агентов на портале Microsoft Foundry.

Important

Функции, возможности или свойства, помеченные (предварительная версия), не охватываются соглашением об уровне обслуживания, не рекомендуются для рабочих нагрузок и могут изменяться или ограничиваться до того, как они становятся общедоступными. Условия предварительной версии Поиск с использованием ИИ Azure применяются ко всем функциям предварительной версии, независимо от того, является ли он автономным или частью общедоступной функции.

Источник знаний на основе файлов (предварительная версия) загружает небольшие и средние наборы файлов непосредственно в Поиск с использованием ИИ Azure для агентного поиска. Источники знаний создаются независимо, ссылаются в базе знаний и используются в качестве базирования данных при запросе базы знаний во время выполнения.

Источники знаний о файлах полезны, если требуется возможность управляемой отправки вместо подготовки служба хранилища Azure, настройки доступа и создания конвейера индексатора через внешний контейнер. Поиск с использованием ИИ Azure обрабатывает отправленные файлы, чтобы их извлеченное содержимое можно было получить из базы знаний.

Используйте вместо этого источник знаний BLOB-объектов, если ваши файлы уже хранятся в Хранилище BLOB-объектов Azure или Azure Data Lake Storage 2-го поколения, если набор файлов превышает или, вероятно, превысит ограничения источника знаний файлов, или если требуется прием данных по расписанию. Кроме того, используйте источник знаний BLOB-объектов, если вы хотите управлять исходными BLOB-объектами с помощью политик управления жизненным циклом Хранилище BLOB-объектов Azure или при необходимости разрешений на уровне документа (предварительная версия) на основе разрешений в служба хранилища Azure.

Поддержка использования

Портал Azure Портал Microsoft Foundry Пакет SDK для .NET Пакет SDK для Python SDK для Java Пакет SDK для JavaScript REST API
❌ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Необходимые условия

  • Служба Поиск с использованием ИИ Azure в любом регионе, который предоставляет агентский доступ. Источники знаний файлов поддерживают как выделенные, так и бессерверные модели ценообразования. Сведения о модели и уровне см. в разделе "Выбор модели ценообразования" и уровня служб.

  • Просмотрите стоимость Поиск с использованием ИИ Azure. Вызовы модели, векторизация и другие виды обработки ИИ могут тарифицироваться отдельно.

  • В Serverless успешные операции загрузки файлов потребляют тарифицируемые вычислительные ресурсы. Неудачные отправки не несут расходов на бессерверные вычислительные ресурсы.

  • Если вам нужен платный agentic retrieval сверх бесплатного ежемесячного лимита, включите стандартный план agentic retrieval. Этот knowledgeRetrieval=standard параметр отличается от расходов на бессерверные вычисления и хранение и не выбирает модель ценообразования.

  • Файлы в поддерживаемом формате.

  • Разрешение на создание источников знаний. Настройте проверку подлинности без ключа с помощью роли участника службы поиска , назначенной учетной записи пользователя (рекомендуется) или используйте ключ API администратора.

  • Если в источнике знаний указана модель Azure OpenAI для эмбеддингов, у службы поиска должно быть управляемое удостоверение с ролью Cognitive Services User для ресурса Microsoft Foundry.

    • Если для ресурса Foundry отключён общедоступный сетевой доступ, создайте foundry_accountобщую частную ссылку от службы поиска к ресурсу Foundry и оставьте параметр Разрешить службам Azure из списка доверенных служб включённым.
  • Если для источника знаний указан режим извлечения содержимого standard, ознакомьтесь с требованиями к навыку Azure Content Understanding.

    • Плата за использование взимается по тарифу Azure Content Understanding in Foundry Tools pricing для ресурса Foundry, настроенного с помощью aiServices

    • Ежедневный бесплатный лимит на 20 документов, доступный для некоторых встроенных навыков, не действует.

    • Для примера, приведённого в этой статье, вам потребуются конечная точка и ключ ресурса Foundry, а также сведения о моделях эмбеддингов и завершения чата Azure OpenAI.

  • Последний пакет предварительной версии Azure.Search.Documents: dotnet add package Azure.Search.Documents --prerelease

  • Для аутентификации без использования ключа пакет Azure.Identity: dotnet add package Azure.Identity

  • Последний пакет предварительной версии azure-search-documents: pip install --pre azure-search-documents

  • Для аутентификации без использования ключа пакет azure-identity: pip install azure-identity

  • 2026-08-01-preview — версия REST API службы поиска.

  • Для проверки подлинности без ключа добавьте маркер Microsoft Entra ID в Authorization заголовок каждого HTTP-запроса.

Поддержка и ограничения файлов

Перед созданием источника знаний о файлах ознакомьтесь с требованиями и ограничениями, влияющими на отправку, извлечение и управление файлами.

Поддерживаемые типы содержимого

Источники знаний файлов принимают файлы на основе обнаруженного типа контента. Тип контента, указанный вызывающей стороной, не отменяет автоматическое определение.

Поддерживаемые типы контента:

  • Формат pdf
  • Word (.doc, .docx)
  • PowerPoint (.ppt, .pptx)
  • Excel (.xls, .xlsx)
  • JSON
  • Сценарии командной оболочки
  • Содержимое, определённое как text/*, например .txt, .md, .html и .csv

Поддерживаемые режимы извлечения

  • Для перечисленных типов контента и 2026-05-01-preview, и 2026-08-01-preview поддерживают minimal. standard доступен только в 2026-08-01-preview.

  • Содержимое, определённое как image/*, не поддерживается в 2026-05-01-preview. В 2026-08-01-preview используйте извлечение standard. minimal извлечение возвращает код состояния HTTP 415 в обеих версиях.

Ограничения и операции с файлами

Ограничения и поддерживаемые операции с файлами различаются по версии API.

Capability 2026-05-01-preview 2026-08-01-preview
Максимальное количество файлов на источник знаний 100 200
Максимальный размер файла 50 МБ на всех поддерживаемых ценовых категориях 50 МБ на уровнях Free и Basic; 100 МБ на других поддерживаемых уровнях Dedicated и Serverless
Длительность обработки Отправка может выполняться до 180 секунд Отправка и обновление может выполняться до 180 секунд
Отправка содержимого и метаданных Содержимое необработанного файла Содержимое необработанного файла или многопартийное содержимое с метаданными
Список отправленных файлов Перечень файлов Фильтрация по пути или имени файла и возврат более подробных сведений о файле
Замена существующего содержимого файла Удаление и повторная отправка Используйте операцию обновления
Доступ браузера к операциям с файлами CORS недоступен Настройка CORS

Note

  • Созданный индекс поиска сохраняет отправленное содержимое. Общие ограничения хранилища по ценовой категории см. в разделе "Ограничения службы".
  • Если вы настраиваете источник знаний на основе файла на разбиение на фрагменты или векторизацию загруженного содержимого, также действуют ограничения модели и последующей обработки.

Проверка существующих источников знаний

Источник знаний — это объект верхнего уровня, который можно использовать повторно. Знание существующих источников знаний полезно для повторного использования или именования новых объектов.

Выполните следующий код, чтобы перечислить источники знаний по имени и типу.

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

Справочник:Источники знаний — список

Вы также можете вернуть один источник знаний по имени, чтобы просмотреть его определение 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}}

Reference:Источники знаний — получить

Следующий код JSON является примером ответа для источника знаний о файле.

{
  "name": "my-file-ks",
  "kind": "file",
  "description": "A sample file knowledge source.",
  "encryptionKey": null,
  "fileParameters": {
    "ingestionParameters": {
      "contentExtractionMode": "minimal",
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      }
    }
  }
}

Создание источника знаний

Создайте источник знаний файла, указывающий модель внедрения, используемую для векторизации отправленного содержимого.

Каждый источник знаний о файле создает индекс, но не индексатор или расписание. Необходимо включить fileParameters.ingestionParameters объект. Служба отклоняет запросы, которые указывают networkAccessMode.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

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

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

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    ContentExtractionMode = "minimal",
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    }
};

var fileParams = new FileKnowledgeSourceParameters
{
    IngestionParameters = ingestionParams
};

var knowledgeSource = new FileKnowledgeSource(
    name: "my-file-ks",
    fileParameters: fileParams
)
{
    Description = "This knowledge source uses directly uploaded product manuals."
};

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

Reference:SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    AzureOpenAIVectorizerParameters,
    FileKnowledgeSource,
    FileKnowledgeSourceParameters,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeSourceAzureOpenAIVectorizer,
    KnowledgeSourceIngestionParameters,
)

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

embedding_params = AzureOpenAIVectorizerParameters(
    resource_url="<aoai-endpoint>",
    deployment_name="<aoai-embedding-deployment>",
    model_name="<aoai-embedding-model>",
)

ingestion_params = KnowledgeSourceIngestionParameters(
    content_extraction_mode="minimal",
    embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
        azure_open_ai_parameters=embedding_params
    ),
)

knowledge_source = FileKnowledgeSource(
    name="my-file-ks",
    description="This knowledge source uses directly uploaded product manuals.",
    file_parameters=FileKnowledgeSourceParameters(ingestion_parameters=ingestion_params),
)

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

Reference:SearchIndexClient

PUT {{search-endpoint}}/knowledgesources/my-file-ks?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
Prefer: return=representation

{
  "name": "my-file-ks",
  "kind": "file",
  "description": "This knowledge source uses directly uploaded product manuals.",
  "encryptionKey": null,
  "fileParameters": {
    "ingestionParameters": {
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-embedding-deployment}}",
          "modelName": "{{aoai-embedding-model}}"
        }
      },
      "contentExtractionMode": "minimal"
    }
  }
}

Справочник:Источники знаний — создание или обновление

Настройка стандартного извлечения

Начиная с версии API 2026-08-01-preview, компонент standard для извлечения данных использует Content Understanding для извлечения, семантического разбиения на фрагменты и обогащения загруженных файлов. Поиск с использованием ИИ Azure управляет этой обработкой как часть источника знаний, а плата за распознавание содержимого взимается отдельно.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;

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

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

var ingestionParameters = new KnowledgeSourceIngestionParameters
{
  ContentExtractionMode = KnowledgeSourceContentExtractionMode.Standard,
  AiServices = new AIServices(new Uri(foundryEndpoint)) { ApiKey = foundryKey },
  EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
  {
    AzureOpenAIParameters = embeddingParameters
  },
  ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(
    new AzureOpenAIVectorizerParameters
    {
      ResourceUri = new Uri(aoaiEndpoint),
      DeploymentName = aoaiChatDeployment,
      ModelName = aoaiChatModel
    })
};

var knowledgeSource = new FileKnowledgeSource(
  "my-file-ks",
  new FileKnowledgeSourceParameters { IngestionParameters = ingestionParameters });

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Configured standard extraction for '{knowledgeSource.Name}'.");

Reference:SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
  AzureOpenAIVectorizerParameters,
  FileKnowledgeSource,
  FileKnowledgeSourceParameters,
  KnowledgeBaseAzureOpenAIModel,
)
from azure.search.documents.knowledgebases.models import (
  AIServices,
  KnowledgeSourceAzureOpenAIVectorizer,
  KnowledgeSourceIngestionParameters,
)

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

embedding_parameters = AzureOpenAIVectorizerParameters(
  resource_url="<aoai-endpoint>",
  deployment_name="<aoai-embedding-deployment>",
  model_name="<aoai-embedding-model>",
)
ingestion_parameters = KnowledgeSourceIngestionParameters(
  content_extraction_mode="standard",
  ai_services=AIServices(
    uri="<foundry-resource-endpoint>",
    api_key="<foundry-resource-key>",
  ),
  embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
    azure_open_ai_parameters=embedding_parameters
  ),
  chat_completion_model=KnowledgeBaseAzureOpenAIModel(
    azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
      resource_url="<aoai-endpoint>",
      deployment_name="<aoai-gpt-deployment>",
      model_name="<aoai-gpt-model>",
    )
  ),
)
knowledge_source = FileKnowledgeSource(
  name="my-file-ks",
  file_parameters=FileKnowledgeSourceParameters(
    ingestion_parameters=ingestion_parameters
  ),
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Configured standard extraction for '{knowledge_source.name}'.")

Reference:SearchIndexClient

PUT {{search-endpoint}}/knowledgesources/my-file-ks?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
Prefer: return=representation

{
  "name": "my-file-ks",
  "kind": "file",
  "description": "This knowledge source uses standard extraction.",
  "fileParameters": {
    "ingestionParameters": {
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-embedding-deployment}}",
          "modelName": "{{aoai-embedding-model}}"
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-gpt-deployment}}",
          "modelName": "{{aoai-gpt-model}}"
        }
      },
      "contentExtractionMode": "standard",
      "aiServices": {
        "uri": "{{foundry-resource-endpoint}}",
        "apiKey": "{{foundry-resource-key}}"
      }
    }
  }
}

Справочник:Источники знаний — создание или обновление

CORS для операций с файлами

Чтобы разрешить операции с файлами в браузере, задайте corsOptions для источника знаний о файлах, указав доверенные источники и максимальное время кэширования preflight-запросов для вашего приложения.

Important

В версии API corsOptions2026-08-01-preview применяется к конечным точкам для загрузки файлов, получения списка, обновления и удаления независимо от режима извлечения. Если не указано corsOptions, источник знаний файлов не имеет политики перекрестного происхождения браузера. CORS не авторизует запросы. Разрешение источников может открыть доступ к операциям службы и данным в контексте браузера и создать угрозы безопасности. Укажите только доверенные источники и не используйте подстановочный знак в рабочей среде. Для запросов из браузера используйте аутентификацию с помощью токена Microsoft Entra с минимально необходимой ролью. Никогда не предоставляйте маркеры доступа или ключи службы в коде браузера.

Отправка файлов

После создания источника знаний отправьте файлы непосредственно в него. Каждая загрузка — это синхронный вызов: Поиск с использованием ИИ Azure извлекает содержимое, разбивает его на фрагменты, при необходимости создает эмбеддинги, индексирует эти фрагменты и сохраняет метаданные файла, прежде чем вызов завершится. Вам не нужно настраивать или запускать отдельный конвейер приема.

Сведения об ошибках, связанных с отправкой и управлением файлами, см. в разделе "Устранение неполадок с файлами".

Отправка необработанного файла

Для прямой загрузки указанное значение fileName берётся из заголовка Content-Disposition: attachment; filename="...". Вызовы REST и пакет SDK .NET задают этот заголовок напрямую, а пакет SDK Python принимает параметр filename и автоматически создает заголовок. Если имя файла не указано, служба назначает автоматически сформированный fileNameфайл.

Имена файлов могут включать относительный путь, например manuals/installation-guide.pdf. Служба преобразует обратные слеши в прямые слеши. Он отклоняет абсолютные пути, пустые сегменты пути, сегменты . или .., сегменты, содержащие двоеточие, и недопустимые символы в имени файла с кодом состояния HTTP 400.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

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

string fileName = "installation-guide.pdf";
byte[] fileBytes = await File.ReadAllBytesAsync(fileName);
string contentDisposition = $"attachment; filename=\"{fileName}\"";

KnowledgeSourceFile uploadedFile = (await indexClient.UploadKnowledgeSourceFileAsync(
    "my-file-ks",
    contentDisposition,
    BinaryData.FromBytes(fileBytes))).Value;

Console.WriteLine($"Uploaded file ID: {uploadedFile.FileId}");

Reference:SearchIndexClient.UploadKnowledgeSourceFileAsync

from pathlib import Path

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

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

file_path = Path("installation-guide.pdf")
uploaded_file = index_client.upload_knowledge_source_file(
    "my-file-ks",
    file_path.read_bytes(),
    filename=file_path.name,
)
print(f"Uploaded file ID: {uploaded_file.file_id}")

Справочник:SearchIndexClient.upload_knowledge_source_file

POST {{search-endpoint}}/knowledgesources/my-file-ks/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="installation-guide.pdf"

<binary file content>

Справочник:Источники знаний — отправка файла

Отправка файла с необязательными метаданными

Начиная с версии API 2026-08-01-preview, используйте многочастный запрос для загрузки одного двоичного файла с необязательными пользовательскими метаданными. Запрос включает ровно одну content часть и необязательную часть JSON metadata .

Если указаны оба имени, metadata.fileName имеет приоритет перед именем файла в части content. Если оно не указано, служба назначает автоматическое имя файла.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var metadata = new FileUploadMetadata
{
  FileName = "installation-guide.pdf",
  Metadata =
  {
    ["department"] = "support",
    ["product"] = "contoso-100"
  }
};

#pragma warning disable SCME0004
var request = new UploadKnowledgeSourceFileMultipartRequest(
  metadata,
  "installation-guide.pdf");
KnowledgeSourceFile uploadedFile = (await indexClient
  .UploadKnowledgeSourceFileMultipartAsync("my-file-ks", request)).Value;
#pragma warning restore SCME0004

Console.WriteLine($"Uploaded file ID: {uploadedFile.FileId}");

Справочник:SearchIndexClient.UploadKnowledgeSourceFileMultipartAsync

from pathlib import Path

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
  FileUploadMetadata,
  UploadKnowledgeSourceFileMultipartRequest,
)

index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
file_path = Path("installation-guide.pdf")
request = UploadKnowledgeSourceFileMultipartRequest(
  metadata=FileUploadMetadata(
    file_name=file_path.name,
    metadata={"department": "support", "product": "contoso-100"},
  ),
  content=(file_path.name, file_path.read_bytes(), "application/pdf"),
)

uploaded_file = index_client.upload_knowledge_source_file_multipart(
  name="my-file-ks",
  body=request,
)
print(f"Uploaded file ID: {uploaded_file.file_id}")

Справочник:SearchIndexClient.upload_knowledge_source_file_multipart

POST {{search-endpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: multipart/form-data; boundary=file-boundary

--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "fileName": "installation-guide.pdf",
  "metadata": {
    "department": "support",
    "product": "contoso-100"
  }
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="installation-guide.pdf"
Content-Type: application/octet-stream

< ./installation-guide.pdf
--file-boundary--

Справочник:Источники знаний — отправка файла

Note

Отправка файла не заменяет существующий файл, даже если вы повторно используете тот же fileNameфайл. Каждая успешная загрузка создаёт новый файл с собственным fileId, поэтому список загруженных файлов может содержать несколько записей с общим fileName.

С помощью 2026-05-01-preview замените содержимое, удалив исходный файл и загрузив новый. При использовании 2026-08-01-preview используйте операцию обновления.

Список отправленных файлов

Выведите список файлов в источнике знаний, чтобы проверить загруженный набор файлов.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

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

await foreach (KnowledgeSourceFile file in indexClient.GetKnowledgeSourceFilesAsync("my-file-ks"))
{
    Console.WriteLine($"{file.FileName} ({file.FileSizeBytes} bytes) error={file.ErrorMessage}");
}

Reference:SearchIndexClient.GetKnowledgeSourceFilesAsync

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

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

for file in index_client.list_knowledge_source_files("my-file-ks"):
    print(f"{file.file_name} ({file.file_size_bytes} bytes) error={file.error_message}")

Справочник:SearchIndexClient.list_knowledge_source_files

GET {{search-endpoint}}/knowledgesources/my-file-ks/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}

Reference:Knowledge Sources — List Files

Ответ содержит метаданные для каждого отправленного файла. Файлы, успешно добавленные в список, имеют errorMessage значение null.

{
  "value": [
    {
      "fileId": "file-abc123",
      "fileName": "installation-guide.pdf",
      "fileSizeBytes": 1048576,
      "createdAt": "2026-05-07T18:10:00Z",
      "lastUpdatedAt": "2026-05-07T18:14:00.803Z",
      "errorMessage": null
    }
  ]
}

Если новая отправка завершается ошибкой, запрос возвращает ошибку и не создает запись метаданных файла. Сбой отправки не отображается в последующих результатах списка и не оплачивается.

Если происходит сбой доступа к модели и ресурс Foundry, в котором размещена модель эмбеддингов, использует частную сеть, убедитесь, что общая частная ссылка foundry_account одобрена, а параметр обхода доверенных служб включен. Отключённый обход возвращает 403 Public access is disabled. Дополнительные сведения о настройке см. в разделе "Предварительные требования".

Список и фильтрация файлов

Начиная с 2026-08-01-preview версии API, используйте prefix для фильтрации файлов по относительному пути или search фильтрации по префиксу имени файла. Задайте pageSize для управления числом результатов.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

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

await foreach (KnowledgeSourceFile file in indexClient.GetKnowledgeSourceFilesAsync(
  "my-file-ks",
  prefix: "manuals/",
  pageSize: 100))
{
  Console.WriteLine($"{file.FileName} ({file.FileId})");
}

Reference:SearchIndexClient.GetKnowledgeSourceFilesAsync

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

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

files = index_client.list_knowledge_source_files(
  "my-file-ks",
  prefix="manuals/",
  page_size=100,
)
for file in files:
  print(f"{file.file_name} ({file.file_id})")

Справочник:SearchIndexClient.list_knowledge_source_files

GET {{search-endpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-08-01-preview&prefix=manuals/&pageSize=100
Authorization: Bearer {{search-access-token}}

Reference:Knowledge Sources — List Files

Ответ включает режимы синтаксического анализа и извлечения, выбранные службой, а также пользовательские метаданные для управления файлами. Метаданные пользователя не доступны для поиска или фильтрации.

{
  "value": [
    {
      "fileId": "file-abc123",
      "fileName": "manuals/installation-guide.md",
      "prefix": "manuals/",
      "metadata": {
        "department": "support",
        "product": "contoso-100"
      },
      "parsingMode": "markdown",
      "extractionMode": "minimal",
      "fileSizeBytes": 1048576,
      "createdAt": "2026-08-03T18:10:00Z",
      "lastUpdatedAt": "2026-08-03T18:14:00Z",
      "errorMessage": null
    }
  ],
  "@odata.nextLink": "<service-generated continuation URL>"
}

Чтобы получить все результаты, переходите по @odata.nextLink, пока этот элемент присутствует. Отправьте полный URL-адрес точно так же, как возвращенный, без изменения параметров запроса.

Обновление отправленного файла

Начиная с версии API 2026-08-01-preview, обновите файл по его fileId. Для многопартийного запроса требуется двоичная content часть. Часть JSON метаданных является необязательной, поэтому поддерживается обновление только для содержимого. Обновление только метаданных не поддерживается.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var metadata = new FileUploadMetadata
{
  FileName = "installation-guide.pdf",
  Metadata =
  {
    ["department"] = "support",
    ["product"] = "contoso-200"
  }
};

#pragma warning disable SCME0004
var request = new UpdateKnowledgeSourceFileRequest(
  metadata,
  "installation-guide.pdf");
KnowledgeSourceFile updatedFile = (await indexClient.UpdateKnowledgeSourceFileAsync(
  fileId,
  "my-file-ks",
  request)).Value;
#pragma warning restore SCME0004

Console.WriteLine($"Updated file ID: {updatedFile.FileId}");

Справочник:SearchIndexClient.UpdateKnowledgeSourceFileAsync

from pathlib import Path

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
  FileUploadMetadata,
  UpdateKnowledgeSourceFileRequest,
)

index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
file_path = Path("installation-guide.pdf")
request = UpdateKnowledgeSourceFileRequest(
  metadata=FileUploadMetadata(
    file_name=file_path.name,
    metadata={"department": "support", "product": "contoso-200"},
  ),
  content=(file_path.name, file_path.read_bytes(), "application/pdf"),
)

updated_file = index_client.update_knowledge_source_file(
  name="my-file-ks",
  file_id=file_id,
  body=request,
)
print(f"Updated file ID: {updated_file.file_id}")

Справочник:SearchIndexClient.update_knowledge_source_file

PUT {{search-endpoint}}/knowledgesources('my-file-ks')/files('{{file-id}}')?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: multipart/form-data; boundary=file-boundary

--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "fileName": "installation-guide.pdf",
  "metadata": {
    "department": "support",
    "product": "contoso-200"
  }
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="installation-guide.pdf"
Content-Type: application/octet-stream

< ./installation-guide.pdf
--file-boundary--

Справочник:Источники знаний — файл обновления

Если обновление не удаётся, предыдущая запись метаданных остаётся. Не предполагайте, что обновление изменяет индексированное содержимое транзакционно.

Удаление отправленных файлов

Удалите файлы из источника знаний, если они больше не нужны для извлечения.

using Azure.Identity;
using Azure.Search.Documents.Indexes;

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

await indexClient.DeleteKnowledgeSourceFileAsync("my-file-ks", "file-abc123");

Reference:SearchIndexClient.DeleteKnowledgeSourceFileAsync

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

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

index_client.delete_knowledge_source_file("my-file-ks", "file-abc123")

Справочник:SearchIndexClient.delete_knowledge_source_file

DELETE {{search-endpoint}}/knowledgesources/my-file-ks/files/file-abc123?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}

Справочник:Источники знаний — удаление файла

Назначение базе знаний

Если вы удовлетворены источником знаний, добавьте его в базу знаний.

Запрос к базе знаний

После настройки базы знаний вызовите действие извлечения или конечную точку MCP для запроса источника знаний.

Удаление источника знаний

Прежде чем удалить источник знаний, необходимо удалить любую базу знаний, которая ссылается на нее или обновить определение базы знаний, чтобы удалить ссылку. Для источников знаний, генерирующих индекс и конвейер индексатора, все созданные объекты также удаляются. Однако если вы использовали существующий индекс для создания источника знаний, индекс не удаляется.

Если вы пытаетесь удалить используемый источник знаний, действие завершается ошибкой и возвращает список затронутых баз знаний.

Удаление источника знаний:

  1. Получите список всех баз знаний в службе поиска.

    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

    Пример ответа может выглядеть следующим образом:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Получите отдельное определение базы знаний для проверки ссылок на источники знаний.

    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

    Пример ответа может выглядеть следующим образом:

     {
       "Name": "earth-knowledge-base",
       "KnowledgeSources": [
         {
           "Name": "earth-knowledge-source"
         }
       ],
       "Models": [
         {}
       ],
       "RetrievalReasoningEffort": {},
       "OutputMode": {},
       "ETag": "\u00220x8DE278629D782B3\u0022",
       "EncryptionKey": null,
       "Description": null,
       "RetrievalInstructions": null,
       "AnswerInstructions": null
     }
    
  3. Удалите базу знаний или, если у вас несколько источников знаний, обновите базу знаний, чтобы удалить источник. В этом примере показано удаление.

    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. Удалите источник знаний.

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

    Reference:SearchIndexClient

  1. Получите список всех баз знаний в службе поиска.

    # 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

    Пример ответа может выглядеть следующим образом:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Получите отдельное определение базы знаний для проверки ссылок на источники знаний.

    # 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

    Пример ответа может выглядеть следующим образом:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Удалите базу знаний или, если у вас несколько источников знаний, обновите базу знаний, чтобы удалить источник. В этом примере показано удаление.

    # 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. Удалите источник знаний.

    # 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. Получите список всех баз знаний в службе поиска.

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

    Справочник:Базы знаний — список

    Пример ответа может выглядеть следующим образом:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Получите отдельное определение базы знаний для проверки ссылок на источники знаний.

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

    Справочник:Базы знаний — получение

    Пример ответа может выглядеть следующим образом:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Удалите базу знаний или, если у вас несколько источников знаний, обновите базу знаний, чтобы удалить источник. В этом примере показано удаление.

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

    Справочник:Базы знаний — удаление

  4. Удалите источник знаний.

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

    Справочник:Источники знаний — удаление

Устранение неполадок при операциях с файлами

Следующие коды состояния относятся к операциям источника знаний о файлах.

Код состояния Причина и действие
400 Файл пуст, не содержит извлекаемый текст, имеет небезопасный относительный путь или имеет недопустимый запрос продолжения. Убедитесь, что файл поддерживает, доступное для чтения содержимое и допустимое имя файла. При операциях со списками используйте @odata.nextLink в точности в том виде, в каком оно возвращено. Не сочетайте search с pageSize или $skiptoken.
409 Файловый источник знаний достиг ограничения по количеству файлов для данной версии API. Удалите файлы перед отправкой дополнительных данных.
415 Служба обнаружила неподдерживаемый MIME-тип или изображение, при этом для источника знаний используется минимальное извлечение данных. Используйте поддерживаемый формат. Для изображений используйте стандартное извлечение. Изменение только типа содержимого, заданного вызывающей стороной, не отменяет автоматическое определение.
429 Очередь обработки заполнена. Используйте ограниченный параллелизм и повторные попытки с экспоненциальной задержкой. Служба не гарантирует наличие заголовка Retry-After.
504 Обработка превысила 180 секунд во время отправки или обновления файла. Уменьшите размер или сложность файла и повторите попытку.