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

一、项目背景重构 RAG 底座、弃用 LangChain4j 后改用 Milvus 原生 SDK 自研 Starter 做向量入库。自建文档分片、Ollama 嵌入向量生成对接 Milvus 2.5.14 做向量持久化。过程中连续遇到三个经典致命报错必填字段缺失、多字段行数不统一、Metadata JSON 类型不匹配挨个排错、逐个落地解法整理成可直接复刻的生产级避坑实录。二、环境版本说明Milvus 版本2.5.14部署方式单机本地容器化客户端Milvus 原生 Java SDK向量维度1024适配 qwen3-embedding 模型集合字段结构id字符串主键text文本字符串metadataJSON 类型元数据vectorFloatVector 向量字段三、逐个踩坑 原报错 根因 最终解法坑一The field: id is not provided原报错plaintextParamException: The field: id is not provided根因Milvus 集合设置 id 为主键且非自增插入时必须手动传入 id 字段及数据缺一个字段直接拦截。解法业务层手动生成 UUID 作为主键构造同结构 List和其他字段列表一一对应传入。坑二Row count of fields must be equal原报错plaintextParamException: Row count of fields must be equal根因每个字段外层必须是 List且所有字段 List 元素个数必须一致向量字段是ListListFloat普通字段是ListString一不小心维度、元素数量对不齐就报错。解法单条写入统一规范所有字段都用Collections.singletonList()包成单元素列表保证每行数据行数严格统一。坑三Metadata JSON 类型不匹配依次踩过的错误类型传普通字符串{}→ 不认传普通 Map → 类型校验失败传 Hutool JSONObject → Milvus SDK 不识别第三方 JSON 对象原报错核心plaintextType 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 对象放入ListJsonObject再传入 Field完美通过类型校验。四、Milvus 插入唯一正确可复用代码模板固定四字段id /text/metadata /vector所有字段统一包成单元素 Listmetadata 使用 Gson JsonObjectjava运行// 1. 向量包装 ListFloat vecList new ArrayList(); for (float v : vectorArr) { vecList.add(v); } ListListFloat vectorData Collections.singletonList(vecList); // 2. 主键ID String milvusId UUID.randomUUID().toString(); ListString idData Collections.singletonList(milvusId); // 3. 文本内容 ListString textData Collections.singletonList(content); // 4. Metadata 必须用 Gson JsonObject Listcom.google.gson.JsonObject metaDataList new ArrayList(); com.google.gson.JsonObject jsonObj new com.google.gson.JsonObject(); metaDataList.add(jsonObj); // 组装字段 ListInsertParam.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);五、Attu 可视化入库验证代码执行无异常、日志打印 Milvus 入库成功 ID进入 Attu 连接对应集合可查到新增文档记录四条字段完整存储vector 向量、metadata 结构正常后续 RAG 向量相似度检索可正常召回分数匹配合理。六、避坑总结Milvus 主键字段若不自增必须手动传 id不能省略多字段插入所有字段 List 元素数量必须严格一致是最容易忽略的基础规则JSON 类型字段不要瞎试 Hutool、Fastjson、Map、字符串2.5.14 只认 Gson JsonObject统一封装固定插入模板后续业务直接复用不再重复踩相同坑尽量用原生 SDK 直白开发少用高层封装框架出问题看不到底层校验逻辑。七、后续规划路线把这套标准插入逻辑封装进自研laoxing-milvus-starter对外提供通用插入方法新增批量插入、按 MilvusId 删除、条件过滤检索通用工具方法统一规范集合初始化、字段定义、向量维度配置纳入 Starter 自动配置完善异常捕获封装友好业务异常不用上层感知 Milvus 原生报错。八、底稿收尾落款本文是《技术底稿》系列第 31 篇记录 Milvus 2.5.14 从字段缺失、行数不匹配到 Metadata JSON 类型适配三连坑完整排错过程给出可直接上线复用的标准插入代码模板全程实战落地无空泛理论可作为 Java 对接 Milvus 原生开发避坑参考范本。