w wyl123ly 的博客
MD

从零实现RAG指南

49 KB 2026.10.18 原文件

从零实现RAG指南

定义

最小 RAG 系统指只依赖本地语料与确定性组件、可以在无网络环境中完成索引、检索、提示组装、生成与评估的检索增强生成管线。把它写成六元组:

其中各符号含义如下。

符号含义
文档集合,
片段集合,
索引,把查询与片段映射为可比较的表示
检索器,返回得分最高的 个片段
提示组装函数,把查询与片段拼成模型输入
生成器,输出答案或拒答
查询
检索返回的片段数,也是拼入上下文的片段数上限
片段 的向量表示
查询的向量表示
分块长度上限,单位为字符
相邻块共享的字符数
上下文 token 预算

术语定义如下。片段(chunk)是文档切分后的连续文本单元,同时是索引单位与上下文单位。TF-IDF 指以词频与逆文档频率加权、再按向量长度归一化的稀疏表示。余弦相似度指两个向量夹角余弦,等于单位向量点积。top-k 指按得分降序取前 个结果。抽取式生成指答案句子直接取自检索片段、不改写内容的生成方式。拒答指系统判定上下文不足时输出固定字符串而非答案。Recall@k 指相关片段进入前 的比例。context precision 指相关片段在上下文中的位置加权精度。

为什么重要

把各环节接成一条可运行管线,会暴露单看组件时看不到的接口错误。分块器给出的片段编号必须与提示中的引用编号一致;检索器返回的得分必须可排序且可复现;生成器的拒答字符串必须与评估脚本比较的字符串完全相同;评估集的证据片段必须能在索引中找到。任何一处不一致,指标都会归零或虚高,而单测各组件时都不会报错。

不依赖付费 API 使实验可复现。语言模型服务会更新版本、改变默认温度与截断行为,同一条查询在不同日期可能得到不同答案。本指南用 TF-IDF 与抽取式生成器替换这两个不确定环节,索引与答案在相同输入下逐字节一致,指标差异只来自被改动的部分。这使消融实验有意义:改分块大小、改 、改重排器时,观察到的变化可以归因到改动本身,而不是服务端波动。

最小系统给出可测量的下界。稀疏检索加抽取式生成在领域术语密集的语料上表现不差,后续引入稠密检索、交叉编码器重排与大模型生成时,必须证明相对该下界的增量。没有下界,改进只是与上一次实验比较,无法判断绝对值是否合理。RAG原理与流程 给出三阶段的抽象流程,本篇把它落成代码;RAG文档分块策略 讨论的五种分块在本篇实现其中两种;Embedding与向量检索 的余弦相似度在本篇以 TF-IDF 向量实现;检索优化与重排Rerank 与 RAG评估 分别对应后续的排序改进与指标扩展。

本篇的边界同样需要说明。TF-IDF 只匹配词面,不处理同义词与语序,跨语言查询无法工作;抽取式生成器不能改写、不能多跳推理、不能可靠拒答;字符级分块与真实分词器的 token 边界不一致。它是一个可运行、可评估、可替换的最小实现,不是生产系统。生产化的替换点在本篇末尾逐项列出。

原理与推导

1 数据流与接口契约

系统由六个阶段组成,数据流如下。

flowchart LR
    D[文档集合] --> CH[分块器]
    CH --> C[片段集合]
    C --> IDX[TF-IDF 索引]
    Q[查询] --> RT[检索器]
    IDX --> RT
    RT --> P[提示组装]
    P --> G[生成器]
    G --> A[答案或拒答]
    A --> E[评估]

每个阶段有明确的输入输出契约。

分块器输入文档字符串,输出片段列表;每个片段有唯一且稳定的 cid,同一文档在相同参数下重建索引时 cid 不变。cid 用于评估时匹配相关片段,若每次重建都重新编号,历史评估集无法复用。

索引输入片段列表,输出固定维度的向量矩阵;词汇表在索引构建时确定,查询阶段只能使用已有词项,未登录词直接忽略。词表外词项不影响余弦计算的正确性,但会降低召回,这是稀疏检索的固有限制。

检索器输入查询与 ,输出按得分降序排列的 (片段, 得分) 列表;列表长度不超过 ,得分相同按 cid 升序打破平局,保证可复现。

提示组装输入查询与检索结果,输出一个字符串;片段按 1 开始编号,编号与引用编号使用同一套整数。

生成器输入查询与检索结果,输出字符串;拒答时输出与 REFUSAL 完全相同的字符串,评估脚本用字符串相等判断拒答,任何前缀或标点差异都会被判为作答。

评估器输入查询、检索结果、答案与标准证据,输出 Recall@k、context precision 与拒答标记。

语料准备在分块之前完成,包含四步:统一转为 UTF-8;去除页眉、页脚与导航文本;为每篇文档分配稳定且唯一的 doc_id;对完全重复的段落去重。示例语料手工构造,每篇文档由若干行组成,行内以句末标点分隔句子,doc_id 与文件名一致。真实语料若跳过这些步骤,重复段落会同时进入多个片段,评估集的证据子串会在多个片段中命中,Recall 的分母被放大;页眉页脚则成为高频噪声,抬高所有查询的相似度,使不相关片段进入前 。文档版本也应写入元数据,索引更新后旧版本的片段必须删除或标记,否则同一事实的两个版本会同时被召回。

2 分块:固定窗口与递归句子

固定窗口分块把文档视为字符序列。设文档长度为 ,窗口长度为 ,步长为 。第 个窗口的起点为 ,覆盖区间 。若保留末尾不足 的窗口,窗口数为

若丢弃末尾不足 的窗口,窗口数为

重叠率为 。取 、,则 ,重叠率 。固定窗口的块数可预测,块长度整齐,便于估算索引体积;代价是切点与句子边界无关,证据可能被切成两半。示例语料 833 字符、6 篇文档,固定窗口产生 14 段,其中只有 7 段结束在句末标点。

