动手学RAG：从零构建企业内部知识库问答系统

前几天帮一位朋友做内部知识库问答，对方提了一个很典型的诉求：团队文档几百份，散落在各台电脑和共享盘里，想用一个问答窗口直接查，比如“上季度项目验收要点是什么”，系统直接给答案，还要标注来源。我试着先做一轮粗暴的关键词检索，效果很差——明明文档里有，答案就是捞不上来。折腾了一圈之后，我意识到真正要做的不是所谓“更强搜索”，而是把大模型和检索拼起来，用上下文喂给模型。这就是RAG，检索增强生成。整个项目从想法到跑通大概花了一天半，我把过程中踩的坑、能用的代码、调优思路都整理在这篇“动手学RAG”里，适合刚接触大模型应用、想快速搭一个知识问答系统的朋友。

1. 为什么我现在才认真写一篇RAG动手笔记

先交代背景。过去我在业务里直接让大模型“硬答”问题，结果大家也猜得到，模型一本正经编答案，特别是私域知识，它根本没学过。一段时间里我几乎把提示词技巧翻了个遍，效果有改善，但核心问题没解决：模型的知识来自训练数据，数据截止日期一过，或者信息太内部，它就无能为力。

RAG的思路其实很朴素——模型不知道没关系，我们先把相关资料“找出来”，和用户问题一起丢给模型，让它基于资料回答。早几年助手类产品就有人这么干，但那时候检索质量和模型理解都不太理想。现在大模型的能力强了，这一步才变得特别值得做。我用一句话跟同事解释：RAG不是让模型“记住”你的文档，而是让模型“现场翻书”。

落地上它和微调是两条路。微调是修改模型的参数，让模型本身记住知识，成本高、周期长、更新麻烦；RAG则是把文档切成小段、转成向量，存进索引，问答时先检索再让模型阅读理解。文档更新，索引更新就行，模型完全不用动。绝大多数“又想快、又想省、又要及时更新”的内部知识问答场景，RAG就是性价比最高的方案。

这篇笔记我刻意写得“动手优先”。先拆解最小工作流，再给一段可以直接跑通的中文示例代码，然后集中讲我实测遇到的三个翻车点，最后补充让RAG从“能用”到“好用”的优化路线。我个人体会是，RAG的门槛不在搭建，而在搭建之后对细节的调校，比如分块怎么切、检索取多少条、上下文怎么拼。这些细节如果不亲手跑一遍，看再多原理也不会有体感。

2. RAG的最小可跑闭环：五步拆给你看

要真正动手，脑子里得先有一幅完整地图。RAG从一份原始文档到回答用户问题，拢共就五步，每一步要完成什么、会产生什么中间产物，我逐一讲清楚。

2.1 文档加载：把每个人手头的文件变成统一文本

第一步是把PDF、Word、Markdown、网页这些乱七八糟的格式，全部抽取成干净文本。这一步容易被低估，但实际坑最多。PDF有两栏排版、有扫描图片、有表格，直接按文本提取会错乱；Word里嵌的批注会混进正文。我的经验是：先解构文档的结构，再决定提取方式，不要一个库硬扛所有格式。

这一步的产出是一批“干净的文本块”，还不能直接切分，因为原始文本里往往有标题层级、段落编号等结构信息，结构是后面智能分块的重要依据。

2.2 文本切分：把长文档截成适合向量检索的片段

大模型输入长度有限，向量检索也以片段为单位，所以必须切分。最简单的是按固定字符长度硬切，比如每512个字切一块，相邻块重叠32个字。但这样会把一个完整段落拦腰斩断。更稳妥的是按标题层级做递归切分，优先保持章节完整，超长章节再继续切。

这里要理解一个关键设计：切分大小决定检索精度。切得太短，语义不完整，“项目验收要点”和“项目验收时间安排”本来一句话能讲清楚，可能被分成两段；切得太长，向量近似度会被无关内容稀释，而且喂给大模型的上下文也更容易超限。后面我会专门展开参数怎么定。

2.3 向量化：让计算机能“比较”两段文字是否相关

