企业官网建设流程全解析

这阵子我一直在折腾一件事：把公司内部散落的各种文档、项目记录、FAQ接进大模型问答。方案前后换了好几版，最后稳定在Chroma 向量库 + RAG 检索工具这套集成方案上。今天把完整的搭建过程、踩过的坑、还有调优思路整理出来，希望能帮到正在做 RAG 落地的朋友。

这套方案说白了就是三件事：让大模型能"看见"私有知识、能针对具体问题找到最相关的原文片段、然后在回答时把检索到的内容作为依据。Chroma 负责的是中间那段"用向量语义找文档"的环节。它轻量、不需要单独起服务、Python 客户端直接调用就能跑，对中小型项目和原型验证非常友好。适合谁看？如果你对 RAG 有基本概念但没完整搭过一版，或者搭过但是检索效果不稳定、不知道从哪调优，这篇应该对你有用。

我不打算写那种"先讲原理再贴代码"的教科书结构，直接按我实际动手的顺序来：先讲为什么选 Chroma 而不是别的向量库，再拆整个集成方案的架构，然后给一份能直接落地的代码流程，后面是排查问题和优化技巧，最后聊聊 RAG 后续可以往哪些方向延伸。

1. 为什么选择"Chroma + RAG"这套组合

1.1 先解决最核心的问题：检索式问答到底解决了什么

大模型最大的尴尬在于知识截止时间和"一本正经地胡说八道"。你问它某个内部系统的接口参数，它大概率会编一个看起来很像样的答案。这不是模型不够聪明，而是它压根没有你的私有数据。RAG 检索增强生成的思路很简单：在回答之前，先从知识库里把与问题最相关的文档片段捞出来，拼进 prompt，让模型基于这些材料作答。这样一来，模型不再需要"记住"所有知识，只需要"读懂"你喂给它的材料，生成准确率会高很多。

我在实际项目中感受最明显的场景是客服问答和内部知识库检索。之前用纯 prompt 方式让模型回答产品问题，同一个问题换个问法就可能给出相反结论。接入 RAG 之后，模型每次回答都有对应文档作为支撑，答案的稳定性和可信度明显提升。你甚至可以要求模型在回答末尾标注信息来自哪篇文档，方便人工追溯。

1.2 Chroma 在 RAG 链路里的角色定位

RAG 链路可以拆成两段：索引阶段和查询阶段。索引阶段要把文档切块、向量化、写入存储；查询阶段要把问题向量化、召回相关片段、交给大模型生成。Chroma 在这条链路里扮演的是"向量存储与相似度检索"的角色，核心功能很简单：存向量、算相似度、按距离排序返回 top-k 结果。

Chroma 最大的特点是轻。它是一个嵌入式向量数据库，类似 SQLite 的地位，直接在本地文件系统里写数据，Python 进程里实例化客户端就能读写，不需要像 Milvus 那样单独部署一套服务。对个人开发者、小团队、企业内部工具来说，这个特性非常香：装个 pip 包就能本地跑起来，数据默认落在你指定的目录，迁移时把目录拷走就行。Chroma 底层用的是 HNSW 索引，高维向量检索效率在百万量级以内都够用，普通项目根本到不了性能瓶颈。

1.3 方案选型时的一些取舍想法

做方案时我对比过几类主流选择：FAISS、Milvus、Weaviate、pgvector，还有 Elasticsearch 加向量插件。FAISS 是一个索引库，胜在性能极致，但可持久化和元数据过滤比较弱，需要自己管理索引文件和增删改逻辑。Milvus 功能强、扩展性好，可同样意味着部署和运维成本高，对小团队来说有点重。pgvector 如果你本身就用 PostgreSQL，顺带加一列向量字段是自然的，但检索性能和高并发场景需要额外调参。Elasticsearch 更适合本来就有一套 ES 体系、需要全文检索和向量混合的场景。

最终选 Chroma 的逻辑其实很朴素：我们当时的核心诉求是尽快跑通"文档问答"这个产品形态，验证效果之后再决定要不要上重型基础设施。Chroma 完美覆盖了这个阶段的需求——部署成本几乎为零，客户端 API 直观，元数据过滤用起来顺手，还内置了简单的持久化方案。当然我也得说实话，如果你预期数据量会到千万级、需要分布式部署和高可用，一开始就别选到 Chroma，直接上 Milvus 这类分布式向量库更稳妥，避免后面换引擎时重新灌库的麻烦。

2. 集成方案的架构设计与核心组件

2.1 数据流转链路总览

