数学
直觉

先区分“值”与“位置”

标量只有一个数值，写成 7 时不需要说明第几个坐标；向量是一组按位置排列的数，写成 (7, 2) 时，两个位置可能分别代表身高和体重，也可能代表平面上的横坐标和纵坐标。数字本身并不能告诉你语义，顺序也不是装饰。如果把一个向量的两个分量交换，数学上得到的是另一个向量；在程序中却可能仍然通过类型检查，直到模型输出明显异常才被发现。

向量可以用行或列的形式书写。[x, y, z] 常用于展示一个长度为 3 的一维数组，[[x], [y], [z]] 则是 3 行 1 列的二维矩阵。它们包含相同的数字，却不一定能直接和同一个矩阵相乘。初学时建议在变量名或注释中写出形状，例如 feature_vector: (4,)、column_vector: (4, 1)。这样做看似啰嗦，却能提前阻止“维度刚好广播成功但语义错误”的问题。

单位同样重要。把“分钟”和“秒”直接相加，Python 不会报错；把表示颜色的 RGB 向量与表示词语的 Embedding 做平均，也可能得到一组合法浮点数。数学直觉不是只问“算式成立吗”，还要问“这个对象允许这样组合吗”。模型训练中常见的归一化、缩放和标准化，本质上都是在改变数值的单位或尺度；改变之后要把新含义记录下来。

from math import isclose

# 先用注释写清楚语义和形状
minutes = 42.0                    # 标量，单位：分钟
feature = [42.0, 0.75, 3.0, 1.0]  # 向量，形状：(4,)

assert len(feature) == 4
assert minutes >= 0
assert 0 <= feature[1] <= 1

# 这是按位置访问，不是按“最接近的含义”访问
minutes_again = feature[0]
assert isclose(minutes_again, minutes)
print("shape=(4,), minutes=", minutes_again)

这段代码没有调用任何机器学习库，却已经包含了一个重要的模型习惯：先写契约，再让程序验证契约。len(feature) 只告诉你有四个位置，并不能证明第一个位置真的代表分钟；语义仍然需要命名、注释、数据字典或测试来保证。后续把列表换成 NumPy 数组时，仍然应保留这些断言，而不是因为库会自动处理形状就放弃说明。

长度是一个函数，不是“看起来有多长”

向量的长度通常用范数表示。二维向量 v=(3,4) 的 L2 范数是 sqrt(3²+4²)=5，它对应平面直角距离；L1 范数是各分量绝对值之和，表示沿坐标轴走过的总路程；无穷范数则只看绝对值最大的分量。不同范数不是谁对谁错，而是在表达不同的成本模型。图像稀疏、特征选择和鲁棒优化中，选择范数就等于选择“什么样的偏差更值得惩罚”。

距离通常是两个向量之间的量，常见的欧氏距离为 ||x-y||₂，余弦相似度则比较方向：cos(x,y)=x·y/(||x||₂||y||₂)。两个向量长度差很多但方向相同，余弦相似度仍可能接近 1；如果任务关心“总量”，欧氏距离更合适；如果任务关心“语义方向”，余弦通常更容易解释。Embedding 检索经常把向量归一化后使用点积，此时点积和余弦相似度在数值上相同，但前提是双方都真的归一化了。

尺度会改变距离的主导因素。一个特征范围是 0 到 1，另一个范围是 0 到 10000，直接计算欧氏距离时，后者几乎决定结果。标准化、最大最小缩放或单位换算可以缓解这种影响，但它们不是“让数据更正确”的魔法：缩放参数必须从训练集估计，验证集和测试集只能复用，不能用全体数据偷看未来。对于向量数据库，还要记录距离度量、归一化方式和版本，否则同一批 Embedding 换一个设置就会得到不同邻居。

from math import sqrt

def dot(left, right):
    assert len(left) == len(right)
    return sum(a * b for a, b in zip(left, right))

def l1(vector):
    return sum(abs(value) for value in vector)

def l2(vector):
    return sqrt(dot(vector, vector))

def cosine(left, right):
    left_norm = l2(left)
    right_norm = l2(right)
    if left_norm == 0 or right_norm == 0:
        raise ValueError("零向量没有可定义的方向")
    return dot(left, right) / (left_norm * right_norm)

a = [3.0, 4.0]
b = [6.0, 8.0]
print("L1(a)=", l1(a))
print("L2(a)=", l2(a))
print("cos(a,b)=", cosine(a, b))  # 方向相同，接近 1

零向量是一个值得单独记住的边界：它的 L1 和 L2 范数都是 0，但余弦相似度需要除以长度，因而没有定义。实际系统中不能把这种情况交给浮点异常或得到一个随意的 0；应该在数据清洗、Embedding 生成或检索函数中明确处理。类似地，浮点数比较要允许合理误差，不要直接写 l2(a) == 5 来判断计算是否成功。

“加权平均”不是随便加权

如果一组基向量能够通过系数相加得到一个目标向量，我们称目标向量是它们的线性组合。二维平面里，单位向量 e₁=(1,0) 和 e₂=(0,1) 可以表达任何 (x,y)=x e₁+y e₂。在特征工程中，基向量可以理解成一组方向；在 Embedding 中，向量的每个维度未必有清晰的人类标签，但线性组合仍然可以表示“多个因素共同出现”的状态。重要的不是把每个维度拟人化，而是观察组合、尺度和相似关系是否稳定。

系数是否非负、是否加起来等于 1，会改变解释。非负且和为 1 的系数形成凸组合，结果落在几个点之间，可解释为混合比例；系数允许为负时，结果可能离开原来的线段或区域，适合表达方向差异，却不能再直接说成“比例”。模型中的权重通常不满足和为 1，它们是优化过程中为了降低损失而学习到的系数。把所有权重都叫“概率”会造成误解，只有经过明确归一化并满足概率约束后才可以这样解释。

线性组合还帮助理解插值和外推。两个已知向量之间的插值通常比较平滑，因为系数在 0 到 1 之间；把系数推到区间外是外推，结果可能落到训练数据没有覆盖的区域。做向量检索或生成式模型分析时，不能因为一条路径在二维图上看起来直线，就断言语义空间一定线性；需要用实际任务、邻居稳定性和多个方向的实验验证这种近似是否有用。

def combine(weights, vectors):
    if not vectors or len(weights) != len(vectors):
        raise ValueError("权重和向量数量必须匹配")
    dimension = len(vectors[0])
    if any(len(vector) != dimension for vector in vectors):
        raise ValueError("所有向量必须拥有相同维度")
    result = [0.0] * dimension
    for weight, vector in zip(weights, vectors):
        for index, value in enumerate(vector):
            result[index] += weight * value
    return result

python = [1.0, 0.0, 0.4]
math = [0.0, 1.0, 0.8]
weights = [0.25, 0.75]
mix = combine(weights, [python, math])
assert abs(sum(weights) - 1.0) < 1e-12
print("凸组合=", mix)

代码中的双层循环揭示了一个常被库函数遮住的事实：线性组合是“每个向量乘一个系数，再按对应位置相加”。如果向量维度不一致，不能靠补零或广播悄悄修复，除非任务明确需要那样做。向量化库会让运算更短，但不应让你忘记维度检查。调试时可以先用二维、三维小例子打印每一步，再换成几百或几千维的 Embedding。

把坐标、尺度和语义放在同一张检查表里

向量进入模型前，至少要回答三层问题。第一层是表示层：每个位置对应什么特征，是否有顺序，是否允许重复或缺失。第二层是尺度层：各维的数值范围、单位和离群点如何处理，缩放参数从哪一批数据估计。第三层是比较层：后续使用内积、欧氏距离还是余弦相似度，零向量和非有限值怎样处理。只写“这是一个 768 维向量”远远不够，因为同样的形状可以承载完全不同的语义和尺度。

标准化也要区分训练阶段与推理阶段。假设用均值 μ 和标准差 σ 把特征变成 (x-μ)/σ，μ、σ 应只从训练数据估计，再原样应用到验证、测试和线上输入。如果把全部数据一起算均值，测试集的信息就泄漏进了预处理；如果每次线上请求重新计算，单个样本会被错误地当作一个总体。保存缩放参数时要带上字段顺序、缺失值策略和版本，恢复模型时先检查这些元数据。

距离度量背后其实是一组假设。欧氏距离把每个坐标的单位和重要性视为可比较，余弦相似度假设方向比长度更重要，L1 范数则让每个坐标的绝对偏差线性累加。没有“通用最好”的指标，只有与任务代价相符的指标。比如文档检索可能关心主题方向，异常检测可能更关心绝对偏离，资源分配则可能不能忽略总量。写实验报告时，把“为什么选这个度量”与结果一起保存。

可视化也可能改变直觉。把高维向量投影到二维后，投影方向、随机种子和降维方法会影响局部邻居；一个二维图上的簇不一定在原空间存在同样的边界。建议固定一组原始向量，分别报告原空间指标、二维图指标和投影参数。图形用来提出问题，回归测试和原始数值用来回答问题。

from statistics import mean, pstdev

train = [10.0, 12.0, 14.0, 16.0]
mean_value = mean(train)
std_value = pstdev(train)
scale = lambda value: (value - mean_value) / std_value if std_value else 0.0
scaled_train = [scale(value) for value in train]
new_value = scale(20.0)
print({"mean": mean_value, "std": std_value, "train": scaled_train, "new": new_value})

这段代码还没有处理异常值和缺失值，正好提醒我们：缩放函数不是清洗函数。正式实现可以返回一份审计记录，列出被跳过的值、训练样本数量和计算版本。对向量检索，应在缩放后再测范数和相似度，确认预处理没有让所有向量塌缩到同一个方向。

标准化、归一化和坐标变换不是同一个词

标准化通常指减去均值再除以标准差，让一列特征接近零均值、单位方差；归一化可能指把数值压到某个区间，也可能指把向量除以 L1 或 L2 范数。不同资料对词语的使用不完全一致，所以实验中要写公式、统计量来源和拟合范围。只在训练集上估计均值与标准差，再把同一组统计量应用到验证和测试，才能避免把未来信息泄漏进预处理。

向量除以范数会改变长度信息，只保留方向。对检索来说，这可能让不同长度的表示更公平；对需要用范数表达置信度的任务，却可能损失信号。L1 归一化让分量绝对值之和为 1，L2 归一化让平方和开根为 1；稀疏特征、概率分布和几何方向分别可能更适合不同范数。选择范数前先写出下游相似度和决策含义。

坐标系改变后，数值大小的直觉也会改变。一个向量在标准基下看起来稀疏，经过旋转后可能每个分量都非零；一个矩阵的元素很大，不代表它会把所有方向都放大，因为奇异值和方向共同决定作用。比较模型表示时，要固定坐标变换、随机种子和降维方法，避免把可视化坐标的变化误认为语义变化。

距离度量隐含了几何假设。欧氏距离假设各轴可相加且尺度可比较，曼哈顿距离对单轴偏差更线性，余弦距离忽略长度，马氏距离还会考虑协方差结构。高维空间会出现距离集中、近邻差异变小等现象，不能直接把低维图上的“远近”套到高维检索。应在真实查询集上验证距离与任务指标的关系。

from math import sqrt

def fit_standardizer(train):
    if not train:
        raise ValueError("训练数据不能为空")
    mean = sum(train) / len(train)
    variance = sum((value - mean) ** 2 for value in train) / len(train)
    scale = sqrt(variance)
    if scale == 0:
        raise ValueError("常数特征不能按标准差缩放")
    return mean, scale

def transform(values, mean, scale):
    return [(value - mean) / scale for value in values]

mean, scale = fit_standardizer([10, 12, 14, 16])
print(transform([11, 15], mean, scale))
# 练习：故意把测试数据加入 fit，观察结果为何发生泄漏

预处理对象应像模型参数一样保存版本。上线时先加载训练阶段拟合出的统计量，再处理新数据；不要每个请求重新计算均值，否则输入分布会改变模型坐标。对于批量推理，记录原始值、转换后值、缺失标记和异常截断数量，才能在结果异常时回溯。

把向量当成接口：长度、方向与单位必须同时可追踪

同一组数字在不同任务中可能代表金额、像素、词向量或梯度。学习向量时，除了会算加减乘，还要给它写上长度、单位和来源。长度决定内存和可相乘的维度，方向决定相似性，单位决定数值大小能否比较。一个没有这些说明的向量，最多只能被当作暂时的数组，不能安全地进入数据管道。

向量化代码的核心是保持不变式：元素顺序不变、样本之间不串位、缺失值的掩码与数据同步、转换前后能恢复或能解释。切片、拼接和排序都会改变位置关系，尤其要警惕先排序特征再排序标签、只对非空值排序或在广播时复制了错误样本。每次变换后打印一个带有 ID 的小样本，比打印一整屏数字更容易核对。

一个好的向量测试包含正例、边界和反例。正例验证常见输入能得到预期形状；边界覆盖空向量、单元素、零向量、最大长度和极端值；反例故意传入长度不一致、NaN、错误单位或重复 ID，确认函数会拒绝而不是悄悄修正。测试名直接写出性质，例如“零向量不能计算余弦”，比“test_case_3”更适合后续维护。

def pairwise_difference(rows):
    if not rows:
        return []
    ids = [row["id"] for row in rows]
    values = [row["value"] for row in rows]
    if len(ids) != len(set(ids)):
        raise ValueError("id 必须唯一")
    if any(not isinstance(value, (int, float)) for value in values):
        raise TypeError("value 必须是数字")
    return [{"id": item_id, "delta": value - values[0]}
            for item_id, value in zip(ids, values)]

print(pairwise_difference([{"id": "a", "value": 2}, {"id": "b", "value": 5}]))
# 练习：加入缺失值并决定是拒绝、填补还是携带 mask

这里的函数没有把缺失值偷偷填成零，因为零可能是有意义的观测。工程上可以选择拒绝、用训练集统计量填补，或返回值与 mask 两个对象；无论哪种方案，都要在接口和实验记录中写明。向量的“基础”真正落地，就是让每一个数字都能被解释、被验证、被追溯。

先用“形状句子”读乘法

若矩阵 A 的形状是 (m,n)，矩阵 B 的形状是 (n,p)，那么 A @ B 的结果形状是 (m,p)。中间的两个 n 必须相等，因为 A 的每一行要和 B 的每一列做点积；外侧的 m 和 p 留在结果里。记忆“行乘列”不如完整说出这句话：左边每个输出行使用左矩阵的一行，右边每个输出列提供一列，沿内侧维度逐项相乘再求和。

线性层通常写成 y = W x + b。若输入 x 是 n 维列向量，权重 W 就是 (m,n)，偏置 b 是 (m,) 或 (m,1)；输出 y 有 m 个分量。一次处理 batch 个样本时，可以把样本按行放成 X:(batch,n)，写成 X @ W.T + b，也可以把样本按列放成 (n,batch) 并使用另一种写法。两种约定都能成立，危险的是在没有说明的情况下混用。

广播让偏置能够加到每一行，但它只是在形状兼容时自动扩展，不会替你确认语义。scores + bias 成功并不说明 scores 的最后一轴真的是类别；如果把批次轴和类别轴调换，代码可能仍然返回一个数组。调试矩阵代码时，除了打印数值，还要打印 shape、每一轴的名称和一个手算样本。

def matmul(left, right):
    if not left or not right:
        raise ValueError("矩阵不能为空")
    left_cols = len(left[0])
    right_cols = len(right[0])
    if any(len(row) != left_cols for row in left):
        raise ValueError("左矩阵不是规则矩阵")
    if any(len(row) != right_cols for row in right):
        raise ValueError("右矩阵不是规则矩阵")
    if left_cols != len(right):
        raise ValueError("内侧维度不相等，不能相乘")
    return [[sum(left[i][k] * right[k][j] for k in range(left_cols))
             for j in range(right_cols)]
            for i in range(len(left))]

