文本
与表示

在提交数据前做一次“反向追问”

看到一条处理后的记录，要能反向回答：它来自哪个文件和字符区间？使用了哪个编码和清洗版本？为什么属于这个 split 和标签？如果答案需要凭记忆补全，说明数据合同还不完整。把这些问题写成检查函数或清单，能让后续的 Token、Embedding 和评估建立在可信输入上。

语料治理也包括删除流程：当来源撤回或用户要求删除时，记录 ID 应能定位原文、chunk、词表统计、向量索引和缓存。学习项目先用 manifest 模拟这条链路，生产项目再接入实际存储和权限系统。可追溯不只为了出错时找原因，也为了知道哪些内容不该继续被模型看到。

把“读不出来”当成数据质量信号

解码失败、空文本、异常控制符和无法识别的许可证，都应进入质量报告而不是被静默跳过。报告记录文件、错误类型、字节数、处理动作和是否需要人工复核；这样下一次采集器升级时，可以比较失败率是否真的下降。对公开资料，保存来源链接和抓取日期也有助于核对内容是否发生变化。

只要一条断言失败，就输出可定位的记录 ID。数据管道宁愿明确少几条样本，也不要用不透明的默认值制造“完整”数据集。

质量抽样：不用读完全部语料，也能及时发现问题

大语料不可能逐条人工阅读，但可以把质量检查设计成分层抽样。先按来源、语言、长度、时间和标签分桶，再从每个桶抽取固定数量；同时保留极短、极长、空值、含异常字符和高频重复样本。抽样报告记录随机种子、桶大小和抽到的 ID，下一次运行才能复现同一批样例。

缺失值要按字段分别处理。缺失标题可能仍可用于分类，缺失正文通常不能用于检索；缺失标签可以进入待标注队列，不能默认为“其他”。对每种缺失决定“保留、填充、删除、待复核”，并记录数量和比例。比例随时间变化时，可能是上游采集器改变，而不是模型突然变差。

from collections import defaultdict
import random

def stratified_ids(records, per_bucket=2, seed=7):
    buckets = defaultdict(list)
    for row in records:
        length_bucket = "short" if len(row["text"]) <= 32 else "long"
        key = (row.get("source", "unknown"), length_bucket, row.get("split"))
        buckets[key].append(row["id"])
    rng = random.Random(seed)
    picked = {}
    for key, ids in buckets.items():
        ids = sorted(ids)
        rng.shuffle(ids)
        picked[key] = ids[:per_bucket]
    return picked

print(stratified_ids(records))

抽样脚本中的随机种子不是质量保证本身，它只是让复核集合稳定。真正的质量证据还包括人工标注意见、异常类型、修复前后数量和处理版本。修复数据后不要覆盖旧报告；保存一份差异清单，说明哪些记录改变以及为什么改变。

当质量问题来自上游时，最有效的修复可能是调整采集或数据合同，而不是在模型前加更多正则表达式。把反馈回传给数据生产者，规定必填字段、合法编码和失败重试，模型团队才能把时间花在表示与任务上。

把语料管道画成一条可审计的流水线

拿到一批文件时，先不要急着调用分词器。第一步是读取元数据：文件名、相对路径、来源、创建或更新时间、许可证和语言。第二步以二进制方式读取并记录字节数，再按照声明的编码解码；解码失败要进入错误清单，不能用一个“尽量修复”的替换字符悄悄吞掉问题。第三步生成规范化副本，同时保留原始哈希。第四步才是切句、切块和构造训练或检索记录。

这条顺序的关键在于每一步都有输入和输出。输入是原文哈希，输出是处理后文本哈希；输入是清洗配置，输出是规则版本；输入是文档 ID，输出是稳定的 chunk ID。只要某个结果无法回答“它由哪一份原文产生”，就还不算可审计。学习时可以把这些字段写进 JSONL；即使只处理十个文件，也要养成不覆盖中间产物的习惯。

编码和规范化还要考虑边界样例：UTF-8 BOM、Windows 换行、混合全角半角、零宽空格、不可见控制符、复制网页带来的不间断空格，以及看起来相同但码点不同的汉字。对每种样例写输入、期望输出和是否保留原文的说明。测试不是为了追求“所有文本都被洗得一样”，而是为了证明规则只在授权范围内改变文本。

import hashlib
import json
from pathlib import Path

def read_record(path):
    raw = path.read_bytes()
    text = raw.decode("utf-8-sig")
    return {
        "document_id": hashlib.sha256(str(path).encode()).hexdigest()[:12],
        "source": str(path),
        "encoding": "utf-8-sig",
        "byte_count": len(raw),
        "raw_hash": hashlib.sha256(raw).hexdigest(),
        "text": text,
    }

records = [read_record(path) for path in Path("corpus").glob("*.txt")]
with Path("documents.jsonl").open("w", encoding="utf-8") as handle:
    for record in records:
        handle.write(json.dumps(record, ensure_ascii=False) + "\n")
print("documents:", len(records))

这段读取器把 BOM 处理写在接口里，并把原始字节哈希存下来。真实项目还应检查文件是否为空、路径是否越界、许可证是否允许处理，以及同一个文档是否被不同路径重复收集。若要把文件内容送给远程服务，先确认隐私和授权边界；学习资料中的示例以公开、可再分发的短文本为宜。

训练、验证和测试的切分必须早于任何会从数据中学习参数的步骤。词表、IDF、均值方差、近似重复阈值和困难负例都只在训练或指定的验证范围内拟合。测试集的文本可以被读取来计算最终指标，但不能反过来影响规则选择。把 split 写进每条记录，比在脚本末尾临时切片更不容易出错。

保留三份文本，给未来的自己留证据

原始文本用于追溯和重新处理，规范化文本用于确定性规则，Token 序列用于模型输入。三者不要互相覆盖。处理记录还应包含清洗函数版本、编码、时间、来源 ID 和失败原因。这样发现“某类文本的召回率突然下降”时，可以回到原文判断是不是编码、空白或清洗规则改变，而不是先怀疑模型。

如果数据来自用户输入或网页，原文可能含有隐私、脚本或恶意提示。学习项目至少记录来源和授权范围，展示样例时脱敏；生产项目再加入访问控制、内容安全和删除机制。数据工程的第一原则是知道自己保存了什么。

清洗函数的易错点

不要用 split() 代替真正的句子切分，因为连续空格、换行和标点会改变结果；不要在训练集和测试集分别拟合清洗统计量，否则预处理本身会泄漏标签或分布信息；不要把错误编码的替换字符 � 当成普通内容静默保留。遇到异常文本时，记录原始 ID 和原始片段，单独进入失败样本表。

清洗版本一旦变化，就应改变 preprocess_version。缓存、词表和向量索引都要知道它依赖哪一版文本。否则你可能用新版规则生成查询，却拿旧版文档向量比较，最终把版本错配误判为模型效果。

从任务卡到数据卡

任务卡回答“要预测或检索什么、谁使用结果、错误有什么代价”；数据卡回答“数据从哪里来、怎样清洗、有哪些偏差、允许怎样使用”。初学者可以各写半页，附上三条正例、三条负例和三条已知限制。它们会直接指导后续词表、采样、指标和错误分析，而不是文档末尾的装饰。

语言分布和领域分布也要进入数据卡。中文、英文、代码、数字、表情混在一起时，一个统一的清洗规则可能并不公平；不同长度、来源和时间段的样本也可能有不同难度。切分时保留这些分组字段，评估时再按组报告，才知道模型在哪些条件下失效。

把 Token 数当作资源预算

同一模型的上下文窗口是有限资源，系统提示、历史对话、检索片段和待生成内容会共同占用它。统计平均值不够，还要看 P95 和最坏样例；否则大多数请求正常，少数长请求会突然截断关键证据。把 Token 预算写进配置并在运行时提示“舍弃了多少内容”，用户才知道答案为什么不完整。