整个系统的数据流可以分成一条清晰的链路。索引阶段：原始文档进入系统后，先做清洗，去掉页眉页脚、无关水印，然后是文档切分，切成适合检索的文本块。切分后的块送入嵌入模型，转成向量。最后把这些向量连同原文、元数据一起写入 Chroma。查询阶段：用户输入问题后做同样的向量化处理，拿问题向量去 Chroma 里做相似度检索，返回最相关的几个文本块。如果需要更高的精度，可以把召回结果再送进一个重排序模型，过滤掉不相关片段，最后将过滤后的文本块拼进 prompt，交给大模型生成答案。

整个链路最关键的节点其实不是向量数据库本身，而是"切分"和"嵌入模型"。Chroma 只是忠实地帮你存和取，但存进去的东西好不好取，取决于前面的步骤。很多 RAG 效果差的项目，问题都不是出在向量库上，而是切分太粗暴或者嵌入模型选错了。后面我会细讲这两个环节的参数和方法。

2.2 文本切分策略：chunk_size 和 chunk_overlap 怎么定

切分是决定检索效果的关键操作。如果整篇文档作为一个文本块入库，向量会被大量无关内容稀释，检索时相关片段很难被命中；如果切得太碎，单个文本块信息量不足，召回的片段可能缺少上下文，答案就显得支离破碎。这里没有万能参数，但有一个常见的起步参考：chunk_size 设 512 个 token，chunk_overlap 设 64 个 token。

为什么要设置重叠？因为文本在切分边界处通常会截断一个完整语义单元，比如一个段落才讲到一半就被切开了。重叠窗口相当于在相邻块之间留出一段缓冲地带，让同一句完整语义有机会同时出现在两块中，避免边界信息丢失。实际操作中，我建议先按"语义完整性优先"的原则来切，优先在段落边界处切割，而不是死板地每隔 N 个 token 硬切。如果你用的是 LangChain，可以考虑 RecursiveCharacterTextSplitter，它按段落、句子、字符的优先级递归切分，效果比纯固定长度切分好不少。

2.3 嵌入模型选型：维度不是越大越好

嵌入模型的作用是"语义编码"，把一段文本变成一串数字向量，语义相近的文本在向量空间里的距离也近。选型时最容易犯的错是盲目追求大模型、高维度。维度高意味着表达能力强，但也意味着计算量大、存储占用高、inference 慢。对中文场景，我实测下来比较稳的有这几个：bge-m3（BAAI 出品，支持中英双语）、m3e（中文效果稳定）、text2vec-large-chinese。如果做纯离线部署，可以考虑 nomic-embed-text 配合 Ollama 使用。

我目前主力是国内开源模型 bge-m3，原因有三个：中文语义理解好，输出 1024 维向量，信息量足够；对长文本的兼容性强，最长能吃到 8192 个 token；权重开源可商用，不需要申请。需要特别强调一个容易踩的坑：同一个知识库里所有文档必须使用同一个嵌入模型，否则向量空间定义不一致，检索相关性直接崩溃。别小看这一点，我见过有人索引时换了模型没通知同事，结果线上检索质量突然暴跌，查了半天才发现是向量来源不一致。

我们来看一个简单的选型对比表格：

2.4 Chroma 集合管理与元数据设计

Chroma 里的核心概念是 Collection，可以理解成一张"带向量的表"。每个 Collection 有名字和距离函数配置，默认的 L2 距离在大多数场景下够用；如果想让相似度分数更直观，可以改用余弦相似度（cosine）。创建 Collection 时最好显式指定 embedding 函数，确保入库和查询是同一套编码逻辑。

元数据是很多人忽略的设计点。每一条入库记录除了向量，还能带一个 metadata 字典。这个字段建议放文档来源、标题、章节路径、更新日期、权限级别等信息。好处是检索时可以按条件过滤，比如"只在这个项目的范围内检索""只查 2024 年之后的文档"。这样不仅能提高精度，还能实现权限控制——不同角色用户检索同一问题，通过 metadata 过滤拿到不同范围的内容。我通常还会把文档的原始 chunk 文本完整存在 document 字段里，检索时直接返回，避免二次查原文。

3. 实操：从零搭建一套完整 RAG 检索工具

3.1 环境准备与依赖清单

环境建议 Python 3.10 以上，操作系统基本不限，Windows、macOS、Linux 都可以。依赖方面，核心需要这几个库：

pip install chromadb langchain langchain-community sentence-transformers

如果你打算用 Ollama 跑本地大模型做生成，再装一个：

pip install ollama

