企业官网建设流程全解析

如果你跟我一样，电脑里散落着几百篇技术笔记、几十个 Markdown 文档，偶尔还有几个 PDF，平时想找一条自己以前总结过的结论，翻半天翻不出来，那你大概率会需要一套“个人知识库问答”系统。简单说，就是让自己的文档变成能聊天问答的资料库：你抛出一个问题，系统先召回最相关的段落，再让大模型结合这些段落生成回答。这个场景本质是 RAG（检索增强生成），而向量数据库是它的地基。我最近用 ChromaDB 在本地把整条链路跑通了，过程不复杂但细节不少，这篇就把完整技术实现方案拆开讲清楚，包括怎么分块、怎么入库、怎么调参，以及我踩过的坑。

1. 整体思路拆解

1.1 一个“个人知识库问答”到底在做什么

先别急着写代码，想清楚架构再动手，能省一半返工时间。个人知识库问答，表面上是个聊天框，实际背后是两条完全不同的流水线：第一条是“建库”，把已有的文档切成小块、转成向量、存进数据库；第二条是“问答”，把你的问题同样转成向量、去库里找回最相近的文本块、把文本块喂给大模型让它组织答案。

这就是 RAG 的标准套路。它解决的核心问题有两个：一是大模型不知道你私有的内容，你没法只靠模型本身回答“我上个月记录的那个配置方案是什么”；二是文档太多了，不可能塞进一次对话的上下文里，必须先靠检索把范围缩小到最相关的几段。用生活化的比喻来说，向量数据库就好比一个图书管理员，他不需要背下馆里所有书，只需要知道你问的“大概在哪个书架的哪本里”，然后精准地把那几页递给你；大模型则像一个表达能力很强的助手，拿到这几页材料后，用自己的话把答案讲清楚。

所以整个系统的性能天花板不在模型，而在“图书管理员”找得准不准。检索召回质量决定了答案的地基，这也是为什么我会花大量篇幅讲分块策略和检索调优。

1.2 向量数据库这么多，为什么选 ChromaDB

选型这一步我对比过几类方案，这里直接给结论。业界常见的向量数据库有 Faiss、Milvus、Elasticsearch 的向量插件、Qdrant，还有 ChromaDB。它们的定位差别还挺大：

我选 ChromaDB 的理由很实在：个人知识库里文档数量撑死了也就几万块文本，ChromaDB 是嵌入式数据库，不需要单独部署服务，数据直接落在一个本地目录，启动就是chromadb.PersistentClient一行代码的事。它原生就在 Python 生态里，支持自定义 Embedding 函数，而且内置了 SQLite 的元数据过滤，能非常方便地按来源、标签、日期筛数据。对于“自己攒了一套笔记，想在上面做问答”这种需求，它属于杀鸡用牛刀正好合适的那把刀。

当然，如果以后数据量真的大到几十万甚至上百万向量，再迁移到 Milvus 也不迟。因为 RAG 的架构是通用的，换向量库只是换一个 Client 对象而已。

2. 环境准备与工具选型

2.1 基础运行环境

先铺垫好基础环境。我用的是 Python 3.10，ChromaDB 对 Python 版本要求不算苛刻，3.9 及以上都行。安装也直接：

pip install chromadb

它会顺带把numpy、onnxruntime、sqlite-vec这些依赖装上。注意一点，ChromaDB 是老版本依赖底层 SQLite 的某些特性，如果你在很老的 Linux 机器上装完启动报sqlite3相关错误，大概率是系统自带的 SQLite 版本太低，升级系统库或者换台新环境是最省事的解法，Windows 和 macOS 上一般不会遇到。

如果后续要处理 PDF、Word 这类非纯文本文件，建议把文档解析库一起装上，比如pypdf、python-docx，我会在第三章讲加载环节的具体用法。另外，如果你打算把知识库问答服务包装成一个网页或者接口，那就再加一个 FastAPI，这个不影响主流程，后面可以随时补。

2.2 Embedding 模型怎么选：中文场景是关键