weights = [[1, 2, 3], [0, 1, 1]]
features = [[2, 1], [1, 0], [3, 2]]
print(matmul(weights, features))  # 结果形状：(2, 2)

手写实现的价值不在于替代 NumPy，而在于把“每个结果位置怎么来的”暴露出来。结果左上角是第一行权重与第一列特征的点积，右下角是第二行与第二列的点积。换成 numpy.matmul 或深度学习框架以后，仍可以用这个两行三列的小例子做回归测试。对大矩阵，库会使用更高效的底层实现，但它仍然遵守相同的内侧维度规则。

旋转、缩放、剪切和投影都可以写成矩阵

在二维平面中，矩阵可以把一个点旋转、拉伸、压缩或剪切。把这些操作想成“坐标系换了一副眼镜”，有助于理解神经网络的线性层：它不是凭空创造信息，而是重新组合已有分量，把输入送到对当前任务更方便的坐标系。随后接上的非线性激活，才让多层组合能够表达不再是单一平面的边界。

线性变换有几个重要性质。零向量会被送到零向量；加法和数乘关系保持不变，即 T(a+b)=T(a)+T(b)、T(ca)=cT(a)。如果有偏置 b，变换变成仿射变换，原点可以移动，严格来说不再是线性。教学和框架文档常把 Wx+b 统称为线性层，是工程上的简称；读公式时仍要知道偏置扮演的是平移，而不是旋转或缩放。

矩阵的列空间告诉你输出可能落在哪些方向，秩表示其中真正独立的方向数量。若权重矩阵的秩低于输出维度，某些输出方向无法独立变化；这可能是有意的低秩压缩，也可能是数据或初始化造成的信息瓶颈。做模型分析时，不要只看矩阵的元素大小，还要观察奇异值、秩和条件数。一个元素很小不等于对应方向不重要，许多小元素组合起来仍可能形成稳定的方向。

from math import cos, sin, pi, hypot

angle = pi / 2
rotation = [[cos(angle), -sin(angle)], [sin(angle), cos(angle)]]
point = [1.0, 0.0]
bias = [2.0, -1.0]

def apply(matrix, vector):
    return [sum(row[i] * vector[i] for i in range(len(vector))) for row in matrix]

rotated = apply(rotation, point)
shifted = [value + delta for value, delta in zip(rotated, bias)]
print("rotated=", [round(value, 6) for value in rotated])
print("shifted=", [round(value, 6) for value in shifted])
assert abs(hypot(*point) - hypot(*rotated)) < 1e-9

由于浮点数不能精确表示所有角度，旋转 90 度后通常会出现接近零但不等于零的数。测试几何变换时使用误差范围，比直接比较字符串或完全相等更可靠。还要区分“矩阵乘法”和“逐元素乘法”：旋转矩阵必须使用行列点积，若误写成星号，代码可能返回形状正确却完全不同的结果。

转置改变方向，逆矩阵不是“每个数取倒数”

转置把行列交换，记作 Aᵀ。点积可以写成 xᵀy，协方差和注意力中的矩阵关系也经常依赖转置。转置不会改变一个矩阵的元素集合，但会改变形状和乘法方向。逆矩阵 A⁻¹ 只有在方阵满足可逆条件时才存在，且它满足 A⁻¹A=I；把每个元素取倒数通常没有意义。实际求解 Ax=b 时，优先使用线性方程求解器，不要先显式计算逆矩阵再相乘，因为求逆通常更慢，也可能放大数值误差。

当方程比未知数多时，往往没有一个点能完全满足所有方程。最小二乘寻找一个让残差平方和最小的解：min ||Ax-b||₂²。它不是“把错误平均掉”这么简单，而是明确选择了 L2 残差作为目标。异常值会被平方放大，所以需要检查残差分布、尺度和数据收集过程。加入正则化后，目标会再惩罚参数大小，得到的是偏差与稳定性的折中。

条件数描述输入的小扰动可能被解放大多少。条件数很大的矩阵接近不可逆，哪怕代码没有报错，结果也可能对舍入误差极其敏感。训练模型时出现 loss 抖动、梯度爆炸或参数异常，未必只是学习率问题，也可能与输入尺度、特征共线和矩阵条件有关。先标准化、检查奇异值和记录误差，再决定是否更换优化器。

import numpy as np

A = np.array([[3.0, 1.0], [1.0, 2.0]])
b = np.array([9.0, 8.0])
x = np.linalg.solve(A, b)
residual = A @ x - b
print("x=", x)
print("residual norm=", np.linalg.norm(residual))
assert np.allclose(A @ x, b)

# 条件数越大，解对输入扰动越敏感
print("condition number=", np.linalg.cond(A))

这段代码使用 NumPy 的线性代数模块，官方参考文档把求解、范数、奇异值分解等例程按主题组织，便于继续查阅。学习时不要只复制调用方式：先写出 A、b 的形状，说明为什么可以求解，再用残差验证输出。模型里的大矩阵通常不会手算，但同样需要记录 dtype、形状、误差容忍度和输入来源。

先给每条轴写名字，再谈矩阵乘法

同一个形状可以代表完全不同的东西。(32, 768) 可能是 32 个句子的句向量，也可能是一个批次中 32 个位置的隐藏状态；如果不写轴名，看到 transpose 或 reshape 时就无法判断它是在改变布局，还是误把语义换掉。建议在草稿、注释和日志里同时记录形状与轴名，例如 tokens:(batch, seq, hidden)、W_vocab:(hidden, vocab)。这一步看似慢，却能把大量“维度能对上、意义却错了”的 bug 变成可定位的检查项。

广播也应该用语义来解释。bias:(hidden,) 加到 states:(batch, seq, hidden) 是沿最后一轴给每个位置加同一组偏置；mask:(batch, seq) 扩展成 (batch, 1, seq) 后参与注意力分数，是为了对每个 query 共享同一套 key 位置屏蔽规则。若广播发生在错误的轴上，结果仍可能通过类型检查，甚至 loss 也会下降一点，因此测试要构造一个“每个轴使用不同数字”的小数组，让错误广播立刻显形。

批量矩阵乘法还涉及“哪一批和哪一批配对”。当 Q:(batch, heads, query, depth)、K:(batch, heads, key, depth) 时，注意力分数需要把 K 的最后两轴转为 (batch, heads, depth, key)，得到 (batch, heads, query, key)。这里转置的目的不是让代码看起来整齐，而是让每个 query 与所有 key 做点积。写出轴名以后，einsum、matmul 和显式循环只是三种实现，数学关系是一致的。

处理真实数据时还要考虑空批次、单样本、长度为一和不同 dtype。numpy 中一维数组与列向量的行为不同；深度学习框架也可能因为 squeeze() 把批次轴悄悄删掉。稳妥的函数应在入口处断言最小维度、允许的 dtype 和每一轴的范围，在出口处检查形状不变式。错误信息应告诉使用者“期望什么、实际是什么、哪一个轴不对”，而不是只抛出一条底层广播异常。

def assert_shape(name, value, expected):
    actual = tuple(value.shape)
    if actual != tuple(expected):
        raise ValueError(f"{name} 期望 {expected}，实际 {actual}")

class FakeTensor:
    def __init__(self, shape):
        self.shape = shape

states = FakeTensor((2, 4, 8))
bias = FakeTensor((8,))
assert_shape("states", states, (2, 4, 8))
assert_shape("bias", bias, (8,))
print("axis contract passed")

# 练习：把 states 改成 (4, 2, 8)，让检查器指出布局变化

这段检查器故意只依赖 shape，它可以迁移到 NumPy、PyTorch 或其他张量库。生产代码中还可以把轴名封装成数据类，或使用命名张量、类型标注和单元测试。重要的是把形状约定变成接口的一部分：调用者无需猜测，未来换实现时也有一条可以回归的契约。

秩、特征值与 SVD：识别矩阵保留了哪些方向

矩阵的秩可以理解为“输出空间里真正独立的方向数”。一个 3×3 矩阵即使写着九个参数，如果三行互相线性相关，它实际只能把输入压到一个更低维的子空间。低秩并不自动等于坏事：LoRA 等参数高效方法会有意用两个小矩阵的乘积近似一个大更新；但如果任务需要区分的方向被丢掉，低秩就会成为表达能力瓶颈。

特征向量满足 Av=λv，表示某些方向经过变换后方向不变，只被缩放。对称矩阵的特征向量可以提供一组相互正交的坐标，协方差矩阵的特征值则反映数据沿这些方向的方差。SVD 把任意矩阵写成 UΣVᵀ：V 描述输入方向，Σ 给出每个方向的缩放强度，U 描述输出方向。按奇异值从大到小截断，就得到一个可解释的低秩近似。

条件数与最小奇异值直接相关。若最小奇异值接近零，逆问题会放大噪声；在训练中，这表现为某些方向的梯度非常大或非常小。解决方案可能是标准化输入、移除冗余特征、增加正则化、使用稳定的求解器，或者接受一个近似解。不要把“换成 float64”当成唯一办法：更高精度只能减轻舍入，无法修复本身信息不足的模型。

矩阵分解还有一个沟通价值：它把“模型在学什么”从一堆元素提升到方向和尺度。可视化奇异值谱、记录有效秩、比较训练前后的谱变化，常常比只看权重均值更能解释压缩、过拟合或表示坍缩。解释结果时要同时说明数据范围、分解算法、截断阈值和随机种子，避免把一次数值现象夸大成普遍结论。

import numpy as np

matrix = np.array([[3.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 0.1]])
u, singular_values, vt = np.linalg.svd(matrix, full_matrices=False)
for rank in (1, 2, 3):
    approx = (u[:, :rank] * singular_values[:rank]) @ vt[:rank, :]
    error = np.linalg.norm(matrix - approx)
    print(f"rank={rank}, error={error:.4f}")

# 练习：把第三个奇异值改为 0.8，观察低秩近似误差如何变化

转置和乘法顺序：用小矩阵建立回归测试

转置满足 (AB)ᵀ=BᵀAᵀ，顺序会反过来；这不是记号游戏，而是因为先应用 B 再应用 A 的组合，在反向描述时要先撤回 A。类似地，矩阵乘法通常不满足交换律，AB 与 BA 可能形状不同甚至一个有定义、另一个没有。写代码前先在纸上标出每个矩阵的输入轴和输出轴，再决定 API 的参数顺序。

批处理让矩阵对象多出一个样本轴。把 X 按行存储时，线性层可写为 XWᵀ；若框架层默认输入形状为 (features,batch)，则公式会写成 WX。不要因为教程中的字母方向不同就认为某个公式错误，重点是约定前后一致，并用一个手算样例验证每个输出位置。

回归测试应包含可预测的特殊矩阵：单位矩阵不改变向量，零矩阵输出为零，对角矩阵只缩放各轴，置换矩阵只交换分量。再加入一个非对称的小矩阵，检查转置、乘法和逆的顺序。特殊例子不能覆盖所有 bug，却能在重构底层实现后快速发现最基本的方向错误。

def matvec(matrix, vector):
    if any(len(row) != len(vector) for row in matrix):
        raise ValueError("内侧维度不一致")
    return [sum(value * item for value, item in zip(row, vector)) for row in matrix]

identity = [[1, 0], [0, 1]]
zero = [[0, 0], [0, 0]]
diagonal = [[2, 0], [0, 3]]
point = [4, -1]
assert matvec(identity, point) == point
assert matvec(zero, point) == [0, 0]
assert matvec(diagonal, point) == [8, -3]
print("special-matrix tests passed")
# 练习：加入交换两个坐标的置换矩阵并写断言

当数值来自浮点运算时，回归测试应使用绝对误差和相对误差；当结果是整数或纯置换时，精确比较更直观。测试名称要说明语义，例如 test_identity_preserves_vector，不要只写 test_matrix_1。这些小测试会成为后续注意力、卷积和低秩模块的安全网。

“调用成功”不等于“使用合法”

函数的定义域是它允许接收的输入集合，值域是它可能返回的输出集合。平方函数对所有实数有定义，平方根在实数范围内要求输入不小于 0，倒数要求输入不等于 0。Python 的 math.sqrt(-1) 会抛出异常，说明库在保护定义域；某些数组库则可能返回 nan 并发出警告，程序仍然继续。无论哪种行为，都应该在数据契约中写明，而不是等结果扩散后才追查。

函数的参数可以改变图像。f(x)=a x+b 中，a 控制斜率，b 控制截距；在神经网络里，权重和偏置也承担类似职责。复合函数 g(f(x)) 先经过内层函数再经过外层函数，顺序不能随意交换。把标准化、激活和损失写成一条链，可以帮助你定位误差究竟是输入范围、非线性还是目标定义造成的。

离散代码和连续数学之间还有一个转换。数学函数可以在任意实数点计算，程序通常在有限数组上采样。采样间隔太大可能漏掉峰值，间隔太小则增加计算成本；绘图中的平滑曲线是若干采样点的连接，不是程序自动证明函数在中间没有剧烈变化。做实验时记录采样范围、步长和随机种子，别人才能复现图形。

from math import log, sqrt

def safe_log(value):
    if value <= 0:
        raise ValueError("log 的输入必须大于 0")
    return log(value)

def describe(function, values):
    rows = []
    for value in values:
        try:
            rows.append((value, function(value), "ok"))
        except (ValueError, ZeroDivisionError) as error:
            rows.append((value, None, type(error).__name__))
    return rows

print(describe(safe_log, [0.1, 1.0, 10.0, 0.0, -1.0]))
print(describe(sqrt, [0.0, 4.0]))

把异常变成结果表的做法适合探索定义域，但正式接口仍应决定是抛错、返回缺失标记还是拒绝整批数据。最忌讳的是在没有记录的情况下把非法输入静默替换成 0，因为 0 可能拥有完全不同的业务含义。函数契约越明确，后续的测试和模型评估越容易解释。

指数放大差异，对数把乘法变成加法

指数函数 eˣ 始终为正，输入相差一点，输出可能相差很多；对数是指数的逆函数，能把连乘的概率变成连加的对数似然。语言模型常处理一串概率的乘积，直接相乘很快会下溢到 0，因此工程实现通常在对数空间计算。看到 log 时，先问它是为了表示尺度、稳定乘法，还是定义某种损失。

Softmax 将一组任意实数分数映射成非负且总和为 1 的权重：softmax(zᵢ)=e^{zᵢ}/Σⱼe^{zⱼ}。它保留相对顺序，但不是把每个分数简单除以总和；指数会让高分更突出。温度参数 T 可以写成 softmax(z/T)，温度高时分布更平，温度低时更尖。温度改变的是不确定性表达，不会自动让模型变得更准确。

直接计算大正数的指数会溢出。利用平移不变性，把所有分数减去最大值：softmax(z)=softmax(z-max(z))，结果不变但数值更安全。这是一个很好的例子：代数上等价的变形可以改善工程可靠性。实现稳定版本时仍要处理空列表、非有限值和维度；对批次数据要明确沿哪条轴归一化。

from math import exp

def softmax(logits, temperature=1.0):
    if not logits or temperature <= 0:
        raise ValueError("分数不能为空，温度必须大于 0")
    shifted = [value / temperature for value in logits]
    pivot = max(shifted)
    weights = [exp(value - pivot) for value in shifted]
    total = sum(weights)
    if not all(map(lambda value: value == value, weights)) or total == 0:
        raise ValueError("分数包含不可计算的值")
    return [weight / total for weight in weights]

for temperature in (0.5, 1.0, 2.0):
    probabilities = softmax([2.0, 1.0, 0.0], temperature)
    print(temperature, probabilities, sum(probabilities))

代码中的 pivot 是数值稳定技巧，不是改变模型偏好的额外参数。三组温度的结果可以帮助你建立直觉：低温让最大分数占更大比例，高温让其他候选仍保留更多质量。报告模型输出时，不要只记录“最高概率”，还要记录温度、候选集合和是否经过截断或过滤。

极限关注“靠近时发生什么”