分词规则改变后，任何依赖序列长度的组件都可能受到影响：padding 批次效率、位置编码上限、训练显存、检索块大小和评估切片。版本清单要把这些依赖串起来，不要只更新一个 tokenizer 文件。

分词器的最小测试矩阵

每次修改规则后，固定跑一张小矩阵：普通中文、含标点的中文、英文长词、数字版本、代码路径、空字符串、表情、连续空白和超长输入。对每个样例保存 tokens、ids、长度、特殊位置和 decode 结果。测试矩阵的目的不是证明分词器理解语义，而是防止输入边界在升级时悄悄改变。

如果差异是有意的，就提高版本并重新生成词表、Embedding 和索引；如果差异不是有意的，就在发布前阻断。分词器是模型输入的源头，源头不稳定，后面的指标都不稳定。

分词器调试的三个视角

第一个视角是表面覆盖：输入的每个字符是否都能映射到某个 Token，是否出现未知符号，中文标点和全角数字是否被意外拆散。第二个视角是长度效率：同一批样本的 Token/字符比、每个 Token 的平均字节数、不同语言的 P50/P95 长度。第三个视角是可逆性：decode 后的文字是否保留必要空格、换行、标点和大小写。三个视角一起看，才能判断分词器是在覆盖、压缩还是丢失信息。

子词合并的直觉可以用一个小语料手算：先把每个词拆成字符，统计相邻对出现次数，把最高频的一对合并，再重复若干轮。合并次数决定词表容量，语料频率决定哪些片段容易复用。真实算法会有边界标记、概率或评分细节，但手算能让你明白“词表不是从字典直接抄来的”，而是从数据分布中学习的压缩方案。

def budget(text, tokenizer, max_length, reserved=4):
    pieces = tokenizer.tokenize(text)
    usable = max(max_length - reserved, 0)
    kept = pieces[:usable]
    return {
        "characters": len(text),
        "tokens": len(pieces),
        "kept_tokens": len(kept),
        "truncated": len(pieces) > usable,
        "discarded_preview": pieces[usable:usable + 8],
    }

for text in ["短句", "A very long technical identifier", "混合 API 与中文"]:
    print(budget(text, tokenizer, max_length=12))

预算函数把保留的特殊位置作为显式参数，而不是在调用处默默减一个数字。若模板以后从 4 个特殊位置变成 6 个，所有长度报告和回归结果都能解释。对滑动窗口，还要返回窗口索引和原文 offset，后续合并检索结果时才不会把同一文本当成多个独立答案。

分词器的性能也值得测量：批量大小、平均 Token 数、P95 Token 数、CPU 时间、内存和是否可以并行。不要只用一条短句做 benchmark；把真实长度分布和最坏样例放进测试。速度优化不能改变 Token 序列，先用固定样例比对结果，再比较耗时。

用一张 Token 账本理解分词器

对每条文本同时记录原文、Token 字符串、Token ID、Token 数和特殊符号位置。这样看到长度突然增加时，可以判断是中文被拆成字符、罕见词退化成很多子词，还是模板额外加入了起止符号。Token 数影响显存、延迟和计费；字符数只描述原文表面长度，不能代替它。

字符级方案的词表小、未知字符少，却可能让长文本变成很长的序列；整词方案可读性强，但新词、拼写变化和中英文混排会产生大量未登录词；子词方案让常见片段复用，同时保留组合能力。BPE 通过合并频繁相邻片段逐步建立词表，WordPiece 也以子词为单位学习词表，Unigram 则从候选片段中选择更合适的分解。它们的训练细节不同，使用时都要把算法、词表和特殊符号一起固定。

特殊 Token 不是普通词。PAD 只负责对齐批次，通常不应贡献池化或损失；UNK 表示词表无法覆盖的输入，出现率过高说明词表或预处理有问题；BOS/EOS 标记序列边界；分类任务可能需要一个聚合位置。给每个符号固定 ID，并在配置中明确它是否参与 attention、loss 和 decode，避免训练与推理使用不同约定。

def inspect(tokenizer, text):
    encoded = tokenizer(text, add_special_tokens=True)
    ids = encoded["input_ids"]
    pieces = tokenizer.convert_ids_to_tokens(ids)
    special = set(getattr(tokenizer, "all_special_ids", []))
    return {
        "text": text,
        "pieces": pieces,
        "ids": ids,
        "length": len(ids),
        "special_positions": [i for i, item in enumerate(ids) if item in special],
    }

for sample in ["模型会读中文", "API_v2.0 与 e-mail", "🙂 组合"]:
    print(inspect(tokenizer, sample))

调试时不要只打印一串 ID。把 Token 还原成字符串片段，并标出特殊位置，才能解释边界。对于带 offset mapping 的分词器，还可以记录每个 Token 对应原文的字符区间，用于高亮、截断和错误定位。若分词器不提供 offset，就不要假装能够精确把模型结果映射回字符。

长度预算应按部署边界倒推：最大序列长度减去系统提示、任务模板、起止符号和可能的生成空间，才是正文可用预算。截断策略有从左截、从右截、头尾保留和按句子截断；检索常常更重视标题和开头，长文档问答可能需要滑动窗口。无论选择哪种策略，都在样例上展示被舍弃的片段，并统计截断率。

版本测试要覆盖 encode→decode 往返、空字符串、全特殊符号、超长输入、Unicode 边界和批量输入。往返不一定恢复完全相同的空白，但应写清允许的差异。词表更新后，旧 ID 不应被新词静默复用；如果必须迁移，生成明确的映射表并重新构建 Embedding。

分词长度不是字数，也不是模型能力

一个中文字符可能对应一个或多个 Token；一个英文常见词可能是一个 Token，罕见拼写会被拆成多个片段；空格、换行和标点也可能占用 Token。Token 数只是模型计算的离散长度，不能直接当作阅读难度或语义复杂度。比较两个语料时，除了字符数，还要报告 Tokenizer、版本和 Token 长度分布。

长度爆炸会带来平方级注意力成本或更高的推理延迟，但一味追求短序列也会损失信息。对检索文本，可保留标题和上下文；对分类文本，可优先保留与标签有关的片段；对代码，则要保留缩进和符号。截断策略应写在任务卡，而不是隐藏在 DataLoader 里。

特殊符号的三条纪律

第一，ID 固定：训练、验证、推理和保存加载使用同一映射；第二，语义固定：PAD 不代表空文本，UNK 不代表删除，EOS 不等于截断；第三，统计固定：长度、注意力和 loss 是否包含特殊符号，要在指标定义中说明。若新增一个特殊符号，词表版本、Embedding 行数和 checkpoint 都应一起升级。

检查一条编码结果时，优先打印“Token 文本 + ID + mask”三列。只看 ID 很难发现 BOS/EOS 位置反了、PAD 被放在前面或 SEP 丢失等问题。把这三列保存到小型 JSON 样例，是最便宜的回归证据。

分词器回归样例应该包含什么

至少准备五类样例：普通中文句子、中英文混合、数字和单位、代码/URL、空文本和超长文本。每条样例保存原文、规范化文本、Token 文本、ID、attention mask、decode 结果和 tokenizer 版本。升级分词器后逐条比较，允许的差异要提前写出，不能看到数字变化才临时解释。

offsets 可以把 Token 映射回原文字符范围，是错误分析和高亮检索结果的重要证据。若分词器不提供 offsets，至少保存 chunk 的起止位置和原文 ID。检索系统返回答案时，读者看到的是原文片段，而不是一串无法解释的 ID。

词表容量与覆盖率的取舍