递归句子分块先按句末标点切句,把每句作为原子;句子超过 时按字符硬切。然后从左到右合并原子,合并后长度不超过 就继续加入下一个原子;超过 时输出当前缓冲区,并从缓冲区尾部取若干完整句子作为重叠,总长度不超过 ,再与下一个原子组成新缓冲区。若重叠加新原子仍超过 ,放弃重叠。

在句子长度不超过 时,该算法保证块边界落在句末;句子被硬切时,边界落在字符位置。示例语料上递归分块同样产生 14 段,且 14 段全部结束在句末。两种策略的块数相同而边界质量不同,说明块数不是分块质量的充分指标。

字符级切分是为了让代码不依赖具体分词器。真实系统的上下文预算按 token 计,中文一个汉字通常对应 1 至 2 个 token,英文一个词对应 1 至数个 token。字符数只能作为预算的近似;上线前应改用与生成模型一致的分词器,并按 token 重新标定 与 。

3 检索:TF-IDF 与余弦相似度

设片段 中词项 的出现次数为 ,词频权重取次线性形式

设片段总数为 ,包含词项 的片段数为 ,逆文档频率取平滑形式

平滑的作用是避免 时 使该词完全失效;末尾的加 1 给出下界 1,使高频词仍保留少量权重。片段向量与查询向量分别为

余弦相似度为

最后一个等号成立是因为两个向量都已归一化。把全部片段向量按行堆叠成矩阵 ,全部得分一次矩阵向量乘法得到:

实现中查询向量的构造与片段向量略有不同:查询只累加 ,不计算 。查询通常很短,词频多为 1,次线性项退化为 1;查询中重复出现的词会按次数累加,等价于线性词频。这一简化必须在文档中写明,否则复现者按公式实现会得到不同数值。

复杂度方面,构建阶段需要遍历全部片段的全部词项,时间为 ,矩阵存储为 。查询阶段一次矩阵向量乘法为 ,若用稀疏矩阵则降为 。稠密矩阵只适用于小语料:、、单精度 4 字节时,矩阵占用 字节,即 40 GB;双精度为 80 GB。生产系统必须使用倒排索引或稀疏矩阵,本篇的稠密实现仅用于数百片段的教学规模。

BM25 是本篇检索器的直接替代。其得分为

其中 控制词频饱和速度, 控制长度归一化强度。TF-IDF 的词频项无上界,长片段通过重复词项可以持续抬高得分;BM25 的词频项饱和,长片段被长度归一化惩罚。把 TfidfIndex 的打分替换为 BM25 需要在索引中额外保存片段长度与 BM25 的 idf,并改写 search 的得分计算,接口不变,可作为本篇的第一个练习。

4 top-k 与确定性

检索返回前 个片段, 同时是拼入上下文的片段数。增大 提高证据覆盖率,也提高噪声比例与生成成本;减小 相反。 的选择应由评估决定,而不是由上下文窗口上限决定。

排序使用稳定排序。np.argsort(-scores, kind="stable") 在得分相同时保留原始顺序,即 cid 升序。若使用默认的不稳定排序,相同得分的片段顺序可能随 NumPy 版本变化,评估结果不可复现。示例中 Q05 第 3 名之后的得分均为 0,稳定排序把它们按 cid 升序排列,返回列表因此固定为 [10, 0, 1]。

检索得分不是概率,也不同查询之间可比。余弦相似度的绝对值受查询长度、词表覆盖与片段长度影响;同一个 0.42 的得分在一个查询上排第一,在另一个查询上可能排第十。因此不能用固定阈值判断“是否相关”,拒答判定也不能只看最高得分。示例中 Q09 的查询词项全部不在词表内,查询向量范数为 0,检索器返回空列表;这是唯一可靠的“无结果”信号。

5 Prompt 组装

提示由四部分组成:系统指令、编号上下文、问题、回答槽。系统指令写明三条约束:只依据上下文回答;每个事实句标注来源编号;上下文不足时输出固定拒答句。上下文按检索顺序编号,每条包含编号、来源文档标识与片段正文。问题放在上下文之后,回答槽之前。

编号是引用可验证的前提。生成器输出的 [2] 必须指向上下文中编号为 2 的片段,评估脚本才能检查引用是否正确。若编号从 0 开始,或按片段在原文中的位置编号,引用与上下文的对应关系需要额外映射,错误率上升。本篇统一使用 1 开始编号,enumerate(hits, 1) 与提示中的 [i] 使用同一个整数。

上下文预算约束为

其中 是系统指令长度, 是第 个片段长度, 是查询长度, 是格式标记长度。超出预算时的截断策略有三种:从末尾丢弃低排名片段、截断单个片段的中部、压缩系统指令。第一种保留排名信息但丢失证据,第二种保留首尾但破坏句子,第三种降低约束强度。本篇不做截断, 的片段总长度远小于预算;生产实现应在组装前计算预算,按整段丢弃低排名片段,并记录实际拼入数。若该数小于 ,Recall@k 的分母仍是评估集的相关片段数,但实际可达上限下降,报告必须区分“检索返回 ”与“上下文实际包含 ”。

文档内容可能包含指令性文本,例如“忽略以上要求”。系统指令声明上下文只作为资料,但本篇没有做指令过滤与转义,这是已知风险。生产系统应在拼接前剥离或转义文档中的角色标记,并对输出做引用一致性检查;相关攻击面见 越狱与安全对齐。

6 生成接口与抽取式基线

生成器接口只规定一个方法:

# 生成器接口:输入查询与检索结果,输出答案或拒答字符串
class Generator:
    def generate(self, query, hits):
        raise NotImplementedError

输入是查询与检索结果,输出是字符串。接口不暴露提示字符串,因为不同生成器的输入格式不同:本地模型接收单段文本,聊天接口接收消息列表,受限解码器接收 schema。把提示组装留在生成器外部,使 build_prompt 可以被单独测试与打印。