Embedding 模型决定文本块在向量空间里的“坐标”准不准。同样一句话，好的中文 Embedding 模型能把它和语义相近的句子拉近，差的模型则可能因为语言不支持而把向量做得乱七八糟。

ChromaDB 自带一个默认的DefaultEmbeddingFunction，也就是all-MiniLM-L6-v2这个轻量级模型，英文效果尚可，但中文效果非常一般，实测中文召回经常“答非所问”。所以如果你的知识库以中文为主，务必换一个中文友好的 Embedding 模型。我梳理了几类选择：

我自己的知识库是中文技术笔记为主，最后选了中文开源模型，配合自定义 Embedding 函数接进 ChromaDB。做法是在 ChromaDB 的EmbeddingFunction接口上做一个薄封装，把“加载模型 + 编码文本”的逻辑包进去，具体代码我放第四章。

2.3 大模型接口怎么接：API 还是本地部署

RAG 的最后一跳是让大模型基于检索结果生成答案。这一步你有两个选择：接各家大模型服务的 API，或者在本地部署开源模型。API 方式省事、效果稳定，缺点是成本和隐私，个人知识库如果包含私人笔记，很多人会介意送出去；本地部署则能保证数据完全不出机器，但需要一定显存。

我的建议是：先把链路跑通时用 API 方式，因为可以直接看到检索部分的效果；等系统稳定了、确有隐私需求，再把模型替换成本地部署的开源模型。两者的调用代码只差一个函数体，不影响整体架构。为了演示通用性，第四章里我会保留一个call_model(context, question)的抽象函数，你自己接 API 还是本地推理，都在里面改。

3. 核心流程实现

3.1 文档加载与清洗：脏数据进库等于白做

很多人忽略这一步，觉得把文本塞进去就行。实际上，笔记里通常混着大量的 Markdown 语法符号、代码块、表格符号、PDF 里解析出来的乱码、行号、页眉页脚。这些东西直接切块的话，不仅浪费 token，还会把语义向量搅浑。比如一篇笔记里如果每个段落前都有“##”符号，模型编码出来的向量重心会偏向格式噪声而不是内容。

我的一般流程是：先按文件类型读取文本，Markdown 和 TXT 用open()直接读，PDF 用pypdf抽取，Word 用python-docx抽取。读进来之后做几轮正则清洗：去掉多余的换行和空格、统一全半角符号、移除 Markdown 图片链接和语法标记、压缩连续空行。代码块内容我会单独标记为“code”类型，因为代码的分块策略和自然语言不同，混在一起会让问答效果变差。

清洗完的文本要保留一个“原始文件路径”字段作为元数据，方便以后追溯这个段落来自哪篇文档。这个习惯非常重要，后面排查错误答案时，你能靠它快速定位是哪一段材料在误导模型。

3.2 分块策略：切多大、要不要重叠

分块是整个流程里最吃经验、也最影响召回效果的环节。块太大会把多个主题混在一起，向量被“平均”掉，检索时匹配不准；块太小则可能把一个完整观点拦腰截断，模型拿到的上下文不完整。我实验下来，中文技术笔记用 400-600 字作为一个块比较合适，英文可以适当放大到 500-800 个 token。

除了块大小，块与块之间的重叠（overlap）也很关键。我用的策略是：每块 500 字，重叠 80 字。这样既能保证相邻块之间的上下文是连贯的——被切在边缘的句子不会凭空消失，又能控制总量。别小看这个设计，没有重叠时，我在实测中经常发现召回结果里头尾段落的意义缺失，特别是那种“上一段末尾其实在解释下一段概念”的笔记。

不同类型的内容还需要微调：代码笔记建议按函数或代码块切，而不是按固定字数硬切；表格类内容建议一行一行的关键信息保留，而不是把整张表塞进一个块。这些细节靠一个规则函数来分发处理，别用一刀切的长度参数。

3.3 分块策略：重叠切片的具体实现

