企业官网建设流程全解析

很多人私下问我，本地知识库到底怎么落地最省心。上个月我正好把一个六百多页的内部资料库做成了私有大模型问答系统，核心存储用的就是Chroma向量数据库，配合Ollama跑本地模型，LangChain负责编排流程。整套方案跑下来，我对Chroma的脾气摸了个七七八八，也踩了不少文档里没写的坑。这篇就把我的选型逻辑、完整实操链路、还有哪些地方最容易翻车，一次性写清楚。

这套东西适合谁？如果你手里有一堆文档、Markdown笔记、PDF或企业内部资料，想用大模型直接在本地做问答，又不想把数据交给云端接口，那这个组合就是最顺手的路线之一。Chroma负责把你文档的“语义”变成向量存起来，LangChain承担切分、拼装、调用模型的脏活，Ollama负责在本地把大模型跑起来。三者配合，你就拥有了一个完全属于自己的、数据不出本机的知识问答系统。

1. 先把Chroma是什么讲清楚：向量数据库里的“轻骑兵”

1.1 为什么知识问答场景离不开“向量化”

先想一个问题：你问大模型“我们的报销流程是什么”，模型并不认识你公司的报销制度，除非你把相关文本提前塞给它。但你又不可能把所有文档整篇塞进上下文，大模型的输入窗口装不下。所以知识库的思路是：提前把文档切成很多小段，每一段用Embedding模型转成一串数字，也就是向量。这个向量代表了这段文字的语义，语义相近的文字，向量之间的距离就小。查询时，把你问题的向量和库里的向量做相似度比较，找出最相关的几段，拼进Prompt里再丢给大模型。这个“先召回、再生成”的技术叫RAG，也就是检索增强生成。Chroma向量数据库在这个链路里的角色就是那个负责存取和检索的中间层。

向量检索和传统数据库完全不同。传统SQL查的是精确匹配，问“报销流程”时，关键词必须同字才能命中。但用Embedding向量做语义匹配，你说“出差费用怎么报销”，库里写着“差旅费申请与核销”，语义很接近也能被召回。这就是向量数据库这类工具存在的意义：它存储的不是结构化字段，而是压缩了语义的浮点数组，并专门为高维向量的近似最近邻搜索做了优化。

1.2 Chroma的四个核心概念：Collection、Document、Embedding、Metadata

用Chroma前，建议先把几个概念吃透，不然调API时会一直犯迷糊。

• Collection（集合）：类似传统数据库里的表。一个知识库可以有多个Collection，比如按部门拆，或者按文档类型拆。每个Collection在创建时就绑定了固定的Embedding模型和向量维度，这个约束很重要，后面踩坑部分会展开讲。
• Document（文本片段）：你要存进去的一段文字，可以是一段话、一页PDF、一个MD段落。Document是检索时返回的基本单位。
• Embedding（向量）：文本经过模型转换后得到的浮点数组。Chroma有两种处理方式：一种是你自己调模型生成向量再传给Chroma，叫“提供Embedding”；另一种是通过Chroma自带的EmbeddingFunction自动生成。在本地知识库里，通常用本地模型生成，避免数据出本机。
• Metadata（元数据）：附带在Document上的标签信息，是一个字典。比如来源文件名、章节号、写入时间。它最大的价值是支持结构化过滤，查询时可以先按Metadata过滤掉无关内容，再做向量相似度搜索，精度和效率都会好很多。

1.3 三种运行形态：内存、持久化目录、客户端服务端

Chroma使用起来很灵活，三种形态我分别说清楚。

• 全内存模式：不指定存储路径，数据只存在当前进程里，进程退出数据就没了。适合开发调试、快速验证效果。
• 持久化模式：核心是PersistentClient(path="./chroma_db")，所有数据落盘到本地目录。个人知识库项目基本都用这种，重启进程数据还在，备份也简单，整个目录复制走就行。这也是我在项目里的主力形态。
• 客户端服务端模式：启动一个Chroma服务进程，应用通过网络接口读写。适合多台机器共享同一个向量库，或者多人协作的场景。这种模式里Collection、Distance等概念会被封装为HTTP接口，需要额外管理服务的生命周期，复杂度会上升一些。

