1. 为什么我要把 Chroma 和 RAG 检索工具拆开再拼起来RAG 这个词这两年已经被说烂了但真正落到工程里十个人有八个卡在同一个地方检索层和生成层耦合太死换一个向量库要动半个项目调一次召回策略要重跑整条链路。我最早做知识库问答的时候用的是最朴素的方案——把文档切块、丢进一个向量库、检索 top-k、拼进 prompt 交给大模型。跑 demo 没问题一上真实数据就露馅召回率忽高忽低改一个参数不知道影响的是检索还是生成排查问题像在黑箱里摸鱼。后来我把这套东西彻底拆了一遍核心思路就一句话把 Chroma 当成一个纯粹的向量存储与检索服务把 RAG 的编排逻辑独立成一层可替换的工具层。Chroma 负责“存”和“找”RAG 工具层负责“怎么找、找多少、找到之后怎么用”。这么拆的好处是检索策略可以单独调、单独测向量库也可以单独换两边互不绑架。这套集成方案适合谁如果你正在做本地知识库、企业文档问答、客服机器人或者你已经在用 LangChain、Spring AI、LangChain4j 这类框架但觉得检索部分不够可控那这套拆法能帮你把 RAG 的“检索”这一半真正握在自己手里。它不依赖任何特定的大模型服务本地模型、云端 API 都能接Chroma 本身也支持本地持久化和客户端/服务端两种模式从小规模验证到中等规模上线都能覆盖。我下面会从整体设计、核心细节、实操落地、问题排查四个层面把这套方案完整讲一遍。所有参数和步骤都是我自己跑过、踩过坑之后沉淀下来的你可以直接抄也可以按自己的场景改。2. 整体设计Chroma 与 RAG 工具层如何各司其职2.1 核心思路存储与编排解耦很多人一上来就把 Chroma 和 LangChain 的 RetrievalQA 绑在一起用图省事。但 RetrievalQA 这类封装把检索、拼接、生成揉成一个黑盒你想单独看“检索出来的 chunk 到底长什么样”都得翻源码。我的做法是反过来先用 Chroma 把检索这一层做扎实再让 RAG 工具层去调用它。具体来说Chroma 这一层只干三件事存向量、存元数据、按向量相似度返回结果。它不关心你后面是喂给 GPT 还是喂给本地 Ollama也不关心你是做问答还是做摘要。RAG 工具层则负责查询改写、多路召回、重排序、上下文拼接、prompt 组装。这两层之间通过一个清晰的接口通信——输入是 query 和过滤条件输出是带 score 的文档列表。这么设计最直接的好处是可测试性。检索层可以单独跑评测给定一批 query 和标准答案直接看 hit rate 和 MRR不用每次都调用大模型省时省钱。生成层出问题的时候你也能快速判断是“没检索到”还是“检索到了但模型没用好”。2.2 为什么选 Chroma 而不是别的向量库向量库这个赛道选择很多FAISS、Milvus、Qdrant、Weaviate 各有拥趸。我选 Chroma 做这套方案的核心主要基于几个现实考量。第一是上手成本。Chroma 的 Python 接口极其简洁collection.add()和collection.query()两个方法就能覆盖 80% 的日常操作不需要你理解什么 segment、partition 的概念。对于中小规模知识库几万到几十万 chunk它完全够用。第二是本地持久化友好。Chroma 支持PersistentClient数据直接落盘到本地目录重启不丢。这对本地知识库场景太重要了——你不需要额外起一个数据库服务一个目录就是全部数据备份、迁移、版本管理都简单。第三是元数据过滤能力。Chroma 的where过滤支持等于、不等于、大于小于、in 等操作还能和向量检索组合使用。这意味着你可以做“先按来源过滤再按相似度排序”这种混合检索而不需要自己写后处理逻辑。当然它也有短板分布式能力弱超大规模千万级以上性能会吃紧HNSW 索引参数可调空间不如专业库。但对于绝大多数 RAG 项目这些都不是瓶颈。真到了那个量级你换 Qdrant 或 Milvus 的时候因为检索层是独立的迁移成本也可控。2.3 RAG 工具层要解决的核心问题RAG 工具层不是简单地把 query 丢给 Chroma 就完事。它要解决几个检索层的“最后一公里”问题。查询改写是第一个。用户问“这个功能怎么配置”直接拿这句话去检索很可能匹配不到“XX 参数设置方法”这种文档。工具层需要把口语化 query 改写成更接近文档表述的形式或者生成多个变体做多路召回。召回数量与阈值是第二个。top-k 设多少相似度阈值卡在哪这两个参数直接决定 hit rate 和噪声比例。我的经验是 k 不要固定而是根据 query 类型动态调整同时用一个相对宽松的阈值先召回再交给重排序去精筛。重排序是第三个。向量相似度高不代表语义相关尤其是短 query 对长文档的时候。工具层可以接一个 cross-encoder 重排序模型把召回结果重新打分这一步对 hit rate 的提升往往比调向量模型还明显。上下文组装是第四个。召回的 chunk 怎么拼进 prompt是简单拼接还是去重合并要不要带上来源元数据这些细节直接影响生成质量也是工具层该管的事。3. 核心细节解析从切块到检索的每个关键决策3.1 文档切块RAG 效果的地基切块这件事我见过太多人随手按固定长度切然后抱怨检索不准。切块是 RAG 的地基地基没打好后面怎么调都是白搭。我的切块策略是语义优先、长度兜底。具体做法是先用段落和标题做一级切分把文档拆成语义相对完整的块然后对超长的块再做二次切分。二次切分的时候保留一定的重叠overlap我一般设 chunk_size 的 10% 到 20%防止关键信息正好卡在边界上被切断。chunk_size 设多少这个没有标准答案但有个经验区间中文文档 300 到 600 字英文文档 500 到 1000 token。太小了语义不完整太大了检索精度下降。我实测下来技术文档用 400 字左右、带 80 字重叠效果比较稳。还有一个容易被忽略的点每个 chunk 都要带上足够的元数据。至少要有来源文件名、章节标题、chunk 在原文中的位置。这些元数据在检索时可以用于过滤在生成时可以用于引用溯源。Chroma 的 metadata 字段支持嵌套字典存这些完全没问题。def split_document(text, source, chunk_size400, overlap80): paragraphs text.split(\n\n) chunks [] buffer for para in paragraphs: if len(buffer) len(para) chunk_size: buffer para \n\n else: if buffer: chunks.append(buffer.strip()) buffer para \n\n if buffer: chunks.append(buffer.strip()) # 对超长块做二次切分 final_chunks [] for i, chunk in enumerate(chunks): if len(chunk) chunk_size * 1.5: final_chunks.append({ text: chunk, metadata: {source: source, index: i} }) else: for j in range(0, len(chunk), chunk_size - overlap): final_chunks.append({ text: chunk[j:j chunk_size], metadata: {source: source, index: i, sub: j} }) return final_chunks注意切块之后一定要人工抽查一批 chunk看看有没有把表格、代码块、列表切得七零八落。结构化内容最好单独处理别和正文混在一起切。3.2 向量模型选择别盲目追大embedding 模型的选择直接决定检索质量的上限。现在可选的有 OpenAI 的 text-embedding-3、BGE 系列、M3E、GTE 等等。我的建议是中文场景优先考虑 BGE 或 M3E英文场景可以用 text-embedding-3-small 或 GTE。为什么不盲目追大模型因为 embedding 模型越大推理越慢、存储越贵而检索质量的提升往往不是线性的。BGE-base 和 BGE-large 在很多中文检索任务上差距不到 3 个点但推理速度差一倍。对于本地知识库这种对延迟敏感的场景base 版本往往是更务实的选择。还有一个关键点查询和文档必须用同一个模型编码。这个听起来是废话但我真的见过有人文档用 BGE 编码、查询用 OpenAI 编码然后纳闷为什么检索全是噪声。向量空间都不一样怎么可能匹配得上。如果你用 Ollama 跑本地模型可以用nomic-embed-text或bge-m3前者英文强后者中英文都还行。用 LangChain 的话HuggingFaceEmbeddings或OllamaEmbeddings都能直接接 Chroma。3.3 Chroma 集合配置HNSW 参数怎么调Chroma 底层用的是 HNSW 索引创建 collection 的时候可以传metadata来配置索引参数。默认参数在中小规模下够用但如果你数据量上了十万级调一下会有明显收益。关键参数有三个hnsw:space、hnsw:construction_ef、hnsw:search_ef。hnsw:space是距离度量默认是l2欧氏距离但做文本检索我强烈建议改成cosine因为文本向量的方向比长度更重要。construction_ef影响建索引时的精度越大越准但越慢一般设 100 到 200。search_ef影响查询时的精度越大召回越全但越慢一般设 50 到 100。collection client.create_collection( nameknowledge_base, metadata{ hnsw:space: cosine, hnsw:construction_ef: 150, hnsw:search_ef: 80 } )提示hnsw:space一旦创建就不能改想换距离度量只能重建 collection。所以建库之前一定想清楚文本检索无脑选 cosine 就对了。3.4 检索策略从单路到多路最简单的检索就是拿 query 向量去查 top-k。但真实场景里单路检索的 hit rate 经常不够看。我的做法是多路召回 重排序。多路召回可以这么设计第一路用原始 query 检索第二路用查询改写后的 query 检索第三路用关键词做 BM25 检索如果 Chroma 版本支持全文检索的话或者外挂一个轻量 BM25。三路结果合并去重再交给重排序模型精排。重排序我用的是 BGE-reranker 或者 Cohere 的 rerank 接口。cross-encoder 会把 query 和每个候选文档拼在一起打分精度比向量相似度高不少。实测下来加了重排序之后 hit rate 能提升 10 到 20 个百分点尤其是 query 比较短、文档比较长的时候。def multi_route_retrieve(query, collection, embed_fn, rerank_fn, top_k20, final_k5): # 第一路原始 query q_vec embed_fn(query) results_a collection.query(query_embeddings[q_vec], n_resultstop_k) # 第二路改写 query这里简化为去掉停用词 rewritten rewrite_query(query) q_vec_b embed_fn(rewritten) results_b collection.query(query_embeddings[q_vec_b], n_resultstop_k) # 合并去重 candidates {} for res in [results_a, results_b]: for doc, meta, dist in zip(res[documents][0], res[metadatas][0], res[distances][0]): key doc[:100] if key not in candidates or dist candidates[key][dist]: candidates[key] {text: doc, meta: meta, dist: dist} # 重排序 docs list(candidates.values()) ranked rerank_fn(query, [d[text] for d in docs]) return ranked[:final_k]4. 实操落地从零搭一套可跑的集成方案4.1 环境准备与依赖安装先把环境搭起来。我假设你用 Python虚拟环境自己建好然后装这几个核心包pip install chromadb langchain langchain-community sentence-transformers pip install ollama # 如果用本地模型Chroma 从 0.4 版本之后 API 有变化建议用 0.4.24 以上的版本。LangChain 的版本迭代很快我写这篇的时候用的是 0.2.x接口和 0.1.x 有差异你装的时候注意看文档。如果你要用 Ollama 跑本地模型先确保 Ollama 服务起来了然后拉两个模型一个 embedding 模型一个生成模型。ollama pull nomic-embed-text ollama pull qwen2.5:7b注意embedding 模型和生成模型是两回事。别拿生成模型去做 embedding效果差而且慢。nomic-embed-text 专门做 embedding体积小速度快适合本地知识库。4.2 初始化 Chroma 并写入数据Chroma 有两种模式PersistentClient本地持久化HttpClient连服务端。本地知识库用前者就够了。import chromadb from chromadb.config import Settings client chromadb.PersistentClient( path./chroma_db, settingsSettings(anonymized_telemetryFalse) ) collection client.get_or_create_collection( nameknowledge_base, metadata{hnsw:space: cosine} )写入数据的时候我建议分批写入每批 100 到 500 条。一次性写几万条容易内存爆掉而且 Chroma 的写入不是事务性的中途失败不好恢复。分批写还能让你在每批之后检查一下进度。def add_documents(collection, chunks, embed_fn, batch_size200): for i in range(0, len(chunks), batch_size): batch chunks[i:i batch_size] texts [c[text] for c in batch] metadatas [c[metadata] for c in batch] ids [fdoc_{ij} for j in range(len(batch))] embeddings embed_fn(texts) collection.add( documentstexts, metadatasmetadatas, idsids, embeddingsembeddings ) print(f已写入 {i len(batch)} / {len(chunks)})提示id 一定要唯一而且最好有规律方便后续更新和删除。我用doc_序号的格式配合 metadata 里的 source 字段能快速定位到某个文件的所有 chunk。4.3 封装检索工具层检索工具层我封装成一个类对外只暴露一个retrieve方法内部处理查询改写、多路召回、重排序、去重。class RAGRetriever: def __init__(self, collection, embed_fn, rerank_fnNone): self.collection collection self.embed_fn embed_fn self.rerank_fn rerank_fn def retrieve(self, query, top_k20, final_k5, whereNone): q_vec self.embed_fn([query])[0] results self.collection.query( query_embeddings[q_vec], n_resultstop_k, wherewhere, include[documents, metadatas, distances] ) docs [] for doc, meta, dist in zip( results[documents][0], results[metadatas][0], results[distances][0] ): docs.append({text: doc, meta: meta, score: 1 - dist}) if self.rerank_fn and docs: docs self.rerank_fn(query, docs) return docs[:final_k]这个类的好处是where参数让你可以做元数据过滤。比如你只想在某个来源的文档里检索传where{source: xxx.md}就行。Chroma 的 where 语法支持$eq、$ne、$gt、$in等操作符组合起来很灵活。4.4 接入生成层prompt 组装与调用检索到文档之后组装 prompt 交给大模型。prompt 模板我一般这么写PROMPT_TEMPLATE 你是一个知识库助手请根据以下参考资料回答用户问题。 如果参考资料中没有相关信息请明确说明资料中未找到相关内容不要编造。 参考资料 {context} 用户问题{question} 回答context 的组装有个细节给每个 chunk 编号并带上来源这样模型引用的时候有据可依你排查问题的时候也能看到它到底用了哪几块。def build_context(docs): parts [] for i, doc in enumerate(docs, 1): source doc[meta].get(source, unknown) parts.append(f[{i}] 来源{source}\n{doc[text]}) return \n\n.join(parts)调用 Ollama 生成import ollama def generate(question, docs): context build_context(docs) prompt PROMPT_TEMPLATE.format(contextcontext, questionquestion) response ollama.chat( modelqwen2.5:7b, messages[{role: user, content: prompt}] ) return response[message][content]4.5 完整链路串起来把上面几块拼起来就是一个完整的 RAG 流程def rag_query(question, retriever, top_k5): docs retriever.retrieve(question, top_k20, final_ktop_k) if not docs: return 未检索到相关文档。 answer generate(question, docs) return answer, docs跑起来之后我建议你先用几个已知答案的问题测一下看看检索出来的 chunk 对不对再看生成的回答有没有依据。这一步别偷懒很多问题在检索层就能暴露出来。5. 常见问题与排查技巧实录5.1 检索不准的排查顺序检索不准是最常见的问题但原因可能出在好几个环节。我总结了一个排查顺序从便宜到贵逐层排除。排查项检查方法常见问题切块质量人工抽查 chunk语义被切断、表格代码混切向量模型换模型对比 hit rate中英文模型用错、查询文档不同模型距离度量确认 hnsw:space文本检索用了 l2 而非 cosinetop-k 与阈值调整参数看召回k 太小漏召回、阈值太严重排序对比有无 rerank重排序模型与场景不匹配查询改写看改写后 query改写过度偏离原意我的经验是八成检索问题出在切块和向量模型上参数调整能解决的不到两成。所以别一上来就调 top-k先回去看你的 chunk 长什么样。5.2 hit rate 上不去的几个真实原因hit rate 是 RAG 检索的核心指标指的是标准答案所在的 chunk 有没有被召回。我踩过的坑有这么几个。第一个是标准答案跨多个 chunk。比如用户问“XX 功能的完整配置流程”答案分散在三个 chunk 里你 top-k 只召回了一个hit rate 自然上不去。解决办法是提高 top-k或者做 chunk 合并把相邻 chunk 拼成更大的上下文。第二个是query 和文档表述差异太大。用户用口语问文档用书面语写向量相似度就是上不去。这时候查询改写和多路召回就派上用场了。第三个是元数据过滤把答案过滤掉了。我见过有人加了where{type: faq}过滤结果答案在type: guide的文档里怎么调都召不回。过滤条件一定要谨慎不确定就先不加。5.3 Chroma 使用中的坑Chroma 用起来简单但有几个坑我踩过提前告诉你。collection 名称不能重复创建。create_collection如果名字已存在会报错用get_or_create_collection更稳。但要注意get_or_create不会覆盖已有的 metadata如果你改了 hnsw 参数想生效得先删了重建。删除数据要用 id。Chroma 的delete支持按 id 或按 where 条件删但不支持按文档内容删。所以写入的时候 id 一定要规划好不然想删某个文件的数据都无从下手。持久化目录别放临时路径。PersistentClient的 path 如果放在/tmp下系统重启就没了。放项目目录下的./chroma_db记得加进.gitignore别把向量数据提交到代码仓库。批量查询注意内存。collection.query的n_results别设太大尤其是数据量大的时候。我一般不超过 50需要更多结果就分页或者用 where 缩小范围。5.4 生成层与检索层的责任边界最后说一个容易被混淆的问题生成效果不好到底是检索的锅还是生成的锅我的判断方法是看检索出来的 chunk 里有没有答案。如果有答案但模型没答对那是生成层的问题可能是 prompt 没写好、模型能力不够、或者上下文太长把关键信息淹没了。如果 chunk 里根本没答案那就是检索层的问题回去调检索。这个判断听起来简单但很多人不做一上来就换模型、改 prompt结果检索层的问题一直没解决怎么调都没用。先确认检索层能召回正确答案再优化生成层这个顺序不能反。6. 一些让方案更稳的工程细节6.1 增量更新与版本管理知识库不是一次建完就完事的文档会更新、会新增。我的做法是给每个文档算一个内容哈希写入的时候把哈希存进 metadata。更新的时候先按 source 查出旧 chunk 的 id删掉再写新的。这样既不会重复也不会漏更新。import hashlib def doc_hash(text): return hashlib.md5(text.encode()).hexdigest() # 更新时 old collection.get(where{source: source}) if old[ids]: collection.delete(idsold[ids]) # 再写入新 chunk6.2 检索结果的可观测性RAG 系统最怕的是黑箱。我强烈建议在检索层加日志把每次查询的 query、召回的 chunk、score、最终用了哪几个都记下来。出了问题能回溯调参的时候也有数据支撑。日志不用多复杂写个 JSONL 文件就行每行一条记录。积累一段时间之后你就能看出哪些 query 经常召回失败针对性去优化。6.3 小规模评测集的建立想持续优化 RAG你得有个评测集。不用多50 到 100 条就够每条包含一个问题和标准答案所在的 chunk id。每次改完检索策略跑一遍评测集看 hit rate 和 MRR 的变化。没有评测集你的所有优化都是凭感觉今天调好了明天可能又坏了。评测集的构建可以半自动先用现有系统跑一批 query人工标注哪些召回是对的慢慢积累。这个过程枯燥但值得它是你判断优化方向的唯一依据。7. 我在实际项目中的几点体会这套 Chroma 加 RAG 工具层的拆法我在三个项目里用过规模从几千 chunk 到几十万 chunk 都有。最大的体会是RAG 的瓶颈从来不在向量库本身而在数据质量和检索策略。Chroma 也好别的库也好它们只是工具真正决定效果的是你怎么切块、怎么改写查询、怎么重排序。另一个体会是别过度设计。我一开始也想搞 GraphRAG、搞本体检索后来发现大部分场景下把基础的向量检索加个重排序就够用了。复杂方案带来的收益往往抵不过它增加的维护成本。先把简单方案做到位遇到真正的瓶颈再上复杂方案。最后评测先行。没有评测集的优化都是耍流氓。我现在的习惯是任何检索策略的改动先跑评测集数据说话。这个习惯帮我省了大量瞎调参数的时间。这套方案你拿去可以直接跑也可以按自己的场景改。Chroma 的接口简单RAG 工具层的每个环节都可以单独替换改起来不伤筋动骨。真正跑起来之后你会发现 RAG 没那么玄乎它就是一个需要耐心调优的工程问题。
Chroma与RAG检索工具解耦集成实战：从切块到重排序的工程指南
1. 为什么我要把 Chroma 和 RAG 检索工具拆开再拼起来RAG 这个词这两年已经被说烂了但真正落到工程里十个人有八个卡在同一个地方检索层和生成层耦合太死换一个向量库要动半个项目调一次召回策略要重跑整条链路。我最早做知识库问答的时候用的是最朴素的方案——把文档切块、丢进一个向量库、检索 top-k、拼进 prompt 交给大模型。跑 demo 没问题一上真实数据就露馅召回率忽高忽低改一个参数不知道影响的是检索还是生成排查问题像在黑箱里摸鱼。后来我把这套东西彻底拆了一遍核心思路就一句话把 Chroma 当成一个纯粹的向量存储与检索服务把 RAG 的编排逻辑独立成一层可替换的工具层。Chroma 负责“存”和“找”RAG 工具层负责“怎么找、找多少、找到之后怎么用”。这么拆的好处是检索策略可以单独调、单独测向量库也可以单独换两边互不绑架。这套集成方案适合谁如果你正在做本地知识库、企业文档问答、客服机器人或者你已经在用 LangChain、Spring AI、LangChain4j 这类框架但觉得检索部分不够可控那这套拆法能帮你把 RAG 的“检索”这一半真正握在自己手里。它不依赖任何特定的大模型服务本地模型、云端 API 都能接Chroma 本身也支持本地持久化和客户端/服务端两种模式从小规模验证到中等规模上线都能覆盖。我下面会从整体设计、核心细节、实操落地、问题排查四个层面把这套方案完整讲一遍。所有参数和步骤都是我自己跑过、踩过坑之后沉淀下来的你可以直接抄也可以按自己的场景改。2. 整体设计Chroma 与 RAG 工具层如何各司其职2.1 核心思路存储与编排解耦很多人一上来就把 Chroma 和 LangChain 的 RetrievalQA 绑在一起用图省事。但 RetrievalQA 这类封装把检索、拼接、生成揉成一个黑盒你想单独看“检索出来的 chunk 到底长什么样”都得翻源码。我的做法是反过来先用 Chroma 把检索这一层做扎实再让 RAG 工具层去调用它。具体来说Chroma 这一层只干三件事存向量、存元数据、按向量相似度返回结果。它不关心你后面是喂给 GPT 还是喂给本地 Ollama也不关心你是做问答还是做摘要。RAG 工具层则负责查询改写、多路召回、重排序、上下文拼接、prompt 组装。这两层之间通过一个清晰的接口通信——输入是 query 和过滤条件输出是带 score 的文档列表。这么设计最直接的好处是可测试性。检索层可以单独跑评测给定一批 query 和标准答案直接看 hit rate 和 MRR不用每次都调用大模型省时省钱。生成层出问题的时候你也能快速判断是“没检索到”还是“检索到了但模型没用好”。2.2 为什么选 Chroma 而不是别的向量库向量库这个赛道选择很多FAISS、Milvus、Qdrant、Weaviate 各有拥趸。我选 Chroma 做这套方案的核心主要基于几个现实考量。第一是上手成本。Chroma 的 Python 接口极其简洁collection.add()和collection.query()两个方法就能覆盖 80% 的日常操作不需要你理解什么 segment、partition 的概念。对于中小规模知识库几万到几十万 chunk它完全够用。第二是本地持久化友好。Chroma 支持PersistentClient数据直接落盘到本地目录重启不丢。这对本地知识库场景太重要了——你不需要额外起一个数据库服务一个目录就是全部数据备份、迁移、版本管理都简单。第三是元数据过滤能力。Chroma 的where过滤支持等于、不等于、大于小于、in 等操作还能和向量检索组合使用。这意味着你可以做“先按来源过滤再按相似度排序”这种混合检索而不需要自己写后处理逻辑。当然它也有短板分布式能力弱超大规模千万级以上性能会吃紧HNSW 索引参数可调空间不如专业库。但对于绝大多数 RAG 项目这些都不是瓶颈。真到了那个量级你换 Qdrant 或 Milvus 的时候因为检索层是独立的迁移成本也可控。2.3 RAG 工具层要解决的核心问题RAG 工具层不是简单地把 query 丢给 Chroma 就完事。它要解决几个检索层的“最后一公里”问题。查询改写是第一个。用户问“这个功能怎么配置”直接拿这句话去检索很可能匹配不到“XX 参数设置方法”这种文档。工具层需要把口语化 query 改写成更接近文档表述的形式或者生成多个变体做多路召回。召回数量与阈值是第二个。top-k 设多少相似度阈值卡在哪这两个参数直接决定 hit rate 和噪声比例。我的经验是 k 不要固定而是根据 query 类型动态调整同时用一个相对宽松的阈值先召回再交给重排序去精筛。重排序是第三个。向量相似度高不代表语义相关尤其是短 query 对长文档的时候。工具层可以接一个 cross-encoder 重排序模型把召回结果重新打分这一步对 hit rate 的提升往往比调向量模型还明显。上下文组装是第四个。召回的 chunk 怎么拼进 prompt是简单拼接还是去重合并要不要带上来源元数据这些细节直接影响生成质量也是工具层该管的事。3. 核心细节解析从切块到检索的每个关键决策3.1 文档切块RAG 效果的地基切块这件事我见过太多人随手按固定长度切然后抱怨检索不准。切块是 RAG 的地基地基没打好后面怎么调都是白搭。我的切块策略是语义优先、长度兜底。具体做法是先用段落和标题做一级切分把文档拆成语义相对完整的块然后对超长的块再做二次切分。二次切分的时候保留一定的重叠overlap我一般设 chunk_size 的 10% 到 20%防止关键信息正好卡在边界上被切断。chunk_size 设多少这个没有标准答案但有个经验区间中文文档 300 到 600 字英文文档 500 到 1000 token。太小了语义不完整太大了检索精度下降。我实测下来技术文档用 400 字左右、带 80 字重叠效果比较稳。还有一个容易被忽略的点每个 chunk 都要带上足够的元数据。至少要有来源文件名、章节标题、chunk 在原文中的位置。这些元数据在检索时可以用于过滤在生成时可以用于引用溯源。Chroma 的 metadata 字段支持嵌套字典存这些完全没问题。def split_document(text, source, chunk_size400, overlap80): paragraphs text.split(\n\n) chunks [] buffer for para in paragraphs: if len(buffer) len(para) chunk_size: buffer para \n\n else: if buffer: chunks.append(buffer.strip()) buffer para \n\n if buffer: chunks.append(buffer.strip()) # 对超长块做二次切分 final_chunks [] for i, chunk in enumerate(chunks): if len(chunk) chunk_size * 1.5: final_chunks.append({ text: chunk, metadata: {source: source, index: i} }) else: for j in range(0, len(chunk), chunk_size - overlap): final_chunks.append({ text: chunk[j:j chunk_size], metadata: {source: source, index: i, sub: j} }) return final_chunks注意切块之后一定要人工抽查一批 chunk看看有没有把表格、代码块、列表切得七零八落。结构化内容最好单独处理别和正文混在一起切。3.2 向量模型选择别盲目追大embedding 模型的选择直接决定检索质量的上限。现在可选的有 OpenAI 的 text-embedding-3、BGE 系列、M3E、GTE 等等。我的建议是中文场景优先考虑 BGE 或 M3E英文场景可以用 text-embedding-3-small 或 GTE。为什么不盲目追大模型因为 embedding 模型越大推理越慢、存储越贵而检索质量的提升往往不是线性的。BGE-base 和 BGE-large 在很多中文检索任务上差距不到 3 个点但推理速度差一倍。对于本地知识库这种对延迟敏感的场景base 版本往往是更务实的选择。还有一个关键点查询和文档必须用同一个模型编码。这个听起来是废话但我真的见过有人文档用 BGE 编码、查询用 OpenAI 编码然后纳闷为什么检索全是噪声。向量空间都不一样怎么可能匹配得上。如果你用 Ollama 跑本地模型可以用nomic-embed-text或bge-m3前者英文强后者中英文都还行。用 LangChain 的话HuggingFaceEmbeddings或OllamaEmbeddings都能直接接 Chroma。3.3 Chroma 集合配置HNSW 参数怎么调Chroma 底层用的是 HNSW 索引创建 collection 的时候可以传metadata来配置索引参数。默认参数在中小规模下够用但如果你数据量上了十万级调一下会有明显收益。关键参数有三个hnsw:space、hnsw:construction_ef、hnsw:search_ef。hnsw:space是距离度量默认是l2欧氏距离但做文本检索我强烈建议改成cosine因为文本向量的方向比长度更重要。construction_ef影响建索引时的精度越大越准但越慢一般设 100 到 200。search_ef影响查询时的精度越大召回越全但越慢一般设 50 到 100。collection client.create_collection( nameknowledge_base, metadata{ hnsw:space: cosine, hnsw:construction_ef: 150, hnsw:search_ef: 80 } )提示hnsw:space一旦创建就不能改想换距离度量只能重建 collection。所以建库之前一定想清楚文本检索无脑选 cosine 就对了。3.4 检索策略从单路到多路最简单的检索就是拿 query 向量去查 top-k。但真实场景里单路检索的 hit rate 经常不够看。我的做法是多路召回 重排序。多路召回可以这么设计第一路用原始 query 检索第二路用查询改写后的 query 检索第三路用关键词做 BM25 检索如果 Chroma 版本支持全文检索的话或者外挂一个轻量 BM25。三路结果合并去重再交给重排序模型精排。重排序我用的是 BGE-reranker 或者 Cohere 的 rerank 接口。cross-encoder 会把 query 和每个候选文档拼在一起打分精度比向量相似度高不少。实测下来加了重排序之后 hit rate 能提升 10 到 20 个百分点尤其是 query 比较短、文档比较长的时候。def multi_route_retrieve(query, collection, embed_fn, rerank_fn, top_k20, final_k5): # 第一路原始 query q_vec embed_fn(query) results_a collection.query(query_embeddings[q_vec], n_resultstop_k) # 第二路改写 query这里简化为去掉停用词 rewritten rewrite_query(query) q_vec_b embed_fn(rewritten) results_b collection.query(query_embeddings[q_vec_b], n_resultstop_k) # 合并去重 candidates {} for res in [results_a, results_b]: for doc, meta, dist in zip(res[documents][0], res[metadatas][0], res[distances][0]): key doc[:100] if key not in candidates or dist candidates[key][dist]: candidates[key] {text: doc, meta: meta, dist: dist} # 重排序 docs list(candidates.values()) ranked rerank_fn(query, [d[text] for d in docs]) return ranked[:final_k]4. 实操落地从零搭一套可跑的集成方案4.1 环境准备与依赖安装先把环境搭起来。我假设你用 Python虚拟环境自己建好然后装这几个核心包pip install chromadb langchain langchain-community sentence-transformers pip install ollama # 如果用本地模型Chroma 从 0.4 版本之后 API 有变化建议用 0.4.24 以上的版本。LangChain 的版本迭代很快我写这篇的时候用的是 0.2.x接口和 0.1.x 有差异你装的时候注意看文档。如果你要用 Ollama 跑本地模型先确保 Ollama 服务起来了然后拉两个模型一个 embedding 模型一个生成模型。ollama pull nomic-embed-text ollama pull qwen2.5:7b注意embedding 模型和生成模型是两回事。别拿生成模型去做 embedding效果差而且慢。nomic-embed-text 专门做 embedding体积小速度快适合本地知识库。4.2 初始化 Chroma 并写入数据Chroma 有两种模式PersistentClient本地持久化HttpClient连服务端。本地知识库用前者就够了。import chromadb from chromadb.config import Settings client chromadb.PersistentClient( path./chroma_db, settingsSettings(anonymized_telemetryFalse) ) collection client.get_or_create_collection( nameknowledge_base, metadata{hnsw:space: cosine} )写入数据的时候我建议分批写入每批 100 到 500 条。一次性写几万条容易内存爆掉而且 Chroma 的写入不是事务性的中途失败不好恢复。分批写还能让你在每批之后检查一下进度。def add_documents(collection, chunks, embed_fn, batch_size200): for i in range(0, len(chunks), batch_size): batch chunks[i:i batch_size] texts [c[text] for c in batch] metadatas [c[metadata] for c in batch] ids [fdoc_{ij} for j in range(len(batch))] embeddings embed_fn(texts) collection.add( documentstexts, metadatasmetadatas, idsids, embeddingsembeddings ) print(f已写入 {i len(batch)} / {len(chunks)})提示id 一定要唯一而且最好有规律方便后续更新和删除。我用doc_序号的格式配合 metadata 里的 source 字段能快速定位到某个文件的所有 chunk。4.3 封装检索工具层检索工具层我封装成一个类对外只暴露一个retrieve方法内部处理查询改写、多路召回、重排序、去重。class RAGRetriever: def __init__(self, collection, embed_fn, rerank_fnNone): self.collection collection self.embed_fn embed_fn self.rerank_fn rerank_fn def retrieve(self, query, top_k20, final_k5, whereNone): q_vec self.embed_fn([query])[0] results self.collection.query( query_embeddings[q_vec], n_resultstop_k, wherewhere, include[documents, metadatas, distances] ) docs [] for doc, meta, dist in zip( results[documents][0], results[metadatas][0], results[distances][0] ): docs.append({text: doc, meta: meta, score: 1 - dist}) if self.rerank_fn and docs: docs self.rerank_fn(query, docs) return docs[:final_k]这个类的好处是where参数让你可以做元数据过滤。比如你只想在某个来源的文档里检索传where{source: xxx.md}就行。Chroma 的 where 语法支持$eq、$ne、$gt、$in等操作符组合起来很灵活。4.4 接入生成层prompt 组装与调用检索到文档之后组装 prompt 交给大模型。prompt 模板我一般这么写PROMPT_TEMPLATE 你是一个知识库助手请根据以下参考资料回答用户问题。 如果参考资料中没有相关信息请明确说明资料中未找到相关内容不要编造。 参考资料 {context} 用户问题{question} 回答context 的组装有个细节给每个 chunk 编号并带上来源这样模型引用的时候有据可依你排查问题的时候也能看到它到底用了哪几块。def build_context(docs): parts [] for i, doc in enumerate(docs, 1): source doc[meta].get(source, unknown) parts.append(f[{i}] 来源{source}\n{doc[text]}) return \n\n.join(parts)调用 Ollama 生成import ollama def generate(question, docs): context build_context(docs) prompt PROMPT_TEMPLATE.format(contextcontext, questionquestion) response ollama.chat( modelqwen2.5:7b, messages[{role: user, content: prompt}] ) return response[message][content]4.5 完整链路串起来把上面几块拼起来就是一个完整的 RAG 流程def rag_query(question, retriever, top_k5): docs retriever.retrieve(question, top_k20, final_ktop_k) if not docs: return 未检索到相关文档。 answer generate(question, docs) return answer, docs跑起来之后我建议你先用几个已知答案的问题测一下看看检索出来的 chunk 对不对再看生成的回答有没有依据。这一步别偷懒很多问题在检索层就能暴露出来。5. 常见问题与排查技巧实录5.1 检索不准的排查顺序检索不准是最常见的问题但原因可能出在好几个环节。我总结了一个排查顺序从便宜到贵逐层排除。排查项检查方法常见问题切块质量人工抽查 chunk语义被切断、表格代码混切向量模型换模型对比 hit rate中英文模型用错、查询文档不同模型距离度量确认 hnsw:space文本检索用了 l2 而非 cosinetop-k 与阈值调整参数看召回k 太小漏召回、阈值太严重排序对比有无 rerank重排序模型与场景不匹配查询改写看改写后 query改写过度偏离原意我的经验是八成检索问题出在切块和向量模型上参数调整能解决的不到两成。所以别一上来就调 top-k先回去看你的 chunk 长什么样。5.2 hit rate 上不去的几个真实原因hit rate 是 RAG 检索的核心指标指的是标准答案所在的 chunk 有没有被召回。我踩过的坑有这么几个。第一个是标准答案跨多个 chunk。比如用户问“XX 功能的完整配置流程”答案分散在三个 chunk 里你 top-k 只召回了一个hit rate 自然上不去。解决办法是提高 top-k或者做 chunk 合并把相邻 chunk 拼成更大的上下文。第二个是query 和文档表述差异太大。用户用口语问文档用书面语写向量相似度就是上不去。这时候查询改写和多路召回就派上用场了。第三个是元数据过滤把答案过滤掉了。我见过有人加了where{type: faq}过滤结果答案在type: guide的文档里怎么调都召不回。过滤条件一定要谨慎不确定就先不加。5.3 Chroma 使用中的坑Chroma 用起来简单但有几个坑我踩过提前告诉你。collection 名称不能重复创建。create_collection如果名字已存在会报错用get_or_create_collection更稳。但要注意get_or_create不会覆盖已有的 metadata如果你改了 hnsw 参数想生效得先删了重建。删除数据要用 id。Chroma 的delete支持按 id 或按 where 条件删但不支持按文档内容删。所以写入的时候 id 一定要规划好不然想删某个文件的数据都无从下手。持久化目录别放临时路径。PersistentClient的 path 如果放在/tmp下系统重启就没了。放项目目录下的./chroma_db记得加进.gitignore别把向量数据提交到代码仓库。批量查询注意内存。collection.query的n_results别设太大尤其是数据量大的时候。我一般不超过 50需要更多结果就分页或者用 where 缩小范围。5.4 生成层与检索层的责任边界最后说一个容易被混淆的问题生成效果不好到底是检索的锅还是生成的锅我的判断方法是看检索出来的 chunk 里有没有答案。如果有答案但模型没答对那是生成层的问题可能是 prompt 没写好、模型能力不够、或者上下文太长把关键信息淹没了。如果 chunk 里根本没答案那就是检索层的问题回去调检索。这个判断听起来简单但很多人不做一上来就换模型、改 prompt结果检索层的问题一直没解决怎么调都没用。先确认检索层能召回正确答案再优化生成层这个顺序不能反。6. 一些让方案更稳的工程细节6.1 增量更新与版本管理知识库不是一次建完就完事的文档会更新、会新增。我的做法是给每个文档算一个内容哈希写入的时候把哈希存进 metadata。更新的时候先按 source 查出旧 chunk 的 id删掉再写新的。这样既不会重复也不会漏更新。import hashlib def doc_hash(text): return hashlib.md5(text.encode()).hexdigest() # 更新时 old collection.get(where{source: source}) if old[ids]: collection.delete(idsold[ids]) # 再写入新 chunk6.2 检索结果的可观测性RAG 系统最怕的是黑箱。我强烈建议在检索层加日志把每次查询的 query、召回的 chunk、score、最终用了哪几个都记下来。出了问题能回溯调参的时候也有数据支撑。日志不用多复杂写个 JSONL 文件就行每行一条记录。积累一段时间之后你就能看出哪些 query 经常召回失败针对性去优化。6.3 小规模评测集的建立想持续优化 RAG你得有个评测集。不用多50 到 100 条就够每条包含一个问题和标准答案所在的 chunk id。每次改完检索策略跑一遍评测集看 hit rate 和 MRR 的变化。没有评测集你的所有优化都是凭感觉今天调好了明天可能又坏了。评测集的构建可以半自动先用现有系统跑一批 query人工标注哪些召回是对的慢慢积累。这个过程枯燥但值得它是你判断优化方向的唯一依据。7. 我在实际项目中的几点体会这套 Chroma 加 RAG 工具层的拆法我在三个项目里用过规模从几千 chunk 到几十万 chunk 都有。最大的体会是RAG 的瓶颈从来不在向量库本身而在数据质量和检索策略。Chroma 也好别的库也好它们只是工具真正决定效果的是你怎么切块、怎么改写查询、怎么重排序。另一个体会是别过度设计。我一开始也想搞 GraphRAG、搞本体检索后来发现大部分场景下把基础的向量检索加个重排序就够用了。复杂方案带来的收益往往抵不过它增加的维护成本。先把简单方案做到位遇到真正的瓶颈再上复杂方案。最后评测先行。没有评测集的优化都是耍流氓。我现在的习惯是任何检索策略的改动先跑评测集数据说话。这个习惯帮我省了大量瞎调参数的时间。这套方案你拿去可以直接跑也可以按自己的场景改。Chroma 的接口简单RAG 工具层的每个环节都可以单独替换改起来不伤筋动骨。真正跑起来之后你会发现 RAG 没那么玄乎它就是一个需要耐心调优的工程问题。