切块代码看起来简单，但边界处理容易踩坑。我习惯用一个基于字符窗口的切分函数，并用start += step的滑动方式实现重叠。核心逻辑是：

def split_text_into_chunks(text, chunk_size=500, overlap=80): chunks = [] start = 0 n = len(text) while start < n: end = start + chunk_size chunk = text[start:end].strip() if chunk: chunks.append(chunk) if end >= n: break start = end - overlap return chunks

这样切出来的是固定窗口，虽然不是语义级分块，但对于笔记类文本已经够用。如果你想要更智能一点，可以按“先按段落分，再把小段落合并到接近 500 字，最后对超过上限的大段落做滑动切分”的思路写个多级分块器，效果会更好，但开发量也大。我自己是从固定窗口起步的，先跑通再优化，这个路线更适合大多数个人项目。

3.4 元数据与 ID 设计：数据管理的命根子

向量库里每一条记录除了document和embedding，还会带id和metadata。id必须是唯一的，它决定了后续的更新、去重、删除能不能精准操作。我把id设计成语义稳定的字符串，比如blog-20241201-003这种格式，代表“来源类型-日期-序号”，这样即使重跑入库，相同来源相同位置的文本块也会得到相同 ID，配合upsert操作天然实现增量更新。

metadata里我会存这些字段：来源文件名、章节标题、文档类型（笔记/代码/PDF）、创建时间、标签列表。为什么这么设计？因为问答场景里“过滤”太常用了。比如你想只在自己的 Java 笔记范围内提问，只需要在查询时加一个where={"doc_type": "java_note"}，ChromaDB 会先把向量库按元数据过滤一遍再做相似度检索。没有元数据，过滤就无从谈起，所有问题都得在全库范围碰运气。

4. 代码实战

4.1 初始化客户端：一种连接、三种用法

ChromaDB 的用法有三种：临时内存模式、本地持久化模式、服务端模式。我们个人知识库场景，直接用本地持久化模式，数据落在磁盘，重启不丢。初始化代码非常简单：

import chromadb from chromadb.config import Settings client = chromadb.PersistentClient( path="./kb_store", settings=Settings(anonymized_telemetry=False) )

path参数指定数据存放目录，所有向量、元数据和索引都会落在这里。Settings(anonymized_telemetry=False)是关闭匿名统计上报，个人隐私意识强的话建议加上。启动之后你可以用client.list_collections()检查目前已经建了哪些集合，这个命令在排查问题时非常有用，后面第五章会讲。

需要注意的一点是，同一套代码如果换成chromadb.Client()，就变成内存模式，退出即丢失，千万别在生产路径上用；而服务端模式需要额外启动一个 Chroma 服务进程，当前阶段完全用不上。

4.2 创建 Collection：把 Embedding 函数绑定上去

Collection 可以理解为一张“专属于某个主题的向量表”。比如你可以把“工作笔记”和“读书笔记”分成两个 Collection，也可以都塞进一个 Collection 然后用metadata区分。我更推荐后一种：Collection 越多，查询时越容易搞混边界；而一个 Collection 加元数据过滤，灵活性反而更高。

创建 Collection 的核心是绑定 Embedding 函数。如果你用的是 ChromaDB 内置的默认模型，直接get_or_create_collection(name="personal_kb")就行；如果你和我一样接自定义中文模型，就要把封装好的函数传进去。同时我建议显式指定距离算法：

collection = client.get_or_create_collection( name="personal_kb", embedding_function=my_embedding_func, metadata={"hnsw:space": "cosine"} )

hnsw:space有三个可选值：l2（欧氏距离）、ip（内积）、cosine（余弦相似度）。语义检索一般用cosine，因为它只关心方向不关心向量的模长，对 Embedding 模型输出的归一化程度不敏感，稳定性最好。如果你的 Embedding 模型本身做了归一化，ip和cosine等价，但为了省心，统一用cosine别纠结。

4.3 文档入库实战：从清洗后文本到向量

入库环节就是把前面准备好的文本块、ID、元数据一次性塞进 Collection。以我的一篇 Markdown 笔记为例：