MockGenerator 是抽取式基线。它对每个检索片段按句切分,计算句子与查询的内容 token 交集大小,保留交集不小于 min_overlap 的句子;按交集降序、检索名次升序排序;去重后取前 max_sentences 句,在句末标点前插入引用编号。若没有句子达到阈值,返回 REFUSAL。

该基线有三个性质。第一,答案句子逐字来自上下文,因此忠实性接近 1;引用编号指向包含该句的片段,字面正确,但句子是否支持答案结论仍需另行检查。第二,它不能改写,因此无法处理同义改写、跨句指代与多跳组合。第三,它用词面交集判断“能否回答”,词面交集高但答案不存在时仍会作答;示例中的 Q10 就是这种情况。

把 MockGenerator 替换为真实模型时,接口不变。需要额外处理的是输出校验:模型可能返回上下文中不存在的编号、可能不遵守拒答格式、可能在答案中包含提示词。生产实现应在返回前解析引用编号、检查编号范围、核对引用句与上下文句的蕴含关系,失败时重试或降级为拒答。

7 评估协议

评估集由 10 条查询组成:8 条可回答,2 条无答案。可回答查询覆盖分块、BM25、重排、父子分块与三个评估指标;无答案查询一条为域外(唐诗),一条为域内无覆盖(BM25 在中文语料上的默认值)。每条可回答查询给出一个标准证据子串,评估脚本在片段集合中查找包含该子串的片段,得到相关片段集合 。

Recall@k 定义为

context precision 采用 RAGAS 的位置加权定义:

其中 表示第 个检索片段属于 。指标细节与统计检验见 RAG评估。

用证据子串匹配相关片段是本篇的简化。生产评估应标注证据的字符区间,并在索引中保存片段到原文的偏移;子串匹配在片段重叠时可能命中多个片段,使 Recall 的分母变大,也会把恰好包含相同子串的无关片段判为相关。示例的递归分块把 3 个完整句子复制到相邻片段,但 8 条可回答查询的证据子串实测都只归属一个片段;通用语料上不能假定这一性质,报告必须写明去重规则。

无答案查询单独统计拒答率,不进入 Recall 与 CP 的均值。拒答率的分母是无答案查询数,分子是输出与 REFUSAL 完全相等的条数。只报拒答率而不报误答内容会掩盖风险:Q10 没有被判为拒答,它给出的英文默认值与问题所问的中文语料默认值不同,属于误答,报告必须在失败样本中列出。

8 复杂度与已知边界

示例规模下各步骤的代价可以直接估算。833 字符、14 个片段、词表 714 项,TF-IDF 矩阵不到 1 MB,构建与查询都在毫秒级。规模扩大后,瓶颈依次转移到三处:分词与词表构建、矩阵存储、逐条评估的生成调用。

设片段数 、平均片段长度 字符、词表 ,稠密矩阵不可行,已如第 3 节计算。倒排索引的存储与片段总长度成正比,查询时间与查询词项的 posting list 长度之和成正比;BM25 可以在倒排索引上直接计算,TF-IDF 的余弦需要按词项累加后再归一化。工程上通常直接用 BM25 或稠密向量检索,很少在十万级片段上使用稠密 TF-IDF 矩阵。

评估的代价主要来自生成。抽取式生成器是本地字符串操作,10 条查询耗时可忽略;换成 API 模型后,每条查询一次调用,1000 条评估需要 1000 次生成调用,另有评审模型的多次调用。评估成本必须与迭代频率一起规划,见 RAG评估 第 8 节。

系统的已知边界如下。词面检索无法处理同义词与跨语言;字符分块与模型 token 边界不一致;抽取式生成无法改写与多跳;拒答只依据词面交集,无法识别“词面相似但答案不存在”;无重排、无查询改写、无缓存、无流式输出。这些边界不是实现缺陷,而是刻意保留的最小性,后续每一节改进都对应一个可测量的指标。

关键直觉

TIP

检索是一个词面过滤器,生成是一个受上下文约束的选择器;评估必须分别测量过滤器漏掉了什么、选择器选错了什么,拒答则是与“答对”“答错”并列的第三种结果。

该表述与 RAG评估 第 1 节的条件分解对应。Recall@k 与 context precision 测量过滤器的召回与排序,faithfulness 与人工评分测量选择器的依据与切题程度,拒答率测量系统在证据不足时的行为。把三者混为一个端到端正确率,会丢失定位能力;把拒答计入错误或计入正确,都会改变指标的语义。示例中 Q01 的 Recall@3 等于 1 而 CP@3 等于 0.5,正是“过滤器召回成功但排序不理想”的独立信号;Q10 的拒答失败则是“选择器在无证据时仍然作答”的独立信号。

例子与代码

运行环境为 Python 3.10 及以上、NumPy 1.24 及以上,除 NumPy 外只使用标准库。将下面三段代码按顺序拼接为 rag_min.py,执行 python rag_min.py。全部输出由固定语料与确定性排序产生,重复运行结果一致。代码共约 240 行,其中前两段构成核心管线,约 180 行;第三段是评估与运行入口。

第一段:语料、分块与分词。

# -*- coding: utf-8 -*-
# Python 3.10+、NumPy 1.24+;除 NumPy 外只使用标准库
import math
import re
from dataclasses import dataclass

import numpy as np