词表越大，常见词和专名越容易以较少 Token 表示，但 Embedding 参数量、加载时间和稀有条目也会增加；词表越小，模型能用更少的行覆盖更多组合，却可能让一句话变得很长。不要凭经验宣称一个固定容量适合所有中文技术语料，先画频次曲线和 Token 长度分布，再根据显存、上下文长度和 OOV 需求选择。

特殊符号的顺序一旦发布就应视为不可变接口。可以在 JSON 中同时保存 format_version、tokenizer_version 和 source_corpus_hash，加载时拒绝不匹配的组合。为迁移准备时，生成旧词表到新词表的映射，但不要把无法一一对应的行当作安全迁移；Embedding 权重可能需要重新初始化或蒸馏。

def validate_vocab(payload):
    token_to_id = payload["token_to_id"]
    id_to_token = {int(k): v for k, v in payload["id_to_token"].items()}
    if len(token_to_id) != len(id_to_token):
        raise ValueError("双向映射长度不一致")
    if set(token_to_id.values()) != set(id_to_token):
        raise ValueError("ID 集合不一致")
    for token, index in token_to_id.items():
        if id_to_token[index] != token:
            raise ValueError(f"映射不对称: {token}")
    special = payload["special_ids"]
    if len(set(special.values())) != len(special):
        raise ValueError("特殊 ID 冲突")
    if payload["max_length"] <= 0:
        raise ValueError("max_length 必须为正")
    return True

print(validate_vocab(vocab_payload))

验证函数应在模型加载前运行，并把错误写到日志中。特别注意 JSON 的对象键总是字符串，加载 id_to_token 时要显式转换为整数；这是许多“本地能跑、部署报错”的细节。对共享词表的团队，还要在代码评审中检查新增 Token 是否有样例和使用理由。

词表不是字典，而是一份长期契约

一个词表至少包含两个方向的映射：Token 到 ID，以及 ID 到 Token。前者用于编码，后者用于调试、解码和展示。特殊 Token 要在普通 Token 之前或之后采用固定顺序，并把 pad_id、unk_id、bos_id、eos_id 明确写入配置；不要在代码里散落数字 0、1、2。重新排序看似只是保存格式变化，却会让旧 Embedding 的每一行对应到错误 Token。

构建词表时，先只用训练语料统计频次，再按规则选择容量。保留全部高频 Token 可能造成稀有片段太多，容量过小又会让 UNK 率升高。中文项目常把标点、数字和英文片段单独观察；技术文档中 API 名称、版本号和路径往往是任务信号，不应因为频次低就一律删除。词表报告至少包括总容量、特殊符号、覆盖率、UNK 率、最高频和最低频样例。

编码器要把“文本为空”“Token 不在词表”“长度超限”“批次需要补齐”分成不同状态。空文本可以返回只有 BOS/EOS 的序列，也可以作为无效样本拒绝，但必须统一；UNK 是可编码但信息未知；截断是保留一部分信息；PAD 只是为了形成矩阵。把四者都写成一串 0，后续的 mask 和错误分析就无法区分。

def encode_tokens(tokens, token_to_id, special, max_length):
    ids = [special["bos_id"]]
    ids.extend(token_to_id.get(token, special["unk_id"]) for token in tokens)
    ids.append(special["eos_id"])
    was_truncated = len(ids) > max_length
    if was_truncated:
        ids = ids[:max_length]
        ids[-1] = special["eos_id"]
    mask = [1] * len(ids)
    while len(ids) < max_length:
        ids.append(special["pad_id"])
        mask.append(0)
    return {"input_ids": ids, "attention_mask": mask,
            "was_truncated": was_truncated}

special = {"pad_id": 0, "unk_id": 1, "bos_id": 2, "eos_id": 3}
vocab = {"文本": 4, "表示": 5, "模型": 6}
print(encode_tokens(["文本", "未知词"], vocab, special, max_length=6))

示例把 EOS 放回最后一个有效位置，避免截断后序列没有边界。但这只是一个策略：对生成任务可能需要保留完整前缀，对分类任务可能保留头尾，对检索任务可能保留标题和问题关键词。策略名称写进输出，例如 truncate_policy="head_keep_eos"，这样错误分析才知道哪个样本被怎样处理。

词表保存要避免只写一个 Python pickle。JSON、文本或 safetensors 等格式更容易检查和迁移；无论使用哪种格式，都在加载后验证 Token→ID 与 ID→Token 的双射关系、特殊 ID 的存在、最大长度为正、版本字段非空。加载后用同一组固定样例做编码，确保不同机器的结果相同。若词表过大，分片保存也要有总 manifest 和顺序信息。

批处理时除了 attention_mask，还可能需要 token_type_ids、position_ids 或标签 mask。不要因为当前模型用不到就把所有字段混成一个字典而不说明来源。数据集类返回的字段应与模型 forward 参数一一对应，字段名和 dtype 都纳入测试。

词表大小不是越大越好

词表变大可以减少拆分和 UNK，但 Embedding 参数量、checkpoint 大小和输入稀疏度也会增加。词表太小则序列变长，训练和推理成本上升。选择大小时同时看覆盖率、平均/长尾 Token 长度、未知率和领域术语保留情况，不能只看训练集频率。

词表排序规则也属于模型协议。频率相同的 Token 若顺序不稳定，模型结果就难以复现。把构建脚本、输入语料版本、min_freq、max_size、特殊 Token 列表和排序规则写入 manifest，未来才能解释一次词表差异。

mask 的易错点

attention mask 的 0 通常表示不参与注意力，loss mask 的 0 表示不计入损失，不能因为名字相似就复用而不检查目标。若用 ignore_index，确认损失函数真的配置了同一个值；若手工加权，确认分母是有效位置数而不是总 padding 长度。验证一个 batch 时，把每一行的真实长度、PAD 数和有效目标数一起打印。

空文本是最容易暴露边界的样例。加入 BOS/EOS 后仍应有可处理的长度；全 PAD 序列不应让 mean loss 除以零；超长文本截断后要决定是否保留 EOS。把这些样例放入回归测试，避免正常句子掩盖协议错误。

截断后的信息损失要被看见

随机抽取一批超长文本，保存原文、截断前后 Token 数、保留片段和丢弃片段。若标签或答案常出现在被丢弃的部分，模型指标下降不是优化器问题，而是长度策略问题。检索系统还要检查标题、章节名和引用是否被切到相邻 chunk，必要时把元数据前缀复制到每个块。

切块参数一改，所有文档向量都可能失效。把 chunk_size、overlap、tokenizer 版本和 normalize 版本写入索引 manifest；查询端和文档端只要有一项不一致，就在启动时提示。这样索引重建是一次明确的迁移，而不是悄悄得到一批不可比较的向量。

形状检查比“看起来能运行”更可靠

在 Embedding 管道中为词表容量、维度、batch、序列长度和 mask 写断言。批次维度错位时，广播可能让代码运行却把另一条样本的 mask 乘到当前向量；这种错误通常不会立刻报错，只会让指标缓慢变差。记录一次从 [B,T] 到 [B,D] 的形状轨迹，是排查池化问题最便宜的办法。

当你把句向量送入相似度模块，明确是否做归一化、是否停止梯度和是否使用同一个编码器。查询与文档若使用不同的训练模式或预处理，向量空间不再可直接比较。先固定接口，再尝试冻结、微调和投影层。

观察 Embedding 是否真的在学习

固定一小组 Token 和句子，训练前后保存向量快照。可以比较相同类别文本的平均距离、不同类别的最近邻和分类验证指标，但不要只看某两个向量的数值变化。向量空间的质量必须用任务验证；如果训练损失下降而检索 Recall 不变，可能是分类目标与检索目标不一致。

把快照、配置和 seed 写入实验目录，下一次更换 pooling 或维度时才有对照。维度更大不保证语义更好，先用消融确认增加参数是否值得。

