Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
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 из списка доверенных служб включённым.
- Если для ресурса Foundry отключён общедоступный сетевой доступ, создайте
Если для источника знаний указан режим извлечения содержимого
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извлечение возвращает код состояния HTTP415в обеих версиях.
Ограничения и операции с файлами
Ограничения и поддерживаемые операции с файлами различаются по версии 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}");
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}")
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}");
}
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}")
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})");
}
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})")
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}");
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}")
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");
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")
DELETE {{search-endpoint}}/knowledgesources/my-file-ks/files/file-abc123?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Справочник:Источники знаний — удаление файла
Назначение базе знаний
Если вы удовлетворены источником знаний, добавьте его в базу знаний.
Запрос к базе знаний
После настройки базы знаний вызовите действие извлечения или конечную точку MCP для запроса источника знаний.
Удаление источника знаний
Прежде чем удалить источник знаний, необходимо удалить любую базу знаний, которая ссылается на нее или обновить определение базы знаний, чтобы удалить ссылку. Для источников знаний, генерирующих индекс и конвейер индексатора, все созданные объекты также удаляются. Однако если вы использовали существующий индекс для создания источника знаний, индекс не удаляется.
Если вы пытаетесь удалить используемый источник знаний, действие завершается ошибкой и возвращает список затронутых баз знаний.
Удаление источника знаний:
Получите список всех баз знаний в службе поиска.
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" } ] }Получите отдельное определение базы знаний для проверки ссылок на источники знаний.
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 }Удалите базу знаний или, если у вас несколько источников знаний, обновите базу знаний, чтобы удалить источник. В этом примере показано удаление.
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
Удалите источник знаний.
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName); System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");Reference:SearchIndexClient
Получите список всех баз знаний в службе поиска.
# 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" } ] }Получите отдельное определение базы знаний для проверки ссылок на источники знаний.
# 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" } }Удалите базу знаний или, если у вас несколько источников знаний, обновите базу знаний, чтобы удалить источник. В этом примере показано удаление.
# 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
Удалите источник знаний.
# 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
Получите список всех баз знаний в службе поиска.
### 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" } ] }Получите отдельное определение базы знаний для проверки ссылок на источники знаний.
### 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" } }Удалите базу знаний или, если у вас несколько источников знаний, обновите базу знаний, чтобы удалить источник. В этом примере показано удаление.
### Delete a knowledge base DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}} Authorization: Bearer {{token}}Справочник:Базы знаний — удаление
Удалите источник знаний.
### 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 секунд во время отправки или обновления файла. Уменьшите размер или сложность файла и повторите попытку. |