极限不是把变量直接代入某个值，而是观察输入越来越接近目标时，输出是否趋向稳定结果。例如 sin(x)/x 在 x 接近 0 时没有直接定义，但极限是 1。连续性要求函数在点上的值和附近的趋势相容；不连续点可能来自除零、分段规则或数据截断。模型中常见的激活、裁剪和阈值，都可以从连续性和局部变化角度检查它们是否会造成突变。

在一个很小的邻域里，函数可以用切线近似：f(x+Δx)≈f(x)+f'(x)Δx。这句话把复杂曲线暂时变成直线，也是梯度下降能工作的核心直觉。近似只在步长足够小、函数在该处变化平滑时可靠；步长太大，二阶曲率会显著影响结果。数值实验要同时改变步长，观察误差随步长如何变化，而不是只打印一次“看起来接近”的结果。

有限差分用 (f(x+h)-f(x))/h 估计导数。h 太大时截断误差大，太小时浮点相减会损失有效数字。中心差分 (f(x+h)-f(x-h))/(2h) 往往更准确，但需要多算一次函数。自动微分并不是魔法地“知道答案”，而是根据计算图应用链式法则；用有限差分做小规模对照，能发现实现中的符号或维度错误。

from math import exp

def function(x):
    return exp(x) + x * x

def exact_derivative(x):
    return exp(x) + 2 * x

def central_difference(function, x, step):
    return (function(x + step) - function(x - step)) / (2 * step)

x = 0.7
for step in (1e-1, 1e-3, 1e-5, 1e-7):
    estimate = central_difference(function, x, step)
    error = abs(estimate - exact_derivative(x))
    print(step, estimate, error)

有限差分结果通常会先变准后变差：步长从大变小时，截断误差下降；再继续变小，浮点误差开始占主导。这个“U 形”现象提醒我们，数值计算总是在精度和稳定性之间取舍。以后看到一个自动微分梯度时，可以在二维玩具函数上用合适步长做抽查，但不要把有限差分当作高维训练的替代品。

函数首先是契约：输入、输出和边界都要说清楚

把函数只看成一个“代入公式的盒子”容易遗漏三个关键信息：允许的输入集合、输出的结构，以及函数是否有状态。sqrt(x) 在实数范围要求 x≥0；分类器的 predict(text) 接受字符串，却可能返回标签、概率和解释信息组成的对象。若调用者把概率列表当成标签使用，Python 不一定报错，错误却会一路传到评估阶段。因此函数文档、类型标注和运行时断言应共同描述契约。

还要区分纯函数和带副作用的函数。纯函数只由输入决定输出，适合单元测试、缓存和批量并行；读取文件、修改全局状态、写日志或更新模型参数的函数则有副作用，应该在名字或接口中体现。把“清洗文本”“计算特征”“保存结果”塞进一个函数，会让复现实验和定位错误都变困难。更好的拆分不是追求函数数量，而是让每个函数拥有一个可独立验收的职责。

函数的单调性、对称性和周期性是很实用的快速检查。若输入增加时输出应增加，可以用一组有序输入验证单调趋势；若函数应对称，检查 f(x) 与 f(-x) 的关系；若模型的归一化函数输出应落在区间内，就测试边界、极端值和空输入。性质测试不能代替完整测试，但能在改写实现后迅速发现方向性错误。

在机器学习中，一个函数往往要同时处理单个样本和批次。接口应明确是否支持广播、是否保留批次维、空批次如何返回，以及输入 dtype 是否会改变。推荐先写标量版本验证数学含义，再写向量化版本并用随机小样本对照；如果向量化结果与逐项循环不一致，优先检查轴、广播和隐式类型转换，而不是盲目调参。

def normalize_scores(scores):
    if not scores:
        raise ValueError("scores 不能为空")
    if any(not isinstance(value, (int, float)) for value in scores):
        raise TypeError("scores 必须是数字序列")
    total = sum(scores)
    if total <= 0:
        raise ValueError("总和必须为正")
    result = [value / total for value in scores]
    if abs(sum(result) - 1.0) > 1e-12:
        raise ArithmeticError("归一化后总和不满足约定")
    return result

print(normalize_scores([2, 3, 5]))
# 练习：为包含负数、NaN 和空列表的输入补测试

示例把错误挡在函数边界，而不是让错误的概率继续向后传播。真实项目还可以使用 math.isfinite 排除无穷和 NaN，使用 typing.Sequence[float] 提升静态检查质量。注意“归一化”有很多含义：除以总和、标准化为零均值单位方差、Softmax 都不是一回事，函数名应该让读者不用翻实现就能知道选择。

数值稳定不是优化细节，而是函数定义的一部分

指数函数会迅速放大差异：当 logits 很大时直接计算 exp(x) 可能溢出，当 logits 很小时可能下溢为零。Softmax 的数学结果没有问题，问题在有限精度的表示方式。常用的稳定写法是先减去最大值：softmax(x)=exp(x-max(x))/Σexp(x-max(x))。因为分子分母同时乘了同一个常数，结果不变，却把指数的范围压到更安全的区间。

交叉熵通常也不应先把 logits 变成概率再取对数，而应直接调用稳定的 log_softmax 或框架的融合损失。融合实现能减少中间张量和舍入误差，还能正确处理忽略标签、类别权重与批次归约。学习阶段仍要会写一个小规模手算版本，用来核对目标类别、平均方式和掩码是否正确。

掩码会引入另一种边界：被屏蔽位置的 logit 常被设为负无穷。若整行都被屏蔽，稳定 Softmax 中的“最大值”也是负无穷，减法可能产生 NaN。因此实现应在归一化前检查是否至少有一个有效位置，或者规定全屏蔽行返回全零并在后续跳过。不要把负无穷当成普通的大负数后就忘了这个特殊情况。

函数的可导性也影响训练。ReLU 在零点不可导，框架会采用一个约定的次梯度；硬阈值、取整和离散索引往往在大部分区间梯度为零。若一个函数用于推理而不是训练，可以接受不可导；若要放进反向传播路径，就必须说明梯度如何定义，必要时使用平滑近似。

import math

def logsumexp(values):
    if not values or not all(math.isfinite(v) for v in values):
        raise ValueError("需要非空有限数值")
    peak = max(values)
    return peak + math.log(sum(math.exp(v - peak) for v in values))

def stable_softmax(values):
    normalizer = logsumexp(values)
    return [math.exp(value - normalizer) for value in values]

scores = [1000.0, 1001.0, 999.0]
probabilities = stable_softmax(scores)
print(probabilities, sum(probabilities))
assert abs(sum(probabilities) - 1.0) < 1e-12

可以把同一组输入交给“直接指数版”和稳定版，对比输出是否一致以及是否出现溢出。测试不要只使用 0 到 1 的小数字，那会掩盖真正的数值风险。还应测试全相同 logits、差距极大的 logits、单元素输入和合法的负值。每个测试都要写出预期的数学性质，例如和为 1、最大 logit 对应最大概率、整体平移 logits 不改变结果。

分段函数和激活函数：表达能力与可训练性要一起看

分段函数用不同区间的规则描述一个整体，ReLU 是最简单的例子：负数区输出零，正数区保持线性。它引入了非线性，让多个线性层不再等价于一层；但大量输入落在负区时，梯度可能长期为零，形成“死亡单元”。观察激活值的分位数、零值比例和不同层之间的尺度，比只看最终 loss 更能发现这种现象。

Sigmoid 和 tanh 在两端都会饱和，输入绝对值很大时输出接近边界，局部导数很小。GELU、SiLU 等平滑激活通过按输入大小调节保留比例，常用于现代网络，但平滑不代表一定更好。激活选择应与归一化、初始化、残差连接和 dtype 一起评估；换激活时至少做一个控制变量实验。

函数的可逆性和单调性决定信息能否被恢复。严格单调函数在定义域上可逆，非单调函数可能把不同输入映射到同一输出。神经网络中的降维、截断和激活会有意丢弃部分信息，但如果任务需要精确重构，就要选择合适的维度和结构。讨论“模型理解了多少”时，也应问哪些信息在函数链路中已经不可逆地消失。

函数图像是很好的实验工具：在同一坐标系画原函数、平移缩放后的函数和导数曲线，能直观看出参数如何改变斜率、饱和区和零点。绘图采样要覆盖极端输入，坐标范围和采样密度要记录；只画中心小区间，可能把真正的爆炸或饱和隐藏掉。

import math

def relu(value):
    return max(0.0, value)

def sigmoid(value):
    if value >= 0:
        z = math.exp(-value)
        return 1 / (1 + z)
    z = math.exp(value)
    return z / (1 + z)

samples = [-20, -2, -0.1, 0, 0.1, 2, 20]
for value in samples:
    print(value, relu(value), sigmoid(value))
# 练习：统计一批随机输入经过 ReLU 后为零的比例

Sigmoid 示例使用按符号分支的稳定写法，避免负数或正数极端时指数溢出。无论使用哪种激活，都要测试 ±∞、极大值、零点和空批次；还要确认反向传播时的梯度约定与文档一致。一个可训练的函数不仅要“返回正确数值”，还要在目标尺度和硬件精度下提供可用的梯度。

导数是“输出变化 ÷ 输入变化”的极限

对一元函数 f(x)，导数 f′(x) 描述在 x 附近输入改变一点时输出的变化速度。正导数表示局部上升，负导数表示局部下降，绝对值大说明对输入敏感。导数为零只说明切线水平，不代表函数已经达到全局最低点；它可能是局部极值、鞍点的一部分，也可能只是曲线暂时平坦。

单位能帮助检查导数是否合理。如果输入是分钟、输出是损失，那么导数单位是“损失/分钟”；把不同特征直接放进同一模型，特征尺度不同会让对应梯度的数值不可直接比较。标准化让优化器面对更均衡的尺度，但不应抹掉业务含义。记录缩放参数、逆变换方法和梯度统计，是让训练结果可解释的一部分。

高阶导数描述斜率如何变化。二阶导数为正通常表示局部向上弯，曲率大意味着同样的步长会产生更明显的非线性误差。梯度下降只使用一阶信息，简单、通用，但在狭长谷底或不同方向曲率差异很大时会来回摆动。后续优化器中的动量、自适应步长和二阶近似，都是在不直接求解全局问题的前提下改善这类局部移动。

from math import isclose

square_loss = lambda x, target=3.0: (x - target) ** 2
analytic_derivative = lambda x, target=3.0: 2 * (x - target)
central_difference = lambda function, x, step: (function(x + step) - function(x - step)) / (2 * step)

for x in (0.0, 2.0, 3.0, 4.0):
    estimate = central_difference(square_loss, x, 1e-5)
    exact = analytic_derivative(x)
    print(x, estimate, exact, abs(estimate - exact))
    assert isclose(estimate, exact, rel_tol=1e-8, abs_tol=1e-8)

平方损失是训练直觉的第一个好例子：目标点两侧的导数符号相反，离目标越远，斜率绝对值越大；在目标点导数为零。代码同时计算解析导数和有限差分，让你看到公式与程序如何互相验收。真正的模型损失可能有数百万参数，但每个参数仍然遵循这个局部定义。

梯度是最陡上升方向，负梯度是局部下降方向

当函数有多个输入，例如 L(w,b)，偏导数 ∂L/∂w 在固定其他变量时观察 w 的变化；梯度把所有偏导数排成向量。梯度的方向是函数上升最快的方向，因此最小化目标时通常沿负梯度移动。这个说法依赖局部可微和步长足够小的近似，不意味着模型会沿一条直线走到全局最低点。

梯度的形状必须和参数一致。标量参数的梯度是标量，向量参数的梯度是同形向量，矩阵参数的梯度是同形矩阵。框架在反向传播后把梯度累积到参数对象上，因此每个训练批次前通常要清零；忘记清零会把多个批次的梯度相加，导致实际更新与预期不同。梯度裁剪、混合精度和分布式同步也都围绕“梯度是什么、何时更新、如何缩放”展开。

方向和大小要分开看。把梯度乘一个正数不会改变方向，只会改变建议步长；把梯度归一化能限制大小，却可能丢掉不同参数之间的相对尺度。梯度爆炸和消失分别意味着数值过大或过小，但具体原因可能来自初始化、激活、输入尺度、损失设计或长链计算。监控梯度范数、分位数和非有限比例，比只看最终 loss 更早发现问题。

loss = lambda w, b: (w - 2) ** 2 + 3 * (b + 1) ** 2
gradient = lambda w, b: (2 * (w - 2), 6 * (b + 1))

w, b = 5.0, 2.0
learning_rate = 0.1
for step in range(5):
    dw, db = gradient(w, b)
    w -= learning_rate * dw
    b -= learning_rate * db
    print(step, loss(w, b), (dw, db), (w, b))

这个二维例子故意让 b 方向的曲率更大，所以相同学习率下两个参数靠近目标的速度不同。观察每一步的损失、梯度和参数，比只看最后一行更能解释训练过程。真实模型通常使用批次估计梯度，梯度还会受到数据顺序和随机性的影响，因此应记录种子、批次大小、聚合方式和更新次数。

复合函数的梯度可以沿计算图反向传递

如果 y=f(g(x))，链式法则告诉我们 dy/dx=(dy/dg)(dg/dx)。直觉上，先问输出对中间量敏感多少，再问中间量对输入敏感多少，两个局部变化率相乘得到整体变化。多层网络只是把这条规则扩展到向量和矩阵：前向阶段保存中间结果，反向阶段从损失开始，逐层计算并传回参数梯度。

保存中间结果会占用内存，反向传播也需要按照正确的拓扑顺序执行。某个分支被多个后续节点使用时，来自不同路径的梯度要相加；把它当成只走一条路径会漏掉贡献。残差连接、注意力分支和共享参数都体现了这个规则。理解“梯度在图上汇合”，比背诵某个框架的 backward() 调用更有迁移价值。

非线性函数的导数会影响梯度流。Sigmoid 在饱和区导数接近 0，长链相乘后容易让早期层梯度变小；ReLU 在正区保持斜率，在负区可能完全不传递。现代架构会通过归一化、残差和合适初始化改善这些问题，但任何技巧都不能替代监控。训练实验应至少记录 loss、参数范数、梯度范数和非有限值计数。

def forward(x, w, b):
    z = w * x + b
    y = max(0.0, z)  # ReLU
    loss = (y - 1.0) ** 2
    return z, y, loss

def backward(x, w, b):
    z, y, loss = forward(x, w, b)
    d_loss_d_y = 2 * (y - 1.0)
    d_y_d_z = 1.0 if z > 0 else 0.0
    d_z_d_w = x
    d_z_d_b = 1.0
    return loss, d_loss_d_y * d_y_d_z * d_z_d_w, d_loss_d_y * d_y_d_z * d_z_d_b

print(backward(2.0, 0.4, 0.5))
print(backward(2.0, -0.4, -0.5))  # z<0，ReLU 让梯度为 0

手写反向传播能让每个局部因子显形：损失对激活的导数、激活对线性输入的导数、线性输入对参数的导数。实际框架会自动构建计算图并处理批次，但你仍要知道哪些节点应该有梯度、哪些操作被刻意停止梯度。用一个两参数例子做有限差分对照，是发现符号、缓存和分支错误的低成本方法。

导数的三个视角：斜率、敏感度与局部近似

对一元函数来说，导数是曲线在某一点附近的斜率；对模型来说，它更像“输出对输入的敏感度”。若 f'(x) 为正，输入在该点附近增加会让输出增加；绝对值越大，单位输入变化带来的输出变化越明显。这个解释必须带上单位：温度对损失的导数和像素对损失的导数不能直接比较，除非输入已经经过相同尺度的标准化。

导数来自极限定义 f'(x)=lim[h→0](f(x+h)-f(x))/h，但计算机不能真的让 h 等于零。h 太大，截断误差明显；h 太小，两个接近的浮点数相减会损失有效位。中心差分 [f(x+h)-f(x-h)]/(2h) 通常比前向差分更准确，但仍需根据函数尺度和 dtype 选择 h。梯度检查的目的不是证明实现绝对正确，而是用独立的近似发现符号、索引和链式法则错误。