DOCS = {
    "doc-01": (
        "检索增强生成在生成前先检索外部文档,把检索结果作为生成条件。索引阶段把文档切分为片段,计算每个片段的稀疏或稠密表示并写入索引。\n"
        "检索阶段对查询做同样的表示,按相似度返回前 k 个片段。生成阶段把片段按编号拼入提示词,要求模型逐句标注引用。"
    ),
    "doc-02": (
        "固定长度分块按字符数切分,实现简单,但会在句子中间截断。递归分块先按段落与句子切分,再合并到长度上限,块边界通常落在句末。\n"
        "重叠用于避免证据被块边界切断,通常取块长的百分之十到百分之二十。父子分块用小片段建立索引,命中后返回其父片段作为生成上下文。"
    ),
    "doc-03": (
        "BM25 用词频、逆文档频率与文档长度归一化对候选片段打分。k1 控制词频饱和速度,k1 越小,词频增益越早饱和。\n"
        "b 控制长度归一化强度,b 等于 0 时不做长度惩罚。BM25 的默认参数为 k1 等于 1.5、b 等于 0.75,这组默认值在英文语料上标定。\n"
        "BM25 不理解同义词,查询与文档用词不一致时召回会下降。"
    ),
    "doc-04": (
        "重排使用交叉编码器对查询与候选片段逐对打分,弥补双塔检索缺少交互的缺陷。交叉编码器不能预先建立索引,只能在召回后的少量候选上运行。\n"
        "重排的收益取决于召回集合的召回率,召回缺失时重排无法恢复。两阶段检索的延迟等于召回延迟与重排延迟之和。"
    ),
    "doc-05": (
        "Recall@k 的分母是该查询的相关片段总数,分子是前 k 个结果中的相关片段数。context precision 只统计上下文中相关片段的比例,并对相关片段所在位置做加权平均。\n"
        "context recall 统计标准答案中的断言能否在检索上下文中找到支持。faithfulness 衡量答案中的断言能否由上下文支持,等于被支持的断言数除以断言总数。\n"
        "端到端评估只看最终答案,分环节评估分别度量检索与生成。"
    ),
    "doc-06": (
        "缓存命中时直接返回历史答案,可省去检索与生成两段延迟。缓存键通常由规范化后的查询与索引版本共同决定。\n"
        "索引更新后必须使旧缓存失效,否则会返回过期答案。线上指标包括点击率、满意度与放弃率,它们与离线指标并不总是一致。"
    ),
}


@dataclass
class Chunk:
    cid: int
    doc_id: str
    text: str


def split_sentences(text):
    """按句末标点切句,保留标点,丢弃空白片段。"""
    return [p.strip() for p in re.split(r"(?<=[。!?!?;;\n])", text) if p.strip()]


def chunk_fixed(text, size=90, overlap=15):
    """字符级固定窗口:窗口长度固定,相邻窗口共享 overlap 个字符。"""
    step = size - overlap
    pieces = [text[i:i + size] for i in range(0, len(text), step)]
    return [p.strip() for p in pieces if p.strip()]


def chunk_recursive(text, size=90, overlap=30):
    """句子级递归分块:先切句,再合并到长度上限,重叠以完整句子回退。"""
    atoms = [s[i:i + size] for para in text.split("\n") for s in split_sentences(para)
             for i in range(0, len(s), size)]
    chunks, buf = [], []
    for atom in atoms:
        if sum(map(len, buf)) + len(atom) <= size:
            buf.append(atom)
            continue
        chunks.append("".join(buf))
        tail, acc = [], 0
        for prev in reversed(buf):
            if acc + len(prev) > overlap:
                break
            tail.insert(0, prev)
            acc += len(prev)
        buf = tail + [atom]
        if sum(map(len, buf)) > size:
            buf = [atom]
    if buf:
        chunks.append("".join(buf))
    return [c.strip() for c in chunks if c.strip()]


TOKEN_RE = re.compile(r"[a-z0-9_]+|[\u4e00-\u9fff]+")
STOP = set("的了是在和与及或对为中上下一这那有并而其之也就都把被将从到个")


def tokenize(text):
    """ASCII 词整体保留,汉字取一元与二元组,过滤单字停用词。"""
    toks = []
    for m in TOKEN_RE.finditer(text.lower()):
        s = m.group(0)
        if s[0].isascii():
            toks.append(s)
        else:
            toks.extend(ch for ch in s if ch not in STOP)
            toks.extend(s[i:i + 2] for i in range(len(s) - 1))
    return toks

这一段的关键行如下。

split_sentences 使用零宽断言 (?<=[。!?!?;;\n]),在标点之后切分并保留标点。若改用普通 split("。"),标点被丢弃,片段拼接后句子之间没有分隔符,引用句与原句无法逐字比对。

chunk_fixed 的 step = size - overlap 决定窗口起点间距。若 overlap=0,窗口首尾相接,边界处的证据被切开后无法在相邻块中找到;若 overlap>=size,步长非正,range 报错。函数保留末尾不足 size 的窗口,因此块数为 ,与第 2 节的公式一致。

chunk_recursive 先构造 atoms:对每个段落切句,再对超长句子按 size 硬切。合并循环中,sum(map(len, buf)) 每次重新求和,片段数很少时可以接受,规模大时应维护累计长度。溢出时从 buf 尾部回退完整句子作为重叠,acc + len(prev) > overlap 时停止,保证重叠不超过 O;若重叠加新原子超过 size,直接放弃重叠,避免块超长。

tokenize 把英文与数字保持为完整词,把连续汉字拆成一元与二元组。二元组让“相关片段”“断言总数”这类搭配获得独立词项,提升词面匹配的区分度;去掉二元组后,中文匹配退化为单字匹配,“相关”与“无关”会共享“关”字,噪声上升。停用字表只过滤单字,二元组中的停用字保留,因为“的”参与构成的搭配仍可能携带信息。

第二段:索引、提示与生成器。