直观一点理解：内存模式是临时草稿，持久化模式是本地文件仓库，客户端服务端模式是公司共享网盘。个人和中小团队做本地知识库，第二种模式通常是性价比最高的选项。

2. 向量数据库选型：为什么这个场景我更推荐Chroma

2.1 主流选型横评：FAISS、Chroma、Milvus、Qdrant、Weaviate

刚开始接触向量数据库的人，大概率会被一堆名字绕晕。我把市面上常见的几个选项拉出来对比一下，重点放在“本地知识库”这个具体场景。

FAISS严格说不算数据库，它是个高效的向量索引库。索引在内存里算得飞快，但持久化、元数据管理、动态删除这些都得自己补，适合算法工程师做实验，不太适合直接做产品。

Milvus很强大，但部署要拉起来一堆依赖，我自己试过，为了一个内部问答工具上分布式存储，纯属杀鸡用牛刀。Qdrant虽然在过滤能力上比Chroma强，但对一个“把文档灌进去、查询时捞几段出来”的本地知识库来说，Chroma完全够用。

2.2 Chroma的取舍逻辑和边界

Chroma的设计理念说白了就四个字：开箱即用。pip install chromadb装完就能跑，不用额外起服务，不用配一堆环境变量，一个PersistentClient加一个Collection就开始读写数据。对个人项目来说，这种“低摩擦”体验是核心竞争力。

它也确实做了牺牲。Chroma的规模上限不如Milvus这类分布式方案，并发能力也比较有限，复杂过滤条件表达力弱，深度定制索引参数的空间不大。这都不是问题，只要你的知识库是几十万条Document以内的量级，跑本地问答完全够用。

我特别欣赏它一点：Metadata过滤和向量检索是原生融合的。比如直接写where={"source": "hr手册"}，就能把检索范围限定在某个具体文档源里。这在做分类知识库时非常顺手。

2.3 选型决策：什么时候可以选，什么时候要换

我给自己定的选型判断标准是这样的：如果你的场景属于“文档总量在百万级以下、单机跑得动、查询并发不高、数据敏感要求私有化”，那Chroma是首选，因为它简单直接，节省大量工程时间。如果已经到了“需要分布式集群、数据量上亿、并发QPS很夸张、要用K8s部署”，再考虑Milvus或Qdrant，但那就意味着你的链路复杂度会上升一个数量级，人员配置也得跟上。

还有一个中间过渡思路，就是先用Chroma把产品原型跑通，业务验证成功后再换到更强方案。因为这套RAG流程里，业务逻辑和Chroma是解耦的，你只要换掉存储层，上游的切分、Embedding、检索逻辑基本不用动。

3. 实操：用LangChain + Ollama + Chroma搭建本地知识库

3.1 整体架构：从文档加载到生成回答的五步闭环

先别急着写代码，把整个数据流向梳理清楚，后面遇到问题才好排查。我把它拆成五个环节：

1. 加载（Load）：读取本地文档，可以是Markdown、TXT、PDF，LangChain里有现成的Loader。
2. 切分（Split）：文档太长必须切成小块，切分长度和重叠窗口直接决定召回效果。后面单独讲。
3. 向量化（Embed）：每个文本块通过Ollama本地模型生成向量。
4. 入库（Store）：向量和文本、元数据一起写进Chroma的Collection中。
5. 问答（Answer）：用户提问，问题向量化后到Chroma里检索最相关的片段，拼进Prompt，交给本地大模型生成回答。

这里有个容易忽略的点：入库时用的Embedding模型，和查询时用的Embedding模型必须是同一个。否则向量维度可能对不上，语义空间也不一致，检索效果会非常差。这个坑后面会展开。

3.2 环境准备与模型准备

我先把需要的东西列出来，这些步骤是我实际验证通过的顺序。

首先确认本机装好了Ollama。安装完成后，拉取两个模型：

# 负责文本转向量的模型，这个很轻量，几百MB ollama pull nomic-embed-text # 负责生成回答的对话模型 ollama pull qwen2.5:7b

第一个是Embedding专用模型，第二个是Chat模型。如果你的机器配置一般，可以把后者换成qwen2.5:3b甚至更小的qwen2.5:1.5b，内存占用差距很大。nomic-embed-text这种Embedding模型一般不吃太多显卡资源，普通CPU跑也能用。

