Spaces:

dongyanggg
/

codestar-backend

Running on Zero

github-actions

Sync backend from GitHub 47e8067

5f7afef 1 day ago

7.33 kB

---
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 自动化测试套件
```

	---
	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 自动化测试套件
	```