修复 RoPE 多频率实验中角度变化的描述 (#8)

[joyehuang]

概述

修复 #8: 改进 exp2_multi_frequency.py 中 demonstrate_multi_frequency 函数的观察说明，使描述更准确清晰。

问题分析

原问题

Issue #8 指出：

• 代码"报告不同维度的角度变化错误"
• RoPE 在嵌入维度上的转动速度是逐渐变慢的
• RoPE 在 token 维度上的转动速度是逐渐变快的（对于高频维度）

代码问题

原代码第 67-70 行的观察说明：

print("\n💡 观察:")
print("  - 维度0（高频）：位置10就转了100度，变化快")
print("  - 维度3（低频）：位置1000才转了0.1度，变化慢")
print("  - 不同维度组合 → 唯一标识每个位置！")

问题：

• 只描述了沿 token 维度（纵向）的角度变化
• 缺少沿嵌入维度（横向）的角度变化说明
• 没有明确表格的两个维度各自的含义

解决方案

修改后的观察说明

print("\n💡 观察（理解这个表格的两个维度）:")
print("  【纵向看 - 沿 token 维度】：")
print("    - 维度0（高频）：随位置增加，角度变化快")
print("      例如：位置10就转了100度")
print("    - 维度3（低频）：随位置增加，角度变化慢")
print("      例如：位置1000才转了0.1度")
print()
print("  【横向看 - 沿嵌入维度】：")
print("    - 从维度0到维度3：频率递减，转动速度逐渐变慢")
print("      例如：在位置1000，维度0转了很多圈，维度3才转0.1度")
print()
print("  【结论】：不同维度组合 → 唯一标识每个位置！")

改进点

1. 明确两个方向：

   • 纵向（沿 token 维度）：位置增加时的角度变化
   • 横向（沿嵌入维度）：不同维度的频率递减

2. 更清晰的标题：

   • 使用【】标记区分不同方向
   • 明确"沿 token 维度"和"沿嵌入维度"

3. 具体示例：

   • 保留原有示例，增加新的横向观察示例
   • 帮助学习者理解表格的二维结构

技术说明

RoPE 的双向特性

表格展示了 角度 = 位置 × 频率[维度] 的二维关系：

方向	变化规律	原因
嵌入维度（横向）	频率递减，转动速度变慢	freqs[i] = 1 / (rope_base ^ (2i / dim))
token 维度（纵向）	高频维度增速快，低频维度增速慢	angle = pos × freq[i]

为什么这样设计？

• 高频维度：编码局部位置（相邻几个 token）
• 低频维度：编码全局位置（整篇文档）
• 多频率组合：每个位置有唯一的"编码指纹"

测试

• 代码修改仅涉及输出文本，不影响功能
• 描述更准确地反映 RoPE 的数学原理
• 帮助学习者理解表格的二维结构

相关 Issue

Closes #8

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
minimind-notes	Ready	Preview, Comment	Feb 16, 2026 5:46am

[claude]

PR 代码审查

总体评估：这个 PR 针对教学材料中的描述准确性进行了有价值的改进，方向正确。以下是详细反馈：

---

优点

1. 问题识别准确：PR 正确地识别了原始代码只描述了单一维度（纵向 token 维度）而忽略了横向嵌入维度的问题。

2. 教学价值提升：修改后的版本通过【纵向看】和【横向看】的结构化分组，帮助学习者更系统地理解 RoPE 的二维特性，符合仓库的教学目标。

3. 变更范围克制：修改仅限于输出文本，不影响任何计算逻辑，降低了引入 bug 的风险。

---

潜在问题

横向示例的准确性存疑

新增的横向观察说明：

print('      例如：在位置1000，维度0转了很多圈，维度3才转0.1度')

这句话与纵向观察中已有的示例（"位置1000才转了0.1度"）重复，但表述目的不同——纵向说的是低频维度在位置1000只转0.1度，横向说的是同一位置下，高频维度转了很多圈而低频只转0.1度。两处描述的数字相同但角度不同，容易让学习者混淆。

建议：横向示例最好提供一个具体的对比数字，例如：

print('      例如：在位置1000，维度0转了约955圈，维度3仅转了0.1度')

（具体数值应由实际计算得出，建议运行代码验证后填入）

---

小建议

"很多圈" 的表述不够精确：对于追求准确性的教学材料，"转了很多圈" 是定性描述，改为实际计算出的近似值会更有说服力，也更符合仓库中理解数学原理的学习目标。

---

技术说明验证

PR 描述中的 RoPE 公式 freqs[i] = 1 / (rope_base ^ (2i / dim)) 正确，表格的二维分析也符合 RoPE 的数学原理。

---

结论

修改的方向和结构是正确的，核心改进有效。建议在合并前：

• 验证横向示例中维度0转了很多圈的实际数值，替换为具体数字，避免与纵向描述产生混淆
• 可选：运行代码确认新输出的可读性和行对齐效果

整体上这是一个有价值的教学内容改进。

[claude]

PR Review: 修复 RoPE 多频率实验中角度变化的描述

总体评价

这个 PR 的方向是正确的——确实需要从两个维度来解释 RoPE 的频率特性，而原代码只描述了纵向（token 维度）。补充横向（嵌入维度）的解释是有价值的改进。

---

问题 1：数值示例存在事实错误（继承自原代码）⚠️

第72行的说明：

print("      例如：从位置0到位置1000，角度仅变化约0.1度")

这个数值是不正确的。使用 MiniMind 的实际参数（rope_base=1000000, head_dim=64）计算：

• freqs[3] = 1 / (1000000 ^ (6/64)) ≈ 0.274 rad/token
• 位置1000的角度 = 1000 × 0.274 × (180/π) ≈ 15699°，即转了约 43.6 圈

代码中用 % 360 显示的结果是 ~159°，而不是 0.1 度。

这个错误在原代码（第67-70行）中就存在，PR 保留了它。建议修正为准确的描述，例如：

print("    - 维度3（低频）：随位置增加，角度变化相对较慢")
print("      例如：频率为维度0的约1/4，转一圈需要约23个token（维度0只需6.3个）")

---

问题 2：横向示例的精确度（小问题）

第78行：

print("                        维度3约每25个token转一圈（约4倍慢）")

实际计算值约为 22.9 个 token，说"约25个"稍有偏差（误差约9%）。更精确的表述可以是"约23个"，或保持"约25个"但说明这是近似值。

---

代码质量

• ✅ 修改仅涉及 print 输出文本，不影响任何计算逻辑，风险低
• ✅ 双括号格式（【纵向看】/【横向看】/【结论】）与文件整体风格一致
• ✅ PR 描述详尽，技术说明清晰
• ✅ 改进了原代码对二维结构描述不完整的缺陷

---

建议

核心建议是修正第72行的数值示例（0.1度 → 实际是多圈旋转），以避免对学习者产生误导。这个文件的教学目的是帮助理解 RoPE，错误的数值会造成困惑。

其余改动是有益的，补充横向（嵌入维度）的解释填补了原说明的空白。

[claude]

PR 审查意见

总体评价

这个 PR 修复了 Issue #8 提出的问题，改进方向是正确的。原代码只描述了纵向（沿 token 维度）的角度变化，确实缺少横向（沿嵌入维度）的说明。

---

✅ 优点

1. 问题分析准确：PR 描述中对 Issue [BUG] #8 的分析是正确的 —— RoPE 在嵌入维度上频率递减（转动变慢），在 token 维度上高频维度随位置增加变化更快。

2. 结构改进明显：使用【纵向看】和【横向看】两个维度分开描述，比原来的单一列表更有教学价值，符合仓库"深度理解"的学习风格。

3. 保留了结论："不同维度组合 → 唯一标识每个位置！" 这句核心结论被保留，且改成了【结论】标签，层次更清晰。

---

⚠️ 需要关注的问题

1. 数值说明有潜在不准确之处

位置10，维度0的角度变化：
原代码描述为"位置10就转了100度"，新代码改为"从位置0到位置10，角度变化约100度"。

根据 MiniMind 的实际参数（rope_base=1000000.0, head_dim=64）：

• 频率0 = 1 / (1000000^(0/64)) = 1.0 rad/token
• 位置10的角度 = 10 × 1.0 × (180/π) ≈ 572.96° → 取模 360° ≈ 212.96°
• 位置0的角度 = 0°
• 实际角度差 ≈ 213°，不是"约100度"

原始代码的"100度"就已经不准确，这个 PR 沿用了这个不准确的值。建议修正为实际计算结果，或改用更通俗的描述（如"变化超过180度"或"已转了超过半圈"）。

2. "约23个token转一圈"的说明

新代码说"维度3约每23个token转一圈（维度0只需6.3个）"。

• 维度0的频率 = 1 / (1000000^(0/64)) = 1.0 → 每 6.28 个token转一圈 ✅（约6.3，正确）
• 维度3的频率 = 1 / (1000000^(6/64)) ≈ 0.272 → 每 23.1 个token转一圈 ✅（约23，正确）
• "约4倍慢"的说法也正确（23.1 / 6.28 ≈ 3.68 倍）

这部分数值是准确的。

3. 说明与表格数据的一致性

代码在第60行计算角度时用了 % 360 取模，所以表格中显示的是已取模的角度（0°~360°范围内）。但新增的观察说明中描述"角度变化"时，读者可能会用表格中取模后的值来验证，导致数字对不上。

建议：在说明中提示读者"表格中的角度已对360°取模，要看变化趋势需关注频率大小，而不是直接做差"。

---

💡 改进建议

建议1：修正"100度"的描述，使其与实际计算一致：

# 当前（不准确）
print("      例如：从位置0到位置10，角度变化约100度")

# 建议改为
print("      例如：从位置0到位置10，角度变化超过180度（高频，快速旋转）")

建议2：在横向说明中增加对表格的直接引导，帮助读者更自然地联系上面的输出：

# 当前
print("      例如：观察表格中任意一行（同一位置），从左到右频率递减")

# 建议改为
print("      例如：在同一位置（纵向同一行），从维度0到维度3，角度数值越来越小")

---

📋 总结

评估维度	结论
修复方向	✅ 正确，确实补充了缺失的横向维度说明
结构清晰度	✅ 明显改善
数值准确性	⚠️ "约100度"不准确（实际≈213°），其余数值正确
教学效果	✅ 改进后更有助于理解 RoPE 的二维特性
代码逻辑	✅ 仅修改输出文字，不影响任何功能

核心问题是"角度变化约100度"这个数值描述与实际计算不符，建议修正后再合并。其余修改都是有价值的改进。

[claude]

PR Review: 修复 RoPE 多频率实验角度描述 (#17)

Overall assessment: This is a solid improvement to the educational content. The fix correctly identifies and addresses a real conceptual gap in the original observations section.

---

What's Done Well

Accuracy improvement: The original code only described angle changes along the token dimension (vertical). This PR correctly adds the missing horizontal dimension (embedding dimension), making the explanation complete and technically accurate.

Concrete examples preserved: The PR keeps the existing concrete examples while adding new ones for the embedding dimension. This maintains the hands-on learning style.

Important clarification added: The note about modulo 360 degrees is a genuinely useful addition. Without this, learners seeing 213 degrees instead of 573 degrees would be confused.

---

Issues and Suggestions

1. Factual accuracy concern: hardcoded numbers need verification

The new code includes comments like "频率约为维度0的1/4，转一圈需要约23个token（维度0只需6.3个）" and "约4倍慢".

These numbers should be verified against the actual frequency calculation in the experiment. For a typical RoPE with rope_base=10000 and dim=8 (4 pairs), the frequency for dimension index 3 is 1 / (10000^(6/8)) = 1/1000 approx 0.001. One full rotation requires 2pi / 0.001 approx 6283 tokens, not 23. The "约4倍慢" ratio also depends entirely on which dimensions are being compared.

Recommendation: Before merging, run the experiment and check the actual printed frequency table to confirm "约23个token", "6.3个token", and "约4倍慢" are accurate. The output must match what the code actually computes, or learners will get the wrong intuition.

2. Visual alignment fragility in continuation print lines

The second line in this pair attempts visual alignment with the first:

print("      参考上面的频率表：维度0每6.3个token转一圈，")
print("                        维度3约每23个token转一圈（约4倍慢）")

This alignment depends on terminal font and may not render correctly everywhere. Consider making each line self-contained, or use a single print with newline escape.

3. Minor: trailing blank line

Consider adding a blank print() after the conclusion line for consistent visual separation with the rest of the function output.

---

Code Quality

The change is purely to print statements with no logic changes — the risk surface is minimal. The PR correctly notes this is text-only. The fix is well-scoped and does not introduce unrelated changes.

---

Summary

Category	Assessment
Correctness of core fix	Both dimensions now explained
360 degree modulo clarification	Good addition
Hardcoded numbers accuracy	Needs verification against actual experiment
Code risk	Text-only, no logic impact
Educational value	Improved clarity

Recommended action: Verify the specific numbers ("约23个token", "6.3个token", "约4倍慢") against the actual computation before merging. If confirmed correct, this PR is ready to merge.

[claude]

PR Review: 修复 RoPE 多频率实验中角度变化的描述

This PR correctly addresses Issue #8 by expanding the observation section of demonstrate_multi_frequency() to describe both dimensions of the angle table.

What's Good

Correctness of the fix: The core issue was that the original code only described the vertical (token dimension) angle change without explaining the horizontal (embedding dimension) frequency decrease. The new explanation correctly addresses both:

• Vertical: angle changes fast for dim0 (high-freq), slow for dim3 (low-freq) as position increases
• Horizontal: frequency decreases from dim0 → dim3 (dim0 is ~4x faster than dim3)

Mathematical accuracy: I verified the numerical claims in the PR:

• dim0 tokens per circle ≈ 6.3 ✓ (2π / freqs[0] = 2π / 1.0 ≈ 6.28)
• dim3 tokens per circle ≈ 23 ✓ (freqs[3] = 1/1000000^(6/64) ≈ 0.274, giving 2π/0.274 ≈ 22.9)
• Position 10, dim0: raw angle ≈ 573°, display 213° (mod 360) ✓
• The ratio claim (dim3 is ~1/4 speed) is directionally correct (actual ratio ≈ 0.274)

Added mod-360 note: The new 【注意】 line clarifying that displayed angles are mod 360° is a good addition — it prevents learners from being confused by why position 1000 doesn't show huge angles.

Issues and Suggestions

1. Minor inaccuracy: "频率约为维度0的1/4" (line 74 in new code)

The actual frequency ratio of dim3 to dim0 is 1/1000000^(6/64) ≈ 0.274, which is closer to 1/3.65, not exactly 1/4. Saying "约为维度0的1/4" is misleading. A more accurate phrasing would be 「频率约为维度0的27%，约慢约4倍」or simply remove the 1/4 claim and rely on the concrete numbers already provided (6.3 vs 23 tokens per circle).

2. Structural consistency with other observation blocks

The existing observation block later in the file (lines 170-173, visualize_position_encoding) and the first observation block (lines 40-43) use a simpler bullet-point style. The new block introduces 【】-bracketed headers which are clearer and more structured — consider applying the same style to those other blocks for consistency.

3. The trailing empty print() (line 85)

A trailing blank print() was added after the conclusion. The original code didn't have this before the function-ending blank line, so it adds an extra blank line in the output. Minor but worth noting.

4. Test coverage

Per the PR checklist: "代码修改仅涉及输出文本，不影响功能" — this is accurate. However, there are no automated tests for the output text, so regressions would only be caught by running the script manually. This is acceptable given the educational nature of the repo, but worth noting.

Summary

The fix is correct and meaningful — it properly addresses the reported issue and improves the pedagogical value of the experiment by explaining both axes of the angle table. The mathematical claims are accurate. The main concern is the "1/4" approximation which overstates the simplicity; the actual ratio is ~1/3.65. Everything else is solid.

Verdict: Approve with the minor suggestion to adjust or remove the imprecise "1/4" claim.

[claude]

PR Review: 修复 RoPE 多频率实验中角度变化的描述

整体评价：这个 PR 解决了一个真实的教学问题，改进方向正确。以下是详细的反馈。

---

正面评价

1. 方向正确：原版只描述了纵向（沿 token 维度）的角度变化，缺少横向（沿嵌入维度）的说明。增加 【横向看】 部分填补了这个教学空白。

2. 取模说明是亮点：【注意】表格中的角度已对360°取模 这一提示非常有价值，帮助学习者避免对表格中数值的误解。

3. PR 描述清晰：Issue 分析、解决方案、技术说明写得很完整，技术背景的 Markdown 表格尤其清楚。

---

潜在问题

1. 具体数值可能不准确（需验证）

第 72 行：

print("      例如：位置10时累计旋转约573度（表中显示213°是取模后的结果）")

这些数值是针对 rope_base=1000000.0、head_dim=64 的具体计算结果。建议运行脚本确认实际输出确实是 213°，否则这个 具体示例 反而会误导学习者。可以用如下方式验证：

import math
head_dim = 64
rope_base = 1000000.0
freq0 = 1.0 / (rope_base ** (0 / head_dim))
angle = 10 * freq0 * 180 / math.pi
print(f"Raw: {angle:.1f}, Mod360: {angle % 360:.1f}")

2. 硬编码具体数值的维护风险

第 82 行：

print("        - 维度3约每23个token转一圈（约4倍慢）")

代码已经在第 32-38 行动态计算并打印了所有频率，但这里把 "23个token" 和 "4倍" 硬编码在注释字符串里。如果以后 head_dim 或 rope_base 参数改变，这些数字会变得不一致，但代码仍能运行，不会有任何报错提示。

建议：要么完全依赖动态输出、不写具体数字，要么把这些数字动态计算：

# 在函数顶部计算好
tpc0 = 2 * math.pi / freqs[0]
tpc3 = 2 * math.pi / freqs[3]
ratio = tpc3 / tpc0
# 然后在 print 中引用
print(f"        - 维度0每{tpc0:.1f}个token转一圈")
print(f"        - 维度3约每{tpc3:.1f}个token转一圈（约{ratio:.1f}倍慢）")

3. 新增描述和上方已有描述的重复

第 40-43 行（上方已有）：

print("  - 高频率（频率0）：每 6.3 个token转一圈 → 编码局部位置")

第 81-82 行（新增）：

print("        - 维度0每6.3个token转一圈")
print("        - 维度3约每23个token转一圈（约4倍慢）")

"维度0每6.3个token转一圈" 与上方第40行几乎完全重复。可以用 参考上面的频率表 替代（当前代码已有这个引用），去掉重复的具体数字，或者把引用改为 请看上面打印的频率表。

---

次要意见

• 第 85 行新增了一个空白 print()，与函数末尾的结构保持一致即可，无大问题。
• PR 描述中的示例数字（"位置1000才转了0.1度"）来自原代码，但现在代码里已删掉了这个说法，PR 描述保留此旧例仅作对比说明，不影响代码本身。

---

总结

类别	评估
教学价值	✅ 显著改进，双维度解释很必要
正确性	⚠️ 请验证硬编码数值（573度、213°、23个token）是否准确
可维护性	⚠️ 硬编码数字存在与参数不同步的风险
代码质量	✅ 修改范围小且纯文本，无逻辑风险

建议合并前验证一下具体数值，或者将具体数字改为动态计算。其余内容质量良好，值得合并。