然后安装Python依赖。我推荐创建一个虚拟环境，避免污染系统环境，也方便以后迁移：

python -m venv chroma-env source chroma-env/bin/activate # Windows上执行 chroma-env\Scripts\activate pip install chromadb langchain langchain-community langchain-chroma langchain-ollama

安装完之后，先在命令行验证一下Ollama接口是否正常：

curl http://localhost:11434/api/tags

能返回模型列表就说明接口通了。所有本地请求都是通过这个地址完成的，数据不出本机。

3.3 核心代码：加载、切分、入库

现在写第一段核心代码，作用是读取本地文档并写入Chroma。

from langchain_community.document_loaders import DirectoryLoader, TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_chroma import Chroma from langchain_ollama import OllamaEmbeddings # 1. 加载目录下的所有md文件 loader = DirectoryLoader( "./docs", glob="**/*.md", loader_cls=TextLoader, loader_kwargs={"encoding": "utf-8"} ) docs = loader.load() print(f"加载到 {len(docs)} 个文件") # 2. 切分文档 splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=50, separators=["\n\n", "\n", "。", "，", " ", ""] ) chunks = splitter.split_documents(docs) print(f"切分为 {len(chunks)} 个文本块") # 3. 初始化Ollama Embedding，本地生成向量 embeddings = OllamaEmbeddings( model="nomic-embed-text", base_url="http://localhost:11434" ) # 4. 写入Chroma vectorstore = Chroma.from_documents( documents=chunks, embedding=embeddings, persist_directory="./chroma_db", collection_name="internal_kb" ) print("入库完成")

这段代码里有几个参数我要特别解释。

chunk_size=500是文本块长度，单位是字符。这个数字不是拍脑袋定的，它和Embedding模型支持的输入长度、最终回答精度直接相关。如果块太大，一个块里包含多个主题，检索时容易把不相关内容一并带出来；块太小，上下文碎片化，大模型得不到足够信息。我测试下来，中文场景500到800字符是个比较平衡的范围。

chunk_overlap=50是相邻块的重叠长度。这算一个容易被人忽略的细节。你想一下，如果一段重要信息刚好被切分线拦腰截断，前半句在上一块，后半句在下一块，那无论哪一块单独被召回，信息都不完整。设置重叠等于给切分留了缓冲，避免信息断崖。

persist_directory="./chroma_db"是存储目录。如果你的项目要跨机器迁移，直接复制这个目录带走就行，非常方便。

3.4 核心代码：检索、问答链路

入库只是第一步，正经的问答系统还要写检索和生成链路。下面是完整的问答实现：

from langchain_ollama import ChatOllama from langchain_core.prompts import PromptTemplate # 从持久化目录读取已有Collection vectorstore = Chroma( collection_name="internal_kb", persist_directory="./chroma_db", embedding_function=OllamaEmbeddings( model="nomic-embed-text", base_url="http://localhost:11434" ) ) # 构建检索器，每次召回Top 4个相关片段 retriever = vectorstore.as_retriever(search_kwargs={"k": 4}) # 本地大模型 llm = ChatOllama( model="qwen2.5:7b", base_url="http://localhost:11434", temperature=0.3 ) # Prompt模板 template = """你是企业内部知识库助手。请根据下面提供的资料回答问题。 资料内容： {context} 用户问题： {question} 回答时注意： 1. 只依据资料内容回答，不要编造。 2. 如果资料中没有对应信息，直接说明“资料里找不到”。 3. 回答尽量简洁、准确。 回答：""" prompt = PromptTemplate( template=template, input_variables=["context", "question"] ) def ask(question): # 1. 检索相关片段 docs = retriever.invoke(question) # 2. 拼接上下文 context = "\n\n".join([doc.page_content for doc in docs]) # 3. 生成Prompt并调用模型 final_prompt = prompt.format(context=context, question=question) response = llm.invoke(final_prompt) return response.content, docs

这里有一处值得注意的设定：temperature=0.3。我故意没有设为0，原因是完全0温度会让回答变得机械，但在知识问答里又不需要太多创造性，0.3是“严谨为主、稍微带一点自然语气”的平衡点。你如果追求绝对的原文照搬，可以设0。