切好的文本块要进入向量索引，就得先通过嵌入模型转成高维向量。简单理解，嵌入模型把一句话变成一串浮点数，语义相近的句子，它们的向量在空间里的距离也相近。“报销流程怎么走”和“如何提交报销申请”字面不同，向量却很接近，这是向量检索能超越关键词检索的核心原因。

选嵌入模型要留意语言适配度。中文场景下，通用的多语言模型能用，但专为中文优化的开源小模型效果更稳，我后面会给对比。向量维度也很重要，模型输出可能是768维或1024维，维度越高信息越丰富，但存储和计算成本也更高，要按文档量选。

2.4 向量检索：查索引，取出最相关的TopN片段

用户提问时，同样用嵌入模型把问题转成向量，再到已经建好的向量库里做“最近邻搜索”。“最近邻”就是把用户问题向量和所有文档块向量算距离，距离最近的K个块就是最相关的上下文。

这个K值是最值得反复调的一个参数。K太小，可能漏掉正确答案；K太大，会把大量不相关内容塞进上下文，模型注意力被干扰，反而答不准。常规场景K取4到8，但要看你对精度的要求，也要看每块文本的长度。

2.5 生成：把问题和检索片段拼进提示词，交给大模型

最后一步是把检索结果按一定格式拼入系统提示词，例如：

请根据以下资料回答问题，如果资料里没有明确信息，直接回答“资料中未找到相关说明”。不要编造。
资料1：...
资料2：...
问题：...
答案：

这一步的提示词设计很讲究。基础版是“把资料贴进去”，但生产环境我还会加三个要素：一是引用来源要求，让模型在回答末尾标注引用了哪个片段；二是拒绝编造指令；三是限定回答格式，别让模型自由发挥太久。把生成这一步和前面的检索分开看，你就能理解为什么RAG调优往往卡在“检索结果为0”或“检索结果太杂”，这会直接决定生成质量。

3. 从零手写一个能问答的RAG小引擎

光讲流程不够，下面我给出一个最小实现。这段代码不用任何重型框架，用最直白的方式把五步串起来，方便你逐行理解。我把调用外部服务的部分都替换成“通用接口”，你可以按自己的环境和账号填入具体实现。

3.1 准备工作与目录结构

我建议先新建一个项目目录，里面放一份测试文档，比如一个把常用业务规则写在里面的TXT文件。项目结构大概是：

code复制project/
├── documents/
│   └── internal_rules.txt
├── simple_rag.py
└── vector_index.json

我用JSON文件做小型向量索引，完全够演示；如果是几万条数据，换成专门向量库更合适，思想上没有任何区别。

安装依赖时，核心是三个组件：嵌入模型接口、大模型接口、基础向量运算库。我强烈建议直接用一个虚拟环境，避免依赖混乱。动手前还要确认有一台能联网的环境，大模型接口申请好Key并能正常调用，这是最容易卡住的前置环节。

3.2 核心流程代码

以下是simple_rag.py的主体，我加了详细注释：

python复制import json
import numpy as np


def load_document(path):
    """第一步：读文档并简化清洗。"""
    with open(path, encoding="utf-8") as fp:
        raw = fp.read()
    # 这里只做基本清洗：去掉连续空行、统一换行符
    lines = [line.strip() for line in raw.splitlines()]
    text = "\n".join([line for line in lines if line])
    return text


def split_text_fixed(text, chunk_size=512, overlap=32):
    """第二步：固定长度+重叠切分。"""
    chunks = []
    start = 0
    n = len(text)
    while start < n:
        end = min(start + chunk_size, n)
        chunks.append(text[start:end])
        if end == n:
            break
        start = end - overlap
    return chunks


def embed_chunks(chunks):
    """
    第三步：向量化。
    这里用端口占位：调用你选择的嵌入模型接口。
    核心要求是返回一个二维数组，每行对应一个chunk。
    """
    # 示例占位逻辑，跑通时替换成真实嵌入调用
    # vectors = your_embed_model.encode(chunks)
    # return np.array(vectors)
    # 下面这行用于演示，随机生成等长向量
    rng = np.random.default_rng(42)
    return rng.random((len(chunks), 256), dtype=np.float32)