从 Token 向量到句子向量的选择题

如果任务只需要粗略主题，平均池化是透明、便宜、容易调试的起点；如果某些维度的强响应很重要，可以试 max pooling；如果模型专门训练了句首聚合位置，再使用首 Token；如果文本中有长短不一的关键区域，可以加入可学习的 attention pooling。每种方法都要用同一份验证集比较，并把 mask、归一化和维度记录在报告中。

池化前最好先做形状断言。假设 hidden 是 [B,T,D]，mask 应能广播为 [B,T,1]；分母是每条样本有效位置的数量，不能用整个 T。对全 PAD 或空文本，规定返回零向量、特殊向量还是拒绝，并在下游相似度中处理零向量。边界约定比某一种池化名称更重要。

import torch

def masked_mean(hidden, mask):
    if hidden.ndim != 3 or mask.shape != hidden.shape[:2]:
        raise ValueError("hidden/mask 形状不匹配")
    weights = mask.to(hidden.dtype).unsqueeze(-1)
    count = weights.sum(dim=1).clamp_min(1)
    pooled = (hidden * weights).sum(dim=1) / count
    empty = mask.sum(dim=1) == 0
    pooled[empty] = 0
    return pooled

hidden = torch.randn(2, 4, 6)
mask = torch.tensor([[1, 1, 0, 0], [0, 0, 0, 0]])
print(masked_mean(hidden, mask).shape)

如果要微调 Embedding，观察梯度范数和冻结策略。全量训练适合有足够标注的任务；数据很少时，冻结底层并训练轻量分类头可能更稳；领域差异很大时，可以用少量学习率更新。无论哪种策略，都要在报告中记录可训练参数量和学习率。不要仅凭训练损失下降就认为向量空间更适合检索，验证任务才是证据。

把 Embedding 看成一张会被训练的查找表

设词表有 V 个 Token，每个向量维度为 D，Embedding 的权重就是一个 V×D 的矩阵。输入 ID 不是数值大小有意义的特征，而是行号：ID 7 和 ID 8 没有“相邻所以更相似”的数学保证。查表只取出对应行，后续的线性层、注意力或池化才会组合这些向量。这个视角能解释为什么词表 ID 不能随意改，也能解释为什么把 ID 直接喂给线性模型通常是不合理的。

训练时，只有本批次出现的 Token 行会收到主要梯度；长期不出现的稀有 Token 可能仍接近随机初始化。可以通过增加样本、使用子词、设置合适的初始化或冻结/微调策略改善。不要把“向量数值看起来有规律”当成语义证据；Embedding 是否有用，要用分类、检索或相似度任务验证，并与简单基线比较。

padding_idx 的作用是把 PAD 行作为不参与更新的占位符。它不自动替你完成所有 mask：平均池化时仍要用 attention mask 排除 PAD，序列模型也要确认 padding 方向与位置编码一致。若把 PAD 当普通词求平均，短文本会被大量零向量或固定向量稀释，长短样本的比较会产生系统偏差。

import torch
from torch import nn

vocab_size, dim, pad_id = 8, 4, 0
table = nn.Embedding(vocab_size, dim, padding_idx=pad_id)
ids = torch.tensor([[2, 3, 0, 0], [4, 5, 6, 0]])
mask = (ids != pad_id).unsqueeze(-1)
hidden = table(ids)
summed = (hidden * mask).sum(dim=1)
counts = mask.sum(dim=1).clamp_min(1)
sentence = summed / counts
print("weight:", table.weight.shape)
print("hidden:", hidden.shape, "sentence:", sentence.shape)
assert torch.allclose(sentence[0], (hidden[0, 0] + hidden[0, 1]) / 2)

用 torch.no_grad() 查看权重时，不要把它误解成模型已经学会了语义；随机初始化的向量也能计算余弦。更有价值的检查是固定 seed 后训练几步，观察损失是否下降，或者让相似文本在验证集上更容易被检索。绘制二维投影只适合帮助观察，不能把投影后的距离当成原空间的精确关系。

池化策略体现了任务假设。平均池化把所有有效 Token 等权相加，稳健但可能冲淡关键否定词；max pooling 保留每个维度的强响应，可能过度依赖一个词；取首位置向量依赖模型是否专门训练了聚合 Token；带权池化可以按注意力或位置加权，但要报告权重来源。先做平均池化基线，再根据错误样例选择更复杂的方案。

设备和 dtype 是工程合同的一部分。词表 ID 通常是 torch.long，Embedding 权重可能是 float32、float16 或 bfloat16；输入和权重在不同设备会报错，混合精度还会影响数值稳定性。每个 batch 进入模型前打印一次形状、dtype、device，确认后再关闭调试日志。很多“模型效果忽高忽低”其实是评估时忘记 model.eval() 或 mask 没有同步移动到 GPU。

Embedding 的三种误解

第一，向量坐标没有固定人类含义；第 1 维不是“积极”，第 2 维也不是“长度”，除非你通过实验验证。第二，单个 Token 向量不等于句子含义，同一个词在不同上下文中可能需要不同表示。第三，向量距离只有在训练目标、归一化和比较集合确定后才有意义，不能看到两行数字接近就下结论。

读 Embedding 时先问它服务的任务。分类模型的 Embedding 可能只需帮助区分标签，检索模型则需要让同义查询和文档靠近；一个任务中有效的空间，不一定适合另一个任务。保存向量时同时保存 Tokenizer、词表、训练目标和模型版本。

训练表示时记录什么

每次训练至少记录 Embedding 维度、词表大小、padding 策略、汇聚方式、loss 定义、正负样本构造和向量归一化。若使用冻结的预训练 Embedding，记录是否允许微调；若只训练分类头，向量空间不会因标签数据改变。冻结与解冻是一个实验变量，不能混在同一运行里。

观察向量变化可以抽取固定 Token 的范数、相似邻居和若干句对的分数。它们不是最终指标，却能帮助发现 Embedding 没有更新、PAD 行被污染或梯度只集中在高频 Token 等问题。

从 Embedding 走向大模型表示

大模型的输入链通常从 Token ID 进入 Token Embedding，再叠加或融合位置表示，经过多层上下文模块，最后得到每个位置或整句的隐藏状态。你现在练习的 shape、mask、device、padding、版本和回归测试，会原样迁移到 Transformer。区别只是上下文模块更复杂、序列更长、资源账本更重要。

不要跳过小模型的表示实验。用几十条文本验证词表、mask、池化和相似度，可以在几秒内发现协议错误；直接上大模型时，同样的错误会被显存、下载和长时间训练掩盖。

把分数与人工判断放在同一行

抽样复核时同时展示查询、候选、分数、排序位置和人工标签；若两位复核者意见不同，保存争议而不是强行取平均。相似度实验的最终目的，是找到能被任务和证据支持的排序规则，学会解释不确定，而不是把一个阈值变成永远正确的答案。

完成本节后，至少应能手算二维向量、写出稳定余弦函数、处理零向量和空候选，并设计一份含 hard negative 的验证集。

小结：先定义空间，再谈相似

你需要能说清向量维度、归一化、分数方向、候选范围、Top-k、阈值、去重和 tie-break。缺少其中任何一项，“相似度 0.8”都只是一个脱离语境的数字。

给相似度实验加上可复盘的表格

每一条查询—候选对都保存 query_id、candidate_id、文本哈希、模型版本、归一化方式、原始分数、展示分数、相关性标签和人工备注。这样当一个边界样例从 0.71 变成 0.69 时，可以判断是模型更新、精度变化、文本处理还是排序规则造成的，而不是凭截图猜测。

实验报告还要标出候选池大小和计算成本。相同 Recall 下，减少一半候选或延迟下降 30% 可能比微小的分数提升更有价值。把每次实验的参数和结论写在同一行，未来换成 Transformer 句向量时仍可直接比较。

