M24：把 TypeScript Attention 映射到 PyTorch 张量操作

内容类型：预习教材（不代表已完成）
日期：2026-09-16
阶段：P1 · AI Model Engineering 90
周次：W4 · Transformer 第一性原理
节奏：周三引导练习
状态：教材已备；学习未完成
标签：TypeScript、PyTorch、Attention、张量映射、实现对照

一句话定义

实现映射是把两种语言中不同的数据结构和循环写法还原为同一组数学张量变换，并逐层确认输入、轴与不变量。

学习目标

1. 从现有 TypeScript 实现识别 Q/K/V、score、mask、softmax 与 output。
2. 将显式循环对应到 PyTorch matmul、transpose 和 broadcasting。
3. 对同一固定输入比较关键中间张量，而不是只比较最终输出。
4. 识别数组布局、索引顺序和数值容差造成的差异。

核心知识

TypeScript 教学实现常用嵌套数组和 for 循环，明确遍历 token、head 和 channel；PyTorch 把同一运算批量化为张量算子。循环的 sum_k q[i][k]*key[j][k] 对应 Q @ K.transpose(-2,-1)。对每个 query 行做稳定 softmax，对应 softmax(scores, dim=-1)。对 value 的加权循环对应 weights @ V。

语言不同不等于算法不同。映射表应包含数学式、TypeScript 变量/循环、PyTorch 表达式、输入 shape、输出 shape、检查项。先对照单头、无 batch，再理解现有实现如何展平或嵌套 heads。

softmax 的稳定实现通常先减去行最大值，再指数化并归一化。TypeScript 若手写此步骤，而 PyTorch 使用内置函数，理论结果相同但浮点舍入会有微小差异。比较时使用合理绝对/相对容差，不能要求所有平台逐位相等。

机制与映射方法

使用固定的微型输入和固定权重，按以下检查点保存：X、Q、K、V、unscaled scores、scaled scores、masked scores、weights、output。第一个不一致点才是最有价值的定位位置；只比较 output 会让前面误差彼此抵消或累积。

若 TypeScript 使用行主数组 [T][D]，PyTorch 同样设 [T,D] 可减少转换。若现有实现是 [head][token][dim] 而 PyTorch 为 [B,H,T,D]，必须显式写轴映射。不要依据变量名猜 shape，应从索引访问和长度验证。

最小练习

1. 阅读现有 transformer.ts 中 attention 相关路径，只标注，不重构。
2. 建立六列映射表：步骤、公式、TS、PyTorch、shape、不变量。
3. 选择 T=2 或 3 的同一输入与权重，计划导出各中间张量。
4. 比较第一个差异点；未运行前保留结果栏为空。
5. 对照已有测试，说明它覆盖的是 shape、数值还是因果属性。

常见误区

• 看到嵌套循环就认为和矩阵 attention 不同。
• transpose 错轴但尺寸碰巧可乘，产生语义错误。
• TS 与 PyTorch 初始化权重不同，却比较最终输出。
• 浮点末位差异被当作算法不一致。
• 测试只断言数组长度，未覆盖 mask 与 softmax 方向。

场景连接

模型系统常在 Python 训练、TypeScript 应用层运行近似逻辑或教学模拟。准确的实现映射能帮助产品与架构背景学习者越过语言表象，关注数据形状、数值契约和可验证边界。

自检问题

1. 双重循环的 q·k 如何映射为矩阵乘法？
2. 为什么要找第一个中间张量差异？
3. 绝对容差与相对容差分别适合什么数值情况？
4. 一个完整 causal attention 测试应覆盖哪些属性？

专业课程对齐

• PyTorch Tutorials：对应 tensor、matmul、transpose、broadcasting 与数值比较，是 TypeScript 数组循环迁移到张量运算的主参照。
• Stanford CS336：对应 attention/Transformer 的从零实现，帮助确定批次、头、序列和通道轴的标准布局。
• Stanford CS224N：对应 attention 公式，用来保证语言迁移没有改变算法语义。

深入学习提示

先以 CS224N 公式建立语言无关的规范，再按 CS336 确定 shape，最后精读 PyTorch 张量操作。给 TypeScript 每个显式循环标注求和轴：QK 点积对应最后一维收缩，score×V 对应 key 位置聚合；再用同一固定输入逐项比较 Q、K、V、scores、masked scores、weights 和 output。公式观察索引写法 s_{ij}=q_i·k_j/√d，防止把 i/j 或 transpose 颠倒。反例包括 JS row-major 直觉映射错轴、广播静默复制、softmax 维度选成 query 轴、mask 布尔意义相反、float64 与 float32 容差不当。阅读顺序完成后应得到一张“循环—einsum/matmul—shape”对照表，而非只保留最终输出相近的断言。

学后填写区

• 实现映射表位置：____
• 同一输入定义：____
• 第一个实际差异点：____
• 测试覆盖缺口：____
• 实际学习日期与用时：____