---
title: Codestar Backend
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.31.0
app_file: app.py
pinned: false
---

# CodeStar — 大模型 AI 手撕在线判题平台 (ML/DL/LLM)

> **差异化定位**：告别传统 LeetCode 算法题，专攻 **机器学习 / 深度学习 / 大模型核心算子（MHA、FlashAttention、RoPE、MLA、GQA）手撕代码与工程判题**（对标 deep-ml.com）。

---

## 🌟 核心特性

- **🎯 专注 AI 底层手撕**：涵盖 Transformer 注意力机制、大模型位置编码、前馈网络、对齐损失函数与文本解码算法。
- **🔬 数值容差对拍机制**：基于 PyTorch & NumPy 浮点容差比对（`allclose`，支持 `atol`/`rtol` 配置），自动校验张量形状（Shape）、检测 NaN/Inf 并计算最大绝对误差。
- **🛡️ AST 防作弊审查**：静态解析语法树，严禁导入危险系统模块（`os`, `sys`, `subprocess` 等）与内建危险调用（`eval`, `exec`），并禁止直接调用官方现成 API（如手撕 SDPA 时禁用 `torch.nn.MultiheadAttention`）。
- **💻 现代化 Monaco IDE**：内置 VS Code 同款代码编辑器，暗黑主题，支持本地 `localStorage` 自动保存与模板重置。
- **📐 KaTeX 公式渲染**：题面完整支持 LaTeX 数学公式渲染，直观呈现算子数学原理。
- **⚡ 零成本 CPU 判题**：纯 CPU 快速评测，无需昂贵 GPU 集群或付费 API。

---

## 📚 当前已上线题库（500 道手撕题，100% 审计自检通过）

CodeStar 已构建包含 **500 道标准化手撕题** 的全栈 AI 题库，涵盖深度学习层、注意力机制、经典机器学习、AI Infra 分布式系统、RL 对齐与解码等全部核心知识点：

| 领域分类 | 题目数量 | 核心考察点代表 |
| :--- | :---: | :--- |
| **深度学习基础与层架构 (DL)** | **96 题** | RMSNorm, GroupNorm, ConvNeXt, DropPath, adaLN-Zero, GeGLU, CKA, VeRA, R-Drop |
| **注意力与大模型 (Attention)** | **85 题** | SDPA, FlashAttention, RoPE, MLA, GQA, SwiGLU, Differential Transformer, PagedAttention |
| **经典机器学习 (ML)** | **82 题** | HMM 前后向, PAVA 保序回归, LOESS 局部加权, OMP, ISTA, GMM EM, OLS, PCA, SVM |
| **数学与信息论 (Math)** | **58 题** | Bhattacharyya/Hellinger/TV 距离, Rényi/Tsallis 广义熵, Gram-Schmidt, SVD, Cholesky |
| **AI Infra 与分布式系统 (AIInfra)** | **60 题** | Int8/Int4/FP8 量化, SmoothQuant, ZeRO-1/2/3, Ring All-Reduce, 1F1B 流水线 |
| **文本解码与采样策略 (Decoding)** | **35 题** | Speculative Decoding, Min-P, Typical Sampling, Beam Search, Repetition Penalty |
| **强化学习与偏好优化 (RL)** | **30 题** | DPO, SimPO, KTO, IPO, ORPO, PPO Clipped Surrogate, GAE-lambda, Bradley-Terry |
| **损失函数 (Loss)** | **28 题** | Label Smoothing, Focal Loss, ArcFace, SupCon, InfoNCE |
| **优化器与学习率调度 (Optim)** | **26 题** | AdamW, Lion, Adagrad, RMSprop, Cosine Annealing, LARS |

### 快速全量自检 (0.4 秒高速验证)
在本地运行快速内存自检脚本，0.6 秒即可完成全部 500 道题目的参考实现与测试用例对拍：
\\ash
python scripts/fast_verify_all.py
\
### 重点核心手撕算子展示