class TfidfIndex:
    def __init__(self, chunks):
        self.chunks = chunks
        self.vocab, tfs = {}, []
        for c in chunks:
            tf = {}
            for t in tokenize(c.text):
                j = self.vocab.setdefault(t, len(self.vocab))
                tf[j] = tf.get(j, 0) + 1
            tfs.append(tf)
        df = np.zeros(len(self.vocab))
        for tf in tfs:
            for j in tf:
                df[j] += 1
        idf = np.log((1 + len(chunks)) / (1 + df)) + 1.0
        self.matrix = np.zeros((len(chunks), len(self.vocab)))
        for i, tf in enumerate(tfs):
            for j, f in tf.items():
                self.matrix[i, j] = (1 + math.log(f)) * idf[j]
        self.matrix /= np.clip(np.linalg.norm(self.matrix, axis=1, keepdims=True), 1e-12, None)
        self.idf = {t: idf[j] for t, j in self.vocab.items()}

    def search(self, query, k=3):
        """查询向量与矩阵的行向量做余弦相似度,返回前 k 个片段。"""
        vec = np.zeros(len(self.vocab))
        for t in tokenize(query):
            if t in self.vocab:
                vec[self.vocab[t]] += self.idf[t]
        norm = np.linalg.norm(vec)
        if norm == 0:
            return []
        scores = self.matrix @ (vec / norm)
        return [(self.chunks[i], float(scores[i]))
                for i in np.argsort(-scores, kind="stable")[:k]]


REFUSAL = "根据现有上下文无法回答该问题。"
SYSTEM_PROMPT = (
    "你是技术文档问答助手,只依据【上下文】回答。\n"
    "规则:\n"
    "1. 每个事实句末尾标注来源编号,格式为 [1]、[2],编号必须是实际引用的片段。\n"
    "2. 不得使用上下文之外的知识,不得补全上下文中没有的数字与结论。\n"
    f"3. 上下文不足以回答时,只输出:{REFUSAL}\n"
)


def build_prompt(query, hits):
    blocks = [f"[{i}] 来源 {c.doc_id}\n{c.text}" for i, (c, _) in enumerate(hits, 1)]
    return f"{SYSTEM_PROMPT}\n【上下文】\n" + "\n\n".join(blocks) + f"\n\n【问题】{query}\n【回答】"


class Generator:
    def generate(self, query, hits):
        raise NotImplementedError


class MockGenerator(Generator):
    """抽取式生成器:从检索片段中挑选与查询词重合度最高的句子拼接。"""

    def __init__(self, max_sentences=3, min_overlap=2):
        self.max_sentences, self.min_overlap = max_sentences, min_overlap

    def generate(self, query, hits):
        q = set(tokenize(query))
        scored = []
        for rank, (chunk, _) in enumerate(hits, 1):
            for sent in split_sentences(chunk.text):
                overlap = len(q & set(tokenize(sent)))
                if overlap >= self.min_overlap:
                    scored.append((overlap, rank, sent))
        if not scored:
            return REFUSAL
        scored.sort(key=lambda x: (-x[0], x[1]))
        picked, seen = [], set()
        for _, rank, sent in scored:
            if sent in seen:
                continue
            seen.add(sent)
            picked.append(f"{sent.rstrip('。;!?')}[{rank}]。")
            if len(picked) >= self.max_sentences:
                break
        return "".join(picked)

这一段的关键行如下。

df 统计按词项遍历每个片段的词频字典,复杂度为 。若写成“对每个词项扫描全部片段”,复杂度变为 ,在万级词表上会明显变慢;这一行是稀疏统计与稠密扫描的分界。

idf 使用 np.log((1 + N) / (1 + df)) + 1.0,与第 3 节公式一致。分母加 1 避免 df=0 时除零,分子加 1 与分母对称;若去掉平滑,只在部分片段出现的词项权重会偏大,长尾词主导排序。

self.matrix[i, j] = (1 + math.log(f)) * idf[j] 实现次线性词频。若直接用原始词频 ,长片段通过重复词项获得过高得分,排序偏向长片段;这是 TF-IDF 与 BM25 都要处理的长度偏差。

self.matrix /= np.clip(...) 按行做 L2 归一化,clip 防止零向量除零。归一化后余弦等于点积,查询阶段只需一次 matrix @ vec;去掉归一化,点积随片段长度增长,短片段被系统性压低。

search 中查询向量只累加 idf,不乘词频项。查询很短,重复词项少,这一简化对排序影响有限;查询较长或允许重复词时,应按与片段相同的公式构造查询向量。norm == 0 直接返回空列表,这是“查询词项全部未登录”的唯一可靠信号。

build_prompt 用 enumerate(hits, 1) 生成 1 开始编号,编号同时出现在上下文标题与引用格式中。join(blocks) 使用两个换行分隔片段,空行让模型更容易区分片段边界;去掉空行,相邻片段可能被读成一段。

MockGenerator 的 overlap 是查询 token 集合与句子 token 集合的交集大小。q 只计算一次,循环内不重复分词查询;句子分词在双重循环内完成,片段多时应缓存。scored.sort(key=lambda x: (-x[0], x[1])) 先按交集降序,再按检索名次升序,保证同分时优先引用排名靠前的片段。

picked.append(f"{sent.rstrip('。;!?')}[{rank}]。") 把引用编号插在句末标点之前,形成“句子[1]。”的格式。若直接拼接 sent + f"[{rank}]",编号落在句号之后,引用检查脚本按句末切分时会把编号归到下一句。

第三段:查询集、指标与运行入口。

QUERIES = [
    ("Q01", "BM25 的 k1 参数控制什么", "k1 控制词频饱和速度"),
    ("Q02", "分块重叠如何避免证据被切断", "重叠用于避免证据被块边界切断"),
    ("Q03", "重排为什么需要交叉编码器", "重排使用交叉编码器对查询与候选片段逐对打分"),
    ("Q04", "Recall@k 的分母是什么", "分母是该查询的相关片段总数"),
    ("Q05", "context precision 如何计算", "对相关片段所在位置做加权平均"),
    ("Q06", "faithfulness 等于什么除以断言总数", "等于被支持的断言数除以断言总数"),
    ("Q07", "父子分块命中后返回什么", "命中后返回其父片段作为生成上下文"),
    ("Q08", "模型回答和检索材料不一致时应该看哪个指标", "faithfulness 衡量答案中的断言能否由上下文支持"),
    ("Q09", "李白的诗歌有哪些艺术特征", None),
    ("Q10", "BM25 的 k1 在中文语料上的默认值是多少", None),
]


