Azure Cognitive Search文档上传报错：search.documentFields不允许空值

核心问题 #

你遇到的报错有两个关键原因：

• 缺少必填的id字段：你的索引定义中id是主键（key=True），属于不可为空的必填字段，但上传的文档里完全没提供这个字段，触发了空值校验错误。
• embedding格式不匹配：索引要求embedding是Collection(Single)类型（即浮点数数组），但你上传的是字符串形式的数组，不是实际的数值数组，这也会导致字段类型校验失败（本质上相当于该字段为空或类型错误）。

修正方案 #

1. 为每个文档添加id字段 #

给每个待上传的文档添加唯一的字符串类型id，示例：

[{"id":"doc1","text":"blah blah","embedding":[-0.01130323, 0.00934206, -0.01263496, ..., -0.02174513, -0.00830184, -0.0122043]}]

2. 转换embedding为浮点数数组 #

如果你的embedding是从numpy数组导出的字符串格式，需要先把它转换成Python列表（浮点数数组），示例代码：

import re

# 示例embedding字符串
embedding_str = "[-0.01130323  0.00934206 -0.01263496 ... -0.02174513 -0.00830184\n -0.0122043 ]"
# 提取所有数值并转换为浮点数
embedding_list = [float(num) for num in re.findall(r'-?\d+\.\d+', embedding_str)]

修正后的完整上传示例 #

# 处理后的文档列表
documents = [
    {
        "id": "doc1",
        "text": "blah blah",
        "embedding": [-0.01130323, 0.00934206, -0.01263496, -0.02174513, -0.00830184, -0.0122043]
    }
]

# 上传代码不变
search_client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)
result = search_client.upload_documents(documents)
print(f"Uploaded {len(documents)} documents")

额外验证点 #

• 确保embedding的维度和索引定义的vector_search_dimensions=1536完全一致，否则也会触发类型/维度不匹配的错误。
• 检查所有必填字段（比如这里的id）都已正确赋值，没有遗漏。

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