在 Azure AI 搜索中将数据加载到搜索索引

本文介绍如何使用 REST API、Azure SDK 或 Azure 门户将文档导入预定义的搜索索引。

提示

若要获取加载数据最快的路径，请使用 Azure 门户中的 “导入数据”向导，该向导创建索引并将其加载到一个工作流中。

先决条件

Azure AI 搜索服务（任何层）。创建服务或查找现有服务。
现有搜索索引。本文假定你已创建索引。如果需要在一个步骤中创建和加载，请使用导入向导或索引器。
加载文档的权限：
- 基于密钥的身份验证：搜索服务的管理员 API 密钥。
- 基于角色的身份验证：搜索服务上的搜索索引数据参与者角色。
对于 SDK 开发，请安装 Azure 搜索客户端库：
- .NET： Azure.Search.Documents
- Python： azure-search-documents
- JavaScript： @azure/search-documents
- Java： azure-search-documents

使用 Azure 门户

在 Azure 门户中，使用导入向导在无缝工作流中创建和加载索引。如果要加载现有索引，请选择替代方法。

使用 Azure 帐户登录 Azure 门户并查找搜索服务。
在 “概述 ”页上，选择命令栏上的 “导入数据 ”或 “导入数据”（新）， 以创建和填充搜索索引。

可以点击以下链接查看工作流：快速入门：创建 Azure AI 搜索索引和快速入门：集成矢量化。
向导完成后，使用搜索资源管理器检查结果。

提示

导入向导会创建并运行索引器。如果已定义索引器，则可以从 Azure 门户重置并运行索引器，这在以增量方式添加字段时非常有用。重置会迫使索引器重头开始，从所有源文档中选取所有字段。

使用 REST API

文档 - 索引是用于将数据导入搜索索引的 REST API。

请求的正文包含要编入索引的一个或多个文档。文档通过区分大小写的键进行唯一标识。每个文档都与一个动作相关联：“上传”、“删除”、“合并”或“合并或上传”。上传请求必须包含文档数据作为一组键/值对。

REST API 适用于初始概念验证测试，可以在其中测试索引工作流，而无需编写大量代码。 @search.action 参数根据特定字段的新值或替换值确定是部分还是全部添加文档。

快速入门：使用 REST 进行全文搜索 介绍了这些步骤。下面的示例是修改后的示例版本。为简洁起见，对该值进行了剪裁，并更改了第一个 HotelId 值，以避免覆盖现有文档。

构建一个 POST 调用，用于指定索引名称、“docs/index”终结点，以及一个包含 @search.action 参数的请求正文。

POST https://[service name].search.azure.cn/indexes/hotels-sample-index/docs/index?api-version=2025-09-01
Content-Type: application/json   
api-key: [admin key] 
{
    "value": [
    {
    "@search.action": "upload",
    "HotelId": "1111",
    "HotelName": "Stay-Kay City Hotel",
    "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of Beijing. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make Beijing one of America's most attractive and cosmopolitan cities.",
    "Category": "Boutique",
    "Tags": [ "pool", "air conditioning", "concierge" ]
    },
    {
    "@search.action": "mergeOrUpload",
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "This is description is replacing the original one for this hotel. New and changed values overwrite the previous ones. In a comma-delimited list like Tags, be sure to provide the full list because there is no merging of values within the field itself.",
    "Category": "Boutique",
    "Tags": [ "pool", "free wifi", "concierge", "my first new tag", "my second new tag" ]
    }
  ]
}

将 @search.action 参数设置为 upload 以创建或覆盖文档。如果要更新文档中的特定字段，请将其设置为 merge 或 uploadOrMerge。上一个示例显示了这两个操作。

动作	效果
上传	类似于“更新插入”（upsert），如果文档是新创建的，则进行插入；如果文档已存在，则进行更新或替换。如果文档缺少索引所需的值，则将文档字段的值设置为 null。
合并	更新已存在的文档，如果找不到文档，该操作则会失败。合并将替换现有值。因此，请务必检查是否有包含多个值的集合字段，例如类型为 `Collection(Edm.String)` 的字段。例如，如果 `tags` 字段以 `["budget"]` 值开头，并且你执行与 `["economy", "pool"]` 的合并，则 `tags` 字段的最终值为 `["economy", "pool"]`。不是 `["budget", "economy", "pool"]`。
合并或上传	如果文档已存在，则行为类似于合并；如果文档是新的，则类似于上传。这是增量更新的最常见操作。
删除	删除从索引中删除指定的文档。在删除作中指定的任何字段（键字段以外的任何字段）将被忽略。如果要从文档中移除单个字段，请改用 merge 并将该字段显式设置为 null。有关详细信息，请参阅搜索索引中的“删除文档”。