k=4代表召回4个文本块。这个值也不是越大越好。块数太多，Prompt膨胀，大模型的注意力会被分散；块数太少，信息可能不够。经验是，一个标准企业问题，能命中的关键信息通常集中在1到2个块里，多召回两三个作为候选，既能覆盖又不会太吵。如果你的知识库比较大，可以先跑一遍测试，再根据回答质量微调。

3.5 效果调优：分块、召回数量与Prompt设计

整套链路跑通之后，你会很快发现一个问题：回答质量不够好。这很正常，RAG系统的效果瓶颈八成不在大模型本身，而在检索质量。我总结了一套调优顺序，你按这个来排查会高效很多。

第一优先排查分块。把某个问题的召回结果直接打印出来看。如果召回的文本块里有一半以上跟问题无关，说明切分太粗或者块太大。试试把chunk_size调小，比如从500调到300，同时chunk_overlap保持在chunk_size的10%左右。

第二调整召回数量。回答太空泛，可能漏信息，把k从4调到6或者8；回答太杂，老是夹带无关内容，把k调回3甚至2。

第三优化Prompt模板。有的模型对指令措辞不敏感，有的特别敏感。你可以试两种风格，一种强调“严格只依据资料回答”，一种是“把资料内容作为背景知识，结合你的理解回答”。前者更稳，后者更自然，根据你的使用场景选。

4. 踩坑实录：本地知识库项目里的高频问题与排查思路

4.1 维度冲突：为什么换Embedding模型后写不进去

这个坑我刚开始就遇到了。一开始觉得nomic-embed-text英文效果好，后来看到一堆文章推荐用中文专用模型，就想着换个模型重新入库。结果代码一跑，Chroma直接报错，提示Collection维度不匹配。

原因就是我在前面反复强调的：Collection在创建时就固定了向量维度。nomic-embed-text输出768维，换成一个输出1024维的模型，老Collection的索引空间还停在768维，新数据自然写不进去。

解决办法很简单，改Collection名，或者删掉旧目录重建。不要想着原地改维度，Chroma不支持。我一般做法是：Collection名称里直接带上模型名，比如internal_kb_nomic、internal_kb_bge，这样一眼就能区分，也避免误操作。

4.2 重复写入和数据膨胀：count()和去重策略

另一个典型问题：脚本跑了两遍，文档被重复写进Collection。向量数据库不像关系数据库有主键约束，你不主动去重，数据就会偷偷膨胀。召回时重复片段还会抢占名额，压掉真正有用的信息，回答质量明显下降。

排查方式很简单，写一行代码看总数：

from langchain_chroma import Chroma from langchain_ollama import OllamaEmbeddings vectorstore = Chroma( collection_name="internal_kb", persist_directory="./chroma_db", embedding_function=OllamaEmbeddings( model="nomic-embed-text", base_url="http://localhost:11434" ) ) print(vectorstore._collection.count())

如果这个数字和预期的文本块数量不一致，说明有重复。我现在的习惯是入库前先检查Collection是否存在，存在就跳过，或者用Metadata里的文件更新时间字段做增量更新。写去重逻辑前先想清楚你的文档变化频率：如果文档是一次性导入，直接跳过已有Collection最简单；如果文档会更新，建议按文件名加更新时间做过滤。

4.3 召回答案偏了：分块策略和文档切割边界

最让人头疼的问题不是技术报错，而是系统不报错，回答内容却总偏。明明文档里有正确答案，大模型却答不上来，或者答非所问。

这种问题的根子几乎都在分块策略上。举个例子，我有一份制度文档，里面是一条条规定，每条之间用空行隔开。RecursiveCharacterTextSplitter按默认的["\n\n", "\n", " ", ""]顺序切，虽然能看到空行，但如果块大小设得太小，它会在单条规定中间硬切一刀，把一条完整制度劈成两半。检索时召回的只是半条，大模型自然给你一个残缺答案。

我的解决办法是：切分规则要和文档结构对齐。Markdown文档可以按#、##标题解析，PDF可以按章节标题分块，不要一律按字符数蛮横地切。LangChain里还有MarkdownHeaderTextSplitter这类针对性更强的切分器，把标题层级作为切分边界，效果通常远好于纯字符切分。