导数还可以用来判断局部趋势。若一阶导数接近零，不代表这里一定是最小值，也可能是最大值、鞍点或平坦区；要结合二阶导数、邻域采样和任务语义。非光滑点则要说明采用左导数、右导数或次梯度的哪一种约定。把“梯度为零”简单等同于“模型学好了”，是初学者常见的误读。

在程序中，数值导数、符号导数和自动微分各有职责。数值导数适合小规模验算；符号推导适合理解公式；自动微分沿计算图精确应用链式法则，适合训练。工程上常把三者配合：先手算简单例子，再用有限差分对一个小张量做抽查，最后依赖框架在大规模数据上高效反向传播。

def loss(x):
    return (x - 3.0) ** 2 + 1.0

def central_difference(fn, x, step=1e-5):
    return (fn(x + step) - fn(x - step)) / (2 * step)

for point in (0.0, 2.0, 3.0, 5.0):
    analytic = 2 * (point - 3.0)
    numeric = central_difference(loss, point)
    print(point, analytic, numeric)
    assert abs(analytic - numeric) < 1e-5

# 练习：把 step 改成 1e-2、1e-8，观察误差为何先降后升

示例还告诉我们一个实验习惯：不要只在一个点比较梯度。选择目标点左侧、驻点和右侧，才能看到符号变化；改变步长并画出误差，才能发现浮点抵消。若函数包含随机数、缓存、离散分支或不可导操作，数值检查要先固定随机种子、关闭随机增强，并记录这些限制。

Jacobian、Hessian 与向量—雅可比积

当输入和输出都是向量时，导数不再是一个数，而是 Jacobian 矩阵。若 y=f(x)，Jacobian 的第 i,j 个元素是 ∂y_i/∂x_j，它回答“每个输入分量分别影响哪个输出分量”。梯度通常专指标量损失对参数的偏导集合，是 Jacobian 的一个特殊形态。写清楚行列方向很重要，因为不同库对 Jacobian 的布局和批次维约定可能不同。

训练神经网络时，通常不需要显式构造巨大的 Jacobian，而是计算向量—雅可比积或雅可比—向量积。反向传播从损失的上游梯度开始，把局部导数按链式法则乘回参数；这样一次反向就能得到所有参数对一个标量损失的梯度。若只想观察某个输出分量，可以传入一个选择向量，避免构造整张矩阵。

Hessian 是二阶导数矩阵，描述梯度如何变化。它能识别曲率、区分平坦方向和陡峭方向，也解释了为什么同一个学习率在不同方向上效果不同。完整 Hessian 对大模型通常太昂贵，因此工程上会使用对角近似、低秩近似、Hessian—vector product 或自适应优化器的二阶统计量。学习时先在二维函数上画等高线，再把概念映射回参数空间。

高阶导数会带来计算图和内存的额外开销。若在 PyTorch 中第一次求梯度后还要对梯度求导，需要保留图；如果只是记录数值，则应使用 detach 或在无梯度上下文中操作，避免把日志张量接回图。训练循环里忘记清零梯度，会让多个 batch 的梯度累积，这有时是有意的梯度累积，有时则是隐藏 bug，必须写在实验记录里。

def objective(theta):
    a, b = theta
    return (a - 2.0) ** 2 + 3.0 * (b + 1.0) ** 2 + a * b

def analytic(theta):
    a, b = theta
    return [2 * (a - 2.0) + b, 6 * (b + 1.0) + a]

def numeric(theta, step=1e-6):
    result = []
    for index in range(len(theta)):
        plus = list(theta); minus = list(theta)
        plus[index] += step; minus[index] -= step
        result.append((objective(plus) - objective(minus)) / (2 * step))
    return result

point = [0.4, -0.3]
for expected, measured in zip(analytic(point), numeric(point)):
    assert abs(expected - measured) < 1e-5
print("gradient check passed")

这个检查器逐个扰动参数，适合验证一个很小的目标函数。注意代码块中的换行实体会被浏览器还原；复制后可以直接运行。对于框架张量，要同时检查梯度的 dtype、device、是否为零和是否包含 NaN。梯度数值正确只是必要条件，最终还要确认更新方向确实降低了验证集目标。

链式法则的阅读顺序：先问“谁依赖谁”

复合函数 z=f(g(x)) 的导数是外层导数乘以内层导数。读神经网络计算图时，可以从输入到输出列出每个中间量，再从损失反向写出局部导数；不要一看到长公式就直接展开。每条边都要标注输入和输出形状，矩阵乘法的转置方向也应随图保留。这样做能把“梯度消失”具体定位到某个饱和激活、过小权重或错误归约，而不是笼统归咎于模型太深。

残差连接提供了一条近似恒等的路径，归一化改变了局部尺度，注意力和 MLP 则通过不同的 Jacobian 组合信息。分析梯度时，分别观察主分支与捷径分支的范数，才能知道哪条路径在主导更新。对一个小网络计算逐层梯度直方图、最大值和零值比例，通常比只看最终参数梯度更有诊断价值。

自动微分记录的是一次具体前向的计算图。改变控制流、调用原地操作、复用带历史的张量，都会改变图的结构或可求导性。把推理代码放进训练图会浪费内存，把训练图误用在评估阶段会产生错误的梯度和速度。写实验时要明确何时启用梯度、何时切断图、哪些中间值只是日志。

def forward(x, w, b):
    hidden = w * x + b
    output = hidden * hidden
    return hidden, output

x, w, b = 2.0, 1.5, -0.5
hidden, output = forward(x, w, b)
upstream = 1.0  # d loss / d output
d_output_d_hidden = 2 * hidden
d_hidden_d_w = x
gradient_w = upstream * d_output_d_hidden * d_hidden_d_w
print("hidden=", hidden, "output=", output, "dL/dw=", gradient_w)
# 练习：把 b 也求导，并用中心差分核对

最小链式法则实验应该同时给出中间值、局部导数和最终梯度。以后换成框架自动微分，只需把手算梯度与框架结果对照；如果不一致，就沿图逐项比，而不是直接重写整个模型。

梯度数值正确之后，还要检查更新是否服务于目标

有限差分与自动微分一致，只能证明“当前函数在当前点附近的导数实现基本一致”，不能证明训练任务定义正确。标签可能错位，mask 可能把有效 token 排除，损失可能沿错误轴求平均，优化器也可能没有拿到真正需要更新的参数。排查时把问题分成四层：先验证目标函数和标签，再验证前向数值与形状，然后验证梯度，最后验证参数更新后损失是否按预期变化。

最小更新测试可以固定一个极小 batch，记录更新前的参数、标量 loss 和梯度；执行一次 step() 后确认至少一个应训练参数发生变化，再对同一 batch 重新前向。单步 loss 不保证每次都下降，尤其使用动量、随机层或较大学习率时，因此实验应关闭 Dropout、固定随机种子并使用足够小的学习率。若梯度非零而参数不变，检查参数是否交给优化器；若参数变化而 loss 完全不变，检查 forward 是否真的使用了这些参数。

这四层检查会在神经网络章节再次出现。现在先记住职责边界：导数回答局部变化率，反向传播高效组合导数，优化器决定怎样使用梯度，而数据与损失共同决定“往哪个目标优化”。把四者混成一句“模型会自动学习”，就无法定位训练为什么失败。

先把“可能发生什么”列完整

样本空间是一次实验所有可能结果的集合，事件是样本空间中的一个子集。抛硬币的样本空间可以是正面和反面；分类模型的样本空间是所有类别，事件“预测正确”还依赖真实标签和模型输出。概率满足非负性、总和为 1 和可加性：互不相交事件的联合概率等于各自概率之和。公式很短，但最容易漏掉的是样本空间不完整——如果数据中没有“未知”或“拒答”这一类，系统就会被迫把它归入错误的类别。

频率和概率有关，却不是同一个词。重复进行相同条件的实验，事件出现的相对频率可能逐渐稳定；这是假设过程稳定、样本独立且抽样方式合理时的经验依据。线上流量变化、标注策略变化或输入分布漂移会破坏这些条件。报告一个准确率或成功率时，应同时写时间范围、样本来源、排除规则和分母，而不是只给一个百分比。

互斥、独立和不相关也要区分。互斥事件不能同时发生，独立事件则是一个事件发生不改变另一个事件的概率；两个变量相关性为零也不一定独立。把这些概念混用，会导致错误的特征选择、数据切分和风险解释。遇到“两个指标没有关系”的结论，先问它是由联合分布、相关系数还是一次样本的图表推出来的。

from collections import Counter

outcomes = ["correct", "correct", "wrong", "abstain", "correct", "wrong"]
counts = Counter(outcomes)
total = len(outcomes)
probabilities = {outcome: count / total for outcome, count in counts.items()}
print(counts)
print(probabilities)
assert abs(sum(probabilities.values()) - 1.0) < 1e-12
not_wrong = probabilities["correct"] + probabilities["abstain"]
print("非错误比例=", not_wrong)

这个例子把一次评测结果当作有限样本，计算的是经验频率，不是对未来所有输入的保证。把 abstain 并入“正确”会改变指标含义；是否这样做要由评测协议决定。工程报告应同时保留原始计数和派生比例，避免四舍五入后无法回算分母。

条件概率的分母已经改变

条件概率 P(A|B) 表示在 B 已发生的前提下 A 的概率，分母是所有满足 B 的结果。它通常不等于 P(B|A)；Bayes 公式通过先验、似然和证据把二者联系起来：P(A|B)=P(B|A)P(A)/P(B)。医学筛查、垃圾邮件过滤和检索排序都需要先问“我们已知什么”，再计算“在这批条件下命中多少”。忽略基率会让一个看似很高的命中率产生过度自信。

先验不是拍脑袋的偏见，它是看到当前证据前的分布假设，可以来自历史数据、业务约束或明确的无信息选择。似然描述在某个假设成立时观察到证据的可能性。证据项把所有假设解释该证据的可能性加总。实际模型往往用训练数据学习这些关系，但分析者仍需知道输入分布变化会让先验或似然失效。

条件信息会产生选择偏差。只在“已经被模型标记为高风险”的样本上计算准确率，结果不能直接推广到全部用户；只分析留下来的日志，可能漏掉被拒答、超时或没有权限访问的请求。每个条件筛选都应记录筛选前后的数量和规则。数据管道中的分层抽样、时间切分和去重，本质上是在控制条件信息，避免评估泄漏。

prior_spam = 0.02
true_positive = 0.90
false_positive = 0.05
prob_positive = true_positive * prior_spam + false_positive * (1 - prior_spam)
posterior_spam = true_positive * prior_spam / prob_positive
print("P(spam|positive)=", posterior_spam)
population = 10000
spam = int(population * prior_spam)
positive_spam = int(spam * true_positive)
positive_normal = int((population - spam) * false_positive)
print(positive_spam / (positive_spam + positive_normal))

当垃圾邮件只占 2% 时，即使检测器对垃圾邮件的命中率达到 90%，阳性中仍可能有不少普通邮件。这个反直觉例子说明“模型说概率很高”必须结合基率和决策阈值。写评测报告时，把混淆矩阵、类别占比和阈值一起展示，比单独列一个 precision 更不容易误导。

平均值描述中心，方差描述波动

离散随机变量的期望是各结果按概率加权的平均：E[X]=ΣxP(X=x)。它是长期重复实验的中心，不保证下一次就等于它。方差 Var(X)=E[(X-E[X])²] 衡量围绕中心的平方偏离，标准差是方差开平方并恢复原单位。平方会放大离群值，所以报告平均值时应同时查看中位数、分位数和样本量。

协方差描述两个变量是否一起增减，相关系数是经过尺度标准化的协方差。协方差受单位影响：把分钟改成秒会放大数值；相关系数通常落在 -1 到 1，但只捕捉线性关系。高相关不等于因果，低相关也不排除非线性关系。模型特征分析中，协方差矩阵可以发现重复信息和尺度差异，但需要配合业务语义与时间顺序。

期望还可以用于决策：如果不同结果有不同代价，应该计算期望损失，而不是只看事件概率。一次系统升级可能降低平均延迟，却增加极端超时的代价；只看均值会遗漏尾部风险。把指标按场景拆成正常、边界和失败三类，记录各类概率、成本和样本量，才能把“平均更好”解释成可执行的选择。

from math import sqrt

x = [2.0, 3.0, 3.0, 8.0]
y = [1.0, 2.0, 4.0, 7.0]
mean_x = sum(x) / len(x)
mean_y = sum(y) / len(y)
variance_x = sum((value - mean_x) ** 2 for value in x) / len(x)
covariance = sum((a - mean_x) * (b - mean_y) for a, b in zip(x, y)) / len(x)
variance_y = sum((value - mean_y) ** 2 for value in y) / len(y)
correlation = covariance / (sqrt(variance_x) * sqrt(variance_y))
print(mean_x, sqrt(variance_x), covariance, correlation)

代码用总体分母计算方差和协方差；如果把这四个值看成从更大总体抽取的样本，统计推断可能使用 n-1 的无偏估计。选择哪种口径要写在报告里，不能只引用库函数默认值。特别是在比较不同样本量的实验时，分母和缺失处理会直接改变结论。

概率建模的第一步：说明事件和观察单位

概率题最容易错在分母。说“抽到红球的概率”之前，要说明一次试验是什么、样本空间包含哪些等可能结果，以及是否放回。机器学习里同样如此：一个样本可以是一条消息、一个用户、一个 token 或一个时间窗口。若把同一用户的多条记录随机拆到训练集和验证集，样本表面上数量增加，事件却不再独立，评估会因为泄漏而虚高。

事件是样本空间的子集，随机变量则把事件映射成数值。把类别标签写成 0、1、2 只是编码，不代表类别之间存在大小关系；把 token id 当作连续变量直接求平均也没有概率意义。需要先判断变量是离散还是连续、是观测结果还是模型输出，再选择计数、密度或质量函数。概率为零也可能只是当前建模假设下不可能，不等于现实中绝对不会发生。

联合概率描述多个事件同时发生，边缘概率把其他变量求和或积分掉，条件概率则在已知信息下重新分配质量。三者的计算顺序和数据切分密切相关。生成模型估计的是 p(x) 或 p(x|context)，分类器常近似 p(label|features)；把条件方向写反，会导致数据、目标和解释完全不同。

独立性是强假设：A 与 B 独立时 p(A,B)=p(A)p(B)，但不相关并不总是独立。文本 token 具有长程依赖，用户行为有时间相关，训练样本共享模板也会相关。使用独立同分布近似是为了让估计可行，不是事实宣言；报告结果时应指出数据来源、采样机制和可能的相关结构。

from collections import Counter

def empirical_probability(samples, predicate):
    if not samples:
        raise ValueError("样本不能为空")
    hits = sum(predicate(item) for item in samples)
    return hits / len(samples)

records = [{"group": "A", "clicked": True}, {"group": "A", "clicked": False},
           {"group": "B", "clicked": True}, {"group": "B", "clicked": True}]
overall = empirical_probability(records, lambda row: row["clicked"])
group_a = [row for row in records if row["group"] == "A"]
conditional = empirical_probability(group_a, lambda row: row["clicked"])
print("p(click)=", overall, "p(click|A)=", conditional)

# 练习：增加一个 group C，比较小样本条件概率的波动

示例把条件筛选放在分母之前，避免“先数点击，再用另一套样本数相除”。真正的数据分析还要处理缺失值、重复记录、权重和时间窗口；这些不是概率公式的附属品，而是定义事件的一部分。建议在结果表中同时输出分子、分母、概率和置信区间，别人才能复核你算的到底是哪一个事件。

期望、方差与协方差：把“平均表现”拆成可解释的部分