def build_index(chunks, vectors, index_path="vector_index.json"):
    """把向量落盘。生产环境请换为向量数据库。"""
    data = {
        "chunks": chunks,
        "vectors": vectors.tolist(),
    }
    with open(index_path, "w", encoding="utf-8") as fp:
        json.dump(data, fp, ensure_ascii=False, indent=2)


def load_index(index_path="vector_index.json"):
    with open(index_path, encoding="utf-8") as fp:
        data = json.load(fp)
    chunks = data["chunks"]
    vectors = np.array(data["vectors"], dtype=np.float32)
    return chunks, vectors


def cosine_similarity(vec1, vec2):
    """余弦相似度，值越大越相关。"""
    dot = np.dot(vec1, vec2)
    norm1 = np.linalg.norm(vec1)
    norm2 = np.linalg.norm(vec2)
    if norm1 == 0 or norm2 == 0:
        return 0.0
    return dot / (norm1 * norm2)


def retrieve(query, chunks, vectors, k=5):
    """第四步：检索TopK。"""
    # query_vec = your_embed_model.encode([query])[0]
    rng = np.random.default_rng(0)
    query_vec = rng.random(256, dtype=np.float32)

    scores = []
    for i, vec in enumerate(vectors):
        sim = cosine_similarity(query_vec, vec)
        scores.append((sim, i))
    scores.sort(key=lambda x: x[0], reverse=True)
    top_matches = scores[:k]
    results = []
    for sim, idx in top_matches:
        results.append({
            "chunk": chunks[idx],
            "score": round(float(sim), 4),
        })
    return results


def generate_answer(question, context_items):
    """
    第五步：拼提示词，调用大模型。
    把下面这部分替换成你实际使用的大模型接口。
    """
    context_text = ""
    for i, item in enumerate(context_items, start=1):
        context_text += f"\n资料{i}（相关度{item['score']}）：{item['chunk']}"

    prompt = f"""
你是一个严谨的问答助手。请只根据提供的资料回答。
回答结束时，用[来源:N]的形式标注使用了哪份资料。
如果资料不足以回答，直接说“资料中未找到相关说明”，不要编造。

资料：
{context_text}

问题：
{question}

回答：
    """
    # 下面是占位返回，实际运行时请调用大模型接口
    # response = your_llm_call(prompt)
    return f"(演示模式) 检索到{len(context_items)}条资料，提示词构造完成。\n{prompt}"


if __name__ == "__main__":
    text = load_document("documents/internal_rules.txt")
    chunks = split_text_fixed(text)
    vectors = embed_chunks(chunks)
    build_index(chunks, vectors)

    chunks, vectors = load_index()
    question = "项目验收需要提交哪些材料"
    result = retrieve(question, chunks, vectors, k=5)
    answer = generate_answer(question, result)
    print(answer)

3.3 把占位调用替换成真实组件

我把示例里的随机向量替换成真实实现时，踩了一个隐蔽的坑。一开始图省事，让文档块和用户问题用不同方式向量化，导致检索相似度整体漂移，结果一律不准。后面统一成同一个嵌入模型、同一个预处理逻辑，才恢复正常。

真实接入时，你只需要替换三个占位处：

• embed_chunks 里换成嵌入模型调用；
• retrieve 里换成对用户问题调用同一个嵌入模型；
• generate_answer 里换成大模型接口。

跑通这个最小版本之后，你就有了一套自己的RAG骨架。剩下的所有调优，都在这段骨架周围加肉。

4. 真正跑起来之后，最容易翻车的三个地方

这一部分我原本不想写，因为网上教程都默认你代码一跑就完美。实际不是这样。我自己调试时，有三次差点怀疑是嵌入模型的锅，最后都发现是设计细节的锅。我按排查的先后顺序列出来，你会发现这些坑有很强的“传染性”。下面是原因、现象、排查过程和解决方向。

4.1 分块把语义切碎了，模型翻不到答案