最后提醒自己：相似度高的文本可能共享模板、标题或关键词，却没有回答同一个问题。把“同主题但方向相反”“同 API 的不同版本”“引用错误结论”加入 hard negative，才能让检索评估接近真实使用。

阈值之外还要决定“返回几条”

Top-k 与阈值解决不同问题：k 限制页面最多显示几条，阈值限制结果最低需要多相关。两者同时使用时，先过滤还是先取 k 会改变结果，必须固定顺序并写入测试。若只有一条结果超过阈值，页面应显示一条并说明候选不足，而不是补上低分内容凑满 k。

在验证集上同时画 k 和阈值的质量—成本曲线，再选择符合用户场景的组合。缓存查询结果时把这两个参数加入键，不能只缓存查询文本。

用小矩阵手算一次 Top-k

假设一条查询向量是 [1,0]，三个候选是 [1,0]、[0.8,0.6] 和 [-1,0]。归一化后，它们的余弦分别接近 1、0.8 和 -1；如果改用未归一化点积，候选长度变大可能改变顺序。先手算这种二维例子，再写批量矩阵代码，能快速发现把转置写反、沿错维度取 Top-k 或把距离当相似度排序的问题。

Top-k 的 tie-break 需要可预测。可以按分数降序、chunk_id 升序排序；如果先用 GPU 的 topk，再对同分结果做稳定排序。展示分数时保留原始浮点用于排序，四舍五入只用于页面；阈值判断也使用未 round 的值。对每次查询记录候选总数、过滤前后数量和最终 rank，才能解释为什么页面只出现两条。

def stable_rank(scores, ids, k):
    rows = [{"id": item_id, "score": float(score)}
            for item_id, score in zip(ids, scores)]
    rows.sort(key=lambda row: (-row["score"], row["id"]))
    return rows[:k]

scores = [0.8, 0.8, 0.2]
ids = ["chunk-b", "chunk-a", "chunk-c"]
print(stable_rank(scores, ids, k=3))

在真实向量检索中，精确矩阵乘法适合小规模实验，近似最近邻索引适合候选很多的场景。换索引算法后，先比较同一批向量的 Recall@k 与延迟，再接入分类或生成模块。近似索引有自己的构建参数、随机性和内存成本，不能只把它当作一个“更快的矩阵乘法”。

相似度可视化可以画分数分布、正负例箱线图或二维投影。图表要标出样本数、切片和归一化策略，不要只展示最容易区分的十个点。若向量都挤在一个小区域，可能是 pooling、训练目标或数据重复造成的塌缩；先查范数和重复，再决定是否改变模型。

相似度只是排序信号，不是事实裁判

向量空间里“靠近”表示模型在训练目标下倾向于给两段文本相似的坐标。它可能受主题、词形、长度、模板和来源影响，并不自动等于事实相同、答案正确或用户满意。比较“如何安装”和“如何卸载”时，词面和主题可能很近，但操作方向相反；比较两段不同版本的 API 时，相似度高也不能证明参数兼容。把相似度作为候选排序信号，再用证据或规则核验，是更稳妥的流程。

点积同时受方向和向量长度影响，适合模型把范数也训练成信号的场景；余弦相似度只看方向，常用于句向量比较；欧氏距离把长度差异也纳入。归一化后，点积与余弦在排序上等价，但归一化前后的阈值不可直接互换。报告中写清是否 L2 normalize、在哪一侧归一化、矩阵乘法的维度和分数的取值范围。

数值边界必须显式处理。零向量无法定义稳定的方向；float16 下很大的点积可能溢出；批量矩阵中一个 NaN 会污染整行排序；候选分数相同却没有 tie-break 会让结果每次顺序不同。工程上可以对范数设置最小值、遇到非有限值拒绝或降级、统一 round 只用于展示而不用于排序，并按 chunk_id 做稳定的次序打破平局。

import torch
import torch.nn.functional as F

def cosine_scores(query, documents):
    query = query.float()
    documents = documents.float()
    if query.ndim == 1:
        query = query.unsqueeze(0)
    if documents.ndim != 2 or query.shape[1] != documents.shape[1]:
        raise ValueError("向量维度不一致")
    q_norm = query.norm(dim=1, keepdim=True)
    d_norm = documents.norm(dim=1, keepdim=True)
    if torch.any(q_norm == 0) or torch.any(d_norm == 0):
        raise ValueError("零向量不能直接计算方向相似度")
    q = F.normalize(query, p=2, dim=1)
    d = F.normalize(documents, p=2, dim=1)
    return q @ d.T

q = torch.tensor([1.0, 0.0])
docs = torch.tensor([[1.0, 0.0], [0.0, 1.0], [-1.0, 0.0]])
print(cosine_scores(q, docs))

对批量查询，输出形状通常是 [B, N]：每行是一条查询对 N 个候选的分数。Top-k 应沿候选维度取值，并同时保留原始索引；如果先过滤权限或语言，再排序，k 的含义是“可见候选中的 k”。若业务需要展示不同文档而不是同一文档的多个 chunk，还要在排序后做文档级去重，并报告去重前后的候选数量。

阈值不是模型常数，而是任务决策点。用验证集画分数与相关性分布，选择满足召回、误报或人工审核成本的阈值；测试集只用于最后报告。对于不同查询长度、语言或来源，最优阈值可能不同，但分组阈值会增加维护复杂度，先确认总体阈值是否已经足够。每一次阈值改变都应产生新的配置和回归报告。

硬负例能帮助你发现“高相似但不相关”的边界：同一主题的错误版本、相反操作、相邻章节和只共享模板的文本。把这些样例加入验证或训练要谨慎，不能把测试答案泄漏进模型。相似度实验最终要回到人工可理解的失败类型，而不是只优化一条曲线。

不要把坐标轴当成可读特征

Embedding 空间可以整体旋转、翻转或重新参数化而保持相似度关系，单独解释“第 8 维代表科技”通常没有依据。可解释性应来自近邻样本、对照实验、分组指标和错误案例，而不是给某一坐标强行命名。降维图适合展示局部结构，不是对高维空间的完整证明。

向量范数也要单独观察。若某类文本的范数普遍更大，点积排序可能偏向它们；若归一化后排名变化很大，说明长度携带了信号或噪声。把归一化前后的分数、Top-k 重叠率和任务指标一起报告，才能决定哪种比较更合适。

阈值不是模型的永久属性

阈值与分词器、Embedding 模型、语料领域和索引分布绑定。模型升级或文档增加后，分数分布可能改变，旧阈值不能直接沿用。用独立验证集选择阈值，报告 precision/recall 变化和无结果率；上线后监控分数分布漂移。

权限和业务规则应在候选过滤层明确处理。一个相似度最高但用户无权查看的文档不应被返回；过滤后结果不足 k 时，接口要能返回少量或无结果，而不是补回不合规候选。

相似度失败的四个常见原因

一是文本清洗把关键否定或数字删除；二是切块把标题和正文拆开；三是池化把 PAD 或长文本噪声混入；四是候选索引与查询模型/版本不一致。排查时先选一条失败查询，打印原文、Token、向量范数、Top-k ID 和分数，再逐层比较成功样例。

如果相似度高但人工认为不相关，检查关键词共现、模板化文本和重复来源；如果相似度低但语义明显相关，检查同义表达、领域术语和负例覆盖。错误类别比单纯增加维度更能指导下一次数据或模型改动。

训练一轮之前，先画出标签和错误的边界

标签编码表应同时保存人类可读名称、整数 ID、定义和示例。不要按字母顺序临时生成 ID 后直接训练；新增类别、类别合并或标签改名都可能改变旧报告。多标签任务使用每个标签独立的 sigmoid 与二元损失，单标签互斥任务使用 softmax 语义的交叉熵，二者的数据格式和阈值策略不同。

