no-magic 中文版

no-magic 项目的中文翻译版本。

原始项目包含 30 个单文件、零依赖的 Python 实现，涵盖了驱动现代 AI 的核心算法。每个脚本都是一个完整的、可运行的程序——从零开始训练模型并执行推理，无框架、无抽象、无隐藏复杂度。

本项目将所有注释、文档字符串和文档翻译为中文，代码逻辑保持不变。

快速开始

# 克隆项目（包含 upstream 子模块）
git clone --recursive https://github.com/YOUR_USERNAME/no-magic-zh.git
cd no-magic-zh

# 运行任意脚本
python 01-foundations/microgpt.py

无需虚拟环境，无需安装依赖。

项目结构

no-magic-zh/
├── upstream/              # 原始英文项目（git submodule，只读参考）
├── scripts/
│   ├── translate.py       # AI 翻译脚本
│   └── sync.sh            # upstream 同步辅助脚本
├── glossary.json          # 术语表（保证翻译一致性）
├── .translation-state.json  # 翻译状态跟踪
│
├── 01-foundations/        # 基础算法（11 个脚本）
│   ├── microgpt.py        #   GPT — 自回归语言模型
│   ├── microbert.py       #   BERT — 双向编码器
│   ├── microtokenizer.py  #   BPE 分词器
│   ├── microembedding.py  #   词嵌入
│   ├── microconv.py       #   卷积神经网络
│   ├── micrornn.py        #   RNN 与 GRU
│   ├── microgan.py        #   生成对抗网络
│   ├── microvae.py        #   变分自编码器
│   ├── microdiffusion.py  #   扩散模型
│   ├── microrag.py        #   RAG 检索增强生成
│   └── microoptimizer.py  #   优化器对比
│
├── 02-alignment/          # 对齐与训练技术（9 个脚本）
│   ├── microlora.py       #   LoRA 低秩适配
│   ├── microqlora.py      #   QLoRA 量化低秩适配
│   ├── microdpo.py        #   DPO 直接偏好优化
│   ├── microppo.py        #   PPO 近端策略优化
│   ├── microgrpo.py       #   GRPO 组相对策略优化
│   ├── microreinforce.py  #   REINFORCE 策略梯度
│   ├── micromoe.py        #   混合专家模型
│   ├── microbatchnorm.py  #   批归一化
│   └── microdropout.py    #   Dropout 正则化
│
├── 03-systems/            # 系统与推理优化（10 个脚本）
│   ├── microattention.py  #   注意力机制变体
│   ├── microflash.py      #   Flash Attention
│   ├── microkv.py         #   KV 缓存
│   ├── micropaged.py      #   PagedAttention 分页注意力
│   ├── microrope.py       #   RoPE 旋转位置编码
│   ├── microquant.py      #   模型量化
│   ├── microbeam.py       #   束搜索
│   ├── microcheckpoint.py #   梯度检查点
│   ├── microparallel.py   #   模型并行
│   └── microssm.py        #   状态空间模型
│
└── README.md              # 本文件

翻译工作流

前置准备

1. 运行初始化脚本：

bash setup.sh

2. 配置 AI 翻译 API（复制 .env.example 为 .env 并填写）：

cp .env.example .env
# 编辑 .env 填写 API 配置

支持所有 OpenAI 兼容 API：OpenAI、DeepSeek、Moonshot、本地 Ollama 等。

翻译命令

# 翻译所有文件
python scripts/translate.py all

# 查看翻译状态
python scripts/translate.py status

# 查看哪些文件需要更新
python scripts/translate.py diff

# 增量翻译（仅翻译有变更的文件）
python scripts/translate.py sync

# 翻译指定文件
python scripts/translate.py file 01-foundations/microgpt.py

跟踪上游更新

当原始项目有更新时：

# 一键检测上游变更
bash scripts/sync.sh

# 执行增量翻译
python scripts/translate.py sync

翻译原则

• 只翻译注释和文档：代码逻辑、变量名、函数名保持英文不变
• 术语一致性：通过 glossary.json 统一专业术语翻译
• 保留英文原文：专业术语采用"中文（英文）"格式，如"注意力机制（Attention）"
• 代码可运行：翻译后的每个脚本仍然是合法的、可运行的 Python 代码

致谢

• 原始项目：no-magic by Mathews-Tom
• 许可证：MIT