期望是按概率加权的长期平均，不一定是某次实验会出现的值。投掷骰子的期望为 3.5，但不存在点数 3.5。方差衡量结果围绕期望的离散程度，量纲是原变量的平方；标准差开平方后才回到原单位。比较不同指标的波动时，要同时关注量纲和尺度，不能只看数字大小。

协方差描述两个变量是否同向变化，相关系数则进一步除以各自标准差，落在 -1 到 1 之间。协方差接近零只能说明线性关系弱，不代表不存在非线性关系。对特征做标准化、白化或降维时，协方差矩阵提供了结构线索；但它由样本估计，少量异常点就可能显著改变结果。

期望的线性性质很有用：E[aX+bY]=aE[X]+bE[Y]，不需要 X、Y 独立。方差却只有在独立或协方差项被正确处理时才可简单相加。训练中的 mini-batch 平均损失是样本损失的估计，如果 batch 采样偏向某些类别，期望就被重新加权；应使用分层采样、样本权重或在报告中说明目标分布。

概率模型的输出还需要区分 aleatoric 与 epistemic 不确定性：前者来自数据本身的噪声，后者来自模型或知识不足。重复采样、集成和分层评估能提供线索，但不能把一次概率值直接解释成“模型知道自己错的概率”。不确定性表达必须和数据收集、校准指标以及决策成本一起讨论。

def mean(values):
    return sum(values) / len(values)

def variance(values):
    center = mean(values)
    return sum((value - center) ** 2 for value in values) / len(values)

def covariance(left, right):
    if len(left) != len(right):
        raise ValueError("两个变量必须一一配对")
    left_mean, right_mean = mean(left), mean(right)
    return sum((a - left_mean) * (b - right_mean) for a, b in zip(left, right)) / len(left)

hours = [1, 2, 3, 4, 5]
scores = [52, 55, 61, 67, 69]
print("mean=", mean(scores), "variance=", variance(scores))
print("covariance=", covariance(hours, scores))

# 练习：给 scores 末尾加入 200，观察方差与协方差的变化

手算统计量时默认使用总体分母还是样本分母，要在函数名或参数中说明。示例使用 n 作为描述性统计；估计总体方差时常见的无偏修正会使用 n-1。两者没有谁“永远正确”，关键是与问题、库函数和报告口径保持一致。

概率结果要带范围：分子、分母、时间与分群

一个“35% 的概率”只有在分子、分母、时间窗口和样本单位都明确时才有意义。是 35% 的请求、用户、token，还是 35% 的会话？是当天、七天还是整个生命周期？同一事件按请求统计与按用户统计，结果可能完全不同。写概率时把这些限定词放进标题和代码变量名，比在正文末尾补一句说明更可靠。

小样本概率的波动很大，观察到 2/5 与 200/500 的点估计都为 40%，证据强度却不同。报告二项比例时可以给出 Wilson 区间或 bootstrap 区间，并显示有效样本量。对于零次命中或全数命中，也不要把区间宽度当成零；边界估计恰恰需要更谨慎的先验或区间方法。

概率还可能随时间、用户群和动作策略反馈而改变。模型提高某类内容的曝光，会改变之后被观察到的样本，形成策略反馈；历史概率不能直接当作未来基线。线上实验需要记录策略版本、流量分配和停止规则，避免中途看结果后随意结束而夸大显著性。

import math

def wilson(successes, total, z=1.96):
    if total <= 0 or not 0 <= successes <= total:
        raise ValueError("计数无效")
    p = successes / total
    denominator = 1 + z * z / total
    center = (p + z * z / (2 * total)) / denominator
    radius = z * math.sqrt(p * (1 - p) / total + z * z / (4 * total * total)) / denominator
    return center - radius, center + radius

print(wilson(2, 5), wilson(200, 500))
# 练习：比较 0/5 与 0/500 的区间，而不是只比较点估计

Bayes 不是“反过来相乘”：先写清先验、证据和后验

Bayes 公式 p(A|B)=p(B|A)p(A)/p(B) 把看到证据后的信念更新拆成三部分。先验 p(A) 反映在看证据前的基准频率，似然 p(B|A) 说明假设成立时出现证据的可能性，边缘概率 p(B) 负责归一化。忽略基准频率会产生“基础率谬误”：一个检测器在正类稀少时，即使灵敏度高，阳性结果也不一定意味着正类最可能。

用赔率形式写 Bayes 更容易看出证据如何累积：后验赔率 = 先验赔率 × 似然比。多个条件独立的证据可以相乘，但“条件独立”必须在给定假设下成立；同一来源的重复信号不能简单当成独立证据。机器学习中的朴素 Bayes 用强假设换取可计算性，效果好坏应通过数据验证，不应把独立假设当成现实事实。

概率模型还要区分观测相关与因果关系。看到“使用某功能”和“留存更高”并不能直接推出功能导致留存，可能存在用户类型、渠道或时间的混杂。条件概率可以帮助分层描述，但要回答干预问题，还需要实验、准实验或明确的因果假设。本章只提供概率语言，不把相关性包装成因果结论。

蒙特卡洛估计用随机样本近似期望：样本越多，随机误差通常下降，但相关样本、重尾分布和高方差函数会让收敛很慢。固定种子便于复现，却不等于一次种子代表真实不确定性；应报告多次运行的均值、标准差和区间。若可以使用分层抽样、控制变量或重要性采样，应说明它们改变了方差而没有改变目标的条件。

def posterior(prior, likelihood_if_true, likelihood_if_false):
    evidence = (likelihood_if_true * prior
                + likelihood_if_false * (1 - prior))
    if evidence == 0:
        raise ValueError("证据概率不能为零")
    return likelihood_if_true * prior / evidence

prior = 0.01
true_positive = 0.95
false_positive = 0.05
print(posterior(prior, true_positive, false_positive))
# 练习：改变先验为 0.2，观察同一检测结果的后验变化

把先验从 1% 改为 20% 后，后验会显著变化，这正是基准率的重要性。实验报告应说明先验来自哪里、是否随时间或分群改变、检测器的正负样本是否独立，以及概率是否经过校准。一个看似精确的后验数字，如果分母和数据来源不清楚，仍然不能支持高风险决策。

随机变量不是“随机的变量名”

随机变量把随机实验的结果映射成数字。Bernoulli 变量只有 0 和 1 两种结果，参数 p 表示取 1 的概率；重复 n 次独立 Bernoulli 实验，成功次数服从二项分布。许多二元评测指标都可以从这个模型开始思考：一次预测是否正确、一次请求是否超时、一个 token 是否命中目标。假设独立并不总成立，例如同一文档的多个片段可能高度相关，不能把它们当成完全独立的样本。

正态分布由均值和标准差控制，是许多测量误差和聚合量的近似模型，但现实数据经常偏斜、截断或有厚尾。标准化 z=(x-μ)/σ 只改变位置和尺度，不会把非正态数据神奇地变成正态。看到钟形曲线时，先问数据生成机制和样本量，而不是凭图形套公式。

分布的尾部对系统风险尤其重要。模型延迟的平均值可能很好，但第 99 百分位很差；错误率整体低，却可能在一个少量子群上集中。用分位数、箱线图和分层统计补充均值，可以把“罕见但昂贵”的情况显示出来。尾部估计需要更多样本，样本不足时要诚实表达不确定范围。

from statistics import mean, pstdev

results = [1, 1, 0, 1, 0, 1, 1, 0, 1, 0]
p = mean(results)
print("Bernoulli 经验 p=", p)
print("标准差=", pstdev(results))

latencies = [120, 128, 131, 133, 140, 145, 150, 166, 220, 480]
ordered = sorted(latencies)
percentile_90 = ordered[int(0.9 * (len(ordered) - 1))]
print("平均=", mean(latencies), "P90 近似=", percentile_90)
assert 0 <= p <= 1

代码故意把正确率和延迟放在同一页观察：二元结果的均值就是成功率，但延迟的均值无法代表尾部。百分位的计算有多种约定，示例只用于建立概念；正式报告应说明插值方式、样本量和是否按用户或请求分组。

样本先要代表你想讨论的总体

总体是你真正想了解的对象，样本是实际收集的一部分。随机抽样、分层抽样、时间切片和方便抽样会产生不同的样本结构。大数定律说明在条件稳定、样本相互独立且抽样合理时，样本平均会趋近总体期望；它没有承诺“样本足够大就能修复系统性偏差”。如果只收集愿意反馈的用户，增加样本量只会更精确地估计这群用户的行为。

中心极限定理解释了为什么许多样本均值在一定条件下近似正态，即使单个观测不正态。它依赖独立性、有限方差和合适的聚合；厚尾、强相关或分布漂移时需要更谨慎。训练和评测中把同一文档的相邻片段随机打散，可能让有效样本量被高估；按来源分组或按时间切分，往往更接近真实部署条件。

重复实验可以估计随机性的影响。固定随机种子有助于复现一次运行，但不应把一次种子当成全部结论；更好的做法是使用多个种子，报告均值、标准差和最差/最好结果。若计算资源有限，可以先在小规模上做三到五次重复，确认趋势后再扩大规模。结果表要保留每次运行的配置和失败原因，不要只留下挑出来的最好曲线。

from statistics import mean, pstdev

runs = [0.81, 0.79, 0.83, 0.80, 0.76]
summary = {"n": len(runs), "mean": mean(runs), "std": pstdev(runs), "min": min(runs), "max": max(runs)}
print(summary)

if summary["std"] > 0.02:
    print("结果波动较大，先检查随机种子、数据切分和训练稳定性")
else:
    print("当前重复运行较稳定，仍需确认样本是否代表部署分布")

这里的标准差只描述这五次运行的波动，不是总体参数的精确置信区间。报告时应把“运行随机性”和“抽样不确定性”分开：前者来自初始化、批次和算法，后者来自样本没有覆盖全部输入。两者同时存在时，单一的误差条可能遮住真正原因。

区间是在表达估计的不确定，不是给未来下保证

样本比例只是总体比例的估计。置信区间用一种规定好的重复抽样程序表达估计的波动：如果重复抽样并按同一方法构造区间，长期来看会有大约某个比例的区间覆盖真实参数。它不是说“真实参数有 95% 的概率在这一个已经算出的区间里”，也不是未来每一次预测都落在区间内。学习阶段可以用正态近似或自助法建立直觉，正式报告要说明方法和适用条件。

模型概率需要校准。一个输出 0.8 的样本集合，如果其中约 80% 最终正确，可以说这一档概率大致校准；如果只有 50% 正确，模型就过度自信。可靠性图、分桶准确率、Brier score 和校准曲线能帮助观察这种关系。校准不等于排序能力：一个模型可以很好地区分高低风险，却给出整体偏高的概率。阈值决策还要结合不同错误的代价。

不确定性有多个来源：数据噪声、样本不足、分布变化和模型本身不知道。增加同分布样本可能减少抽样波动，却不能消除测量错误或新场景风险。把拒答、人工复核和置信度阈值当作系统的一部分，比强迫每个输入都给一个确定答案更诚实。监控应同时看置信度分布、错误率和覆盖率。

predicted = [0.1, 0.2, 0.3, 0.7, 0.8, 0.9, 0.9, 0.8]; actual = [0, 0, 1, 1, 0, 1, 1, 1]; pairs = list(zip(predicted, actual)); brier = sum((score - label) ** 2 for score, label in pairs) / len(pairs); print("Brier=", brier); print("mean confidence=", sum(predicted) / len(predicted), "accuracy=", sum(actual) / len(actual))

分桶的示例故意使用很少的数据，只用于展示“平均预测概率”和“实际正确率”的比较。正式校准要选择足够的样本、说明分桶边界，并按时间或关键子群检查。一个整体看起来校准的模型，可能在少数高风险子群上严重失准。

从一组观测到一条分布：不要把直方图当成事实本身

分布是对随机变量取值规律的描述，直方图只是有限样本和分箱规则共同产生的近似。箱宽太大，会把多峰结构抹平；箱宽太小，会把随机噪声看成模式。画图时应同时报告样本数、分箱边界、是否归一化以及异常值处理。对模型输出，密度曲线的平滑带宽也会改变视觉印象，不能只挑一张“看起来最合理”的图。

均值、方差和分位数是分布的摘要，而不是分布的全部。两个数据集可以拥有相同均值和标准差，却有完全不同的尾部、偏度或多峰结构。语言数据中的长度、置信度和延迟尤其常呈长尾，平均值可能被少数极端样本拉高。报告延迟或 token 数时，建议同时给出中位数、P90/P95/P99 和样本量。

中心极限定理解释了为什么许多样本均值在条件满足时趋近正态，但它不保证原始数据正态，也不替代检查独立性和有限方差。小样本、重尾、相关序列和分层数据都可能让正态近似失效。使用近似区间时，要标出近似依据；若不确定，可以使用 bootstrap、置换检验或按组重采样。

分布比较要先确定比较目标：位置变化、尺度变化、形状变化还是尾部风险。KS 距离、Wasserstein 距离、分位数差异各有侧重；统计显著不代表业务重要。大样本会让很小的差异也显著，应该同时报告效应大小、置信区间和实际阈值。

import random

def bootstrap_means(values, repeats=2000, seed=7):
    if not values:
        raise ValueError("values 不能为空")
    rng = random.Random(seed)
    n = len(values)
    return [sum(rng.choices(values, k=n)) / n for _ in range(repeats)]

def percentile(values, q):
    ordered = sorted(values)
    index = (len(ordered) - 1) * q
    low, high = int(index), min(int(index) + 1, len(ordered) - 1)
    weight = index - low
    return ordered[low] * (1 - weight) + ordered[high] * weight

sample = [12, 13, 15, 16, 19, 21, 25]
estimates = bootstrap_means(sample)
print(percentile(estimates, .025), percentile(estimates, .975))
# 练习：改变 seed 和 repeats，观察区间的稳定程度

bootstrap 把观测样本当作经验总体，反复有放回抽样来近似估计量的抽样分布。它能提供实用的区间，却不能修复样本代表性问题：如果原始样本漏掉了某类用户，重复抽样只会更稳定地重复这个偏差。时间序列、群组数据和强相关样本应按块或按组重采样，不能逐行打乱。

校准、漂移与阈值：概率输出要经得起时间考验

校准关注的是“模型说 0.7 的样本，长期是否约有 70% 正例”，而不是只看排序能力。一个模型可以 AUC 很高却过度自信；另一个模型排序一般但概率更接近真实频率。可靠性图把预测概率分桶，再比较每桶的平均预测与实际命中率；分桶数、每桶样本量和置信区间都应记录，避免小桶的偶然波动被误读。

阈值是决策层的选择，不是模型概率自动带来的答案。医疗提醒、内容审核和资源分配的误报与漏报成本不同，同一组概率在不同场景应使用不同阈值。调阈值时只能使用验证集或独立校准集，不能在测试集上反复挑选，否则测试集也被间接训练。

数据漂移可以发生在输入、标签关系或类别比例。输入分布变了不一定影响性能，关系变了却可能让旧阈值失效；因此监控应同时记录特征分布、预测分布、延迟、缺失率和有标签后的真实指标。漂移检测的报警不是自动回滚命令，而是触发抽样复核、分群评估和再训练决策的证据。

线上分布还会受到版本、季节、渠道、语言和攻击行为影响。把所有样本混成一条总体曲线可能掩盖某个小群体的严重退化。应预先定义关键分群、最小样本量和报警窗口，并保留可追溯的模型版本、数据快照与随机种子。这样当指标变化时，能判断是模型、数据还是测量系统发生了变化。

def reliability_bins(probabilities, labels, bins=5):
    if len(probabilities) != len(labels):
        raise ValueError("概率与标签长度不一致")
    result = []
    for bucket in range(bins):
        lower, upper = bucket / bins, (bucket + 1) / bins
        pairs = [(p, y) for p, y in zip(probabilities, labels)
                 if lower <= p < upper or (bucket == bins - 1 and p == upper)]
        if pairs:
            result.append({"range": (lower, upper),
                           "predicted": sum(p for p, _ in pairs) / len(pairs),
                           "observed": sum(y for _, y in pairs) / len(pairs),
                           "count": len(pairs)})
    return result