对于首先执行请求正文中的哪项操作并未提供排序保证。不建议在单个请求正文中将多个“merge”操作与同一文档关联。如果同一文档需要多个“merge”操作，请先在客户端执行合并操作，然后再更新搜索索引中的文档。

在基元集合中，如果文档包含值为 ["budget"] 的 Tags 字段，并且对其执行值为 ["economy", "pool"] 的合并，则 Tags 字段的最终值为 ["economy", "pool"]。它不是[“预算”、“经济”、“池”]。

在复杂集合中，如果文档包含名为 Rooms 的复杂集合类型的字段，其值为 [{“Type”: “Budget Room”, “BaseRate”: 75.0}]，并合并值为 [{“Type”: “Standard Room”}, {“Type”: “Budget Room”, “BaseRate”: 60.5}]，那么 Rooms 字段的最终值将为 [{“Type”: “Standard Room”}, {“Type”: “Budget Room”, “BaseRate”: 60.5}]。它不会是以下任一项：

[{ “Type”： “Budget Room”， “BaseRate”： 75.0 }， { “Type”： “Standard Room” }， { “Type”： “Budget Room”， “BaseRate”： 60.5 }]（追加元素）
[{ “Type”： “Standard Room”， “BaseRate”： 75.0 }， { “Type”： “Budget Room”， “BaseRate”： 60.5 }]（按顺序合并元素，然后追加任何额外内容）

注释

将包含时区信息的 DateTimeOffset 值上传到索引时，Azure AI 搜索将这些值规范化为 UTC。例如，2025-01-13T14：03：00-08：00 将存储为 2025-01-13T22：03：00Z。如果需要存储时区信息，请将额外的列添加到索引中。

发送请求。

下表说明了可在响应中返回的各种每文档状态代码。某些状态代码会指示请求本身的问题，而另一些代码会指示临时错误条件。对于后者，应在延迟后重试。

状态代码	Meaning	可重试	注释
200	文档已成功修改或删除。	n/a	删除操作是幂等的。也就是说，即使索引中不存在某个文档键，使用该键尝试执行删除操作也会生成 200 状态代码。
201	已成功创建文档。	n/a
400	文档中存在阻止其编入索引的错误。	否	响应中的错误消息指示文档存在的问题。
404	文档无法合并，因为索引中不存在给定键。	否	此错误不会在上载时发生，因为它们会创建新文档；对于删除操作，也不会发生此错误，因为删除操作是幂等的。
409	尝试将文档编入索引时检测到了版本冲突。	是的	尝试将相同文档同时多次编入索引时，可能发生此错误。
422	索引暂时不可用，因为在将“allowIndexDowntime”标志设置为“true”的情况下更新了它。	是的
429	表明您已超出了每个索引可用的文档数量配额。	否	必须创建新的索引或升级以提高容量限制。
503	搜索服务暂时不可用，可能是因为负荷较重。	是的	在此情况下，代码应在重试前等待，否则面临延长服务不可用性状态的风险。

注释

如果客户端代码经常遇到 207 响应，则一个可能的原因是系统过载。可以通过检查 statusCode 503 的属性来确认这一点。如果是这种情况，我们建议限制索引请求。否则，如果索引流量不下降，系统可能开始使用 503 错误拒绝所有请求。

查阅你刚才添加的文档，作为验证步骤：

GET https://[service name].search.azure.cn/indexes/hotel-sample-index/docs/1111?api-version=2025-09-01

参考：文档 - 索引，文档 - 获取

成功的索引请求会返回 HTTP 200（成功），如果所有文档都处理成功；如果某些文档处理失败，则返回 HTTP 207（多状态）。响应正文包含每个文档的状态：

{
    "value": [
        { "key": "1111", "status": true, "statusCode": 201 },
        { "key": "2", "status": true, "statusCode": 200 }
    ]
}