ids = [f"blog-20241201-{i:03d}" for i in range(len(chunks))] metadatas = [ { "source": "python_notes.md", "doc_type": "markdown", "created_at": "2024-12-01", "tags": ["python", "异步"] } for _ in chunks ] collection.add( ids=ids, documents=chunks, metadatas=metadatas )

这里你会看到一个关键点：我们没有手动传embeddings。因为 Collection 创建时绑定了 Embedding 函数，add时会自动调用它对documents做向量化。如果数据量不大（几百个块），这个操作几秒内完成；如果你有个性化需求，也可以提前算好向量，用embeddings参数传进去。不过在 ChromaDB 的 API 里，documents和embeddings二选一即可，不要同时传，否则会报参数冲突。

入库完之后，可以用collection.count()看看总数是不是符合预期。我每次入库都会跑这一句，确保没有因为重复 ID 或者清洗阶段丢数据而产生偏差。

4.4 检索实现：拿到最相关的几个片段

问答的第一步是检索。ChromaDB 的query方法非常直观：

results = collection.query( query_texts=[question], n_results=5, where={"doc_type": "markdown"}, include=["documents", "metadatas", "distances"] )

n_results是返回多少条候选文本，个人知识库一般取 3-5 条就够了，取太多会引入噪音，模型生成答案时容易被不相关片段带偏。where是元数据过滤条件，属于可选项。include参数控制返回哪些字段，注意distances返回的是距离而非相似度：如果你用的是cosine距离，值越小表示越相近，取值范围在 0 到 2 之间。

这里有个实际经验：不要只看 top1，也不要固定只看 top5。我建议把候选结果打印出来看一眼，确认检索到的片段确实和问题相关，再进入生成环节。检索环节不满意，后边再怎么调 Prompt 都白搭。我经常在调试时写一个debug_search()函数，专门把检索结果和距离一起打出来，这样能直观地看到“问题被映射到了什么语义位置”。

4.5 组装 Prompt 生成回答：把素材喂给大模型

检索到相关片段之后，接下来就是生成。这里最容易犯的错误是把所有文本一股脑塞进 Prompt，而是要做轻量整理：把多个候选片段按距离排序，拼接成“参考资料”段落，再附上问题。我常用的 Prompt 模板是这样的：

def build_prompt(question, retrieved_docs): context = "\n\n".join( f"[片段{i+1}] {doc}" for i, doc in enumerate(retrieved_docs) ) prompt = f"""你是一个基于个人知识库的问答助手。 请只依据下面提供的资料回答用户问题，不要使用自身记忆补充。 如果资料中没有相关信息，请直接回答“知识库中没有相关内容”。 资料： {context} 问题：{question} 回答：""" return prompt

这个模板里有两处关键设计。第一是“只依据资料回答”这句约束，它能在很大程度上缓解大模型“不懂装懂”的毛病；第二是“没有相关内容就明说”这一句，这给模型留了一个诚实的出口，而不是强行编造。生成时，我会把大模型的温度调得偏低（0.2 左右），保证答案更贴近资料原文而非自由发挥。

最后把prompt传给call_model()函数。这个函数内部可以用任何大模型 API，也可以调用本地推理框架。我个人把超时处理和重试逻辑放在这里统一管理，这样就算大模型服务偶尔抖动，知识库问答的整体可用性也不会降得太多。

5. 常见问题与排查技巧

5.1 检索结果为空或者答非所问，先查这几处

这是初学者最容易撞上的问题。我梳理了一个排查顺序，按这个顺序查能快速定位：

我特别想强调第二行：如果你在创建 Collection 时没传 Embedding 函数，它默认用内置的 MiniLM；后来你换了中文模型重新建库，但 Collection 名字沿用旧名字，get_or_create_collection会直接返回旧 Collection，它内部的向量还是旧模型生成的，查询时却用新模型编码问题，两个模型的向量空间不兼容，结果自然牛头不对马嘴。解决方式是：要么换一个 Collection 名字重建，要么delete_collection后重建。这也是为什么我强烈建议在 Collection 的metadata里记录当时的 Embedding 模型名，比如{"embedding_model": "bge-zh", "hnsw:space": "cosine"}，防止自己把版本搞混。