print(reliability_bins([.1, .2, .4, .7, .9], [0, 0, 1, 1, 1]))
# 练习：为每个桶加入 Wilson 区间或最小样本量规则

可靠性表里的每一行都应能追溯到原始预测与标签。若一个桶只有两条样本，观察频率可能从 0 跳到 1，不能据此宣布模型失准。实际报告可以合并小桶、显示置信区间，或采用等频分桶。无论选择哪种方法，都要在版本之间保持一致，才能比较校准变化。

随机性要被量化：一次结果不能代表一条分布

生成模型或随机优化器的一次输出只是分布中的一个样本。若要比较两个配置，至少固定输入并重复采样，报告均值、离散程度和尾部，而不是挑一条最漂亮的结果。对文本生成，还应区分 token 级随机性、整段主题变化和评审者噪声；三者需要不同的重复设计。

置信区间描述估计过程的不确定性，不是“真实参数落在区间内的概率”这一句简单口号。区间的构造方法、重复次数和覆盖假设都重要。把同一测试集反复用于调参会让区间偏乐观；留出独立测试集或采用嵌套评估，才能保留更可信的泛化估计。

当分布有明显分群时，先分层再汇总通常更安全。整体均值可能出现辛普森悖论：每个分组都变好，混合后的总体却变差，原因只是分组比例改变。报告总体指标时同时给出关键分组和样本量，必要时采用加权汇总，才能避免把结构变化误判为模型变化。

import random

