README.md

metadata

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 一键启动（推荐开发使用）

在项目根目录下双击运行：

.\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 一键部署

docker compose up -d --build

打开浏览器访问 http://localhost:3000 即可开始刷题。

---

方式 3：手动启动

启动后端 (FastAPI)

python scripts/run_server.py

启动前端 (Next.js)

cd frontend
npm install
npm run dev

---

🧪 自动化测试

项目拥有严格的端到端自动化测试体系：

# 运行全部 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 自动化测试套件