学习率、batch size、epoch、class weight、dropout、seed 和 early stopping 都属于实验配置。训练日志至少记录每轮训练损失、验证损失、主要指标和最佳 checkpoint；只保存最后一轮，可能错过验证集表现最好的模型。测试集只在最终选择方案后运行，避免把测试结果当成调参反馈。

from collections import defaultdict

def error_buckets(rows):
    buckets = defaultdict(list)
    for row in rows:
        if row["gold"] == row["pred"]:
            continue
        text = row["text"]
        if len(text) < 12:
            key = "too_short"
        elif any(char.isdigit() for char in text):
            key = "contains_number"
        elif "不" in text or "未" in text:
            key = "negation"
        else:
            key = "other"
        buckets[key].append(row["id"])
    return {key: {"count": len(ids), "ids": ids}
            for key, ids in buckets.items()}

print(error_buckets(prediction_rows))

错误分桶只是起点，不要把一个规则标签当成根因。抽取代表样例后，判断问题来自输入缺信息、标签边界、模型表示、阈值还是展示。每个修复动作都应该对应一组回归样例，下一次训练才能判断它是否真的减少了该类错误。

先把分类器当作一个输入输出合同

一个单标签分类器接收批量 input_ids 和可选的 attention_mask，输出形状为 [batch_size, num_classes] 的 logits。标签是形状 [batch_size] 的整数类别索引，而不是 one-hot 文本。CrossEntropyLoss 内部会处理 log-softmax 和负对数似然，因此训练时传 logits，不要先手动 softmax 再传入。预测阶段才用 softmax 或 argmax 解释概率和类别。

先写多数类、随机、关键词和词袋基线，能够回答“任务是否比猜测更难”。如果 Embedding 平均池化只比多数类高一点，不一定是代码错，也可能是样本太少、标签含糊、文本截断或任务本身需要上下文。基线还可以作为回归护栏：任何复杂模型都不应在同一 split 上明显输给一个合理的简单方案却没有解释。

训练循环要分清训练模式和评估模式。训练时清零梯度、前向、计算损失、反向和更新；验证时使用 model.eval() 与 torch.no_grad()，不能把验证样本加入梯度。固定 seed 只能减少随机波动，不能保证所有 GPU 算子绝对确定；报告中写出设备和确定性设置。

import torch

def train_one_epoch(model, loader, optimizer, loss_fn, device):
    model.train()
    total_loss, total_items = 0.0, 0
    for batch in loader:
        ids = batch["input_ids"].to(device)
        mask = batch["attention_mask"].to(device)
        labels = batch["labels"].to(device)
        optimizer.zero_grad(set_to_none=True)
        logits = model(ids, mask)
        loss = loss_fn(logits, labels)
        loss.backward()
        optimizer.step()
        total_loss += loss.item() * labels.size(0)
        total_items += labels.size(0)
    return total_loss / max(total_items, 1)

@torch.no_grad()
def predict(model, loader, device):
    model.eval()
    outputs = []
    for batch in loader:
        logits = model(batch["input_ids"].to(device), batch["attention_mask"].to(device))
        outputs.extend(logits.argmax(dim=1).cpu().tolist())
    return outputs

类别不平衡时，可以在损失中使用 class weight、在采样器中提高少数类概率，或收集更有代表性的样本。三者都可能改变训练分布，所以验证和测试仍应保持真实分布。阈值调节尤其适合二分类或多标签任务，不能为了提高单一 F1 而让线上误报成本失控。

错误分析要回到文本而非只看 confusion matrix。把错误按“否定词、数字/版本、过短、过长、混合语言、标签边界、近似重复、无上下文”分桶，抽取每桶的支持数和代表样例。若某个桶很大，先补数据或改任务说明；若只是少数异常，记录已知限制可能比增加模型层数更诚实。

分类数据的最低审计

统计每类样本数、文本 Token 长度、空文本比例、重复 ID、重复文本和 split 交集。随机抽取每类若干条，检查标签是否符合定义；尤其关注否定、反讽、代码、数字和边界案例。类别极不平衡时，先报告多数类基线和每类支持数，再决定加权损失或采样。

标签映射要有方向和版本：label_to_id 供训练，id_to_label 供报告。不要在评估脚本里按字母序重新生成映射，否则混淆矩阵的列名可能错位。把映射写进 manifest，加载 checkpoint 时检查类别数一致。

学习率和损失的观察

训练 loss 快速下降而验证 loss 上升，可能是过拟合、切分泄漏或验证 transform 不一致；训练和验证都不动，可能是标签、mask、学习率或参数未注册；loss 变成 NaN，先回到输入和梯度的有限性检查。记录第一批 logits、第一步梯度和每个 epoch 的有效样本数，通常比只看最后一轮更有用。

优化器应在创建模型后一次性接收参数。若冻结 Embedding，确认 requires_grad=False 且没有把它误传给需要更新的优化器；若解冻，记录解冻 epoch 和学习率。模型、词表、标签映射和训练配置共同决定结果。

把错误变成数据改进假设

如果错误集中在标签边界，先重写标注指南并抽样复核；如果集中在未知 Token，检查词表或领域数据；如果短文本缺少上下文，比较拼接标题、字符级表示或上下文模型；如果高置信度错误来自模板，检查重复和泄漏。每个假设只改一个因素，保留旧模型和旧报告。

改进后的指标必须和旧版本使用同一验证集、同一类别映射和同一分母。若新增数据或改变切分，报告应明确这是新实验，不要把数字直接放在旧曲线旁边当作同一条件下的提升。

两阶段检索要分别回答两个问题

第一阶段问“相关内容有没有进入候选池”，第二阶段问“候选中谁应该排在前面”。如果第一阶段就漏掉了相关 chunk，重排模型再强也无法补回；如果候选池很大但排序差，用户会看到噪声。分别记录 candidate_recall、rerank_mrr、候选数量和每阶段耗时，才能知道瓶颈是召回还是排序。

查询和文档的编码模板要成对设计。查询可以加入“问题：”，文档可以加入标题和段落边界；模板改变会改变向量分布，必须进入模型/预处理版本。对技术资料，标题、API 名称和版本号常常值得额外权重，但权重应在验证集上调，而不是凭一条成功案例固定。

def trace_query(query_id, query, candidates, visible_acl, threshold):
    trace = {"query_id": query_id, "candidate_count": len(candidates), "filtered": []}
    visible = []
    for item in candidates:
        if not set(item["acl"]).intersection(visible_acl):
            trace["filtered"].append({"id": item["chunk_id"], "reason": "acl"})
            continue
        if item["score"] < threshold:
            trace["filtered"].append({"id": item["chunk_id"], "reason": "threshold"})
            continue
        visible.append(item)
    visible.sort(key=lambda item: (-item["score"], item["chunk_id"]))
    trace["results"] = [
        {"rank": rank, "chunk_id": item["chunk_id"], "source": item["source"]}
        for rank, item in enumerate(visible, start=1)
    ]
    return trace

print(retrieval_trace("q-01", "如何编码", candidates, {"public"}, 0.6))

日志中的过滤理由应是有限、稳定、对用户安全的类别，例如 acl、threshold、duplicate、invalid_metadata。不要把“这篇内部文档与查询很相似”写进无权限用户可见的错误消息。调试日志可以更详细，但也要遵守脱敏和保留期限。

结果解释最好同时展示一个语义信号和一个词面信号：相似度告诉用户为什么进入候选，关键词命中或标题字段告诉用户为什么排序靠前。两个信号冲突时，不要自动选择看起来更合理的一个，而是保留分数和规则，交给评估与人工复核。可解释性是让错误变得可定位，不是给模型编造理由。

