1. RAG 项目里为什么偏偏是 Milvus先说结论做 RAG 知识库向量数据库是整个系统的“记忆中枢”。前面文档解析、切块做得再好embedding 模型选得再强最后检索阶段拉闸整个问答体验一样稀碎。我见过太多项目把精力全花在调 prompt 上结果向量库里存的都是一坨没法稳定召回的数据应用上线后用户随便问一句就答非所问。所以这个系列到专题二我决定先把 Milvus 单独拎出来讲透。这一篇不是教你背 Milvus 的 API 文档而是带着你从零搭一套“Spring AI Milvus”的完整 RAG 服务。我默认你已经会用 Spring Boot 写接口也大概知道 RAG 是“检索增强生成”但对向量库可能还停留在概念层面。看完这篇你能回答这几个问题Milvus 在这条链路里到底干了什么、它和 ChromaDB、PGVector、Qdrant 有什么区别、Docker 怎么装、Spring AI 怎么接、检索出来的东西怎么和 ChatClient 串成最终答案以及生产环境最容易踩的坑有哪些。1.1 先看一条完整内容链路一个典型的 RAG 问答系统跑完整流程是这样的拿一批文档PDF、Word、Markdown 都行先做解析和清洗然后按固定长度切块每块文本丢给 embedding 模型转成向量向量和原文一起写入向量数据库。用户提问时把问题也转成向量去向量库里做相似度检索召回最相关的几个片段最后把这些片段和问题拼成 prompt交给大模型生成回答。这个链路里向量数据库服务两个核心动作写入和检索。写入要快不能因为文档一多就写入超时检索要准语义相关的片段必须排到前面同时还要支持按照文档来源、时间、业务类型等 metadata 做过滤。Milvus 恰恰在这三点上做得比较均衡这也是我在 Java 技术栈里优先选它的原因。1.2 向量库选型ChromaDB、PGVector、Qdrant、Milvus 怎么选很多人第一次接触向量数据库上来就问“哪个最火”我不太喜欢这种问法。选型先看场景再看团队维护成本。我整理了一张对比表是最近给一个知识库项目做技术调研时用过的直接放出来方案适合场景部署方式检索能力维护成本ChromaDB个人项目、原型快速验证单机进程内基本向量搜索极低PGVector已有 PostgreSQL数据量中等作为 PG 插件基本向量搜索 SQL 过滤低Qdrant中小规模生产、Rust 技术栈Docker / K8s向量 payload 过滤中Milvus 2.x生产级知识库、千万级向量、高并发Docker / K8s / 云服务向量 标量过滤 混合检索中到高如果你是个人博客问答、几百个文档的小玩具ChromaDB 装在本地就行别折腾。如果公司已经重度使用 PostgreSQL数据量又不到百万级PGVector 8 核机器也能扛。但一旦你的目标是做相对正式的知识库产品要考虑多人并发、定期全量更新、按业务线做隔离Milvus 的收益就出来了它把向量索引和标量过滤做成了原生能力不需要你手动拼 SQL 去降级检索质量。Milvus 明显的短板是部署比 ChromaDB 重。单机 standalone 至少要依赖 etcd 和 MinIO你可能觉得“不就存个向量吗怎么还要对象存储”。这个后面第二章会解释先记住一个结论这个重是有价值的换来了数据持久化和索引扩展能力。1.3 Milvus 架构简读Milvus 2.x 的架构拆开看核心角色有这么几个access layer 负责接收请求coordinator 管元数据和调度worker node 干实际的索引和查询的活。单机部署时这些角色封装在一起对外只暴露一个 19530 端口内部走 etcd 存元数据、MinIO 存日志和索引文件。理解这个架构对写代码没直接影响但对排查问题帮助很大。比如你发现 Milvus 容器一直重启大概率是 etcd 连不上查询性能骤降可能不是索引问题而是 MinIO 磁盘满了。Spring AI 接入时你只需要面向 19530 端口写 gRPC 连接剩下的内部组件不用关心但心里要有这张拓扑图出问题时候能猜到是哪层的事。2. 先把 Milvus 跑起来Docker 部署与健康检查2.1 Docker Compose 一键起 standaloneMilvus 官方现在推荐用 Docker Compose 部署 standalone 模式。我在本地和测试环境都是这么干的一条命令拉起整套依赖不污染宿主机。先准备一个docker-compose.ymlversion: 3.5 services: etcd: container_name: milvus-etcd image: quay.io/coreos/etcd:v3.5.14 environment: - ETCD_AUTO_COMPACTION_MODErevision - ETCD_AUTO_COMPACTION_RETENTION1000 - ETCD_QUOTA_BACKEND_BYTES4294967296 - ETCD_SNAPSHOT_COUNT50000 volumes: - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd command: etcd -advertise-client-urlshttp://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd healthcheck: test: [CMD, etcdctl, endpoint, health] interval: 30s timeout: 20s retries: 3 minio: container_name: milvus-minio image: minio/minio:RELEASE.2023-03-20T20-16-18Z environment: MINIO_ACCESS_KEY: minioadmin MINIO_SECRET_KEY: minioadmin ports: - 9001:9001 - 9000:9000 volumes: - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data command: minio server /minio_data --console-address :9001 healthcheck: test: [CMD, curl, -f, http://localhost:9000/minio/health/live] interval: 30s timeout: 20s retries: 3 standalone: container_name: milvus-standalone image: milvusdb/milvus:v2.4.13 command: [milvus, run, standalone] security_opt: - seccomp:unconfined environment: ETCD_ENDPOINTS: etcd:2379 MINIO_ADDRESS: minio:9000 volumes: - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus healthcheck: test: [CMD, curl, -f, http://localhost:9091/healthz] interval: 30s start_period: 90s timeout: 20s retries: 3 ports: - 19530:19530 - 9091:9091 depends_on: - etcd - minio这个文件里有几个值得注意的地方。etcd 的ETCD_QUOTA_BACKEND_BYTES我设了 4GB这是 Milvus 元数据能增长的上限如果你的 collection 数量非常多可以调大但别随随便便弄到几十 GBetcd 本身不适合存大数据量。MinIO 的账号密码默认minioadmin本地测试无所谓生产环境必须改成强密码并且建议用环境变量注入不要写死在 compose 里。Milvus 2.4 这个版本是目前我用下来比较稳的也是和 Spring AI 集成兼容性最好的一个主线版本。2.5 之后的结构化过滤和 full text search 更强但 API 变动也大等社区把坑填完再上不迟。2.2 起完容器后先做这几件事执行docker compose up -d之后不要急着去写代码先确认三个状态。第一三个容器都健康。看日志用docker compose ps如果 standalone 容器卡在 unhealthy多半是 etcd 或 MinIO 没起来先修依赖再重试。第二确认 19530 端口通了。我用一个简单的 Java 测试类验证 gRPC 连接import io.milvus.client.MilvusServiceClient; import io.milvus.param.ConnectParam; import io.milvus.param.RpcStatus; public class MilvusConnectionCheck { public static void main(String[] args) { MilvusServiceClient client new MilvusServiceClient( ConnectParam.newBuilder() .withUri(http://localhost:19530) .build()); RpcStatus status client.getVersion(); if (status.getStatus() RpcStatus.Success.getStatus()) { System.out.println(连接成功 new String(status.getMessage())); } else { System.err.println(连接失败 status.getMessage()); } client.close(); } }第三确认 9091 端口的健康检查接口能返回OK。curl http://localhost:9091/healthz如果返回的不是 OK说明 Milvus 内部组件还没就绪等一会儿再试。2.3 CentOS 7 / 资源紧张机器上的注意事项热词里有人搜“centos7安装milvus”我多说两句。CentOS 7 默认内核和 Docker 版本都比较老装 Milvus 容易遇到两个坑一是 Docker 版本低于 20compose 语法解析失败先升级 Docker二是内存不足导致 etcd 频繁挂掉Milvus 单机版本建议至少 8GB 内存4GB 机器能跑但非常吃力我实测在 4GB 机器上启动一个 collection 就要七八分钟。如果机器内存紧张可以给 compose 文件加上资源限制比如deploy: resources: limits: memory: 4G这样至少不会把宿主机拖死。另外磁盘记得预留 20GB 以上MinIO 默认会把索引和日志文件写进 volume小磁盘很快会被撑满。3. Spring AI 集成依赖、配置与仓库抽象3.1 引入 spring-ai-milvus-store 依赖Spring AI 官方把向量数据库的集成拆成了很多独立模块Milvus 对应的是spring-ai-milvus-store。要注意Spring AI 1.0.0 之前还在迭代artifact 版本经常带M1、M6这类里程碑后缀所以我建议用 BOM 统一管理版本避免手动写错。dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0-M6/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-milvus-store/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai/artifactId /dependency /dependencies顺带解释一下为什么用 BOMSpring AI 的spring-ai-milvus-store会传递依赖 Milvus 的 Java SDK如果你手动引入 SDK 版本和模块内置版本不一致很容易出现MethodNotFound这类诡异报错。BOM 能把所有组件锁在同一批版本上这种问题基本就避免了。3.2 YAML 配置与 Client 构建Spring AI 的 Milvus 集成没有提供完全自动的spring.autoconfigure配置需要你手动声明MilvusServiceClient和VectorStoreBean。这一开始我也觉得麻烦但后来发现反而更透明连接参数和 collection 行为一目了然。milvus: uri: http://localhost:19530 token: database-name: default collection-name: knowledge_base embedding-dimension: 1024 index-type: HNSW metric-type: COSINE consistency-level: StrongJava 配置类如下Configuration public class MilvusConfig { Bean public MilvusServiceClient milvusClient(Value(${milvus.uri}) String uri, Value(${milvus.token:}) String token) { ConnectParam.Builder builder ConnectParam.newBuilder() .withUri(uri); if (StringUtils.hasText(token)) { builder.withToken(token); } return new MilvusServiceClient(builder.build()); } Bean public VectorStore vectorStore(MilvusServiceClient milvusClient, EmbeddingModel embeddingModel, Value(${milvus.collection-name}) String collectionName, Value(${milvus.embedding-dimension}) int dimension, Value(${milvus.consistency-level}) String consistency) { MilvusVectorStoreConfig config MilvusVectorStoreConfig.builder() .withCollectionName(collectionName) .withEmbeddingDimension(dimension) .withConsistencyLevel(consistency) .build(); return new MilvusVectorStore(milvusClient, config, embeddingModel); } }这里有个关键点collection-name和embedding-dimension是强绑定的。embedding 模型一旦换掉向量维度跟着变但 Milvus 里的 collection schema 不会自动重建必须手动删除旧 collection 或者换一个 collection 名。我见过有人把 OpenAI 的 1536 维数据写完以后切到 768 维的本地模型检索结果一直为空查了半天才发现是维度不一致导致的数据类型检查失败。3.3 VectorStore 抽象换向量库不用改业务代码Spring AI 把向量库操作收敛成了VectorStore接口核心方法就几个add、similaritySearch、delete。业务层拿到的是VectorStore而不是某个具体实现类。这意味着你把 Milvus 换成 PGVector、ChromaDB、Qdrant业务代码几乎不用动只要换掉 Bean 实现就行。我一开始也觉得这个抽象有点过度设计直到有一次某篇文章推荐了另一个向量库我为了评估性能把整个存储层切过去跑 benchmark改的只是配置类和依赖三天就完成了对比测试。如果你后续有“向量库替换”的潜在需求这个抽象能省下大量返工成本。3.4 Embedding 模型选型接 OpenAI 还是 Qwen 还是本地 BGESpring AI 的EmbeddingModel是可以替换的这也是整个链路里最影响最终效果的一环。选型上我分三种情况说。接 OpenAI 的text-embedding-3-small最简单效果稳1536 维但调用要花钱而且数据要出网隐私敏感场景直接排除。接通义的Qwen embedding也就是热词里那个qwen embedding在中文场景下效果不错1024 维能走 Spring AI Alibaba 的 dashscope 通道适合国内业务数据合规的场景。本地部署 BGE 系列模型比如bge-m31024 维用 Ollama 或者 Xinference 起一个 embedding 服务延迟低、免费、数据不出内网但机器需要额外显存模型效果上中文略弱于商业 API。我的建议是项目初期先用商业 API 把链路跑通验证业务效果等到文档量大了、调用成本上来了再切本地模型。维度变化时记得重建 collection别偷懒。4. 从文档到问答一个完整 RAG 流程的 Java 实现4.1 文档加载与切块Spring AI 提供了DocumentReader家族常见的有PagePdfDocumentReader、TikaDocumentReader、JsonReader。PDF 解析我用PagePdfDocumentReader比较多它按页返回Document每页自带页码 metadata方便后面统计和溯源。var reader new PagePdfDocumentReader(classpath:/docs/spring-ai-guide.pdf); ListDocument documents reader.get();切块用的是TokenTextSplitter。它的底层是按 token 数切而不是字符数这对中文更友好。基本用法var splitter new TokenTextSplitter(); ListDocument chunks splitter.apply(documents);默认参数下切出来的块可能偏大偏小我一般在项目里自定义参数。下面是调参后的示例每块约 500 token重叠 80 tokenvar splitter TokenTextSplitter.builder() .withChunkSize(500) .withChunkOverlap(80) .build(); ListDocument chunks splitter.apply(documents);为什么重叠不能省因为切块时如果正好把一个完整语义段落砍成两半后半个片段单独召回时缺少前文信息大模型拿到手里也读不明白。重叠 60120 token 能在语义连续性和检索精度之间取个平衡。4.2 写入 Milvusid 幂等、metadata 字段切完块以后调用VectorStore.add()写入。我建议在Document里预留好id和自定义 metadata别用默认生成的随机 id否则后续数据更新时会很痛苦。String docId doc_spring_ai_guide; for (int i 0; i chunks.size(); i) { Document chunk chunks.get(i); chunk.setId(docId _ i); chunk.getMetadata().put(source, spring-ai-guide.pdf); chunk.getMetadata().put(page, chunk.getMetadata().get(page)); chunk.getMetadata().put(docId, docId); } vectorStore.add(chunks);幂等性怎么保证如果同一份文档重新导入你需要先删掉旧的同 docId 的向量再写入新的。Milvus 的 delete 支持表达式过滤可以按docId删vectorStore.delete(List.of(docId)); // 等价于按 id 删除但只删精确 id // 更推荐的做法遍历 docId 前缀再删除这里有个容易踩的坑Spring AI 的delete(ListString)删除的是 Document 的 id也就是我上面拼的doc_spring_ai_guide_0而不是 metadata 里的 docId。如果你希望“按业务文档维度批量删除”要靠 metadata 过滤实现。Spring AI 1.0 之后在VectorStore接口增加了delete(SearchRequest)的重载但不同版本兼容性有差异我建议在没有把握时直接调 Milvus SDK 的 delete 表达式完成批量清理。4.3 向量检索与 metadata 过滤写入之后最关键的就是检索。Spring AI 的检索入口ListDocument hits vectorStore.similaritySearch( SearchRequest.builder() .query(什么是 Spring AI 的 RAG 流程) .topK(5) .build() );这背后做的事情是把问题文本转成向量去 Milvus 里按 COSINE 相似度召回 topK 个片段。如果你要限制只搜某一份文档或者只看某个页面可以加过滤条件SearchRequest.builder() .query(什么是 RAG) .topK(5) .filterExpression(docId doc_spring_ai_guide) .build();filterExpression 的语法不是 SQL是 Milvus 的布尔表达式。等号要用字符串用单引号多个条件用。第一次写的时候容易手滑写成或者漏了引号然后报Expr evaluate error报错信息还贼隐晦。4.4 混合检索与重排纯向量检索在语义匹配上很强但在关键词精确匹配上有时反而拉胯。比如用户搜“Spring AI 1.0 发布”如果文档里写的是“Spring AI 1.0.0 版本发布”语义相近但关键词不完全一致向量检索通常也能召回。但搜“错误码 404”这种强标识性内容时向量检索可能把语义相近但完全无关的文档翻出来。这时候就需要混合检索向量召回 关键词召回再合并重排。Milvus 2.4 之后支持了 full text search可以在同一个集合里做 BM25 检索然后和向量检索做 RRFReciprocal Rank Fusion合并。我用 Java SDK 直接调的话大致是两层先做向量search再做 full textsearch最后在 Java 侧合并。Spring AI 1.0 的VectorStore接口对混合检索的原生支持还不够完整所以我的做法是在 Service 层手动实现。核心代码结构如下public ListDocument hybridSearch(String query, String collectionName, int topK) { // 第一步向量检索 ListDocument vectorHits vectorStore.similaritySearch( SearchRequest.builder().query(query).topK(topK).build()); // 第二步关键词检索走 Milvus SDK ListDocument bm25Hits fullTextSearch(query, collectionName, topK); // 第三步RRF 合并 return RrfFusion.merge(vectorHits, bm25Hits, topK); }RRF 的核心逻辑是给每个候选分配一个1/(k rank)的分数k 一般取 60。我实际测下来RRF 合并比简单拼接两个结果列表稳定得多简单拼接会让重复命中的片段被排两次导致最终返回的上下文重叠度太高浪费大模型上下文窗口。重排列re-rank又是另一层。如果你有资源跑一个交叉编码器模型或者调外部 rerank API可以在混合检索之后再精排一次。我目前在生产环境没有接 rerank因为延迟会多出来 200500 毫秒对内部知识库问答来说收益不大。但如果你的场景是“从 100 个候选里精挑 5 个”rerank 的价值就非常明显了。4.5 交给 ChatClient 生成回答检索回来的片段最终要拼进 prompt。Spring AI 1.0 里可以这么组织String context hits.stream() .map(Document::getText) .collect(Collectors.joining(\n\n---\n\n)); PromptTemplate promptTemplate new PromptTemplate( 你是企业知识库助手请基于以下资料回答用户问题。 如果资料中没有相关信息请直接说明“未找到相关内容”不要编造。 资料 {context} 用户问题{question} 回答 ); Message message promptTemplate.createMessage(Map.of(context, context, question, question)); var response chatClient.call(new Prompt(message));这一步有个容易忽视的细节召回片段拼接时最好在每段之间加上分隔符并在 prompt 里明确告诉模型“资料用分隔符隔开”。如果不加分隔符模型可能把两段不相干的内容当成一个连续上下文回答出现逻辑混乱。还有一个经验topK 不是越大越好。我之前调到 8结果大模型回答里混入了两个不相关片段答案反而比 topK3 时更差。后来固定 topK4并在 prompt 里要求“如果某条资料与问题明显无关忽略它”效果稳定很多。这个值的取舍一定要拿评测集去试别拍脑袋。5. 影响效果的几个关键参数5.1 Collection 与索引参数Milvus 的 collection 建好后索引类型、metric type、索引参数都不能随意改了。所以建 collection 之前最好先想清楚。Spring AI 的MilvusVectorStoreConfig默认建的索引是 HNSW。HNSW 有两个关键参数M控制每个节点的连接数efConstruction控制建索引时的搜索范围。M一般设 16 或 32。M越大召回精度越高但内存和检索耗时都会增加。efConstruction我习惯设 200构建慢一点没关系查询阶段的召回率提升明显。如果你对延迟更敏感可以降到 64。metric type 我推荐 COSINE。L2 距离在向量没有归一化时可能受向量模长干扰内积IP在高维稀疏向量里有一些特效但对常规 dense embeddingCOSINE 是“不怎么会错”的选择。5.2 切分参数对召回率的影响切分参数是 RAG 调优里性价比最高的地方。chunk size 太小比如 200 token召回片段很多但每个片段信息量不足大模型需要拼凑多个片段才能回答容易漏信息。chunk size 太大比如 1000 token单片段信息是够了但语义可能混杂检索时精确匹配率下降。我按文档类型给过一套经验值技术文档 / FAQchunk 400600 tokenoverlap 80100长文本 / 书籍chunk 600800 tokenoverlap 120150对话记录 / 工单chunk 300400 tokenoverlap 5080这是一个起手配置不是银弹。最稳的方法还是抽一批真实问题做评测集用召回率指标来定参数。热词里有“rag文档加载解析详细全流程”说明大家确实在这块踩了很多坑我这里先给一个能跑的经验起步值。5.3 检索 topK 与 score 阈值score 阈值是个很玄学的东西。Milvus 返回的相似度分数在不同 metric 下含义不同COSINE 在 01 之间严格说是 -11但 embedding 模型输出通常非负。如果你设scoreThreshold0.6可能把一些语义相关的长尾片段过滤掉也可能放进来噪音。我的建议是开发阶段不要设 score 阈值先看 topK 召回的内容是否合理确认之后再根据实际分数分布定阈值。如果某个查询的平均相似度是 0.75把阈值设成 0.7 会安全一些。最忌讳的是从别处抄一个“0.5 阈值”直接上线不同 embedding 模型的分数分布差异巨大照搬必踩坑。5.4 数据更新与一致性知识库不是只写一次就完事。文档更新时我习惯先按业务 docId 批量删除旧向量再重新加载新文档写入。Milvus 默认的一致性级别是 Bounded也就是允许一小段时间内的数据滞后对知识库场景完全够用。如果你用的是 Strong 级别的强一致写入完立刻查询能保证读到最新数据但吞吐会受一点影响。Spring AI 的配置里可以用withConsistencyLevel设置。内部知识库如果更新不频繁用 Strong 更省心高频写入的日志分析类场景Bounded 更合适。6. 排查实录与避坑清单6.1 容器起不来还疯狂刷日志我遇到最多的问题是 standalone 容器一直 unhealthy。第一反应去看完整日志docker compose logs standalone如果看到fail to init meta client字样的十有八九是 etcd 没就绪。此时不是重启 standalone 就行而是先看 etcd 的健康状态。还有一种情况之前在 CentOS 7 上遇到的Docker 默认存储驱动是overlay2但老内核支持不好MinIO 写入时直接把磁盘写满Milvus 报no space left on device。解决方法是清理 Docker 无用的镜像和 volume或者给 MinIO 单独挂一块大磁盘。6.2 连接失败 / 鉴权问题连接http://localhost:19530失败先确认端口有没有被防火墙拦截。CentOS 7 上我踩过无数次firewalld的坑19530端口没放行Java 客户端一直超时但本机 curl 又正常。开端口命令firewall-cmd --zonepublic --add-port19530/tcp --permanent firewall-cmd --reload鉴权问题多发生在生产环境。如果你配置了 tokenMilvus 客户端连接时必须要带 token否则报authentication failed。Spring AI 的配置里可以给MilvusServiceClient的ConnectParam设置.withToken(token)。这里有个我没想通的坑Milvus 的 token 是username:password格式而不是普通密钥字符串如果你直接填一个 UUID 格式的 token认证一样报错。构造方式可以去查一下 root 用户的 token 规则。6.3 明明有数据却搜不到“有数据但搜不到”这种情况第一反应查 consistency level。我刚从 Bounded 切到 Strong 时遇到过写入成功但立刻查询空结果。因为 Milvus 的查询默认走副本/分段的数据可见性写入到可读之间有小窗口Strong 能规避这个问题。第二个原因是没有指定 partition 或者过滤条件写错。如果你的代码里加了filterExpression先把它去掉再试一次如果去掉就有结果问题在表达式语法或是指错了 metadata 字段名需要对比写入时的 metadata key 和过滤表达式里的 key 是否完全一致。Spring AI 写入 metadata 时有些类型会被转换比如 Integer 可能变成 Long导致page 1匹配不上要写成page 1L。第三个原因是 collection 的 schema 里没有定义能用于过滤的字段。Spring AI 的MilvusVectorStore默认会把 metadata 存成 dynamic field支持过滤但如果你手动建过 collection 且没有开启 dynamic field过滤就会静默失败。日志里看不到任何报错只有结果为空。6.4 常见错误速查表现象可能原因处理方式Connection refusedMilvus 端口未开放 / 容器未启动检查容器状态、防火墙Collection not foundcollection 名拼错或未自动创建确认配置里的 collection-namedimension mismatch换模型后维度变了删掉旧 collection 重建Expr evaluate errorfilterExpression 语法错误检查、单引号、cast检索结果总是第一页重复没有正确存储或恢复 Document id设置稳定的业务 id大批量写入后查询变慢索引参数不够 / 内存不足调 HNSW 参数或扩容disk fullMinIO 数据过多清理 volume / 扩容磁盘6.5 推荐一个调试利器 AttuAttu 是 Milvus 官方出的 Web 管理界面Docker 一键起。调试的时候我经常用它直接看 collection 里到低存了什么、metadata 长什么样、检索结果分数是多少省去了写各种临时代码的麻烦。docker run -p 8000:3000 -e MILVUS_URLhttp://host.docker.internal:19530 zilliz/attu:latest然后浏览器打开http://localhost:8000连上 Milvus 就能看到所有 collection。排查“明明有数据却搜不到”这类问题时Attu 里直接跑一次查询能看到原始向量和分数的分布比在代码里猜测快得多。最后再分享一点自己的体会Milvus 给我的整体感觉是学习曲线比 ChromaDB 高但换来的确定性和扩展性对得起这份投入。尤其是当你手里的文档从几百页涨到几十万页、查询并发从 1 个涨到 100 个的时候ChromaDB 会先崩PGVector 会先慢Milvus 可能还在稳定输出。当然这并不意味着每个项目都必须上 Milvus。如果只是个人博客和几百个文档别折腾ChromaDB 就能满足如果你的目标是认真做知识库产品、要支撑团队协作和企业级并发那把 Milvus 作为核心组件是很值的一笔投资。另外再补一个经验RAG 系统的瓶颈从来不是单点组件的性能而是“文档处理质量 切片策略 embedding 模型 检索策略”这套组合拳。Milvus 只是其中一环但也是最核心的一环。把这一环打牢后面换模型、换 prompt、换应用层框架都不会伤筋动骨。下一篇专题我打算把文档加载、清洗、切分的完整流程单独展开那个环节的细节经常决定知识库最终能不能用建议先把 Milvus 这一篇里的代码跑通再往下走。
1. RAG 项目里为什么偏偏是 Milvus先说结论做 RAG 知识库向量数据库是整个系统的“记忆中枢”。前面文档解析、切块做得再好embedding 模型选得再强最后检索阶段拉闸整个问答体验一样稀碎。我见过太多项目把精力全花在调 prompt 上结果向量库里存的都是一坨没法稳定召回的数据应用上线后用户随便问一句就答非所问。所以这个系列到专题二我决定先把 Milvus 单独拎出来讲透。这一篇不是教你背 Milvus 的 API 文档而是带着你从零搭一套“Spring AI Milvus”的完整 RAG 服务。我默认你已经会用 Spring Boot 写接口也大概知道 RAG 是“检索增强生成”但对向量库可能还停留在概念层面。看完这篇你能回答这几个问题Milvus 在这条链路里到底干了什么、它和 ChromaDB、PGVector、Qdrant 有什么区别、Docker 怎么装、Spring AI 怎么接、检索出来的东西怎么和 ChatClient 串成最终答案以及生产环境最容易踩的坑有哪些。1.1 先看一条完整内容链路一个典型的 RAG 问答系统跑完整流程是这样的拿一批文档PDF、Word、Markdown 都行先做解析和清洗然后按固定长度切块每块文本丢给 embedding 模型转成向量向量和原文一起写入向量数据库。用户提问时把问题也转成向量去向量库里做相似度检索召回最相关的几个片段最后把这些片段和问题拼成 prompt交给大模型生成回答。这个链路里向量数据库服务两个核心动作写入和检索。写入要快不能因为文档一多就写入超时检索要准语义相关的片段必须排到前面同时还要支持按照文档来源、时间、业务类型等 metadata 做过滤。Milvus 恰恰在这三点上做得比较均衡这也是我在 Java 技术栈里优先选它的原因。1.2 向量库选型ChromaDB、PGVector、Qdrant、Milvus 怎么选很多人第一次接触向量数据库上来就问“哪个最火”我不太喜欢这种问法。选型先看场景再看团队维护成本。我整理了一张对比表是最近给一个知识库项目做技术调研时用过的直接放出来方案适合场景部署方式检索能力维护成本ChromaDB个人项目、原型快速验证单机进程内基本向量搜索极低PGVector已有 PostgreSQL数据量中等作为 PG 插件基本向量搜索 SQL 过滤低Qdrant中小规模生产、Rust 技术栈Docker / K8s向量 payload 过滤中Milvus 2.x生产级知识库、千万级向量、高并发Docker / K8s / 云服务向量 标量过滤 混合检索中到高如果你是个人博客问答、几百个文档的小玩具ChromaDB 装在本地就行别折腾。如果公司已经重度使用 PostgreSQL数据量又不到百万级PGVector 8 核机器也能扛。但一旦你的目标是做相对正式的知识库产品要考虑多人并发、定期全量更新、按业务线做隔离Milvus 的收益就出来了它把向量索引和标量过滤做成了原生能力不需要你手动拼 SQL 去降级检索质量。Milvus 明显的短板是部署比 ChromaDB 重。单机 standalone 至少要依赖 etcd 和 MinIO你可能觉得“不就存个向量吗怎么还要对象存储”。这个后面第二章会解释先记住一个结论这个重是有价值的换来了数据持久化和索引扩展能力。1.3 Milvus 架构简读Milvus 2.x 的架构拆开看核心角色有这么几个access layer 负责接收请求coordinator 管元数据和调度worker node 干实际的索引和查询的活。单机部署时这些角色封装在一起对外只暴露一个 19530 端口内部走 etcd 存元数据、MinIO 存日志和索引文件。理解这个架构对写代码没直接影响但对排查问题帮助很大。比如你发现 Milvus 容器一直重启大概率是 etcd 连不上查询性能骤降可能不是索引问题而是 MinIO 磁盘满了。Spring AI 接入时你只需要面向 19530 端口写 gRPC 连接剩下的内部组件不用关心但心里要有这张拓扑图出问题时候能猜到是哪层的事。2. 先把 Milvus 跑起来Docker 部署与健康检查2.1 Docker Compose 一键起 standaloneMilvus 官方现在推荐用 Docker Compose 部署 standalone 模式。我在本地和测试环境都是这么干的一条命令拉起整套依赖不污染宿主机。先准备一个docker-compose.ymlversion: 3.5 services: etcd: container_name: milvus-etcd image: quay.io/coreos/etcd:v3.5.14 environment: - ETCD_AUTO_COMPACTION_MODErevision - ETCD_AUTO_COMPACTION_RETENTION1000 - ETCD_QUOTA_BACKEND_BYTES4294967296 - ETCD_SNAPSHOT_COUNT50000 volumes: - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd command: etcd -advertise-client-urlshttp://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd healthcheck: test: [CMD, etcdctl, endpoint, health] interval: 30s timeout: 20s retries: 3 minio: container_name: milvus-minio image: minio/minio:RELEASE.2023-03-20T20-16-18Z environment: MINIO_ACCESS_KEY: minioadmin MINIO_SECRET_KEY: minioadmin ports: - 9001:9001 - 9000:9000 volumes: - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data command: minio server /minio_data --console-address :9001 healthcheck: test: [CMD, curl, -f, http://localhost:9000/minio/health/live] interval: 30s timeout: 20s retries: 3 standalone: container_name: milvus-standalone image: milvusdb/milvus:v2.4.13 command: [milvus, run, standalone] security_opt: - seccomp:unconfined environment: ETCD_ENDPOINTS: etcd:2379 MINIO_ADDRESS: minio:9000 volumes: - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus healthcheck: test: [CMD, curl, -f, http://localhost:9091/healthz] interval: 30s start_period: 90s timeout: 20s retries: 3 ports: - 19530:19530 - 9091:9091 depends_on: - etcd - minio这个文件里有几个值得注意的地方。etcd 的ETCD_QUOTA_BACKEND_BYTES我设了 4GB这是 Milvus 元数据能增长的上限如果你的 collection 数量非常多可以调大但别随随便便弄到几十 GBetcd 本身不适合存大数据量。MinIO 的账号密码默认minioadmin本地测试无所谓生产环境必须改成强密码并且建议用环境变量注入不要写死在 compose 里。Milvus 2.4 这个版本是目前我用下来比较稳的也是和 Spring AI 集成兼容性最好的一个主线版本。2.5 之后的结构化过滤和 full text search 更强但 API 变动也大等社区把坑填完再上不迟。2.2 起完容器后先做这几件事执行docker compose up -d之后不要急着去写代码先确认三个状态。第一三个容器都健康。看日志用docker compose ps如果 standalone 容器卡在 unhealthy多半是 etcd 或 MinIO 没起来先修依赖再重试。第二确认 19530 端口通了。我用一个简单的 Java 测试类验证 gRPC 连接import io.milvus.client.MilvusServiceClient; import io.milvus.param.ConnectParam; import io.milvus.param.RpcStatus; public class MilvusConnectionCheck { public static void main(String[] args) { MilvusServiceClient client new MilvusServiceClient( ConnectParam.newBuilder() .withUri(http://localhost:19530) .build()); RpcStatus status client.getVersion(); if (status.getStatus() RpcStatus.Success.getStatus()) { System.out.println(连接成功 new String(status.getMessage())); } else { System.err.println(连接失败 status.getMessage()); } client.close(); } }第三确认 9091 端口的健康检查接口能返回OK。curl http://localhost:9091/healthz如果返回的不是 OK说明 Milvus 内部组件还没就绪等一会儿再试。2.3 CentOS 7 / 资源紧张机器上的注意事项热词里有人搜“centos7安装milvus”我多说两句。CentOS 7 默认内核和 Docker 版本都比较老装 Milvus 容易遇到两个坑一是 Docker 版本低于 20compose 语法解析失败先升级 Docker二是内存不足导致 etcd 频繁挂掉Milvus 单机版本建议至少 8GB 内存4GB 机器能跑但非常吃力我实测在 4GB 机器上启动一个 collection 就要七八分钟。如果机器内存紧张可以给 compose 文件加上资源限制比如deploy: resources: limits: memory: 4G这样至少不会把宿主机拖死。另外磁盘记得预留 20GB 以上MinIO 默认会把索引和日志文件写进 volume小磁盘很快会被撑满。3. Spring AI 集成依赖、配置与仓库抽象3.1 引入 spring-ai-milvus-store 依赖Spring AI 官方把向量数据库的集成拆成了很多独立模块Milvus 对应的是spring-ai-milvus-store。要注意Spring AI 1.0.0 之前还在迭代artifact 版本经常带M1、M6这类里程碑后缀所以我建议用 BOM 统一管理版本避免手动写错。dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0-M6/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-milvus-store/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai/artifactId /dependency /dependencies顺带解释一下为什么用 BOMSpring AI 的spring-ai-milvus-store会传递依赖 Milvus 的 Java SDK如果你手动引入 SDK 版本和模块内置版本不一致很容易出现MethodNotFound这类诡异报错。BOM 能把所有组件锁在同一批版本上这种问题基本就避免了。3.2 YAML 配置与 Client 构建Spring AI 的 Milvus 集成没有提供完全自动的spring.autoconfigure配置需要你手动声明MilvusServiceClient和VectorStoreBean。这一开始我也觉得麻烦但后来发现反而更透明连接参数和 collection 行为一目了然。milvus: uri: http://localhost:19530 token: database-name: default collection-name: knowledge_base embedding-dimension: 1024 index-type: HNSW metric-type: COSINE consistency-level: StrongJava 配置类如下Configuration public class MilvusConfig { Bean public MilvusServiceClient milvusClient(Value(${milvus.uri}) String uri, Value(${milvus.token:}) String token) { ConnectParam.Builder builder ConnectParam.newBuilder() .withUri(uri); if (StringUtils.hasText(token)) { builder.withToken(token); } return new MilvusServiceClient(builder.build()); } Bean public VectorStore vectorStore(MilvusServiceClient milvusClient, EmbeddingModel embeddingModel, Value(${milvus.collection-name}) String collectionName, Value(${milvus.embedding-dimension}) int dimension, Value(${milvus.consistency-level}) String consistency) { MilvusVectorStoreConfig config MilvusVectorStoreConfig.builder() .withCollectionName(collectionName) .withEmbeddingDimension(dimension) .withConsistencyLevel(consistency) .build(); return new MilvusVectorStore(milvusClient, config, embeddingModel); } }这里有个关键点collection-name和embedding-dimension是强绑定的。embedding 模型一旦换掉向量维度跟着变但 Milvus 里的 collection schema 不会自动重建必须手动删除旧 collection 或者换一个 collection 名。我见过有人把 OpenAI 的 1536 维数据写完以后切到 768 维的本地模型检索结果一直为空查了半天才发现是维度不一致导致的数据类型检查失败。3.3 VectorStore 抽象换向量库不用改业务代码Spring AI 把向量库操作收敛成了VectorStore接口核心方法就几个add、similaritySearch、delete。业务层拿到的是VectorStore而不是某个具体实现类。这意味着你把 Milvus 换成 PGVector、ChromaDB、Qdrant业务代码几乎不用动只要换掉 Bean 实现就行。我一开始也觉得这个抽象有点过度设计直到有一次某篇文章推荐了另一个向量库我为了评估性能把整个存储层切过去跑 benchmark改的只是配置类和依赖三天就完成了对比测试。如果你后续有“向量库替换”的潜在需求这个抽象能省下大量返工成本。3.4 Embedding 模型选型接 OpenAI 还是 Qwen 还是本地 BGESpring AI 的EmbeddingModel是可以替换的这也是整个链路里最影响最终效果的一环。选型上我分三种情况说。接 OpenAI 的text-embedding-3-small最简单效果稳1536 维但调用要花钱而且数据要出网隐私敏感场景直接排除。接通义的Qwen embedding也就是热词里那个qwen embedding在中文场景下效果不错1024 维能走 Spring AI Alibaba 的 dashscope 通道适合国内业务数据合规的场景。本地部署 BGE 系列模型比如bge-m31024 维用 Ollama 或者 Xinference 起一个 embedding 服务延迟低、免费、数据不出内网但机器需要额外显存模型效果上中文略弱于商业 API。我的建议是项目初期先用商业 API 把链路跑通验证业务效果等到文档量大了、调用成本上来了再切本地模型。维度变化时记得重建 collection别偷懒。4. 从文档到问答一个完整 RAG 流程的 Java 实现4.1 文档加载与切块Spring AI 提供了DocumentReader家族常见的有PagePdfDocumentReader、TikaDocumentReader、JsonReader。PDF 解析我用PagePdfDocumentReader比较多它按页返回Document每页自带页码 metadata方便后面统计和溯源。var reader new PagePdfDocumentReader(classpath:/docs/spring-ai-guide.pdf); ListDocument documents reader.get();切块用的是TokenTextSplitter。它的底层是按 token 数切而不是字符数这对中文更友好。基本用法var splitter new TokenTextSplitter(); ListDocument chunks splitter.apply(documents);默认参数下切出来的块可能偏大偏小我一般在项目里自定义参数。下面是调参后的示例每块约 500 token重叠 80 tokenvar splitter TokenTextSplitter.builder() .withChunkSize(500) .withChunkOverlap(80) .build(); ListDocument chunks splitter.apply(documents);为什么重叠不能省因为切块时如果正好把一个完整语义段落砍成两半后半个片段单独召回时缺少前文信息大模型拿到手里也读不明白。重叠 60120 token 能在语义连续性和检索精度之间取个平衡。4.2 写入 Milvusid 幂等、metadata 字段切完块以后调用VectorStore.add()写入。我建议在Document里预留好id和自定义 metadata别用默认生成的随机 id否则后续数据更新时会很痛苦。String docId doc_spring_ai_guide; for (int i 0; i chunks.size(); i) { Document chunk chunks.get(i); chunk.setId(docId _ i); chunk.getMetadata().put(source, spring-ai-guide.pdf); chunk.getMetadata().put(page, chunk.getMetadata().get(page)); chunk.getMetadata().put(docId, docId); } vectorStore.add(chunks);幂等性怎么保证如果同一份文档重新导入你需要先删掉旧的同 docId 的向量再写入新的。Milvus 的 delete 支持表达式过滤可以按docId删vectorStore.delete(List.of(docId)); // 等价于按 id 删除但只删精确 id // 更推荐的做法遍历 docId 前缀再删除这里有个容易踩的坑Spring AI 的delete(ListString)删除的是 Document 的 id也就是我上面拼的doc_spring_ai_guide_0而不是 metadata 里的 docId。如果你希望“按业务文档维度批量删除”要靠 metadata 过滤实现。Spring AI 1.0 之后在VectorStore接口增加了delete(SearchRequest)的重载但不同版本兼容性有差异我建议在没有把握时直接调 Milvus SDK 的 delete 表达式完成批量清理。4.3 向量检索与 metadata 过滤写入之后最关键的就是检索。Spring AI 的检索入口ListDocument hits vectorStore.similaritySearch( SearchRequest.builder() .query(什么是 Spring AI 的 RAG 流程) .topK(5) .build() );这背后做的事情是把问题文本转成向量去 Milvus 里按 COSINE 相似度召回 topK 个片段。如果你要限制只搜某一份文档或者只看某个页面可以加过滤条件SearchRequest.builder() .query(什么是 RAG) .topK(5) .filterExpression(docId doc_spring_ai_guide) .build();filterExpression 的语法不是 SQL是 Milvus 的布尔表达式。等号要用字符串用单引号多个条件用。第一次写的时候容易手滑写成或者漏了引号然后报Expr evaluate error报错信息还贼隐晦。4.4 混合检索与重排纯向量检索在语义匹配上很强但在关键词精确匹配上有时反而拉胯。比如用户搜“Spring AI 1.0 发布”如果文档里写的是“Spring AI 1.0.0 版本发布”语义相近但关键词不完全一致向量检索通常也能召回。但搜“错误码 404”这种强标识性内容时向量检索可能把语义相近但完全无关的文档翻出来。这时候就需要混合检索向量召回 关键词召回再合并重排。Milvus 2.4 之后支持了 full text search可以在同一个集合里做 BM25 检索然后和向量检索做 RRFReciprocal Rank Fusion合并。我用 Java SDK 直接调的话大致是两层先做向量search再做 full textsearch最后在 Java 侧合并。Spring AI 1.0 的VectorStore接口对混合检索的原生支持还不够完整所以我的做法是在 Service 层手动实现。核心代码结构如下public ListDocument hybridSearch(String query, String collectionName, int topK) { // 第一步向量检索 ListDocument vectorHits vectorStore.similaritySearch( SearchRequest.builder().query(query).topK(topK).build()); // 第二步关键词检索走 Milvus SDK ListDocument bm25Hits fullTextSearch(query, collectionName, topK); // 第三步RRF 合并 return RrfFusion.merge(vectorHits, bm25Hits, topK); }RRF 的核心逻辑是给每个候选分配一个1/(k rank)的分数k 一般取 60。我实际测下来RRF 合并比简单拼接两个结果列表稳定得多简单拼接会让重复命中的片段被排两次导致最终返回的上下文重叠度太高浪费大模型上下文窗口。重排列re-rank又是另一层。如果你有资源跑一个交叉编码器模型或者调外部 rerank API可以在混合检索之后再精排一次。我目前在生产环境没有接 rerank因为延迟会多出来 200500 毫秒对内部知识库问答来说收益不大。但如果你的场景是“从 100 个候选里精挑 5 个”rerank 的价值就非常明显了。4.5 交给 ChatClient 生成回答检索回来的片段最终要拼进 prompt。Spring AI 1.0 里可以这么组织String context hits.stream() .map(Document::getText) .collect(Collectors.joining(\n\n---\n\n)); PromptTemplate promptTemplate new PromptTemplate( 你是企业知识库助手请基于以下资料回答用户问题。 如果资料中没有相关信息请直接说明“未找到相关内容”不要编造。 资料 {context} 用户问题{question} 回答 ); Message message promptTemplate.createMessage(Map.of(context, context, question, question)); var response chatClient.call(new Prompt(message));这一步有个容易忽视的细节召回片段拼接时最好在每段之间加上分隔符并在 prompt 里明确告诉模型“资料用分隔符隔开”。如果不加分隔符模型可能把两段不相干的内容当成一个连续上下文回答出现逻辑混乱。还有一个经验topK 不是越大越好。我之前调到 8结果大模型回答里混入了两个不相关片段答案反而比 topK3 时更差。后来固定 topK4并在 prompt 里要求“如果某条资料与问题明显无关忽略它”效果稳定很多。这个值的取舍一定要拿评测集去试别拍脑袋。5. 影响效果的几个关键参数5.1 Collection 与索引参数Milvus 的 collection 建好后索引类型、metric type、索引参数都不能随意改了。所以建 collection 之前最好先想清楚。Spring AI 的MilvusVectorStoreConfig默认建的索引是 HNSW。HNSW 有两个关键参数M控制每个节点的连接数efConstruction控制建索引时的搜索范围。M一般设 16 或 32。M越大召回精度越高但内存和检索耗时都会增加。efConstruction我习惯设 200构建慢一点没关系查询阶段的召回率提升明显。如果你对延迟更敏感可以降到 64。metric type 我推荐 COSINE。L2 距离在向量没有归一化时可能受向量模长干扰内积IP在高维稀疏向量里有一些特效但对常规 dense embeddingCOSINE 是“不怎么会错”的选择。5.2 切分参数对召回率的影响切分参数是 RAG 调优里性价比最高的地方。chunk size 太小比如 200 token召回片段很多但每个片段信息量不足大模型需要拼凑多个片段才能回答容易漏信息。chunk size 太大比如 1000 token单片段信息是够了但语义可能混杂检索时精确匹配率下降。我按文档类型给过一套经验值技术文档 / FAQchunk 400600 tokenoverlap 80100长文本 / 书籍chunk 600800 tokenoverlap 120150对话记录 / 工单chunk 300400 tokenoverlap 5080这是一个起手配置不是银弹。最稳的方法还是抽一批真实问题做评测集用召回率指标来定参数。热词里有“rag文档加载解析详细全流程”说明大家确实在这块踩了很多坑我这里先给一个能跑的经验起步值。5.3 检索 topK 与 score 阈值score 阈值是个很玄学的东西。Milvus 返回的相似度分数在不同 metric 下含义不同COSINE 在 01 之间严格说是 -11但 embedding 模型输出通常非负。如果你设scoreThreshold0.6可能把一些语义相关的长尾片段过滤掉也可能放进来噪音。我的建议是开发阶段不要设 score 阈值先看 topK 召回的内容是否合理确认之后再根据实际分数分布定阈值。如果某个查询的平均相似度是 0.75把阈值设成 0.7 会安全一些。最忌讳的是从别处抄一个“0.5 阈值”直接上线不同 embedding 模型的分数分布差异巨大照搬必踩坑。5.4 数据更新与一致性知识库不是只写一次就完事。文档更新时我习惯先按业务 docId 批量删除旧向量再重新加载新文档写入。Milvus 默认的一致性级别是 Bounded也就是允许一小段时间内的数据滞后对知识库场景完全够用。如果你用的是 Strong 级别的强一致写入完立刻查询能保证读到最新数据但吞吐会受一点影响。Spring AI 的配置里可以用withConsistencyLevel设置。内部知识库如果更新不频繁用 Strong 更省心高频写入的日志分析类场景Bounded 更合适。6. 排查实录与避坑清单6.1 容器起不来还疯狂刷日志我遇到最多的问题是 standalone 容器一直 unhealthy。第一反应去看完整日志docker compose logs standalone如果看到fail to init meta client字样的十有八九是 etcd 没就绪。此时不是重启 standalone 就行而是先看 etcd 的健康状态。还有一种情况之前在 CentOS 7 上遇到的Docker 默认存储驱动是overlay2但老内核支持不好MinIO 写入时直接把磁盘写满Milvus 报no space left on device。解决方法是清理 Docker 无用的镜像和 volume或者给 MinIO 单独挂一块大磁盘。6.2 连接失败 / 鉴权问题连接http://localhost:19530失败先确认端口有没有被防火墙拦截。CentOS 7 上我踩过无数次firewalld的坑19530端口没放行Java 客户端一直超时但本机 curl 又正常。开端口命令firewall-cmd --zonepublic --add-port19530/tcp --permanent firewall-cmd --reload鉴权问题多发生在生产环境。如果你配置了 tokenMilvus 客户端连接时必须要带 token否则报authentication failed。Spring AI 的配置里可以给MilvusServiceClient的ConnectParam设置.withToken(token)。这里有个我没想通的坑Milvus 的 token 是username:password格式而不是普通密钥字符串如果你直接填一个 UUID 格式的 token认证一样报错。构造方式可以去查一下 root 用户的 token 规则。6.3 明明有数据却搜不到“有数据但搜不到”这种情况第一反应查 consistency level。我刚从 Bounded 切到 Strong 时遇到过写入成功但立刻查询空结果。因为 Milvus 的查询默认走副本/分段的数据可见性写入到可读之间有小窗口Strong 能规避这个问题。第二个原因是没有指定 partition 或者过滤条件写错。如果你的代码里加了filterExpression先把它去掉再试一次如果去掉就有结果问题在表达式语法或是指错了 metadata 字段名需要对比写入时的 metadata key 和过滤表达式里的 key 是否完全一致。Spring AI 写入 metadata 时有些类型会被转换比如 Integer 可能变成 Long导致page 1匹配不上要写成page 1L。第三个原因是 collection 的 schema 里没有定义能用于过滤的字段。Spring AI 的MilvusVectorStore默认会把 metadata 存成 dynamic field支持过滤但如果你手动建过 collection 且没有开启 dynamic field过滤就会静默失败。日志里看不到任何报错只有结果为空。6.4 常见错误速查表现象可能原因处理方式Connection refusedMilvus 端口未开放 / 容器未启动检查容器状态、防火墙Collection not foundcollection 名拼错或未自动创建确认配置里的 collection-namedimension mismatch换模型后维度变了删掉旧 collection 重建Expr evaluate errorfilterExpression 语法错误检查、单引号、cast检索结果总是第一页重复没有正确存储或恢复 Document id设置稳定的业务 id大批量写入后查询变慢索引参数不够 / 内存不足调 HNSW 参数或扩容disk fullMinIO 数据过多清理 volume / 扩容磁盘6.5 推荐一个调试利器 AttuAttu 是 Milvus 官方出的 Web 管理界面Docker 一键起。调试的时候我经常用它直接看 collection 里到低存了什么、metadata 长什么样、检索结果分数是多少省去了写各种临时代码的麻烦。docker run -p 8000:3000 -e MILVUS_URLhttp://host.docker.internal:19530 zilliz/attu:latest然后浏览器打开http://localhost:8000连上 Milvus 就能看到所有 collection。排查“明明有数据却搜不到”这类问题时Attu 里直接跑一次查询能看到原始向量和分数的分布比在代码里猜测快得多。最后再分享一点自己的体会Milvus 给我的整体感觉是学习曲线比 ChromaDB 高但换来的确定性和扩展性对得起这份投入。尤其是当你手里的文档从几百页涨到几十万页、查询并发从 1 个涨到 100 个的时候ChromaDB 会先崩PGVector 会先慢Milvus 可能还在稳定输出。当然这并不意味着每个项目都必须上 Milvus。如果只是个人博客和几百个文档别折腾ChromaDB 就能满足如果你的目标是认真做知识库产品、要支撑团队协作和企业级并发那把 Milvus 作为核心组件是很值的一笔投资。另外再补一个经验RAG 系统的瓶颈从来不是单点组件的性能而是“文档处理质量 切片策略 embedding 模型 检索策略”这套组合拳。Milvus 只是其中一环但也是最核心的一环。把这一环打牢后面换模型、换 prompt、换应用层框架都不会伤筋动骨。下一篇专题我打算把文档加载、清洗、切分的完整流程单独展开那个环节的细节经常决定知识库最终能不能用建议先把 Milvus 这一篇里的代码跑通再往下走。