当文档键或 ID 为新时， null 将成为文档中未指定的任何字段的值。对于现有文档上的操作，更新后的值将替换之前的值。 “merge”或“mergeUpload”未指定的任何字段都在搜索索引中保持不变。

使用 Azure SDK

以下 Azure SDK 中提供了可编程性。

Azure SDK for Python 提供以下 API，用于将文档简单或批量上传到索引中：

Reference：SearchClient、 IndexDocumentsBatch

代码示例包括：

sample_crud_operations.py
请务必查看 azure-search-vector-samples 存储库以获取展示如何索引矢量字段的代码示例。

Azure SDK for .NET 提供以下 API，用于将简单和批量文档上传到索引中：

以下示例将文档上传到现有索引：

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Create the search client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample-index";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.azure.cn");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Define documents to upload
var documents = new[]
{
    new { HotelId = "1111", HotelName = "Stay-Kay City Hotel", Category = "Boutique" },
    new { HotelId = "1112", HotelName = "Old Century Hotel", Category = "Luxury" }
};

// Upload documents
IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(
    IndexDocumentsBatch.Upload(documents));

Console.WriteLine($"Uploaded {result.Results.Count} documents");

Reference：SearchClient、 IndexDocumentsAsync、 IndexDocumentsBatch

有几个示例说明了在简单和大规模索引中如何进行索引：

“加载索引”说明了基本步骤。
来自 Azure SDK 团队的“Azure.Search.Documents 示例 - 索引文档”添加了 SearchIndexingBufferedSender。
“教程：索引任何数据”使用测试策略关联批量索引来确定最佳大小。
请务必查看 azure-search-vector-samples 存储库以获取展示如何索引矢量字段的代码示例。

验证您的数据加载

加载文档后，验证数据是否已正确编制索引。

在 Azure 门户中，打开搜索服务 “概述 ”页。
从命令栏中选择 搜索资源管理器 。
从下拉列表中选择索引。
选择 “搜索 ”以运行返回所有文档的空查询。
验证文档计数和抽查字段值。

使用获取文档 API 按键检索特定文档：

GET https://[service-name].search.azure.cn/indexes/hotels-sample-index/docs/1111?api-version=2025-09-01
api-key: [admin-key]

预期响应：如果 JSON 文档存在，则返回 HTTP 200；如果密钥不存在，则返回 HTTP 404。

// Verify document was indexed
var document = await searchClient.GetDocumentAsync<Hotel>("1111");
Console.WriteLine($"Found: {document.Value.HotelName}");

数据导入的工作原理

搜索服务接受符合索引架构的 JSON 文档。搜索服务可以在 JSON 文档中导入和索引纯文本内容和矢量内容。

纯文本内容通过从外部数据源的字段、元数据属性或由技能集生成的丰富内容中获取。技能可以从图像和非结构化内容中提取或推断文本说明。
矢量内容从提供它的数据源中检索，或者由在 Azure AI 搜索索引器工作负载中实现集成矢量化的技能集创建。

你可自行准备这些文档，但是如果内容驻留在支持的数据源中，那么运行索引器或使用导入向导可自动完成文档检索、JSON 序列化和索引。

索引数据后，索引的物理数据结构将被锁定。有关可更改和不可更改的内容的指南，请参阅更新并重新生成索引。

索引不是一个后台进程。搜索服务平衡索引编制和查询工作负荷，但如果查询延迟过高，可以添加容量或识别用于加载索引的低查询活动的时间段。

有关详细信息，请参阅数据导入策略。

解决常见问题

错误	原因	解决方案
HTTP 400 错误请求	文档包含无效数据或缺少必填字段	检查特定字段的错误消息。确保所有必填字段都存在，并且数据类型与索引架构匹配。
HTTP 404 未找到（合并）	尝试合并不存在的文档	如果文档可能不存在，则使用 `mergeOrUpload` 而不是 `merge`。
HTTP 409 冲突	对同一文档的并发更新	使用指数退避实现重试逻辑。
HTTP 413 有效负载太大	批大小超过限制	减少每个批的文档数。最大批大小为 1,000 个文档或 16 MB。
HTTP 429 请求过多	超出配额	检查您的服务层级限制。请考虑升级或创建新索引。
HTTP 503 服务不可用	服务负载过大	使用指数退避实现重试逻辑。减少索引请求频率。

Last updated on 2026-03-02