索引的核心是“能找到，也能回去”

向量索引并不只是一个矩阵。它还要保存每一行向量对应的 chunk ID、文档 ID、标题、来源、字符 offset、权限、语言和版本。矩阵顺序一旦改变，metadata 必须同步重排；否则相似度算对了，展示出来的正文仍可能来自另一篇文档。学习阶段可以把向量和 metadata 放在同一个 JSON/NPY 配对目录，加载时先检查数量和 ID 顺序。

切块大小会在召回率、证据完整性和延迟之间折中。块太小，查询命中后缺少上下文；块太大，主题混杂且向量被多个意图平均。重叠窗口可以减少边界丢失，但会制造重复候选和更大的索引。先用段落切块建立基线，再用固定 Token 窗口、标题拼接和 overlap 做单变量对照，所有参数进入 manifest。

召回阶段优先追求覆盖，重排阶段再追求顺序。第一阶段可以用近似向量搜索、BM25 或词袋快速取较大的候选池；第二阶段把查询和候选一起交给更精细的交互模型或规则。两阶段的分数不在同一尺度时，要先归一化或在验证集学习权重，不能直接把 0.8 的余弦和 12.0 的关键词计数相加。

权限过滤的顺序要符合安全目标：用户无权查看的文档不能因为高分先出现在页面或日志。如果索引支持预过滤，记录过滤条件；如果只能后过滤，扩大召回池并统计被过滤数量，避免所有可见结果都被挡掉。没有权限字段的旧 chunk 要默认不可见，而不是默认公开。

import hashlib
import json
from pathlib import Path

def make_manifest(chunks, model_name, preprocess_version):
    ids = [row["chunk_id"] for row in chunks]
    if len(ids) != len(set(ids)):
        raise ValueError("chunk_id 必须唯一")
    return {
        "index_version": "index-v1",
        "model_name": model_name,
        "preprocess_version": preprocess_version,
        "chunk_count": len(chunks),
        "chunk_order_hash": hashlib.sha256(
            "\n".join(ids).encode("utf-8")
        ).hexdigest(),
        "dimensions": chunks[0]["vector_dim"] if chunks else 0,
    }

chunks = [{"chunk_id": "c-1", "vector_dim": 384}]
Path("index_manifest.json").write_text(
    json.dumps(make_manifest(chunks, "demo-embedding", "clean-3"),
               ensure_ascii=False, indent=2),
    encoding="utf-8",
)

查询日志也要分层保存：原始查询、规范化查询、Token 数、候选池大小、召回耗时、重排耗时、最终结果 ID、空结果原因和用户权限版本。日志中不要直接保存敏感正文，必要时使用哈希和短片段。这样可以计算 P50/P95 延迟、定位慢查询，并区分“没有相关文档”和“有相关但被权限过滤”。

去重有两个层次：相同 chunk_id 的重复属于程序错误；同一文档相邻重叠块的重复属于策略问题。可以先按文档取最高分，再用相邻 offset 合并展示，但评估时要保留原始 rank，避免把后处理的漂亮页面误当成召回能力。对标题和正文混合打分时，记录每个信号，方便解释重排。

切块的三个反例

只按固定字符数切块，可能把标题、表格行或代码函数截断；只按自然段切块，可能让一个超长段落超过模型上限；只保存向量不保存原文，命中后无法核验。遇到长段落，可以先按句子切分再合并到目标长度，并在 metadata 里标记是否跨段。

重复 chunk 会让 Top-k 被同一内容占满。索引前按 text_hash 去重，或检索后按 document_id 做多样性过滤；选择哪一种要根据任务。报告中说明去重发生在索引前还是排序后，否则 Recall@k 的分母和候选集合都不清楚。

延迟账本与质量账本要同时记录

一次检索至少记录查询 Token 数、Embedding 时间、索引搜索时间、重排时间、过滤数量、最终返回数和总 wall-clock。质量侧记录 Recall@k、MRR、无结果率和人工相关率。只优化延迟可能让召回下降，只优化指标可能让成本失控；两本账放在同一份 run 记录里，才能做真实取舍。

候选索引可以分片或分块计算。分块搜索时每块先取局部 Top-k，再合并成全局 Top-k；不能简单拼接局部结果。合并时保留稳定 tie-breaker，使用相同 dtype 和归一化，否则边界分数可能出现不一致。

一条结果的证据卡

可以把每条结果整理成“查询—候选—模型—规则—权限—原文”六格证据卡：查询 ID 和原文，candidate/chunk ID，Embedding 模型和分数，关键词或重排信号，用户可见范围，最终展示片段。出现错误时沿六格回放，能够快速判断是向量不相似、规则过滤、权限变化还是展示映射错。

解释文本时避免使用“模型认为这段一定正确”。相似度只是排序信号，不能替代事实核验。对知识库问答，后续生成模型也应引用检索到的原文并标记不确定；本章先把检索证据链做好。

把每个数字绑定到一个可复算的问题

评估前先写“如果系统真的有用，用户会看到什么变化”。分类可能是少数类漏报下降，检索可能是第一条证据更常包含答案；这些目标再映射到 macro-F1、Recall@k、MRR 或人工采纳率。报告同时保留支持数和失败样例，防止一个总体均值掩盖小群体的严重问题。

标注协议要规定边界：同义表达算相关吗？只包含关键词但没有回答算相关吗？多段拼起来才能回答的问题，单个 chunk 给几级相关性？两位标注者意见不一致时如何仲裁？协议变化会改变 gold，必须记录版本并重新解释旧指标。宁可承认一部分样例“待复核”，也不要用模糊标签制造虚假的确定性。

回归测试应分成快速 smoke、完整离线评估和人工复核三层。Smoke 只跑几十个固定样例，检查接口、形状、ID、空值和权限；完整评估计算全部指标和切片；人工复核查看最重要的升降与新出现的错误。三层速度不同，但都引用同一份版本清单，避免快速测试与正式评估使用不同规则。

对于随机模型或小数据，保存多个 seed 的结果；对于检索，保存每条查询的排名而不只是平均 Recall。遇到指标变化时，可用每条样例的配对差异查看是少数案例推动，还是普遍改善。统计显著性不是唯一标准，业务风险、延迟和证据质量同样重要。

def compare(current, baseline, gates):
    failures = []
    for name, rule in gates.items():
        now, old = current[name], baseline[name]
        delta = now - old
        if rule["direction"] == "up" and delta < -rule["tolerance"]:
            failures.append((name, delta, "下降超过容差"))
        if rule["direction"] == "down" and delta > rule["tolerance"]:
            failures.append((name, delta, "上升超过容差"))
    return failures

gates = {
    "macro_f1": {"direction": "up", "tolerance": 0.01},
    "empty_rate": {"direction": "down", "tolerance": 0.02},
}
print(compare({"macro_f1": 0.79, "empty_rate": 0.08},
              {"macro_f1": 0.80, "empty_rate": 0.07}, gates))

门禁规则只负责发现变化，不负责替你决定是否发布。报告里把“硬失败”和“需要人工确认”分开：核心少数类召回大幅下降可能硬失败；某个小切片有轻微波动则进入人工复核。每次豁免也要写原因和到期时间，避免告警永久被忽略。

读懂指标的四个追问

第一，样本单位是什么？一行是句子、文档、查询，还是一个用户会话？第二，正例是谁标的，标注指南怎样处理争议？第三，阈值或 k 是事先固定还是在测试集上挑出来的？第四，指标下降时，用户实际多了哪一种错误？这四个追问能把“F1 从 0.81 变成 0.83”的兴奋，变成可以行动的结论。

不要把训练集、验证集和测试集的结果放在同一张没有标题的表里。至少标出 split、样本数、模型版本、预处理版本和运行时间。对于检索，另外记录候选池大小、去重规则、过滤规则和是否经过重排。只有上下文相同的数字才适合横向比较。

