【技术底稿 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：文本字符串
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);

五、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 原生开发避坑参考范本。