现象：检索结果看着每一条都沾边，可答案就是模棱两可。比如一句话的完整逻辑“仅当项目验收通过，且合同款项结清，才能申请尾款支付”，被固定512字符切分拦腰斩断，后半句孤零零变成“才能申请尾款支付”，这个半截片段在向量空间里会往奇怪的方向偏。

排查方法很简单：把检索出来的原始片段打印出来，一条条看。我以前懒得看，靠相似度分数判断，分数高还以为是好事。后来发现有一段相似度0.83，但内容只剩半句话，完全没法用。

我后来把固定切分改成了结构化切分：优先按Markdown标题、段落、句子层级切；标题下面内容过长时，再按“句子窗口”往下切。简单起见，也可以做一个“按段落先切，段落超长再切”的函数。给分块加上重叠也非常有效，重叠量一般是切分长度的5%到10%。

分块参数参考维度整理成表格：

4.2 TopK调参不当，信息过多把模型带偏

第二个高发坑是K值。一开始我贪心，K设成20，想着多喂点资料总不至于错。结果模型面对二十段来源混乱的资料，注意力完全分散，回答里混着好几处自相矛盾。尤其是资料里有相似项目时，模型会把两份文档的内容缝合在一起，输出看似流畅实际错误的答案。

调参思路：先在开发环境把K从1依次递增到10，每次跑20条固定测试问题，人工判断“答案是否脚踏实案、是否有幻觉”两个维度。大多数内部知识问答，K落在4到6最稳。此外，我还会给每条检索结果设一个“及格线”相关性阈值，低于阈值直接丢弃。宁可让模型说“不知道”，也不要让它拿弱相关内容硬答。

这里还要提醒一点：不要只看TopK准确率。TopK准确率高，不代表生成答案好；片段之间内容重复，模型会把重复信息当成强调，越自信越危险。所以我在拼提示词前会做一轮“去重折叠”，内容相似度高于阈值的碎片只留一条。

4.3 中文检索里的“字面看似相关，语义南辕北辙”

第三个坑，也是中文场景特有的。通用的多语言嵌入模型在中文长尾语料上表现没那么稳定，特别容易受同词干扰。比如“甲方逾期付款”和“甲方逾期验收”都含有“甲方”“逾期”，向量距离非常近，但问题问的是付款违约条款，检索结果却可能全是验收条款。

我曾经以为是切分问题，调了半天分块长度，效果不大。最后把嵌入模型换成中文语料优化过的版本，同一条测试问句，命中立刻靠谱了很多。嵌入模型的选型对中文用户来说，优先级非常高。

选型时我不建议直接看某个模型的总分，最好用你自己的几十条业务问题+文档片段做小评测。把文档里每个片段手动标注上“回答哪个问题需要用”，然后跑一遍全流程，统计前5命中率，比任何排行榜都可信。成本不高，但能避开很多“评测集里很强、实际业务很虚”的模型。

整体对比维度如下：

5. 从“能用”变成“好用”：我验证过的优化路径

最小闭环跑通以后，我建议先别急着加很多花活。RAG系统的收益，本质由“检索质量”和“生成质量”两条腿决定。两条腿都要有量化评估，不然你加再多元件也不知道是变好了还是变坏了。这一节我重点讲三件事：评测集怎么搭、检索怎么补强、生成怎么稳住。

5.1 先给自己建一套评测集，不然优化全是盲人摸象

我吃过一个亏：随手找几个问题测了两轮，觉得召回不错，上线后却被报告“很多问题找不到答案”。问题在于我测的几句话结构简单，而真实用户问题五花八门，有缩写、有口语、有错别字。从那以后，任何RAG项目我都先建评测集。

评测集不需要很复杂，20到50条就够了。每条三个字段：用户问题、期望命中的文档ID、期望答案要点。我会从真实聊天记录和用户反馈里挑，没有真实来源就自己模拟。评测指标也不一定要算RA@K这些指标，手工过一轮，记录三档评价：回答正确、回答有误、直接没找到。跑几轮优化后回看，比对改进方向是否有效。

这套最小评测集直接决定了后面的优化能不能落地。没有它，你可能调了一周，最后只是自我感觉良好。

5.2 重排序：向量召回之后再粗排一次