偏差报告不要变成泛泛的道德口号

好的偏差记录会写出“哪一组、多少样本、哪一个指标、与总体差多少、可能原因、下一步验证”。例如：“短文本（Token≤8）占测试集 18%，macro-F1 比总体低 0.14；错误多为上下文不足，下一轮增加短标题样本并测试字符级基线。”这样的句子既承认风险，也让修复可以被验证。

如果某一切片样本太少，不要给出过度精确的排名。可以报告支持数、置信区间和“暂不下结论”，并把它列入数据收集计划。谨慎不是降低标准，而是避免把噪声包装成事实。

回归失败时的处理顺序

先确认输入和版本是否真的相同，再确认失败是硬门槛还是统计波动；然后定位到具体切片和样例，最后决定是修代码、修数据、改阈值还是更新任务边界。不要一看到总分下降就立刻调大模型。很多回归来自空白处理、排序 tie-break、权限过滤或样例标签变化。

一份成熟的报告会保留“未解决问题”栏目。比如某类长文档仍会被固定窗口截断，当前只通过提高重叠缓解，尚未验证新的分块策略。把未知写出来，后续的人就不会把临时补丁误当成最终方案。

把综合项目拆成三个可独立验收的里程碑

里程碑一是“文本可追溯”：输入公开文件，产出 documents 和 chunks，任意 chunk 都能通过文档 ID 与 offset 回到原文。里程碑二是“结果可解释”：输入查询，返回稳定排序、来源、分数、过滤理由和无结果原因。里程碑三是“结论可复核”：固定 gold，生成指标、切片、错误和版本报告。每个里程碑都先用标准库基线完成，再接入更复杂的模型。

验收时做一次故障演练：修改清洗版本、删除一个索引文件、把一个用户 ACL 改掉、输入空查询、加入重复文档。系统应明确失败或给出降级，不应继续输出看似正常但无法追溯的结果。故障演练比只测试成功路径更能证明项目真的掌握了数据契约。

from pathlib import Path
import hashlib
import json

def file_hash(path):
    return hashlib.sha256(path.read_bytes()).hexdigest()

root = Path("artifacts")
manifest = {
    "project_version": "chapter7-v1",
    "files": {
        name: file_hash(root / name)
        for name in ["documents.jsonl", "chunks.jsonl",
                     "vocab.json", "index.json", "gold.json"]
        if (root / name).exists()
    },
}
(root / "manifest.json").write_text(
    json.dumps(manifest, ensure_ascii=False, indent=2),
    encoding="utf-8",
)
print("manifest entries:", len(manifest["files"]))

项目档案不只是给老师打分，也是在为后续 Transformer 实验保留稳定起点。下一章替换编码器后，仍可以使用同一批 chunks、gold 和 smoke test；若结果变化，才能把原因聚焦到上下文表示、注意力或微调策略。

把作品写成一份可交接的项目档案

项目目录可以采用 data/raw、data/processed、artifacts、src、tests 和 reports 的分层。原始文件只读，处理结果带版本，模型和索引由 manifest 指向，报告按 run_id 保存。目录清晰不是形式主义：当你换一台电脑、重建词表或回看一个错误查询时，能迅速找到该找的文件。

README 开头写一个五分钟成功路径，再写完整命令和限制。成功路径应能从少量公开样例生成一个结果；完整路径再加入批处理、评估和消融。每个命令注明输入、输出和预计耗时，遇到失败给出常见原因。不要把“在我的 notebook 里运行过”当作安装说明，隐藏状态会让别人无法复现。

交付验收可以按功能、质量、可解释性和安全四个维度评分。功能看能否读取、切块、编码、检索和返回结果；质量看 gold 指标与回归；可解释性看结果能否回到来源和 offset；安全看 ACL、日志和删除。代码行数只是一种成本指标，不是学习成果。职责清楚、数据契约稳定、失败边界诚实，比堆更多模型层更重要。

def smoke_search(pipeline):
    result = pipeline.search("如何设置编码", user_acl={"public"}, top_k=3)
    assert result["query_id"]
    assert len(result["items"]) <= 3
    for item in result["items"]:
        assert item["chunk_id"]
        assert item["source"]
        assert item["text"]
        assert item["index_version"]
        assert set(item["acl"]).intersection({"public"})
    return {"status": "ok", "items": len(result["items"])}

print(smoke_search(pipeline))

Smoke test 不需要知道模型内部每个浮点数，但要检查用户真正依赖的合同：结果数量、字段完整、权限可见、版本存在、空结果有原因。再增加一个无权限查询和一个没有相关文档的查询，确认系统不会通过异常或日志泄露正文。测试数据可以很小，边界要有代表性。

后续进入 Transformer 学习时，可以保持项目接口不变，只替换表示模块：把平均 Embedding 换成上下文编码器，把静态相似度换成训练好的句向量，把简单重排换成交互模型。每次替换都重新跑同一份 gold 和回归样例，才能知道提升来自上下文表示还是其他改动。项目因此成为贯穿后续章节的实验基座。

项目启动前的四张纸

第一张是任务卡：用户输入什么，结果要显示什么，什么叫“相关”，无结果时怎么办。第二张是数据字典：每个字段、来源、许可、缺失策略。第三张是版本清单：代码、清洗、分词器、词表、Embedding、索引。第四张是错误预算：允许多少空结果、重复结果、权限误展示和延迟。写完这四张纸，项目范围会比“做一个搜索器”清楚得多。

学习项目可以只用本地公开资料，不要直接把私人聊天、公司内部文档或含个人信息的文件放进练习目录。展示结果时保留出处和许可说明；自制图示可以解释架构，但不要复制受版权保护的整页截图。

三种常见的“假提升”

第一，测试查询被加入了词表或索引，导致 OOV 减少但未来并没有这份信息。第二，调参多次后只报告最好的一次，忽略了选择过程本身使用了测试集。第三，缓存没有包含预处理版本，实际上读取的是旧向量。排查时把原始 manifest、运行日志和缓存命中信息一起看，通常比重新训练更快找到原因。

消融表最好同时有“配置、核心指标、支持数、成本、观察、决定”。“不显著”也是结论：它可能说明数据太小、组件不适合任务，或需要更合理的标注，而不是说明实验白做了。

从项目作品回看知识地图

如果文本乱码，回到 7.1.1 看 bytes、str 和编码；如果长度忽长忽短，回到 7.1.2 和 7.2.1 看规范化与 Token；如果 ID 对不上，回到 7.3.1～7.3.3 看特殊符号、padding 和截断；如果句子向量不稳定，回到 7.4.1～7.4.3 看查表、mask 和 pooling；如果排序看似相似却不相关，回到 7.5.1～7.5.3 看向量几何和阈值；如果总体分数漂亮但用户不满意，回到 7.6～7.8 看基线、切片、泄漏和回归；如果流程无法重跑，回到本节检查版本和产物。

学习资料的价值不只在“记住一个 API”。你要逐渐养成一种工程化阅读方式：每个概念都有输入、输出、假设、可观测证据和失败边界。带着这五个问题进入 Transformer，注意力、位置编码和预训练就不再是孤立名词，而会成为表示链路中可以被实验和评估的组件。

官方参考阅读

想继续查原始定义，可阅读 Python Unicode HOWTO，理解 Unicode 与编码；阅读 PyTorch nn.Embedding API，核对查表层的参数和 padding_idx；阅读 PyTorch Data Tutorial，把本章的文本 Dataset 与批处理契约迁移到官方数据管道。

官方文档是查定义和边界的地方，本章正文负责把它们组织成零基础可以运行的实验。遇到版本差异，以你当前环境的官方文档和版本号为准，并把差异写进项目 manifest。