向Azure Cognitive Search Index上传数据时遇RequestEntityTooLargeError的解决方法

错误原因 #

使用search_client.upload_documents()批量上传含嵌入向量的文档时，请求体总大小超出Azure Cognitive Search的批量索引请求上限，触发RequestEntityTooLargeError。

官方限制规则 #

Azure Cognitive Search对批量索引请求有明确限制：

• 单批请求的最大大小为16MB（与批次内文档数量无关）
• 单个文档的大小上限同样为16MB，若单文档超出该值，拆分批次无法解决问题，需单独处理文档

解决方法 #

1. 拆分批量请求 #

将大文档列表拆分为多个小批次，确保每批请求总大小控制在16MB以内（建议预留1MB余量避免边界问题）。以下是按字节大小拆分的示例代码：

import json
from azure.search.documents import SearchClient

def split_document_batches(items, max_batch_mb=15):
    max_batch_bytes = max_batch_mb * 1024 * 1024
    batches = []
    current_batch = []
    current_size = 0

    for item in items:
        # 估算单个文档序列化后的字节大小
        item_bytes = len(json.dumps(item).encode('utf-8'))
        # 单个文档超上限时抛出异常
        if item_bytes > max_batch_bytes:
            raise ValueError(f"单文档大小({item_bytes/1024/1024:.2f}MB)超出16MB上限")
        # 当前批次加入新文档后超限时，保存当前批次并新建批次
        if current_size + item_bytes > max_batch_bytes:
            batches.append(current_batch)
            current_batch = [item]
            current_size = item_bytes
        else:
            current_batch.append(item)
            current_size += item_bytes
    # 加入最后一批未完成的文档
    if current_batch:
        batches.append(current_batch)
    return batches

# 调用示例
search_client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)
document_batches = split_document_batches(items)
for batch in document_batches:
    indexing_result = search_client.upload_documents(batch)
    # 检查索引结果，处理失败项
    for res in indexing_result:
        if not res.succeeded:
            print(f"文档{res.key}索引失败: {res.error_message}")

2. 处理超大单个文档 #

若存在单个文档大小超过16MB的情况（如包含超长文本），需先对文档进行处理：

• 对大文本进行截断、压缩，或拆分为多个子文档后分别上传
• 若嵌入向量本身过大（非常规情况），需确认嵌入模型的输出维度是否符合要求

官方参考路径 #

该限制属于Azure Cognitive Search的服务配额，可在Azure门户的搜索服务概览页面查看「配额」板块，或在官方文档中搜索「Azure Cognitive Search service limits」获取完整的服务限制说明。

内容的提问来源于stack exchange，提问作者Vkdhiman