def context_precision(retrieved, relevant):
    """RAGAS 式 context precision:只对相关位置求 precision@k 的均值。"""
    hits, precisions = 0, []
    for i, cid in enumerate(retrieved, 1):
        if cid in relevant:
            hits += 1
            precisions.append(hits / i)
    return sum(precisions) / len(precisions) if precisions else 0.0


if __name__ == "__main__":
    # 1 建索引:把每个片段编码为 TF-IDF 向量
    chunks = [Chunk(i, doc_id, piece) for i, (doc_id, piece) in enumerate(
        (d, p) for d, t in DOCS.items() for p in chunk_recursive(t))]
    index, generator = TfidfIndex(chunks), MockGenerator()
    fixed = [p for t in DOCS.values() for p in chunk_fixed(t)]
    end = ("。", "!", "?")
    print(f"文档 {len(DOCS)} 篇,字符 {sum(map(len, DOCS.values()))} 个,"
          f"固定分块 {len(fixed)} 段(句末结束 {sum(p.endswith(end) for p in fixed)} 段),"
          f"递归分块 {len(chunks)} 段(句末结束 {sum(c.text.endswith(end) for c in chunks)} 段)")
    # 2 逐条查询:检索、生成、计算 Recall@3 与 CP@3
    recalls, precisions, refused = [], [], []
    for qid, query, gold in QUERIES:
        hits = index.search(query, k=3)
        retrieved = [c.cid for c, _ in hits]
        answer = generator.generate(query, hits)
        rel = {c.cid for c in chunks if gold and gold in c.text}
        if rel:
            recall = len(rel & set(retrieved)) / len(rel)
            cp = context_precision(retrieved, rel)
            recalls.append(recall)
            precisions.append(cp)
            print(f"{qid} R@3={recall:.2f} CP@3={cp:.2f} 检索={retrieved} 答案={answer[:34]}")
        else:
            refused.append(answer == REFUSAL)
            print(f"{qid} 无答案 拒答={refused[-1]} 检索={retrieved} 答案={answer[:34]}")
    print(f"平均 Recall@3={np.mean(recalls):.4f} 平均 CP@3={np.mean(precisions):.4f} "
          f"无答案拒答率={np.mean(refused):.2f}")
    # 3 打印一条完整 Prompt 与对应答案,检查编号与引用是否一致
    print("\n【Q01 的 Prompt】\n" + build_prompt("BM25 的 k1 参数控制什么",
                                                  index.search("BM25 的 k1 参数控制什么", 2)))
    print("\n【Q01 的答案】" + generator.generate("BM25 的 k1 参数控制什么",
                                                  index.search("BM25 的 k1 参数控制什么", 2)))

这一段的关键行如下。

QUERIES 的第三列是标准证据子串,None 表示无答案。证据子串必须完整落在某个片段内;若子串跨越切点,rel 会变成空集,指标把可回答查询误判为无答案。构造评估集时应先用分块器预检每个证据子串的归属。

context_precision 只累加相关位置上的 hits / i。hits 是到目前为止的相关片段数,i 是当前位置。若上下文中没有相关片段,函数返回 0;这与“无答案查询不进入 CP 均值”的处理是两回事,调用方用 rel 是否为空区分。

主流程的 chunks 用列表推导建立,enumerate 保证 cid 从 0 连续递增。(d, p) for d, t in DOCS.items() for p in chunk_recursive(t) 先遍历文档再遍历片段,doc_id 与片段正文一同进入 Chunk。

rel = {c.cid for c in chunks if gold and gold in c.text} 在全部片段中查找证据子串。若 gold 为 None,条件短路,返回空集。生产实现应改为读取标注的字符区间,并检查区间是否被切点切开。

可回答分支计算 Recall 与 CP 并累加;无答案分支只记录拒答标记。两个分支都打印检索编号与答案前 34 个字符,便于人工核对。answer[:34] 是字符切片,中文按字符计数,不会截断 UTF-8 字节。

最后打印一条完整 Prompt 与对应答案。Prompt 中包含两条检索片段、编号、来源与拒答句,可直接检查编号与引用是否一致;答案中的 [1]、[2] 应与 Prompt 中的编号对应。

运行输出如下。

文档 6 篇,字符 833 个,固定分块 14 段(句末结束 7 段),递归分块 14 段(句末结束 14 段)
Q01 R@3=1.00 CP@3=0.50 检索=[5, 4, 9] 答案=BM25 的默认参数为 k1 等于 1.5、b 等于 0.75,这组
Q02 R@3=1.00 CP@3=1.00 检索=[3, 2, 11] 答案=重叠用于避免证据被块边界切断,通常取块长的百分之十到百分之二十[1]
Q03 R@3=1.00 CP@3=1.00 检索=[7, 8, 1] 答案=重排使用交叉编码器对查询与候选片段逐对打分,弥补双塔检索缺少交互的缺
Q04 R@3=1.00 CP@3=1.00 检索=[9, 1, 10] 答案=Recall@k 的分母是该查询的相关片段总数,分子是前 k 个结果
Q05 R@3=1.00 CP@3=1.00 检索=[10, 0, 1] 答案=context precision 只统计上下文中相关片段的比例,并
Q06 R@3=1.00 CP@3=1.00 检索=[11, 5, 9] 答案=faithfulness 衡量答案中的断言能否由上下文支持,等于被支
Q07 R@3=1.00 CP@3=1.00 检索=[3, 2, 12] 答案=父子分块用小片段建立索引,命中后返回其父片段作为生成上下文[1]。缓
Q08 R@3=0.00 CP@3=0.00 检索=[6, 13, 1] 答案=BM25 不理解同义词,查询与文档用词不一致时召回会下降[1]。线上
Q09 无答案 拒答=True 检索=[] 答案=根据现有上下文无法回答该问题。
Q10 无答案 拒答=False 检索=[5, 4, 6] 答案=BM25 的默认参数为 k1 等于 1.5、b 等于 0.75,这组
平均 Recall@3=0.8750 平均 CP@3=0.8125 无答案拒答率=0.50