| 序号 | 题目名称 | 分类 | 难度 | 核心考察点 |
| :--- | :--- | :--- | :--- | :--- |
| 1 | **手撕缩放点积注意力 (SDPA)** | `Attention` | `Medium` | Causal Mask, Scale 因子, 交叉注意力 |
| 2 | **手撕 FlashAttention 前向与分块** | `Attention` | `Hard` | Tiling 分块, Online Softmax 递推更新 |
| 3 | **手撕旋转位置编码 (RoPE)** | `Attention` | `Medium` | 广播旋转, 偶数维复数旋转矩阵 |
| 4 | **手撕分组查询注意力 (GQA)** | `Attention` | `Medium` | KV-Cache 优化, `repeat_interleave` |
| 5 | **手撕潜在多头注意力 (MLA)** | `Attention` | `Hard` | DeepSeek-V2/V3 核心, 低秩 KV 压缩与上采样 |
| 6 | **手撕线性偏置注意力 (ALiBi)** | `Attention` | `Medium` | 相对位置衰减斜率, 长度外推性 |
| 7 | **手撕 SwiGLU 门控激活函数** | `Attention` | `Easy` | LLaMA FFN 核心, SiLU 门控与参数投影 |
| 8 | **手撕 RMSNorm 均方根归一化** | `DL` | `Easy` | LLaMA 标配归一化, 均方根缩放与可学习参数 |
| 9 | **手撕 LoRA 低秩适配层与参数合并** | `DL` | `Medium` | $W_0 + \frac{\alpha}{r}AB$ 增量更新, 权重吸纳 |
| 10 | **手撕 Inverted Dropout 丢弃层** | `DL` | `Easy` | 期望不变性缩放 $\frac{1}{1-p}$, 训练/评估模式切换 |
| 11 | **手撕标签平滑交叉熵损失** | `DL` | `Easy` | Label Smoothing, 正则化, NLLLoss 与均匀分布 |
| 12 | **手撕 DPO 直接偏好对齐损失** | `RL` | `Medium` | RLHF, 策略模型与参考模型 Log-Ratio, `logsigmoid` |
| 13 | **手撕 Top-K 采样截断过滤** | `ML` | `Easy` | 候选集过滤, 非 Top-K 位置填充 `-inf` |
| 14 | **手撕 Top-P (Nucleus) 核采样截断** | `ML` | `Medium` | 累积概率阈值截断, 至少保留首位 Token |

---

## 🚀 快速启动

### 方式 1：Windows 一键启动（推荐开发使用）

在项目根目录下双击运行：
```cmd
.\scripts\start_dev.bat
```
将自动启动：
- **FastAPI 判题后端**：`http://127.0.0.1:8000`（交互文档：`http://127.0.0.1:8000/docs`）
- **Next.js Web 前端**：`http://localhost:3000`

---

### 方式 2：Docker Compose 一键部署

```bash
docker compose up -d --build
```
打开浏览器访问 `http://localhost:3000` 即可开始刷题。

---

### 方式 3：手动启动

#### 启动后端 (FastAPI)
```bash
python scripts/run_server.py
```

#### 启动前端 (Next.js)
```bash
cd frontend
npm install
npm run dev
```

---

## 🧪 自动化测试

项目拥有严格的端到端自动化测试体系：
```bash
# 运行全部 20 项核心引擎、AST 安全、容差与 API 测试
pytest -v tests

# 运行全量 14 道上线题目的标答自检
python scripts/verify_all_problems.py
```

---

## 🛠️ 项目结构

```
codestar/
├── codestar/                 # Python 判题内核与后端
│   ├── core/
│   │   ├── schemas.py        # Pydantic 数据契约 (Problem, JudgeResult)
│   │   ├── ast_checker.py    # AST 语法解析与防作弊安全检查
│   │   ├── comparator.py     # PyTorch & NumPy 数值容差比对器
│   │   ├── runner.py         # 子进程沙箱评测驱动 Harness
│   │   └── engine.py         # JudgeEngine 协调引擎
│   ├── problems/
│   │   └── loader.py         # 题库持久化与仓储模块
│   └── server/               # FastAPI RESTful API 服务
│       ├── app.py
│       └── routes/
├── data/
│   └── problems/             # 14 道标准题目 JSON 定义文件
├── frontend/                 # Next.js 14 Web 前端应用
│   ├── src/
│   │   ├── app/              # App Router (首页、工作台、全局样式)
│   │   ├── components/       # Monaco IDE、Navbar、控制台组件
│   │   └── lib/              # API Client 封装
├── docker/                   # Dockerfile 配置
├── scripts/                  # 运维、测试与启动工具脚本
└── tests/                    # 完整 pytest 自动化测试套件
```