def summarize(generator, repeats=20, seed=7):
    rng = random.Random(seed)
    scores = [generator(rng) for _ in range(repeats)]
    scores.sort()
    mean = sum(scores) / len(scores)
    median = scores[len(scores) // 2]
    return {"mean": mean, "median": median, "min": scores[0], "max": scores[-1]}

def noisy_score(rng):
    return 0.7 + rng.uniform(-0.08, 0.08)

print(summarize(noisy_score))
# 练习：把 repeats 改为 3、100，观察摘要的稳定性

分布差异先问“来自哪里”：抽样、测量还是生成机制

看到两条分布曲线不同时，至少有三类解释：样本来自不同总体，测量流程发生变化，或生成机制本身改变。用户画像变化属于抽样/总体变化；埋点字段改名属于测量变化；模型版本更新导致预测分布改变则是生成机制变化。三者处理方式不同，不能统一叫“数据漂移”。先对齐时间、样本单位、过滤规则与数据版本，再比较形状。

抽样偏差常来自方便样本、幸存者偏差、缺失不随机和标签只在特定事件后产生。加权可以修正已知的选择概率，但如果选择机制未知，权重也会引入更大方差。报告分布时要保留纳入/排除流程、缺失比例和每个分群的样本量。一个总体直方图看起来稳定，不代表未观测人群没有发生变化。

分位数是稳健沟通尾部风险的工具，但分位数本身也是估计量。样本很少时，P99 可能由一个点决定；不同插值规则也会造成小差异。比较版本时使用同一分位数定义、相同过滤与时间窗口，并给出 bootstrap 区间或至少标注样本量。若尾部是安全阈值，宁可保守处理，也不要用平均值替代。

采样温度控制的是从分布中抽取时的随机性，不会凭空增加模型知识。降低温度通常让高概率 token 更集中，提高温度会增加探索；top-k、top-p 等截断则改变可采样的支持集。评估生成模型时，要固定 prompt、tokenizer、最大长度、采样参数和随机种子，分别比较质量、多样性、重复率和安全约束。

def quantile(values, q):
    if not values or not 0 <= q <= 1:
        raise ValueError("样本或 q 无效")
    ordered = sorted(values)
    position = (len(ordered) - 1) * q
    lower = int(position)
    upper = min(lower + 1, len(ordered) - 1)
    fraction = position - lower
    return ordered[lower] + fraction * (ordered[upper] - ordered[lower])

latency = [80, 82, 85, 87, 91, 94, 110, 145, 300, 610]
for q in (.5, .9, .95, .99):
    print(f"P{q * 100:g}={quantile(latency, q):.1f} ms")
# 练习：删除最大值后比较 P99，说明小样本尾部的脆弱性

分位数函数的插值规则只是一个选择，生产环境应与分析库保持一致。更重要的是把原始样本量、采样窗口、单位和是否去重一起输出。对于线上监控，可保存分位数摘要结构而非全部原始数据，但要验证摘要在合并分片后仍能近似目标分位数，并明确误差界限。

平方误差和绝对误差对异常值的态度不同

均方误差 MSE 把每个残差平方后平均，较大的错误会被显著放大；平均绝对误差 MAE 只取绝对值，对离群点更鲁棒。二者都可以用于回归，但它们表达的业务代价不同：如果严重偏差会带来平方级损失，MSE 合理；如果希望每一分钟误差承担近似线性代价，MAE 更直接。选择损失前先画残差分布，观察异常值是否是真实风险、测量错误还是数据录入问题。

损失的缩放和聚合也会改变梯度。对一个批次求和，批次越大损失和梯度通常越大；求平均则让梯度尺度相对稳定。按样本加权可以处理类别不平衡或业务优先级，但权重必须写在契约里，不能在调参时悄悄修改。报告训练曲线时说明 reduction、样本权重和忽略的标签，才能比较不同实验。

训练损失下降不必然等于真实质量提升。模型可能利用数据泄漏、记住训练样本，或优化了容易计算却与最终目标不一致的代理指标。验证集损失、分层指标、人工检查和错误案例共同构成证据。把“可优化”与“值得优化”分开，是从数学走向工程判断的重要一步。

errors = [0.2, -0.4, 0.1, 3.0]; mse = sum(error ** 2 for error in errors) / len(errors); mae = sum(abs(error) for error in errors) / len(errors); threshold = 1.0; huber = sum(0.5 * error ** 2 if abs(error) <= threshold else threshold * (abs(error) - 0.5 * threshold) for error in errors) / len(errors); print({"mse": mse, "mae": mae, "huber": huber})

同一组误差下，MSE 会被 3.0 这个离群点强烈拉高，而 MAE 和 Huber 反应较温和。这个结果不说明某个损失永远更好，只说明它们在优化时传递了不同的代价信号。用真实业务损失、验证集和错误分层共同决定，而不是为了让训练曲线更好看而选择。

似然是“在参数固定时，数据出现的可能性”

给定一组观测数据和模型参数，似然把每个观测在模型下的概率相乘。最大似然估计选择让观测数据最可能出现的参数；取负对数后，连乘变成求和，数值更稳定，也更容易按批次累积。分类任务中的交叉熵，通常就是对真实类别的预测概率取负对数并求平均。真实类别概率越低，损失越大；只要预测正确但概率不够高，仍会收到惩罚。

交叉熵要和标签编码对应。单标签多分类使用 one-hot 或类别索引，每个样本只有一个目标类别；多标签任务可以让多个标签同时为 1，损失形式不同。标签平滑会把绝对的 0/1 目标变成稍微柔和的分布，降低过度自信，但也改变了优化目标。不要把“概率最高的类别”与“分布完整”混为一谈，评估时还应查看校准、召回和置信度。

数值稳定性再次出现：如果预测概率为 0，-log(0) 在数学上趋向无穷，浮点实现会得到无穷或异常。框架通常直接接收 logits，在内部使用 log-sum-exp 技巧，而不是让你先手动 Softmax 再取对数。了解这一点能避免重复归一化、梯度变差和溢出。排查 loss 异常时，记录 logits 范围、目标索引和非有限数量。

from math import exp, log

logsumexp = lambda values: max(values) + log(sum(exp(value - max(values)) for value in values))
cross_entropy = lambda logits, target: logsumexp(logits) - logits[target]

for logits, target in [([2.0, 0.0, -1.0], 0), ([2.0, 0.0, -1.0], 2)]:
    print(cross_entropy(logits, target))

第二组把目标类别从最高分改成最低分，损失会明显增大。实现中用 logsumexp 避免先计算可能溢出的指数和；真正的框架还会处理批次、设备和梯度。手算版本的价值是确认“目标索引、分数顺序和聚合方式”都符合预期。

交叉熵可以拆成真实分布的熵加上 KL 差异

对两个离散分布 P 和 Q，KL 散度 DKL(P||Q)=ΣP(x)log(P(x)/Q(x)) 衡量用 Q 近似 P 时多付出的信息代价。它非负，但不对称，交换 P 和 Q 通常得到不同结果，因此不能简单称为“距离”。蒸馏、正则化和分布对齐会使用 KL，但必须写清谁是参考分布、谁是被优化分布。

熵衡量一个分布本身的不确定性。均匀分布的熵较高，集中在一个结果上的分布熵较低。语言模型在真实 token 上的平均负对数似然可以指数化为困惑度：perplexity=exp(cross-entropy)。困惑度直觉上像模型面对每个位置时的“有效候选数”，但它依赖词表、分词方式、数据清洗和计算口径，不能跨不同 tokenizer 直接比较。

信息量与概率成反比：I(x)=-log P(x)。罕见 token 信息量高，常见 token 信息量低；这不代表罕见内容一定重要，也不代表低困惑度等于事实正确。评测生成模型时，把交叉熵、任务准确率、人工质量、校准和安全错误放在一起，才能避免单一代理指标主导系统。

from math import log, exp

p = [0.7, 0.2, 0.1]; q = [0.5, 0.3, 0.2]
entropy = -sum(value * log(value) for value in p)
cross_entropy = -sum(value * log(predicted) for value, predicted in zip(p, q))
kl = sum(value * log(value / predicted) for value, predicted in zip(p, q))
print({"entropy": entropy, "cross_entropy": cross_entropy, "kl": kl, "perplexity": exp(cross_entropy)})
assert abs(cross_entropy - entropy - kl) < 1e-12

分解关系 H(P,Q)=H(P)+DKL(P||Q) 是一个很好的自检：如果实现的交叉熵、熵和 KL 不满足近似等式，优先检查概率是否归一化、零概率如何处理和对数底数是否一致。不同文档可能使用自然对数或以 2 为底的对数，数值单位分别是 nat 和 bit，比较时要注明。

损失函数是训练目标，不等于最终评价

损失把一次预测与目标之间的差异转成可优化的标量。它选择了“什么错误更贵”的观点：MSE 放大大误差，MAE 对离群点更稳，Huber 在小误差区像 MSE、在大误差区像 MAE。没有一种损失天然正确，选择应由数据噪声、决策成本、梯度性质和最终任务共同决定。训练损失下降，只能说明模型更擅长当前目标，不保证用户体验、事实性或安全性同步改善。

损失的归约方式会改变梯度尺度。对 token 级交叉熵，可以求所有有效 token 的平均、求和，或按样本先平均再对样本平均；当序列长度不同、padding 很多时，三者的权重不同。若忽略掩码，把 padding 也计入平均，模型会学到填充符而不是内容。实现时要明确分母是有效 token 数、样本数还是固定 batch size，并在日志中同时记录分子和分母。

类别不平衡时，未加权损失可能被多数类主导。类别权重、重采样、focal loss 和阈值调整都能改变学习压力，但它们的作用位置不同：权重改变训练梯度，重采样改变看到的数据分布，阈值只改变决策。若同时使用多个方法，要做消融实验，避免把收益归因给错误的组件。权重还可能放大少数类噪声，需配合校准和分群评估。

损失函数的实现应满足基本性质：正确预测时是否达到最小、概率是否归一、对称性是否符合任务、输入为极端值时是否稳定、梯度是否有合理方向。最好先在一维或二维网格上画出曲线，再用自动微分检查梯度。对自定义损失，写出一个可读的参考实现与一个高效实现，随机输入对照数值和梯度。

def masked_mean(values, mask):
    if len(values) != len(mask):
        raise ValueError("values 与 mask 长度不一致")
    selected = [value for value, keep in zip(values, mask) if keep]
    if not selected:
        raise ValueError("没有有效元素")
    return sum(selected) / len(selected)

token_losses = [0.2, 1.1, 0.7, 8.0, 0.4]
valid = [True, True, False, False, True]  # padding/忽略标签
print("masked mean=", masked_mean(token_losses, valid))
print("valid count=", sum(valid))

# 练习：比较全量平均、有效 token 平均和按样本平均的权重

这个例子特意把一个很大的损失放在被屏蔽位置，提醒我们掩码不是装饰。实际代码还要处理分布式训练：各设备的有效 token 数可能不同，不能先对每卡平均再简单平均，否则短序列卡片权重会被放大。应汇总有效损失和有效计数，再做全局除法，或者使用框架提供的正确归约。

交叉熵、标签平滑与困惑度：概率质量的不同读法

交叉熵 H(p,q)=-Σp(x)log q(x) 衡量用模型分布 q 编码来自目标分布 p 的样本需要多少信息。分类的 one-hot 标签是特殊情况，只取正确类别的负对数概率。它对“自信但错误”惩罚很重，因此能推动模型把概率质量放到正确位置；但标签本身有噪声或类别边界模糊时，过分追求 one-hot 也会导致过度自信。

标签平滑把 one-hot 目标变成“正确类占大部分、其他类分到少量质量”的分布，能抑制极端 logits、改善校准，但也可能降低模型区分非常相近类别的能力。它不是无条件的正则化开关，平滑系数应在验证集上比较，并观察 NLL、准确率、校准和生成质量。对语言模型，padding、特殊 token 和不同序列长度还会改变有效 token 的分母。

困惑度常写为交叉熵的指数，是“模型平均分给真实 token 的有效分支数”的一种直观表达。它依赖 tokenizer、上下文窗口、归约方式和数据预处理，不能跨 tokenizer 或不同语料直接比较。困惑度下降说明预测分布更贴近评测文本，不等于事实性、指令遵循或安全性提高。

对数的底决定单位：自然对数对应 nats，底数为 2 对应 bits。换底只改变常数比例，不改变最优分布，但报告指标时必须注明。数值实现中，优先使用 logits 版融合交叉熵或稳定的 log-softmax，避免先取概率再取对数造成下溢。

import math

def cross_entropy(logits, target, smoothing=0.0):
    if not logits or not 0 <= target < len(logits):
        raise ValueError("target 或 logits 无效")
    peak = max(logits)
    log_z = peak + math.log(sum(math.exp(x - peak) for x in logits))
    classes = len(logits)
    target_mass = 1.0 - smoothing
    other_mass = smoothing / (classes - 1) if classes > 1 else 0.0
    return -sum((target_mass if i == target else other_mass) * (x - log_z)
                for i, x in enumerate(logits))

print(cross_entropy([2.0, 0.1, -1.0], target=0))
print(cross_entropy([2.0, 0.1, -1.0], target=0, smoothing=0.1))
# 练习：检查平移所有 logits 不改变损失

参考实现把归一化常数写出来，便于逐项检查。优化版本可能使用向量化和融合 kernel，但应与这个版本在小输入上对齐。做对齐时要比较不同 reduction、dtype、忽略标签和权重设置；只比较最终一个 batch 的平均值，很容易把归约差异误认为实现 bug。

检查损失的三个方向：数值、梯度和决策

自定义损失至少要做三类检查。数值检查确认正确预测更小、输入平移或缩放符合预期、极端值不产生 NaN；梯度检查确认符号和量级与有限差分一致；决策检查则把损失变化映射到真正关心的错误，例如少数类召回、拒答率或人工偏好。只有三类证据相互支持，才适合把损失放进较大实验。

损失的目标分布也应与数据管道同步。分类标签是整数 id 还是概率分布，序列目标是否右移一位，padding 是否忽略，soft label 是否包含温度或平滑，都会改变公式。最有效的排错方法是打印一个样本的 logits、目标、有效 mask、逐项损失和最终归约，手算其中一项，再与框架输出对齐。

如果损失对某些样本极端敏感，可以记录逐样本分布而不是只记录平均值。高损失样本可能是难例、脏标签、分布外输入或模型真正的失败；把它们混成一个均值会错过改进线索。抽样查看高、中、低损失样本，并按来源、长度和类别分组，能帮助判断该调整数据、模型还是目标。

import math

def nll_for_example(logits, target):
    peak = max(logits)
    log_z = peak + math.log(sum(math.exp(value - peak) for value in logits))
    return -(logits[target] - log_z)

batch = [([2.0, .1, -1.0], 0), ([.0, .1, .2], 2), ([8.0, -2.0, -3.0], 1)]
values = [nll_for_example(logits, target) for logits, target in batch]
print("per-example=", values, "mean=", sum(values) / len(values))
# 练习：按类别分组，找出平均损失最大的组

先定义错误的代价，再选择损失的形状

同一个预测任务可以有多种合理损失，因为“错多少”与“错在哪里”的代价不同。预测房价时，差 10 万元在不同价格区间的意义不同；审核任务里漏放一条高风险内容可能比误拦一条普通内容代价更高；生成任务里一个事实错误可能比措辞不自然更严重。损失应尽量把重要差异编码进梯度，同时把难以微分或需要人工判断的目标留给独立评估。

损失的尺度影响优化器的步长。把每个样本损失乘以 100，不改变理论最优点，却会把梯度放大 100 倍，混合精度和梯度裁剪的行为也会改变。比较实验时要记录 reduction、样本权重和损失单位；如果改变了权重，学习率往往也需要重新校准。不要只看 loss 的绝对值跨实验排序，先确认定义和尺度相同。

多任务训练把多个损失加权求和，权重决定不同目标之间的谈判。权重太大的一项会压制其他梯度，权重太小的一项几乎没有作用；动态权重、梯度归一化和分阶段训练都是解决办法，但每一种都引入新的假设。报告多任务结果时要分别给出各子损失、主指标、护栏指标和权重曲线，不能只报一个总 loss。

可微并不等于可优化。一个损失即使连续，仍可能有平坦区、尖锐区、局部极小或梯度很大。画一维切片、做小步下降测试、检查梯度方向和对极端样本的响应，是理解损失形状的低成本方法。自定义损失上线前还要检查有限性、设备/dtype、空 batch、忽略标签和分布式归约。

def weighted_loss(task_losses, weights):
    if set(task_losses) != set(weights):
        raise ValueError("任务与权重键必须一致")
    if any(weight < 0 for weight in weights.values()):
        raise ValueError("权重不能为负")
    total = sum(task_losses[name] * weights[name] for name in task_losses)
    return total

losses = {"quality": 0.8, "safety": 0.2, "format": 0.4}
weights = {"quality": 1.0, "safety": 3.0, "format": .5}
print(weighted_loss(losses, weights))
# 练习：分别把 safety 权重改为 0.1 与 10，比较各项贡献

示例把权重和子损失显式打印出来，避免总值遮住某一项。若安全项是硬约束，单纯加权可能仍允许模型用质量收益换取安全退化，此时应增加拒绝条件、分层门槛或在训练流程中使用约束优化。权重不是“越大越重视”这么简单，还会改变优化轨迹和可达的折中区域。

基本更新式只有一句，但前提很多

梯度下降的更新写成 θ ← θ - η∇L(θ)，其中 θ 是参数，η 是学习率，∇L 是损失对参数的梯度。负号表示朝局部下降方向走。学习率决定步长，不是“模型学习能力”的单一分数；它必须和损失尺度、批次大小、参数化方式及优化器配套。把学习率从 0.001 改到 0.01，实际改变的是每次参数移动的距离。

批量梯度使用所有训练样本，随机梯度使用一个样本，小批量梯度在噪声和效率之间折中。小批量更新的噪声有时能帮助离开狭窄的局部区域，却也会让曲线抖动。比较实验时记录有效更新次数，而不仅是 epoch；不同 batch size 下一个 epoch 的梯度估计次数不同。梯度累积可以模拟更大批次，但需要说明何时除以累积步数、何时更新学习率调度器。

学习率策略包括预热、衰减、周期变化和按指标降低。预热让初始阶段的参数和统计量先稳定，衰减在后期用更小步长细化。任何调度都应通过验证曲线和梯度统计验收，而不是因为名字流行就使用。遇到 loss 突然变为 NaN，先检查输入、logits、梯度和学习率范围，再决定是否降低学习率。

loss = lambda x: (x - 3.0) ** 2 + 1.0; gradient = lambda x: 2 * (x - 3.0); results = {}; [results.setdefault(learning_rate, []) for learning_rate in (0.1, 0.8, 1.1)];
# 练习时把每个学习率的更新轨迹记录下来，再比较收敛与发散

学习率 0.1 会稳步接近最低点，0.8 可能在两侧快速摆动，1.1 则可能发散。这个一维例子不代表真实网络的全部行为，却能让你先理解“步长超过局部稳定范围”的概念。学习曲线要记录完整轨迹，不能只报告最后损失，因为不同设置可能在中途经历完全不同的风险。

优化器的差异是更新规则的差异

随机梯度下降用当前小批次估计梯度，估计会有噪声；动量维护一个历史方向，让连续朝同一方向的更新累积，减少狭长谷底中的来回摆动。自适应方法会为不同参数维护梯度平方等统计量，按历史尺度调整步长。它们能改善训练的数值行为，却不能修复错误标签、泄漏或不合适的损失。

Adam 常被描述为“结合动量和自适应学习率”，但真正决定结果的还有 β 参数、ε、权重衰减、学习率调度和梯度裁剪。更换优化器时应把其他变量尽量固定，并使用相同的训练/验证切分与随机种子集合。否则观察到的提升可能来自 batch、初始化或数据顺序，而不是优化器本身。

优化器状态也是实验状态。动量和二阶统计量会随着训练累积，恢复模型时若只保存参数、不保存优化器状态，继续训练的轨迹可能不同。检查点要记录模型权重、优化器状态、调度器步数、随机状态、数据版本和代码版本。比较两个 checkpoint 时，不要只看参数文件大小，要确认它们是否在同一训练阶段。

gradient = [2.0, -1.0]; parameter = [4.0, -3.0]; velocity = [0.0, 0.0]; learning_rate = 0.1; momentum = 0.9;
for step in range(1, 4):
    velocity = [momentum * old + current for old, current in zip(velocity, gradient)]
    parameter = [value - learning_rate * move for value, move in zip(parameter, velocity)]
    print(step, parameter, velocity)
# 恢复训练时，parameter 和 velocity 都是检查点的一部分

这个简化例子没有实现 Adam 的偏置修正和平方梯度统计，只用于显示“优化器有状态”。如果只保存 parameter 而丢掉 velocity，从同一点继续训练会得到不同轨迹。实验报告应注明实现、版本和所有影响状态的超参数。

优化训练损失和获得新数据上的可靠性不是同一目标

模型参数很多时，可以把训练样本记得非常细，却在新样本上表现下降，这就是过拟合的典型表现。正则化通过在目标中加入参数大小、输出平滑或随机扰动的约束，减少模型依赖偶然细节。L2 权重衰减倾向于限制参数整体规模，L1 会鼓励部分参数变为零；Dropout 在训练时随机屏蔽部分激活，迫使网络不要依赖单一路径。每一种方法都改变了目标或训练过程，不应只把它们当成“让分数变高”的开关。

早停使用验证集监控来决定何时停止训练：当验证指标在若干轮内不再改善，就保存最佳检查点并停止。耐心轮数、最小改善幅度和监控指标需要提前写出，否则会在看到曲线后随意挑一个 checkpoint。验证集被反复用于调参，也会逐渐参与决策，最终应保留一个真正未参与选择的测试集或时间外样本。

泛化还取决于数据覆盖和任务定义。正则化不能补齐没有出现的语言、长度、领域或失败类型；早停不能修复标签泄漏和不一致的预处理。对大模型微调，训练集损失下降可能伴随通用能力、事实性或安全表现变化，因此需要多维评测和回归测试。最可靠的做法是把训练、验证、测试、人工审查和上线监控连成一条证据链。

validation_scores = [0.62, 0.68, 0.70, 0.69, 0.695, 0.694, 0.693]; best_score = float("-inf"); best_step = None; patience = 2; stale = 0;
for step, score in enumerate(validation_scores, start=1):
    if score > best_score: best_score, best_step, stale = score, step, 0
    else: stale += 1
    if stale >= patience: print("stop at", step, "restore", best_step, best_score); break

早停示例保存的是验证集最佳分数对应的步骤，而不是最后一次运行。真实训练还要处理指标越小越好、多个指标冲突、检查点写入失败和训练被中断等情况。把停止规则写成代码并记录，就能避免“凭曲线截图挑结果”。

把梯度下降看成一套可观察的控制回路

梯度下降的更新式 θ_{t+1}=θ_t-η∇L(θ_t) 只写了方向和步长，真正的训练还需要观测回路：记录当前损失、梯度范数、参数范数、学习率、吞吐和验证集指标，再决定下一步是否继续。学习率太大时，损失可能震荡、发散或在狭窄谷底来回跳；太小时，损失下降很慢，甚至被数值噪声掩盖。先在一个小数据集上让模型过拟合，是检查更新方向和损失实现的有效方法。

非凸目标通常存在平坦区、鞍点、多个局部结构和不同尺度的方向。梯度下降并不需要找到全局最优才能得到有用模型，但实验必须说明“优化成功”的定义：训练损失达到阈值、验证指标不再提升、约束满足，还是预算耗尽。只看最后一个 loss 数字无法区分模型已经收敛、学习率过小、梯度被截断，还是数据管道没有真正更新。

学习率调度是时间维度上的建模选择。预热可以避免初始更新过猛，余弦衰减或分段衰减让后期步长变小，周期策略则允许在不同尺度探索。调度器的步进位置很关键：按 batch、按 epoch 或按实际更新次数会产生不同曲线；梯度累积、跳过 batch 和恢复 checkpoint 时，必须保存调度器状态，否则恢复后的学习率会错位。

梯度裁剪控制的是更新的最大幅度，不等同于修复爆炸原因。按全局范数裁剪会把所有参数的梯度同比缩放，按值裁剪则逐元素截断，二者对方向的影响不同。发现频繁裁剪时，应回查输入尺度、损失归约、混合精度、异常 batch 和模型初始化；否则裁剪可能只是把问题隐藏在一个看似稳定的训练曲线后面。

def update(parameter, gradient, learning_rate, clip_norm=None):
    if clip_norm is not None:
        norm = sum(value * value for value in gradient) ** 0.5
        if norm > clip_norm:
            scale = clip_norm / norm
            gradient = [value * scale for value in gradient]
    new_parameter = [p - learning_rate * g for p, g in zip(parameter, gradient)]
    return new_parameter, sum(g * g for g in gradient) ** 0.5

parameter = [2.0, -1.0]
gradient = [4.0, -3.0]
parameter, grad_norm = update(parameter, gradient, .1, clip_norm=2.0)
print("parameter=", parameter, "effective grad norm=", grad_norm)
# 练习：记录裁剪前后的范数，解释方向是否发生改变

示例把更新与观测放在同一个小函数中，方便验证。完整训练器还应返回步数、是否发生裁剪、当前学习率和有限性检查结果。若出现 NaN，先保存触发问题的 batch 和 checkpoint，再缩小学习率或关闭混合精度做对照；直接跳过 NaN batch 会丢失诊断证据。

SGD、动量与 Adam：状态变量改变了更新的记忆

随机梯度下降用一个 mini-batch 估计总体梯度，噪声有时能帮助离开狭窄结构，但也让曲线抖动。动量为梯度建立指数移动平均，相当于保留过去更新的方向；它能穿过小尺度的来回摆动，却可能在学习率过大时积累错误方向。Adam 同时维护一阶矩和二阶矩，按每个参数的历史尺度自适应调整，但它的默认超参数并非普适常数，权重衰减与 L2 惩罚也不总是同一件事。

Adam 的偏置修正是因为移动平均在训练初期从零开始，会系统性偏小。更新中的 m_hat 与 v_hat 用当前步数修正后，早期行为才与长期估计更一致。实现优化器时，参数、梯度、一阶状态、二阶状态和步数必须一一对应；恢复 checkpoint 时少保存一个状态，就会得到“参数相同、后续轨迹不同”的隐蔽差异。

权重衰减可以理解为每一步让参数向零收缩，但在自适应优化器中，直接把 L2 项加进梯度与解耦权重衰减的行为不同。选择哪一种取决于框架实现和实验目的。记录优化器类、版本、betas、epsilon、weight decay、是否解耦以及参数分组，比只写“用了 Adam”可复现得多。

不同参数组常需要不同学习率，例如预训练骨干与新加的分类头、Embedding 与输出投影、偏置与归一化参数。参数分组时要检查没有重复或遗漏，冻结参数要确认 requires_grad 与优化器列表同时反映冻结状态。否则“学习率调优”可能只是在给一个根本没有更新的参数组换数字。

def adam_step(parameter, gradient, state, lr=.01, beta1=.9, beta2=.999, eps=1e-8):
    state["step"] += 1
    state["m"] = [beta1 * m + (1 - beta1) * g for m, g in zip(state["m"], gradient)]
    state["v"] = [beta2 * v + (1 - beta2) * g * g for v, g in zip(state["v"], gradient)]
    t = state["step"]
    m_hat = [m / (1 - beta1 ** t) for m in state["m"]]
    v_hat = [v / (1 - beta2 ** t) for v in state["v"]]
    return [p - lr * m / ((v ** .5) + eps) for p, m, v in zip(parameter, m_hat, v_hat)]

parameter = [1.0, -2.0]
state = {"step": 0, "m": [0.0, 0.0], "v": [0.0, 0.0]}
for gradient in ([.5, -1.0], [.2, -.4]):
    parameter = adam_step(parameter, gradient, state)
    print(parameter, state["step"])
# 练习：删掉偏置修正，比较前两步的差异

停止、回滚与继续训练：把“最佳模型”定义清楚

训练停止并不只因为步数用完。常见条件包括验证指标在若干次评估内没有改善、梯度或损失出现非有限值、资源预算耗尽、护栏指标越界，以及达到预设目标。早停的 patience、最小改善量和比较方向必须写进配置；否则不同实验可能用不同的“最佳”定义，结果无法公平比较。

保存 checkpoint 时通常同时保留最近版本与验证集最佳版本。最近版本便于诊断和恢复，最佳版本用于交付；两者可能不同。回滚后要重新评估主指标和护栏，不能只看保存时的一个分数。对于长时间训练，还应定期验证 checkpoint 可读、权重与优化器状态形状一致，并在独立进程中做一次加载测试。

继续训练改变的不只是参数，还可能改变数据顺序、学习率、随机增强和标签版本。若数据或代码发生变化，应把它记录为新实验，而不是覆盖原运行。恢复后第一步可以使用较小学习率或只跑验证，确认状态对齐，再恢复正常更新。模型文件、配置和日志应有同一个运行 ID，方便从指标回到具体权重。

def should_stop(history, patience=3, min_delta=1e-3):
    if not history:
        return False, "没有评估记录"
    if not all(value == value and abs(value) != float("inf") for value in history):
        return True, "验证指标非有限"
    best = min(history)
    recent = history[-patience:]
    if len(recent) == patience and min(recent) >= best - min_delta:
        return True, "patience 用尽"
    return False, "继续"

for scores in ([1.0, .8, .7, .69, .691, .692], [.9, .7, float("nan")]):
    print(should_stop(scores))
# 练习：把“越高越好”的指标改写为同一策略

收敛不是一条漂亮曲线：用对照实验判断更新是否有效

损失曲线下降只是结果，不是原因。为了确认优化器真的在工作，可以固定一个小批次，分别执行一次正向、反向和小步更新，检查更新后的目标是否下降；再把梯度乘以负方向和正方向各走一步，比较哪一边更好。若两边都变差，可能处于噪声、非光滑点或实现有误；若只有大步变差，可能是学习率过大。

学习率搜索应有明确范围和停止规则。对数尺度试探通常比线性尺度覆盖更广；每个候选至少运行相同的更新次数和数据顺序，并记录达到目标所需的步数、最佳验证指标和峰值资源。不要只选择最终 loss 最小的曲线，早期收敛速度、稳定性和推理成本也可能是决策因素。

当训练不稳定时，逐项关闭复杂因素比同时换十个超参数更容易定位：先关闭混合精度，再固定数据顺序，再关闭 dropout，最后换回简单 SGD。每次只改变一个变量，并保留失败日志。若改变一个设置后曲线好看了，要确认收益不是因为有效 batch、梯度归约或随机种子同时被改变。

分布式训练还会改变梯度统计。数据并行需要在设备间聚合梯度，梯度平均还是求和会影响有效学习率；梯度累积与通信频率也会改变噪声。恢复训练时，数据采样器位置、参数分片、优化器状态和调度器步数都要一致。一个单卡可复现的实验，不能直接假设多卡结果在数值和吞吐上完全相同。

def quadratic(theta):
    return sum((value - target) ** 2 for value, target in zip(theta, [1.0, -2.0]))

def gradient(theta):
    return [2 * (value - target) for value, target in zip(theta, [1.0, -2.0])]

theta = [4.0, 3.0]
before = quadratic(theta)
g = gradient(theta)
step = 0.1
candidate = [value - step * direction for value, direction in zip(theta, g)]
opposite = [value + step * direction for value, direction in zip(theta, g)]
print("before=", before, "negative step=", quadratic(candidate), "positive step=", quadratic(opposite))
assert quadratic(candidate) < before < quadratic(opposite)

单步探针可以在没有数据加载器、分布式通信和复杂模型的情况下验证优化方向。把它嵌入真实模型时，保存更新前后的参数摘要和损失；如果梯度方向正确但训练仍不收敛，再查 batch 噪声、条件数、调度器和正则，而不是回到公式本身。

Embedding 是坐标，不是“意义本身”

Embedding 把离散对象映射到连续向量空间。相似文本往往被训练成方向或邻域更接近，但“相似”依赖训练目标、数据、分词、语言和距离度量。余弦相似度忽略向量长度，适合关注方向的检索；点积同时受方向和长度影响，若向量已归一化，两者才在数值上等价。欧氏距离则把向量看成空间中的位置。选择指标是系统设计的一部分，不是数据库的默认细节。

检索管道至少包含四个可检查阶段：文本预处理、Embedding 生成、索引构建和候选排序。任一阶段改变，邻居都可能变化。预处理中的空白、大小写、截断和语言识别会影响向量；模型版本或批处理方式变化会影响数值；索引的距离和 top-k 参数会影响排序。保存一条检索结果时，除了文档 ID 和分数，还应保留查询文本、Embedding 模型版本、归一化方式、索引版本和过滤条件。

高相似度不是事实正确性的证明。两个文档可能共享模板或常见词，却在关键数字上相反；一个问题可能没有真正相关的候选，但系统仍会返回最相近的结果。设置相似度阈值、允许“无合适结果”、展示来源片段并进行人工抽查，能避免把近邻当作答案。评测检索时同时看 Recall@k、MRR、人工相关性和错误类型。

from math import sqrt

dot = lambda left, right: sum(a * b for a, b in zip(left, right))
norm = lambda vector: sqrt(dot(vector, vector))
cosine = lambda left, right: dot(left, right) / (norm(left) * norm(right)) if norm(left) * norm(right) else None

query = [0.8, 0.1, 0.2]; documents = {"A": [0.7, 0.2, 0.1], "B": [-0.1, 0.8, 0.3], "C": [0.6, 0.2, 0.2]}
ranked = sorted(((doc_id, cosine(query, vector)) for doc_id, vector in documents.items()), key=lambda item: item[1], reverse=True)
print(ranked)

示例只在内存中完成排序，真实系统还要处理向量维度不一致、空文本、零向量、索引分页和权限过滤。先用小数据打印全部候选，再接入近似最近邻索引；当结果异常时，优先对比一组固定查询的邻居和分数，而不是只看在线总体指标。

注意力先计算相关性，再按权重混合信息

给定查询矩阵 Q、键矩阵 K 和值矩阵 V，缩放点积注意力的核心形式可以写成 softmax(QKᵀ/√dk)V。QKᵀ 产生每个查询与每个键的相关性矩阵，除以 √dk 降低维度变大时点积方差膨胀的影响，Softmax 把一行分数变成权重，最后用权重对 V 加权求和。每一步都对应前面学过的矩阵乘法、范数/尺度和概率分布。

形状是读懂注意力的钥匙。若序列长度为 n、每头维度为 d，Q、K、V 可写成 (n,d)；K 转置后为 (d,n)，点积得到 (n,n) 的位置关系矩阵；与 V 相乘又回到 (n,d)。批次和多头会增加轴，但内侧维度仍需匹配。注意力掩码把不允许看到的位置设成极小分数，Softmax 后它们的权重接近零。掩码的方向和广播形状错了，代码可能仍运行，却会产生信息泄漏。

注意力权重是当前层在当前输入上的相对分配，不是人类可直接阅读的因果解释。高权重位置可能只是格式、标点或重复模式；不同头、不同层和不同输入的权重会变化。做可解释性实验时要同时看输出变化、遮挡对照和任务指标，不能只截一张热力图下结论。

from math import exp, sqrt

def softmax(values):
    pivot = max(values)
    weights = [exp(value - pivot) for value in values]
    total = sum(weights)
    return [weight / total for weight in weights]

def attention(query, keys, values):
    dimension = len(query)
    scores = [sum(a * b for a, b in zip(query, key)) / sqrt(dimension) for key in keys]
    weights = softmax(scores)
    output = [sum(weight * value[index] for weight, value in zip(weights, values)) for index in range(len(values[0]))]
    return scores, weights, output

q = [1.0, 0.0]; k = [[1.0, 0.0], [0.0, 1.0], [0.7, 0.7]]; v = [[10.0, 0.0], [0.0, 10.0], [5.0, 5.0]]
print(attention(q, k, v))

玩具实现把一个查询与三个键比较，输出是三个值向量的加权混合。把 /sqrt(dimension) 删除，再把维度扩大，观察 Softmax 是否更尖，可以帮助理解缩放项的动机。真实实现还包括批次、多头、掩码、设备和高效内核；先用小矩阵核对数值，再依赖框架。

最后的数学能力是把结论限制在证据里

一个大模型实验可以被写成输入分布、参数配置、目标函数、随机过程和输出指标的组合。输入分布决定你讨论的是哪类样本；参数配置决定模型和推理行为；目标函数决定训练偏好；随机过程决定重复运行的波动；指标决定什么算成功。任何一项没有记录，别人就难以复现或解释差异。把公式写成字段和表格，是从课堂练习走向工程的关键一步。

指标要和问题成对出现。生成质量不能只看困惑度，检索不能只看平均相似度，分类不能只看准确率，训练稳定性不能只看最后 loss。为每个主指标指定分母、方向、样本范围和失败处理，再补充一个能揭示风险的护栏指标。若指标冲突，先说明优先级和决策规则，不要在结果出来后挑最有利的一项。

最小可复现实验应包含：版本化输入、固定或记录随机种子、明确环境、可运行入口、结构化日志、模型/索引检查点、评测脚本和一份结果摘要。摘要里不只写最终数字，还要保留关键中间量的范围、形状和非有限计数。发生失败时保存错误信息和已完成步骤，避免把失败运行从历史中抹掉。数学直觉最终要落到这种可审计的行为上。

项目的评分重点不是代码长短，而是职责是否清楚：至少拆出“计算向量指标”“估计梯度”“计算分布损失”“执行注意力”四个函数；不要把所有逻辑写在一个循环里。每个函数都要有输入形状、返回结构和边界行为。完成后检查 JSON 是否能被再次读取，图表是否能从同一输入重新生成，报告中的数字是否能由代码复算。

从 token 到向量：Embedding 不是词典，而是可训练的坐标系

Tokenizer 先把文本切成 token，再把 token 映射成整数 id；Embedding 表把每个 id 查成一个向量。id 本身只是索引，不能拿来计算“词 100 比词 20 更接近”。真正可比较的是向量空间中的距离或夹角，而且相似性依赖训练目标、语料和层的位置。输入 Embedding、位置表示和上下文混合后的隐藏状态，语义会随着层数逐步变化，不能把某一层的坐标当成固定词义。

词表大小、向量维度、特殊 token 和分词规则会共同决定模型的输入接口。更换 tokenizer 会改变序列长度、未知词处理和困惑度分母，不能只替换词表文件。中文、代码、数字、表情和混合语言应分别做覆盖测试；长文本还要验证截断策略，避免把关键指令静默截掉。训练与推理必须使用同一套 tokenizer 版本和规范化规则。

检索中的余弦相似度只比较方向，不比较长度；点积同时受方向和范数影响。若向量范数携带了置信度或频率信息，归一化可能丢掉有用信号；若范数主要反映文档长度，点积会偏向长文档。选择相似度前要用标注查询集验证，并报告召回率、延迟、索引大小和长尾查询，而不是只展示几个“相似句子”。

Embedding 的可视化也有陷阱。降维算法会改变局部距离和全局结构，二维图只能辅助观察，不能证明高维空间真实呈现某种语义边界。应配合近邻一致性、跨域检索、分群指标和随机种子复现。对隐私敏感数据，向量仍可能保留可识别信息，不能因为它看起来像一串浮点数就忽略访问控制。

import math

def cosine(left, right):
    if len(left) != len(right):
        raise ValueError("向量维度不一致")
    numerator = sum(a * b for a, b in zip(left, right))
    denominator = math.sqrt(sum(a * a for a in left)) * math.sqrt(sum(b * b for b in right))
    if denominator == 0:
        raise ValueError("零向量没有方向")
    return numerator / denominator

query = [1.0, .2, .0]
documents = {"A": [1.0, .1, .0], "B": [.0, .8, .4], "C": [-.5, .0, .2]}
ranking = sorted(((cosine(query, vector), name) for name, vector in documents.items()), reverse=True)
print(ranking)
# 练习：给 query 与每个文档加同一倍数，比较余弦与点积排序

在真正的向量数据库中，还要考虑索引近似带来的召回损失、更新延迟、元数据过滤和权限隔离。先用暴力搜索建立小数据集基线，再替换为近似索引；如果结果变化，才能区分是 Embedding、相似度还是索引参数造成的。查询日志应脱敏，评估集不能直接来自线上用户的答案回流，否则会形成隐性测试泄漏。

注意力把相似度变成条件计算：每个位置都在重新选择上下文

缩放点积注意力可以写成 softmax(QKᵀ/√d_k)V。Q 表示当前查询想找什么，K 表示各位置提供什么线索，V 是真正被加权汇总的内容。QKᵀ 给出每个 query-key 配对分数，除以 √d_k 控制维度增大时点积方差，Softmax 把分数变成一行一和的权重。这个公式没有“记忆检索”的魔法，只有投影、点积、归一化和加权求和。

多头注意力把隐藏维拆成多个子空间，让不同头学习不同关系；头之间仍共享同一批 token，却使用不同的 Q/K/V 投影。实现时要检查 reshape 前后的元素总数、head_dim 是否整除 hidden_dim，以及合并头的顺序是否恢复。把 view 当成免费转置或在非连续张量上直接重排，可能得到形状正确但语义错位的结果。

因果掩码只允许位置看到自己和之前的位置，padding 掩码则屏蔽无效 token；二者的广播形状和加法位置不同。常见实现把无效位置的分数加上一个很大的负值，但必须避免整行全被屏蔽导致 Softmax NaN。训练与生成阶段的 mask、KV cache 和位置偏移要分别测试，不能因为短序列输出正常就假设长序列正确。

注意力的全连接分数矩阵让序列长度带来近似二次的时间和显存开销。长上下文方案可能使用滑动窗口、稀疏模式、低秩近似或线性注意力，但改变了可见范围和误差结构。比较方案时要同时报告长度、batch、硬件、dtype、吞吐、峰值显存和质量指标；只报一个速度数字会掩盖计算预算的转移。

import math

def softmax(values):
    peak = max(values)
    weights = [math.exp(value - peak) for value in values]
    total = sum(weights)
    return [weight / total for weight in weights]

def attention(query, keys, values):
    if len(keys) != len(values):
        raise ValueError("keys 与 values 数量不一致")
    depth = len(query)
    scores = [sum(a * b for a, b in zip(query, key)) / math.sqrt(depth) for key in keys]
    weights = softmax(scores)
    return [sum(weight * value[i] for weight, value in zip(weights, values))
            for i in range(len(values[0]))], weights

context, weights = attention([1.0, 0.0], [[1.0, 0.0], [0.0, 1.0]], [[2.0, 0.0], [0.0, 3.0]])
print("context=", context, "weights=", weights, "sum=", sum(weights))
assert abs(sum(weights) - 1.0) < 1e-12
# 练习：加入一个 mask，禁止 query 看到第二个 key

玩具实现每次只处理一个 query，故意省略批次和多头，以便手算权重。扩展到张量时，先保留一个同样的单 query 回归测试，再逐步加入 batch、head、mask 和 cache。官方框架的融合注意力会在内部优化内存访问，但输出仍应满足权重归一、屏蔽位置不贡献和形状契约。

把数学实验升级为大模型实验协议

一个可信的小实验至少要有问题、假设、变量、基线、指标和停止条件。问题要具体到“改变温度是否改善校准”或“截断 rank=4 对召回损失多少”，而不是泛泛地问“哪个模型更好”。假设写出预期方向与可能反例；变量区分自变量、控制变量和结果变量；基线是能够独立复现的简单方案。

指标要和决策对应。检索实验需要 Recall@k、MRR、延迟和索引成本；生成实验除了 loss 或困惑度，还要检查事实性、格式遵循、拒答、安全和人工偏好；训练稳定性要看梯度、峰值显存、吞吐、checkpoint 恢复和多次种子的方差。指标越多，越要预先写清主指标、护栏指标和统计汇总方式，避免挑对自己有利的结果。

实验日志不是最后补的截图，而是数据管道的一部分。每次运行保存配置、代码版本、数据快照、tokenizer、环境、硬件、随机种子、耗时、异常和评估集哈希。随机实验至少运行多个种子并报告均值和离散程度；若预算只能跑一次，要在结论中明确不确定性，不把单次结果写成定律。

最终报告应能回答四个问题：改了什么、为什么改、证据是什么、还不知道什么。把失败实验和边界条件一起保留，后续学习者才能知道公式何时适用。对于第三方实现，应链接官方文档并注明版本；对于自己绘制的图表，保留生成数据与脚本，确保图不是不可追溯的装饰。

from dataclasses import dataclass, asdict
import json

@dataclass
class ExperimentCard:
    question: str
    hypothesis: str
    baseline: str
    primary_metric: str
    guardrails: tuple
    seed: int
    data_version: str

card = ExperimentCard(
    question="温度 0.8 是否改善校准？",
    hypothesis="降低温度会降低过度自信，但可能损失召回",
    baseline="原始 logits，温度 1.0",
    primary_metric="ECE",
    guardrails=("Recall@5", "P99 latency", "NaN count"),
    seed=7,
    data_version="eval-2026-08-01",
)
with open("experiment-card.json", "w", encoding="utf-8") as handle:
    json.dump(asdict(card), handle, ensure_ascii=False, indent=2)
print("card saved")
# 练习：加载 JSON，检查主指标和护栏是否都已填写

这张实验卡把数学对象、工程变量和决策证据放到同一个接口里。它不会自动保证结论正确，却能防止“跑完以后才想起基线、分母和随机种子”。完成本章后，应该能独立解释一个公式、写出一个最小实现、列出边界条件、设计一个对照实验，并用表格或图形把结果交代清楚。