5.2 召回质量差：不是模型差，是分块和数量的问题

如果检索回来的片段“看起来有点关系但不够精确”，先反思分块策略。我遇到过最典型的情况是：一篇笔记里有个大表格，整块被切进一个 chunk，表格里的单元格太多导致向量被稀释，问具体某一行数据时，检索出来的却是大表格这种“模糊匹配”。解决方法是把表格按行拆开，每一行（或两行）作为一个独立文本块入库，而不是整表一把梭。

另外，n_results的设置也不是越大越好。5 个结果里，前两个往往精确命中，后三个可能已经开始跑偏。这时候与其加大数量，不如提升质量：我后来给检索链路加了一个“粗排 + 精排”策略，先用 ChromaDB 粗召回 20 个片段，再在内存里按一个轻量重排规则（比如关键词重叠度加权）选出最相关的 5 个，效果明显好于直接取 top5。如果预算允许，接一个专门的重排模型会更稳，但对个人项目来说，规则重排已经能解决 80% 的问题。

5.3 大模型回答“一本正经胡说八道”

生成环节出现幻觉，主要原因是 Prompt 约束不够，以及检索到的片段本身被污染。先说 Prompt，我见过很多人只在模板里写“根据资料回答”，但没说明“资料中没有就直说”，模型就会倾向于用自身知识硬补，这在个人知识库场景里特别危险——因为很多问题恰恰是只有你文档里有答案的。

我的处理方式是三层控制：第一层，Prompt 里强制“只依据资料，不得使用自身记忆”；第二层，把检索到的片段按来源文件名编号列出来，并告诉模型引用时标注来源，默认不加引用就回答时模型会犹豫；第三层，如果你有原始片段的位置信息，可以在回答下方追加一个“参考来源”列表，方便回溯。实际上，第三层是在代码层面做的后处理：拿到生成的回答后，把本次检索到的 source 元数据附在答案后面，这样就算模型真的说错了，你也能很快定位是哪段素材误导了它。

5.4 增量更新、去重和备份

知识库不是建完就不动的，你每天都会写新笔记。ChromaDB 的upsert方法专门用来处理“有则更新、无则插入”的需求，配合我前面设计的稳定 ID，重跑一遍处理脚本就能同步新增和修改的内容。注意，add遇到重复 ID 会直接报错，而upsert不会。

数据备份同样不能忽略。ChromaDB 的持久化目录kb_store本质上是一堆文件，我每天写个定时任务把这个目录压缩归档到另一个磁盘。恢复时只需把目录解压回去，再启动PersistentClient指向它即可。别以为本地数据不重要，我见过一位朋友因为重装系统，整个向量库灰飞烟灭，重新 Embedding 几万条文本的滋味真的不好受。

6. 一些实操上的个人体会

整套系统跑通之后，我最大的体会是：知识库问答这类项目，真正花时间的不是调模型，而是调数据和调流程。分块参数的微调，元数据规范的确立，检索结果的人工抽检，这些环节决定了系统到底好不好用。很多人在 Demo 阶段跑通了就以为大功告成，实际一用发现召回质量稀烂，于是开始怀疑模型不行，其实是前面几步偷了懒。

还有一个小技巧想分享：把“检索结果”和“最终答案”分开展示。我在自己的知识库问答界面上，会先显示命中的文档片段及其来源，再显示模型生成的答案。这样做有两个好处：一是你自己能直观地检查检索是否跑偏，随手发现问题；二是回答里写了什么你都能追溯来源，心里踏实。后续如果想扩展，可以在这个基础上加入全文关键词搜索做混合检索，或者用知识图谱把文档之间的引用关系也建模进去，但那是后话了。先把基础链路做扎实，后面任何扩展都是水到渠成的事。