关于 LangChain 多说一点：LangChain 本身是个快速搭建 RAG 流程的框架，但并不是必需品。如果你习惯直接掌控细节，完全可以用原生代码操作 Chroma 客户端，配合 sentence-transformers 做嵌入，再直接调 Ollama 的 API 或 OpenAI SDK。我自己的做法是 LangChain 用来做文档加载和切分，向量读写和检索走 Chroma 原生 API，各用各的长处，减少框架之间的隐性坑。

3.2 文档入库：加载、切分、嵌入、写入

文档入库是跑通整套方案的第一步。我以一个典型场景为例：你手上有几个 Markdown 格式的说明文档，需要把它们灌进 Chroma。代码如下：

import chromadb from langchain_community.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from sentence_transformers import SentenceTransformer # 1. 加载文档 loader = TextLoader("./docs/product_manual.md", encoding="utf-8") documents = loader.load() # 2. 切分文本 splitter = RecursiveCharacterTextSplitter( chunk_size=512, chunk_overlap=64, separators=["\n## ", "\n### ", "\n\n", "\n", "。", ".", " "] ) chunks = splitter.split_documents(documents) # 3. 加载嵌入模型 embedder = SentenceTransformer("BAAI/bge-m3") # 4. 初始化 Chroma 持久化客户端 client = chromadb.PersistentClient(path="./chroma_data") collection = client.get_or_create_collection( name="product_manual", metadata={"hnsw:space": "cosine"} ) # 5. 组装数据并写入 ids = [f"chunk_{i}" for i in range(len(chunks))] texts = [chunk.page_content for chunk in chunks] metadatas = [{"source": "product_manual.md", "chunk_index": i} for i in range(len(chunks))] embeddings = embedder.encode(texts).tolist() collection.add( ids=ids, documents=texts, metadatas=metadatas, embeddings=embeddings ) print(f"成功写入 {len(chunks)} 个文本块")

这一段代码里有一个关键决策：PersistentClient指定了本地数据目录，数据会落盘持久化，下次启动仍然可用。get_or_create_collection会在集合不存在时自动创建，配合metadata里的hnsw:space参数指定距离函数，这里我用了 cosine。写入时同时传了documents、metadatas和embeddings，这样查询时可以直接拿到原文和来源信息。

特别提醒：bge-m3模型第一次加载会从 Hugging Face 拉取权重，需要提前确认网络环境。如果完全离线的环境，需要在一台能联网的机器上下载模型权重后拷贝到本地路径，然后通过SentenceTransformer("/本地路径/bge-m3")加载。

3.3 检索问答：拼接 prompt 并调用大模型

入库完成之后，就进入查询阶段。流程是：问题向量化，在 Chroma 里找最相似的文本块，然后把文本块作为上下文交给大模型。下面是一版完整的问答函数：

def ask_question(question, top_k=5): # 1. 问题向量化 query_embedding = embedder.encode([question]).tolist() # 2. 在 Chroma 中检索 result = collection.query( query_embeddings=query_embedding, n_results=top_k, include=["documents", "metadatas", "distances"] ) # 3. 组装上下文 contexts = [] for doc, meta in zip(result["documents"][0], result["metadatas"][0]): context = f"[来源: {meta['source']}, 片段: {meta['chunk_index']}]\n{doc}" contexts.append(context) context_text = "\n\n".join(contexts) # 4. 构建 prompt prompt = f"""你是知识库问答助手。请基于以下材料回答问题。 如果材料中没有足够的信息，请明确回答"材料中未找到相关信息"，不要编造。 材料： {context_text} 问题：{question} 回答：""" # 5. 调用本地 Ollama 模型 response = ollama.chat( model="llama3.1:8b", messages=[{"role": "user", "content": prompt}] ) return response["message"]["content"]

几个细节值得解释。top_k控制召回数量，太小容易漏信息，太大会把无关内容塞进 prompt，既影响回答质量又浪费 token。我一般从 5 起步，根据实际效果调到 4 到 10 之间。prompt 里特意要求模型在信息不足时说"未找到相关信息"，这是对抗幻觉的有效手段。把来源信息放进上下文，既方便模型理解片段出处，也为后续人工追溯留下了线索。

如果你用的是 OpenAI 类 API，把ollama.chat换成对应 SDK 调用即可，prompt 结构完全不用改。想增强效果，还可以在 prompt 里加上"如果材料之间有冲突，以更新时间较新的材料为准"这类规则。

3.4 检索命中率评估：怎么判断系统到底行不行

RAG 系统最容易让人迷惑的一点是：问答结果看起来还行，但不知道是不是"瞎猫碰上死耗子"。所以我强烈建议在正式上线前先做一次检索命中率评估。简单说，就是准备一组"问题 -> 预期文档"的测试集，然后反复查询，统计预期文档被召回的比例。