向量检索擅长找“语义相关”，但不擅长精确判断“哪一条最配得上这个问题的答案”。我做得最多的一个优化，是在检索和生成之间加一个重排序步骤。

具体做法：先用向量检索召回10到20条候选片段，再用一个交叉编码器或者更轻量的排序模型逐条和问题打分，最后取前3到5条送给大模型。这就像先通过网络搜出一堆相关页面，再由编辑快速精读，挑出真正有用的几页。代价是多了一次排序计算，但生成质量的提升非常明显。

重排序还有一个副作用：可以顺便做“硬负样例”过滤。如果候选片段和问题相关性低于某个阈值，直接干掉，减少上下文污染。如果你不想引入额外模型，也可以用规则粗排：含有问题关键词多的片段排前，标题层级更深的排后，低成本也能有一点效果。

5.3 混合检索：把向量和关键词优势叠起来

向量检索不是万能的。像合同编号“CT-2024-0089”、产品型号“X7-Pro”这种精确片段，向量检索往往把语义接近的一堆内容都捞上来，精确字符串优势却发挥不出来。这时候关键词检索反而更可靠。

所以生产环境我更倾向于混合检索：一路走向量召回，一路走BM25倒排索引或全文搜索，两路结果做加权合并。加权系数通常向量0.7、关键词0.3起步，具体根据你文档特点调整。代码合同类的精确查找场景，关键词权重可以提高；自然语言问“有哪些风险控制措施”则向量权重更大。

这是我在一个项目里的真实体验：纯向量检索精确ID的能力很弱，加上关键词召回后，相关命中稳定提升。遇到“用户能准确复述某个编号，但模型始终找不到”的情况，不妨先查这一条优化。

5.4 生成侧的提示词与引用控制

检索侧优化到了瓶颈后，生成侧还能挤出不少空间。我总结出一套“克制式提示词”模板，核心原则是：限定要求、限定来源、限定不知道时的行为。

在上一章的generate_answer里已经给出过雏形，生产环境我会再补一句：

回答时只能使用资料中出现的信息；每个关键断言后方的来源编号不得隐瞒；若多个来源存在冲突，请明确指出冲突而非自行调和。

这句指令解决了两个常见问题：一个是模型爱“脑补细节”，另一个是不同文档间说法不一致时，模型倾向于强行缝合，制造不存在的“统一口径”。加上明确要求后，模型会主动提示“资料A说法与资料B说法不一致，需要人工确认”，这对企业场景是重要能力。

引用控制也很关键。我要求模型在输出格式上严格给引用标记，比如“根据资料2”，然后我在前端把资料2高亮出来。这不仅是体验问题，更是信任问题——用户能看到回答有依据，才算真正用起来。

5.5 缓存与增量更新，决定能否长期用

最后一个容易被忽略的方面是工程可持续性。很多RAG小项目跑通后就被扔在一边，因为文档一更新，索引就过期。我梳理了一套穷但实用的策略：

• 文档切分后给每个文本块计算哈希，只有哈希变化的块才重新向量化；
• 问题级缓存：相同问题直接返回历史答案，节省大模型调用成本；
• 向量库按文档集合打标签，支持局部删除再重建，不必全量重跑。

这些策略看起来普通，却是从“演示项目”走向“长期服务”的关键。一个每周都要手工重建索引的系统，很快就会被人弃用；一个能自动感知更新的系统，才可能真正融入工作流。

结束前，我再分享一个具体的小习惯：每次跑RAG实验，把检索结果、提示词、最终答案一起存成一条日志。这个日志不仅是排查问题的依据，也相当于给你自己积累了一套“哪些问题容易失败”的案例库。后续任何调优，先翻日志，再动手，效率高很多。

RAG的难度曲线其实是在前几步。只要亲手搭一遍最小闭环，你会发现它并不神秘，真正费心思的是后面那些检索细节、评测和工程化。这套东西我做下来最大的体会是：不要追求一步到位的“完美RAG”，先让它跑起来，再让评测告诉你往哪里优化。你可以从今天那份最常被别人问起的内部文档开始，把它变成第一个能回答问题的RAG小引擎。