【Q01 的 Prompt】
你是技术文档问答助手,只依据【上下文】回答。
规则:
1. 每个事实句末尾标注来源编号,格式为 [1]、[2],编号必须是实际引用的片段。
2. 不得使用上下文之外的知识,不得补全上下文中没有的数字与结论。
3. 上下文不足以回答时,只输出:根据现有上下文无法回答该问题。

【上下文】
[1] 来源 doc-03
b 控制长度归一化强度,b 等于 0 时不做长度惩罚。BM25 的默认参数为 k1 等于 1.5、b 等于 0.75,这组默认值在英文语料上标定。

[2] 来源 doc-03
BM25 用词频、逆文档频率与文档长度归一化对候选片段打分。k1 控制词频饱和速度,k1 越小,词频增益越早饱和。b 控制长度归一化强度,b 等于 0 时不做长度惩罚。

【问题】BM25 的 k1 参数控制什么
【回答】

【Q01 的答案】BM25 的默认参数为 k1 等于 1.5、b 等于 0.75,这组默认值在英文语料上标定[1]。k1 控制词频饱和速度,k1 越小,词频增益越早饱和[2]。b 控制长度归一化强度,b 等于 0 时不做长度惩罚[1]。

结果可以逐项核对。

分块统计:6 篇文档共 833 字符,固定窗口 14 段,其中只有 7 段结束在句末;递归分块同样 14 段,14 段全部结束在句末。块数相同而边界质量不同,说明块数不能单独作为分块质量的指标。固定窗口的第 14 段是末尾不足 90 字符的部分窗口,它与前一段重叠 15 字符,覆盖了文档尾部。

Q01:Recall@3 等于 1,CP@3 等于 0.5。相关片段是编号 4 的块,它包含“k1 控制词频饱和速度”,但检索把它排在第 2 名;第 1 名是编号 5 的块,包含“BM25 的默认参数为 k1 等于 1.5”,与查询共享 bm25、k1、参数 等词项,却回答的是默认值而不是控制作用。这是同实体不同属性的难负例,单靠词面无法区分。CP 只对相关位置求均值,第 1 名不相关使相关片段的 降为 。Q01 的答案也印证了这一点:抽取式生成器先选了默认值句,再选控制作用句,答案包含正确信息,但首句答非所问。

Q02 至 Q07:Recall@3 与 CP@3 都等于 1,相关片段排第 1。Q07 的答案多了一句“缓存命中时……”,因为查询中的“命中”与缓存句共享词项,抽取式生成器把无关句子一并拼入。忠实性没有受损,因为句子来自上下文,但答案相关性下降;这正是 RAG评估 中“忠实性高、答案相关性低”的格子。

Q08:Recall@3 与 CP@3 都等于 0。查询“模型回答和检索材料不一致时应该看哪个指标”与标准证据“faithfulness 衡量答案中的断言能否由上下文支持”几乎没有共享词项:查询用“回答”“材料”“指标”,证据用“答案”“上下文”“断言”。检索按词面返回了包含“不一致”的 doc-03 片段、包含“指标”的 doc-06 片段与包含“检索”的 doc-01 片段,证据片段未进入前 3。这是词面检索的典型失败,改进方向是稠密检索或查询改写,而不是调 。

Q09:查询词项全部未登录,查询向量范数为 0,检索返回空列表,生成器没有可抽取的句子,输出拒答。该拒答是正确的,但它依赖“检索为空”这一强信号;若语料中有少量无关但共享单字的片段,检索不再为空,拒答逻辑就会失效。

Q10:查询问“BM25 的 k1 在中文语料上的默认值”,语料只给出英文语料上的默认值 1.5 与 0.75,没有中文语料的标定结果。检索返回编号 5、4、6 的片段,生成器抽取默认值句并作答。答案逐字来自上下文,忠实性高,但它把英文默认值当作中文默认值,属于误答。拒答率 0.50 表示两条无答案查询中只有一条被正确拒答;只报拒答率会掩盖这条误答,报告必须同时列出误答内容。

总体:8 条可回答查询的平均 Recall@3 为 0.875,平均 CP@3 为 0.8125,两者都未达到 1。差距主要来自 Q08 的检索失败与 Q01 的排序失败,而不是生成失败。若只做端到端人工判断,Q01 的答案包含正确信息,可能被判为部分正确,Q08 的答案包含无关句子,可能被判为错误;分环节指标把两者分别定位到排序与召回,改进动作不同。

人工评分表模板如下。评分维度与锚点应按 RAG评估 第 9 节定义,本表只给记录格式;每条查询由一名标注者填写,20% 样本由第二名标注者独立填写,用于计算一致性。

查询检索编号答案摘要忠实性 1–5相关性 1–5引用正确完整性 1–5备注
Q015,4,9默认值 + 控制作用是/否首句答非所问
Q023,2,11重叠避免边界切断是/否
Q037,8,1交叉编码器逐对打分是/否
Q049,1,10Recall@k 分母是/否
Q0510,0,1CP 位置加权是/否
Q0611,5,9断言支持比例是/否
Q073,2,12父片段作为上下文是/否含缓存噪声句
Q086,13,1词面不一致与指标是/否检索未命中
Q09空拒答不适用正确拒答
Q105,4,6英文默认值是/否误答,需标注

改进路线按投入产出排序如下,每条都给出可测量的验收指标。

重排:对前 20 个候选使用交叉编码器逐对打分,再取前 3 拼入上下文。预期 Q01 的相关片段从第 2 名升到第 1 名,Q01 的 CP@3 从 0.50 升到 1.00,平均 CP@3 从 0.8125 升到 0.875;代价是每条查询增加一次模型前向,延迟上升。验收标准是 CP@3 提升且 Recall@3 不下降。实现参考 检索优化与重排Rerank。

