使用Python SDK向GCP数据存储上传带元数据非结构化文档报错排查

错误根源 #

1. JSONL格式不符合Discovery Engine规范：你当前的JSONL使用了嵌套的content对象和驼峰式的structData字段，而Discovery Engine的custom schema要求用content_uri直接指定非结构化文件路径，且字段名需采用蛇形命名（如struct_data而非structData）。系统无法识别你指定的内容路径，因此判定文档无内容，触发CONTENT REQUIRED的校验错误。
2. 控制台上传错误：同样因JSONL格式不规范，导致系统无法解析元数据文件。

具体修复步骤 #

1. 修正metadata.jsonl格式 #

将原JSONL中的structData改为struct_data，并将嵌套的content对象替换为content_uri字段，示例如下：

{"id": "1", "struct_data": {"title": "Coldsmokesubmittal", "category": "212027"}, "content_uri": "gs://meta-data-testing/ColdSmokeSubmittal.pdf", "mimeType": "application/pdf"}
{"id": "2", "struct_data": {"title": "Defssubmittal", "category": "212027"}, "content_uri": "gs://meta-data-testing/DEFSSubmittal.pdf", "mimeType": "application/pdf"}
{"id": "3", "struct_data": {"title": "Cmu Submittal", "category": "222039"}, "content_uri": "gs://meta-data-testing/CMU_Submittal.pdf", "mimeType": "application/pdf"}
{"id": "4", "struct_data": {"title": "Concrete Mix Submittal", "category": "222039"}, "content_uri": "gs://meta-data-testing/Concrete_Mix_Submittal.pdf", "mimeType": "application/pdf"}

如果不需要嵌套的结构化元数据，也可以直接将元数据设为顶层字段，简化格式：

{"id": "1", "title": "Coldsmokesubmittal", "category": "212027", "content_uri": "gs://meta-data-testing/ColdSmokeSubmittal.pdf"}

2. 验证Discovery Engine服务账号权限 #

确保Discovery Engine的默认服务账号（格式为service-${PROJECT_NUMBER}@gcp-sa-discoveryengine.iam.gserviceaccount.com）拥有GCS Bucket的Storage Object Viewer角色，或直接授予storage.objects.get权限，使其能读取Bucket中的PDF文件。

3. 重新执行导入代码 #

保持原代码逻辑不变，使用修正后的metadata.jsonl文件再次运行导入请求，系统将正确关联元数据与PDF内容，满足CONTENT REQUIRED的配置要求。

4. 控制台上传修复 #

在GCP控制台导入时，选择「自定义元数据（JSONL）」选项，指定修正后的metadata.jsonl的GCS URI，即可避免格式错误。

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