需要自托管 ML 编码练习与即时判题时：用 Pyre…

在本地或 Docker 自托管 Pyre Code，练习、扩展 ML 编码题并通过 FastAPI 判题服务获得即时反馈。

适用场景

解决思路

1. 安装方式 A（推荐一行命令）：运行 `git clone https://github.com/whwangovo/pyre-code.git`，`cd pyre-code`，`./setup.sh`，`npm run dev`；`setup.sh` 会创建 `.venv`（优先 `uv`，回退 `python3 -m venv`），安装所有 Python 依赖，然后打印启动命令。
2. 安装方式 B（Conda）：运行 `git clone https://github.com/whwangovo/pyre-code.git`，`cd pyre-code`，`conda create -n pyre python=3.11 -y && conda activate pyre`，`pip install -e ".[dev]"`，`npm install`，`npm run dev`。
3. 安装方式 C（Docker）：运行 `git clone https://github.com/whwangovo/pyre-code.git`，`cd pyre-code`，`docker compose up --build`；进度持久化在 Docker volume，用 `docker compose down -v` 重置。
4. 安装后访问：判题服务 `http://localhost:8000`，Web 应用 `http://localhost:3000`。
5. 项目结构：`web/` 是 Next.js 前端（`src/app/` 页面和 API 路由，`src/components/` UI 组件，`src/lib/` 工具和题目数据）；`grading_service/` 是 FastAPI 后端判题 API；`torch_judge/` 是判题引擎（`problems/` 题目模块，`runner.py` 测试执行逻辑）；`setup.sh` 环境引导脚本；`package.json` 开发脚本（并发运行前后端）；`pyproject.toml` Python 包配置。
6. 常用命令：`npm run dev` 同时启动前端和后端；`cd grading_service && uvicorn main:app --reload --port 8000` 只启动判题服务；`cd web && npm run dev` 只启动前端；`pytest torch_judge/` 运行 Python 测试；`pip install -e ".[dev]"` 以 editable 模式安装 Python 包及开发依赖；`docker compose up --build` 构建并启动 Docker；`docker compose down -v` 停止并删除 volume（重置进度）。
7. 配置环境变量：创建 `web/.env.local` 覆盖默认值，设置 `GRADING_SERVICE_URL=http://localhost:8000`，`DB_PATH=./data/pyre.db`。
8. 配置 AI 帮助（可选）：复制 `web/.env.example` 到 `web/.env`，配置 `AI_HELP_BASE_URL=https://api.openai.com/v1`，`AI_HELP_API_KEY=$OPENAI_API_KEY`，`AI_HELP_MODEL=gpt-4o-mini`；任何 OpenAI 兼容端点均可（OpenAI、通过代理的 Anthropic、Ollama 等）；如果无服务端配置，用户也可在 UI 中设置自己的 key。
9. 按问题类别选择：Fundamentals（ReLU、Softmax、GELU、SwiGLU、Dropout、Embedding、Linear、Kaiming Init）；Normalization（LayerNorm、BatchNorm、RMSNorm）；Attention（Scaled Dot-Product、Multi-Head、Causal、GQA、Flash、Differential、MLA）；Position Encoding（Sinusoidal PE、RoPE、ALiBi、NTK-aware RoPE）；Architecture（GPT-2 Block、ViT Block、Conv2D、MoE、Depthwise Conv）；Training（Adam、Cosine LR、Gradient Clipping、Mixed Precision、Activation Checkpointing）；Distributed（Tensor Parallel、FSDP、Ring Attention）；Inference（KV Cache、Top-k Sampling、Beam Search、Speculative Decoding、Paged Attention）；Alignment（DPO、GRPO、PPO、Reward Model）；Diffusion（Noise Schedule、DDIM Step、Flow Matching、adaLN-Zero）；Adaptation（LoRA、QLoRA）；Reasoning（MCTS、Multi-Token Prediction）；SSM（Mamba SSM）。
10. 添加新问题：在 `torch_judge/problems/` 创建 Python 模块；模块包含 `PROBLEM_ID`、`TITLE`、`DIFFICULTY`（easy、medium、hard）、`CATEGORY`、`DESCRIPTION`、`STARTER_CODE`、`REFERENCE_SOLUTION`、`make_test_cases()`、`grade()`；`make_test_cases()` 返回包含 `input`、`expected`、`description` 的用例列表；`grade()` 用 `exec(submission_code, namespace)` 执行提交代码，检查函数存在，遍历用例，用 `torch.allclose(output, case['expected'], atol=1e-5)` 判断，返回 `passed`、`total`、`results`。
11. 注册新问题：在问题注册表（通常是 `torch_judge/registry.py` 或等价文件）导入 `from torch_judge.problems import my_new_problem`，并把 `my_new_problem` 加入 `PROBLEMS` 列表。
12. 调用判题服务 API：`GET /health` 健康检查；`GET /problems` 列出所有问题；`GET /problems/{problem_id}` 获取指定问题；`POST /submit` 提交解答，`Content-Type: application/json`，body 包含 `problem_id` 和 `code`；响应包含 `problem_id`、`passed`、`total`、`results`。
13. 从 Python 调用判题 API：使用 `requests.post("http://localhost:8000/submit", json={"problem_id": "softmax", "code": "..."})`，然后读取 `result['passed']`、`result['total']` 和 `result['results']`，打印每个用例状态和错误。
14. 实现 Scaled Dot-Product Attention 参考做法：`scores = torch.matmul(q, k.transpose(-2, -1)) / math.sqrt(d_k)`；若有 mask 则 `scores = scores.masked_fill(mask == 0, float('-inf'))`；`weights = F.softmax(scores, dim=-1)`；返回 `torch.matmul(weights, v)`。
15. 实现 RMSNorm 参考做法：`rms = x.pow(2).mean(dim=-1, keepdim=True).add(eps).sqrt()`；返回 `x / rms * weight`。
16. 实现 LoRA Linear 参考做法：定义 `weight`、`lora_A`、`lora_B`，`scale = alpha / rank`；forward 中 `base = x @ self.weight.T`，`lora = x @ self.lora_A.T @ self.lora_B.T`，返回 `base + self.scale * lora`。
17. 实现 Cosine Learning Rate Schedule 参考做法：若 `step >= max_steps` 返回 `lr_min`；否则 `progress = step / max_steps`，返回 `lr_min + 0.5 * (lr_max - lr_min) * (1 + math.cos(math.pi * progress))`。
18. 实现 KV Cache 参考做法：用 dataclass 存 `keys` 和 `values` 列表；`update` 追加 `new_k` 和 `new_v`；`get` 返回 `torch.cat(self.keys, dim=-2), torch.cat(self.values, dim=-2)`；`__len__` 返回 `len(self.keys)`。
19. 选择学习路径：根据目标选择 Transformer Internals、Attention & Position Encoding、Train a GPT from Scratch、Inference & Distributed、Alignment & Reasoning、Vision Transformer、Diffusion & DiT、LLM Frontier Architectures；推荐顺序：Fundamentals → Transformer Internals → Train a GPT from Scratch，再分别进入 Attention & PE / Inference & Distributed，最后进入 LLM Frontier Archs / Alignment & Reasoning。
20. 排错：判题服务不可达时运行 `curl http://localhost:8000/health`；如果未运行，手动启动：`cd grading_service`，`source ../.venv/bin/activate`，`uvicorn main:app --reload --port 8000`。
21. 排错：Python 环境问题运行 `which python && python --version`（应为 3.11+）；重装依赖 `pip install -e ".[dev]"`；用 uv 时 `uv pip install -e ".[dev]"`。
22. 排错：前端无法连接判题服务时检查 `web/.env.local` 中 `GRADING_SERVICE_URL=http://localhost:8000`；修改后重启 Next.js。
23. 排错：Docker 端口冲突时运行 `lsof -i :3000` 和 `lsof -i :8000`；停止冲突进程，然后重试 `docker compose up --build`。
24. 排错：提交总是 import 错误时，确保提交代码只使用环境中可用包；核心依赖包括 `torch`、`numpy`、`math`；查看 `pyproject.toml` 获取完整列表。
25. 排错：进度不持久化时，默认 SQLite DB 位于 `./data/pyre.db`；Docker 下确保 volume 挂载，在 `docker-compose.yml` 中设置 `volumes: - pyre_data:/app/data`。
26. 贡献问题：1. 创建 `torch_judge/problems/{problem_id}.py` 并使用上述结构；2. 包含 `PROBLEM_ID`、`TITLE`、`DIFFICULTY`、`CATEGORY`、`DESCRIPTION`、`STARTER_CODE`、`REFERENCE_SOLUTION`、`make_test_cases()` 和 `grade()`；3. 在问题注册表中注册；4. 写至少 3 个测试用例：basic、edge case、larger/random tensor case；5. 在开 PR 前用 `pytest torch_judge/` 验证；6. 新类别或结构变更先开 issue。

适用边界 · 注意事项

• 需要无需维护的托管 SaaS 平台时，不适合自托管 Pyre Code。
• 需要 GPU 大规模训练或生产级分布式训练而非编码练习时，不适用。
• 无法运行 Python/Node/Docker 或不能访问 GitHub/本地端口的环境，不适用。