查询改写:对查询做同义词扩展或让模型生成改写,再用改写结果检索。目标是把 Q08 的“回答/材料/指标”映射到“答案/上下文/断言”。验收标准是 Q08 的 Recall@3 从 0 变为 1,同时其余查询的 Recall@3 不下降。查询改写的风险是引入噪声,必须用同一评估集对照。

父子分块:用小片段建索引,命中后返回父片段作为上下文。它提高证据完整性,代价是上下文变长。验收标准是 CP@3 不下降、人工完整性评分上升;若上下文预算不足,需要配合截断策略。实现参考 RAG文档分块策略。

缓存:以规范化查询与索引版本为键缓存答案,命中时直接返回。验收标准是缓存命中率与 P95 延迟;索引更新必须使旧缓存失效,否则返回过期答案。缓存不改变离线指标,只改变在线延迟与成本,评估时应单列。

流式:生成器按句或按 token 逐步返回,降低首字延迟。离线指标不变,在线指标应增加首 token 时间;实现时要注意引用编号必须在句子完成后再输出,否则用户会看到未完成的引用。

替换为真实 LLM 时,保持 Generator 接口不变,新增一个类即可。下面的代码需要网络与 API key,本篇不执行,也不下载任何模型权重。

# 可选:需要网络与 OPENAI_API_KEY,本篇不执行
from openai import OpenAI


class APIGenerator(Generator):
    def __init__(self, model="gpt-4o-mini"):
        self.client = OpenAI()          # 也可传 base_url 指向本地 vLLM/Ollama
        self.model = model

    def generate(self, query, hits):
        resp = self.client.chat.completions.create(
            model=self.model,
            temperature=0,
            messages=[{"role": "user", "content": build_prompt(query, hits)}],
        )
        return resp.choices[0].message.content.strip()

若要在本地使用句向量检索,接口占位如下。安装 sentence-transformers 并准备模型权重是使用者的责任,本篇不提供下载脚本,也不伪造本地路径。

class EmbeddingIndex:
    """本地句向量接口占位:需自行安装 sentence-transformers 并准备权重。"""

    def __init__(self, model_path):
        raise NotImplementedError(
            "用 SentenceTransformer(model_path).encode 生成单位向量,"
            "再把 TfidfIndex.search 的点积替换为向量余弦。"
        )

易错点

WARNING

- 用字符数当 token 预算:中文一个汉字通常对应 1 至 2 个 token,英文一个词对应 1 至数个 token;按 90 字符设定的块在中文里约 90 至 180 token,在英文里远小于该值,上下文预算与块数统计都会偏差。

- 用答案文本反查证据片段:先有答案再在片段中搜索答案,等于用被测系统的输出定义标签,指标虚高;证据必须来自独立标注,且保存字符区间而不是只存文本。

- 检索的 与上下文实际拼入的片段数不一致:截断后只放入 2 条却按 计算 CP,分母与位置都错;评估必须记录实际拼入数,或保证不截断。

- 引用编号错位:enumerate 从 0 开始、上下文标题从 1 开始,或过滤片段后重新编号,都会使 [2] 指向错误片段;编号必须在组装提示时一次生成,后续不再改写。

- 把 MockGenerator 的抽取式答案当作生成质量基线:它逐字复制上下文,忠实性天然接近 1,不能代表真实模型的改写、幻觉与拒答行为;它只用于验证管线与指标计算。

- 只统计拒答率而不检查误答:Q10 未被拒答且答案看似合理,若只看拒答率 0.50 会以为系统“一半正确”;必须列出误答内容并按错误类型计数。

关联笔记

  • RAG原理与流程(前置):给出索引、检索、生成三阶段的抽象流程与失效模式,本篇把它落成可运行代码。
  • RAG文档分块策略(前置):本篇实现固定窗口与递归句子两种分块,其余三种策略的取舍见该篇。
  • Embedding与向量检索(前置):余弦相似度与向量归一化的定义来自该篇,本篇用 TF-IDF 向量实现同一计算。
  • 检索优化与重排Rerank(后续):在召回集合上加入交叉编码器重排,直接改善本篇 Q01 的排序失败。
  • RAG评估(后续):本篇只计算 Recall@3 与 context precision,完整的指标定义、置信区间与人工协议见该篇。

达标检测

  • [ ] 能运行本篇代码,复现平均 Recall@3 等于 0.875、平均 CP@3 等于 0.8125 的输出。
  • [ ] 能把 k 从 3 改为 1,说明哪些查询的 Recall 与 CP 下降,并解释原因。
  • [ ] 能把分块长度从 90 改为 45,记录片段数、句末结束比例与指标变化。
  • [ ] 能把 TfidfIndex.search 的打分替换为 BM25,并在同一评估集上对比 Recall@3。
  • [ ] 能为 Q10 设计一个基于检索得分的拒答规则,并说明它为什么仍不能可靠识别域内无答案。
  • [ ] 能构造一条多跳查询,使其 Recall@3 小于 1,并写出对应的失败归因。
  • [ ] 能按人工评分表模板标注 10 条结果,计算两名标注者在忠实性维度上的 Cohen's 。

参考来源

  • Lewis et al., Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks, arXiv:2005.11401, 2020 —— 对应本篇检索结果作为生成条件、端到端流程与生成器接口的设计来源。
  • Gao et al., Retrieval-Augmented Generation for Large Language Models: A Survey, arXiv:2312.10997 —— 对应索引、检索、生成三阶段划分与各阶段失效模式。
  • LangChain 文档,Retrieval 与 Vector stores 章节 —— 对应检索器接口、top-k 返回结构与提示组装方式。
  • LlamaIndex 文档,Ingestion Pipeline 与 Retrieval 章节 —— 对应分块、索引构建与检索评估的工程组织。
  • d2l.ai《动手学深度学习》,线性代数与注意力机制章节 —— 对应余弦相似度、矩阵乘法与按相似度加权聚合的实现视角。