4.4 常见问题速查表

我把实操中容易遇到的几个问题整理成一张速查表，方便你排查时直接对照。

4.5 一个绕不过去的点：Embedding模型的选择

谈到中文召回，这个问题绕不开。很多人图省事直接用默认的nomic-embed-text，但实际测试下来，它对中文的支持只能说及格。我的经验是：如果你的语料以英文为主，用nomic-embed-text完全够；如果知识库主体是中文，建议换用bge-m3或者其他中文优化过的Embedding模型。这类模型对中文语义、成语、行业术语的理解明显更有优势。

换了模型之后记得重建Collection，长痛不如短痛。先确认模型已通过Ollama拉取：

ollama pull bge-m3

然后把代码里的Embedding模型名替换掉，重跑入库脚本，检索效果会有一个肉眼可见的提升。这个替换成本不高，却往往能解决“老是召不回正确答案”的大难题。

5. 再往前一步：Chroma在生产环境中的实际用法与边界

5.1 Metadata过滤：给知识库加上“分类检索”

如果你的文档来源多样，比如有HR手册、技术文档、项目记录，混在一个Collection里，检索时就容易出现跨域串扰。你问一个技术问题，系统却把HR制度也捞进来。这时候Metadata过滤就派上用场了。

入库时给每个Document带一个source标签：

from langchain_community.document_loaders import DirectoryLoader, TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_chroma import Chroma from langchain_ollama import OllamaEmbeddings loader = DirectoryLoader( "./docs/tech", glob="**/*.md", loader_cls=TextLoader ) docs = loader.load() for doc in docs: doc.metadata["source"] = "tech" doc.metadata["filename"] = doc.metadata.get("source", "") splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50) chunks = splitter.split_documents(docs) embeddings = OllamaEmbeddings( model="nomic-embed-text", base_url="http://localhost:11434" ) vectorstore = Chroma.from_documents( documents=chunks, embedding=embeddings, persist_directory="./chroma_db", collection_name="internal_kb" )

检索时通过where参数限定范围：

retriever = vectorstore.as_retriever( search_kwargs={ "k": 4, "filter": {"source": "tech"} } )

5.2 备份、并发和生命周期管理

Chroma的持久化方式让我觉得很安心的是，一个目录就是整个库。备份时直接复制目录，恢复时把目录放回去就行。升级版本前先备份，这个习惯能避免很多意外。

并发方面我得提醒一句：Chroma对并发支持有限，尤其多线程同时写同一个Collection，很容易遇到锁竞争。我现在的做法是写入操作集中到一个进程里，批量完成；检索操作可以正常并发，因为读操作相对安全。如果你预期写入频繁且并发高，就要考虑上服务端模式甚至换方案了，但个人知识库场景基本用不到。

生命周期管理也要想清楚：知识库不是一次建好就完事的。文档更新后，你要么按filename过滤出旧文本块，删除后再写入新的；要么在metadata里加一个version字段，更新时整体重建。我倾向于在文档变化不频繁时直接用整体重建方案，简单可靠，省去大量去重和矛盾处理的成本。

多说一句，我在实际使用中最大的体会是：不要迷信“更复杂的方案一定更好”。在本地知识库这个场景，工具链的能力冗余往往没有意义。Chroma这种轻量方案反而能让日常维护变得透明简单。

5.3 与业务系统集成的一点建议

最后给一个集成层面的建议。如果这个本地知识库要嵌入到团队工具里，比如做成一个内部问答机器人，建议把RAG链路封装成一个独立服务，提供两个接口：一个接收文档做增量入库，一个接提问返回回答。这样业务方不需要关心底层到底是Chroma还是别的东西，只要调用接口即可。等哪天数据量真的涨到Chroma扛不住，你换后端的成本也只是内部实现变化，对外接口完全不用动。

至于要不要把对话历史也存下来，取决于你的场景。如果是单轮问答，当前代码已经够用。如果需要多轮对话，建议自己维护一个history列表，把历次问答拼进Prompt，同时注意历史信息不要喧宾夺主，始终以检索出的资料为准。这个思路本质上是让Chroma只负责精准召回，让大模型负责把召回内容组织成通顺、符合语境的回答，各司其职，整个链路反而更可控。