当前位置：首页 > news >正文

【技术底稿 31】Milvus 2.5.14 实战避坑实录：字段缺失、行数不匹配、Metadata JSON 类型三连坑完整解法

news 2026/5/10 18:51:51

一、项目背景

重构 RAG 底座、弃用 LangChain4j 后，改用 Milvus 原生 SDK + 自研 Starter 做向量入库。自建文档分片、Ollama 嵌入向量生成，对接 Milvus 2.5.14 做向量持久化。过程中连续遇到三个经典致命报错：必填字段缺失、多字段行数不统一、Metadata JSON 类型不匹配，挨个排错、逐个落地解法，整理成可直接复刻的生产级避坑实录。

二、环境版本说明

Milvus 版本：2.5.14

部署方式：单机本地容器化

客户端：Milvus 原生 Java SDK

向量维度：1024（适配 qwen3-embedding 模型）

集合字段结构：

id：字符串主键
text：文本字符串
metadata：JSON 类型元数据
vector：FloatVector 向量字段

三、逐个踩坑 + 原报错 + 根因 + 最终解法

坑一：The field: id is not provided

原报错

plaintext

ParamException: The field: id is not provided

根因Milvus 集合设置 id 为主键且非自增，插入时必须手动传入 id 字段及数据，缺一个字段直接拦截。解法业务层手动生成 UUID 作为主键，构造同结构 List，和其他字段列表一一对应传入。

坑二：Row count of fields must be equal

原报错

plaintext

ParamException: Row count of fields must be equal

根因每个字段外层必须是 List，且所有字段 List 元素个数必须一致；向量字段是List<List<Float>>，普通字段是List<String>，一不小心维度、元素数量对不齐就报错。解法单条写入统一规范：所有字段都用Collections.singletonList()包成单元素列表，保证每行数据行数严格统一。

坑三：Metadata JSON 类型不匹配

依次踩过的错误类型

传普通字符串"{}"→ 不认
传普通 Map → 类型校验失败
传 Hutool JSONObject → Milvus SDK 不识别第三方 JSON 对象

原报错核心

plaintext

Type mismatch for field 'metadata': JSON field value type must be JSON, current type: xxx

根因Milvus 2.5.14 Java SDK 的 JSON 字段，只认 com.google.gson.JsonObject，其他任何 String、Map、HutoolJSON 全都过不了源码类型校验。

最终唯一解法统一使用new com.google.gson.JsonObject()构造空 JSON 对象，放入List<JsonObject>再传入 Field，完美通过类型校验。

四、Milvus 插入唯一正确可复用代码模板

固定四字段：id /text/metadata /vector所有字段统一包成单元素 List，metadata 使用 Gson JsonObject

java

运行

// 1. 向量包装 List<Float> vecList = new ArrayList<>(); for (float v : vectorArr) { vecList.add(v); } List<List<Float>> vectorData = Collections.singletonList(vecList); // 2. 主键ID String milvusId = UUID.randomUUID().toString(); List<String> idData = Collections.singletonList(milvusId); // 3. 文本内容 List<String> textData = Collections.singletonList(content); // 4. Metadata 必须用 Gson JsonObject List<com.google.gson.JsonObject> metaDataList = new ArrayList<>(); com.google.gson.JsonObject jsonObj = new com.google.gson.JsonObject(); metaDataList.add(jsonObj); // 组装字段 List<InsertParam.Field> fields = new ArrayList<>(); fields.add(new InsertParam.Field("id", idData)); fields.add(new InsertParam.Field("text", textData)); fields.add(new InsertParam.Field("metadata", metaDataList)); fields.add(new InsertParam.Field("vector", vectorData)); // 执行插入 InsertParam insertParam = InsertParam.newBuilder() .withCollectionName(collectionName) .withFields(fields) .build(); InsertResult result = milvusClient.insert(insertParam);