test_cases = [ {"question": "产品支持哪些导入格式？", "expected_source": "product_manual.md"}, {"question": "API 调用频率限制是多少？", "expected_source": "api_docs.md"}, # 更多测试用例... ] hit_count = 0 for case in test_cases: result = collection.query( query_embeddings=embedder.encode([case["question"]]).tolist(), n_results=10 ) sources = [meta["source"] for meta in result["metadatas"][0]] if case["expected_source"] in sources: hit_count += 1 hit_rate = hit_count / len(test_cases) print(f"检索命中率: {hit_rate:.2%}")

命中率如果低于 80%，基本不用指望生成效果能多好。这个指标最大的价值是帮你把问题定位在"检索环节"还是"生成环节"。命中率低，问题出在数据切分、embedding 或者检索策略上；命中率正常但回答质量差，问题出在 prompt 设计或者上下文组装上。在实际项目中，我把这个测试集从 30 条逐步扩充到 200 条，每次调整切分参数或检索逻辑后跑一遍，用数据说话而不是凭感觉。

4. 踩坑实录：集成过程中的高频问题与排查技巧

4.1 检索不到相关内容：先别怀疑模型，检查数据

这句话我在团队里说了不下十遍：检索不到东西，大概率不是向量库的问题，而是数据在进入向量库之前就出了问题。最常见的三种情况：第一，切分参数不合理，整个文档被切得过碎，一个完整知识点被拆到多个文本块里，每个块单独看都跟问题不相关；第二，元数据过滤条件写错，比如权限字段值不匹配，导致某些文档被过滤掉了；第三，入库时用的 embedding 模型和查询时不一致，向量空间不对齐，查出来的结果完全是乱的。

排查顺序建议是：先随手挑一条测试问题，打印出 Chroma 返回的原始结果，看召回的文本块原文跟问题是否沾边。如果连原文都明显无关，问题在数据阶段；如果原文相关但最终回答不对，问题在 prompt 阶段或模型选择。这一步能帮你快速缩小排查范围，别一上来就去调向量库参数。

4.2 向量库持久化与并发写入问题

Chroma 的本地持久化虽然方便，但有一个隐蔽的坑：新版 Chroma 默认持久化格式是 SQLite，本地目录里会出现一张很大的 sqlite 文件。如果你在代码升级后打开了旧版本的数据库，可能会遇到"数据库 schema 不兼容"的报错，解法是备份目录后用新版本重建索引。另外一个常见问题是并发写入：多个进程同时往同一个 PersistentClient 写数据时会碰到锁冲突，导致写入失败或数据损坏。

应对策略很简单：写入操作串行化，尽量集中在一个独立脚本里批量灌数据；查询操作可以开多个客户端实例。我曾经在一个服务里既做写入又做查询，高并发下频繁报database is locked，改成分离读写之后问题消失。集成到 Web 服务时，不要让每个请求都重新初始化 Chroma 客户端，而是启动时初始化一次，全局复用。

4.3 中文场景的特殊处理

中文文档处理比英文多一些麻烦。首先是切分边界问题，英文按空格和标点可以切得比较自然，中文的语义边界模糊，一不小心就把一个完整句子拦腰截断。实践中我会在 separators 里加入中文标点，比如句号、感叹号、问号，让切分器优先在句子边界上切。其次是编码问题，字符全角半角不统一、空格混用，会导致检索时看起来差不多的文本互相命中不了。建议入库前做一次基础清洗，统一全半角，去掉多余的空白字符和零宽字符。

再就是 embedding 模型的选择，这一点在中文场景下尤其重要。用面向英文优化的模型处理中文，检索效果会明显打折扣。国内开源模型如 bge-m3 对中文的支持要成熟得多，不用迷信国外模型。最后是关键词与语义的权衡：中文用户习惯于精确关键词检索，但向量检索是语义匹配，两者经常对不上。我的做法是给 Chroma 的查询结果加上一条"原文关键词匹配"的辅助逻辑，比如通过 metadata 里的简单字段或额外的关键词索引做二次过滤，把两部分结果合并，配合重排序提升体验。

4.4 本地部署细节：Ollama + Chroma 的零基础套路

很多朋友关心数据隐私问题，不想把内部文档发送到外部 API，于是会选择全本地部署。这条路是完全走得通的，而且现在成本不高。流程大概是这样：本地装 Ollama，用ollama pull llama3.1:8b拉一个生成模型；同时可以拉一个 embedding 模型，比如ollama pull nomic-embed-text；Chroma 仍然按前面说的方式本地持久化。查询时，Ollama 提供本地 HTTP 服务，代码里直接调用它的 SDK 或标准 OpenAI 兼容接口就行。

需要注意的点有三个。第一，本地生成模型的推理速度取决于硬件，8B 模型在普通 CPU 上生成速度会比较慢，有条件的话用 GPU 效果好很多；如果想更快，可以换成量化版本模型如llama3.1:8b-q4_0，视觉效果几乎不变但速度提升明显。第二，Ollama 的 embedding 模型和 sentence-transformers 返回的向量维度可能不同，要保证入库和查询都走同一条链路。第三，要把嵌入模型固定下来，存入项目配置文件，否则哪天换模型就要重新灌所有文档。全本地方案的好处是文档零外传、断网可用，适合企业内部知识库、个人笔记助手这类对隐私敏感的场景。

5. 再往前一步：Agentic RAG、GraphRAG 与多模态扩展

5.1 Agentic RAG：从"一锤子检索"到"多步决策"

基础版 RAG 是单轮检索：一个问题，查一次向量库，拼进 prompt，得到回答。它的局限很明显：遇到复杂问题需要多步推理、需要查多个数据源、需要根据中间结果决定下一步检索方向时，单轮检索就力不从心了。Agentic RAG 的思路是把 LLM 当作一个"决策大脑"，让它自己判断是否需要检索、检索什么关键词、要不要再查一次、要不要换个数据源。

实操层面，可以把 Chroma 封装成 Agent 的工具函数，让 LLM 在对话循环里调用这些工具。比如设计一个search_internal_docs(query)的函数，模型觉得需要查资料时就调用它，拿到结果后继续推理。这种模式特别适合那种"多条件筛选"的问题，比如"最近一个月哪个功能的投诉量最高"，模型需要先查投诉记录，再查功能文档，再综合判断。我目前在一个售后问答场景里试过，用 Agentic RAG 之后，原先需要人工分步处理的问题能自动搞定，虽然逻辑复杂度的增加也会带来推理时间变长、交互轮数变多，但对于真实复杂问题，这种付出是值得的。

5.2 GraphRAG 与本体 RAG：解决知识割裂

如果文档之间的关系复杂，实体与实体之间存在大量关联，普通向量检索就容易"看到树木看不到森林"。比如你问"A 模块的改动会影响哪些模块"，如果文档没有直接写明"影响关系"，向量检索很难关联起来。GraphRAG 的思路是在向量检索之上叠加一层知识图谱，先抽取实体和关系，再将实体向量化、关系结构化入库。

本体 RAG 则更进一步，引入领域本体对检索结果做约束和补全，让检索更贴合特定业务的知识结构。这些方案的共同目标是解决"知识割裂"——单篇文档内容独立时检索准确，一涉及跨文档、跨层级的问题就开始掉链子。在实现上，可以先用 LLM 抽取文档中的实体与关系，构建简单的图谱结构并存储，查询时先沿图结构找出相关子图，再结合 Chroma 的向量检索结果一起送入 prompt。这套方案我目前还在试验阶段，但效果上确实能看到跨文档关联问题的回答质量明显提升。

5.3 RAG 知识库能存储图片吗？多模态数据怎么处理

有不少人问我：RAG 知识库能不能存图片？直接答案是：Chroma 存的是向量，不是图片本身。你可以把图片经过处理后变成向量存进去，查询时再用相同的处理方式把问题的文本或图片变成向量进行匹配。纯文本模型只能处理文本，但基于图片生成文本描述或特征向量的方式，实践中非常可行。

简单给一个低成本方案：第一层，对图片做 OCR，把文字内容抽出来，作为文本块加入向量库；第二层，用多模态嵌入模型（比如 CLIP 类模型）把图片整体编码成一个向量，存进独立的 Chroma 集合。查询时，如果用户上传图片，就用多模态模型编码后去图片集合里找相似图；如果用户输入文字，可以同时检索文本集合和图片集合，再汇总结果。本地文档拆解工具方面，我最近常用unstructured和markitdown来解析 PDF、Word、HTML 等格式，它们能较好地提取正文内容，再配合正则清洗后进入切分流程。整体看下来，把非结构化数据纳入 RAG 并不是遥不可及的，核心思路始终是"先转为向量，再统一检索"。

整套方案搭下来，我最深的体会是：RAG 系统的上限由数据质量决定，而不是模型。向量库只是一个组织数据的仓库，真正决定效果的是切分策略、元数据设计和检索逻辑这些细节。你要问我现在再搭一套还会怎么做，我会先把测试集准备好，把检索命中率当成第一道验收关卡，命中率达标了再去调生成环节。这个顺序能帮你节省大量无效调参的时间。工具会一直迭代，但"数据先行、指标护航"的思路不会过时。