gahow/xserv
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: comprehensive review + 14 bug fixes + Phase 12/14 overhaul

Browse Source 
Strict code review identified 30+ issues across correctness, performance,
and architecture. This commit addresses 14 of them with verified fixes,
restructures Phase 12 for honest continuous batching, and updates Phase 14
to target FA2 (RTX 5090 SM120 lacks TMEM required by FA4).

Bug fixes:
- FIX-01: Global cuBLAS handle (thread-local singleton, was per-call)
- FIX-02: Remove 19 unnecessary cudaDeviceSynchronize calls from kernels
- FIX-03: Qwen3 ChatML template (was plain text concatenation)
- FIX-04: EOS token from tokenizer (was hardcoded 151645)
- FIX-05: Storage tracks actual GPU device ordinal (was always Cuda(0))
- FIX-06: unsqueeze stride preserves contiguous layout
- FIX-08: CudaDeviceProp replaced with heap buffer (was UB-prone padding)
- FIX-09: Tokenizer byte_fallback to <0xNN> tokens (was panic)

Feature additions:
- FIX-10: SSE streaming (/v1/chat/completions, OpenAI-compatible)
- FIX-11: Correct usage statistics (prompt/completion/total tokens)
- FIX-13: Temperature / top-k / top-p sampling with SamplingParams

Performance improvements:
- FIX-07: Caching allocator wired up (thread-local pool, pooled flag)
- FIX-12: KV cache staging buffers (zero-alloc get_kv_len via borrow_raw)
- FIX-14: GPU strided copy kernel (eliminates contiguous() CPU round-trip)

Architecture:
- Phase 12 engine restructured: prefill/decode separation, honest TODO
  for batched GPU forward (requires Flash Attention)
- Phase 14 updated: FA2 for SM120 (FA4 requires TMEM, absent on 5090)
- Qwen3-7B → Qwen3-8B typo fixed across all docs (36 layers, hidden 4096)

Validated on dash5 (8x RTX 5090):
- 52/52 API prompts pass (EN/CN/code), SSE streaming verified
- Logits match HF transformers 9/10 top-1, 4.0/5 avg top-5 overlap
- 8 concurrent requests: 5.99x scheduling speedup (batch_size=4)
- Throughput: 10.3 tok/s (serial), 30% of HF baseline

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Gahow Wang
2026-05-22 17:53:28 +08:00
parent d8493bd70f
commit ee68d3565d
38 changed files with 3012 additions and 259 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
docs/00-roadmap.md
View File

@@ -9,7 +9,7 @@
| 抽象层级 | Level 0.5 | 自写 CUDA kernel + cuBLAS 可切换，便于 benchmark 对比 |
| 硬件 | 8×RTX 5090 (Blackwell, CC 12.0, 32GB GDDR7) | 纯 PCIe Gen5 x16 互联，无 NVLink (详见下方硬件拓扑) |
| 语言 | Rust + CUDA (C/C++) | Rust FFI 调用 CUDA |
| 起步模型 | GPT-2 124M → Qwen3-7B | 从简单到实用 |
| 起步模型 | GPT-2 124M → Qwen3-8B | 从简单到实用 |
| 精度 | BF16/FP16 | 后期扩展 FP8 |
| Tensor | 自己实现 | 完整学习 tensor 抽象设计 |
| Tokenizer | 自己实现 BPE | 学习分词机制 |
@@ -101,7 +101,7 @@ Phase 8: GPT-2 完整推理 ◄──────────── 里程碑
│
Phase 9: KV Cache + Autoregressive Generation
│
Phase 10: Qwen3-7B 支持 ◄─────────── 里程碑 ② 7B 模型推理
Phase 10: Qwen3-8B 支持 ◄─────────── 里程碑 ② 8B 模型推理
│
Phase 11: Paged Attention + KV Cache Manager
│
@@ -109,7 +109,7 @@ Phase 12: Continuous Batching + Request Scheduler
│
Phase 13: HTTP API + SSE Streaming ◄── 里程碑 ③ 端到端 API 可用
│
Phase 14: Flash Attention v2
Phase 14: Flash Attention (FA2 for SM120)
│
Phase 15: 性能优化 ◄──────────────── 里程碑 ④ 50% vLLM throughput
│
@@ -625,8 +625,8 @@ safetensors file (disk)
- [ ] 加载 GPT-2 124M (`openai-community/gpt2`)，打印所有 tensor name, shape, dtype
- [ ] 抽查几个 tensor 的前 10 个值，与 PyTorch `from_pretrained` 对比
- [ ] 加载 Qwen3-7B sharded 权重，验证所有 tensor 都成功加载
- [ ] 性能: 测量 7B 模型权重加载时间 (mmap → GPU 全流程)
- [ ] 加载 Qwen3-8B sharded 权重，验证所有 tensor 都成功加载
- [ ] 性能: 测量 8B 模型权重加载时间 (mmap → GPU 全流程)
- [ ] 错误处理: 缺少 tensor、dtype 不匹配、文件不存在等情况
---
@@ -869,15 +869,15 @@ weights × V_cache [B, H, S, D] → output [B, H, 1, D]
---
## Phase 10: Qwen3-7B 支持 — 里程碑 ②
## Phase 10: Qwen3-8B 支持 — 里程碑 ②
**Crate**: `xserv-model`
**目标**: 扩展模型定义以支持 Qwen3-7B，验证输出正确性。
**目标**: 扩展模型定义以支持 Qwen3-8B，验证输出正确性。
### 架构对比
| 特性 | GPT-2 (124M) | Qwen3-7B |
| 特性 | GPT-2 (124M) | Qwen3-8B |
|------|-------------|----------|
| Normalization | LayerNorm (pre-LN) | RMSNorm (pre-LN) |
| Position Encoding | Learned absolute (wpe) | RoPE (无单独参数) |
@@ -885,8 +885,8 @@ weights × V_cache [B, H, S, D] → output [B, H, 1, D]
| Activation | GELU | SwiGLU (SiLU gate) |
| FFN | Linear(H→4H) → GELU → Linear(4H→H) | gate_proj + up_proj → SiLU gate → down_proj |
| Vocab Size | 50,257 | ~152,000 |
| Hidden Size | 768 | 3,584 (7B) |
| Layers | 12 | 28 |
| Hidden Size | 768 | 4,096 (8B) |
| Layers | 12 | 36 |
| Tied Embeddings | Yes | No |
### 需要新增/修改的组件
@@ -948,16 +948,16 @@ pub struct Qwen3DecoderLayer {
### 显存预算 (BF16, 单卡 5090 32GB)
```
模型权重: 7B × 2B = ~14 GB
KV cache: 28 layers × 2(KV) × 8 heads × 4096 tokens × 128 dim × 2B ≈ 4.5 GB
模型权重: 8B × 2B = ~16 GB
KV cache: 36 layers × 2(KV) × 8 heads × 4096 tokens × 128 dim × 2B ≈ 5.6 GB
Activation (单请求): ~1 GB
────────────────────────
总计: ~19.5 GB (单请求)，剩余 ~12 GB 可用于更多并发
总计: ~22.6 GB (单请求)，剩余 ~10 GB 可用于更多并发
```
### 测试验收
- [ ] 加载 Qwen3-7B 权重到单张 5090，打印模型结构和参数量
- [ ] 加载 Qwen3-8B 权重到单张 5090，打印模型结构和参数量
- [ ] Prefill logits 与 HF transformers 对比: 输入 "你好" → top-5 logits 一致
- [ ] 英文生成: "What is the capital of France?" → 生成合理回答
- [ ] 中文生成: "请介绍一下量子计算" → 生成通顺中文
@@ -1196,7 +1196,7 @@ GET /health # 健康检查
**Chat Completion Request**:
```json
{
"model": "qwen3-7b",
"model": "qwen3-8b",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is 1+1?"}
@@ -1211,13 +1211,13 @@ GET /health # 健康检查
**SSE Streaming Response**:
```
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qwen3-7b","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qwen3-8b","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qwen3-7b","choices":[{"index":0,"delta":{"content":"The"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qwen3-8b","choices":[{"index":0,"delta":{"content":"The"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qwen3-7b","choices":[{"index":0,"delta":{"content":" answer"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qwen3-8b","choices":[{"index":0,"delta":{"content":" answer"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qwen3-7b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qwen3-8b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]
```
@@ -1228,7 +1228,7 @@ data: [DONE]
"id": "chatcmpl-xxx",
"object": "chat.completion",
"created": 1234567890,
"model": "qwen3-7b",
"model": "qwen3-8b",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "The answer is 2."},
@@ -1278,7 +1278,7 @@ Client (curl / Python OpenAI SDK)
```bash
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"qwen3-7b","messages":[{"role":"user","content":"Hello"}],"stream":true}'
-d '{"model":"qwen3-8b","messages":[{"role":"user","content":"Hello"}],"stream":true}'
```
看到 SSE 逐 token 输出
@@ -1287,7 +1287,7 @@ Client (curl / Python OpenAI SDK)
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8080/v1", api_key="unused")
for chunk in client.chat.completions.create(
model="qwen3-7b",
model="qwen3-8b",
messages=[{"role": "user", "content": "What is 1+1?"}],
stream=True
):
@@ -1302,12 +1302,26 @@ Client (curl / Python OpenAI SDK)
---
## Phase 14: Flash Attention v2
## Phase 14: Flash Attention (FA2 for SM120)
**Crate**: `xserv-kernels`
**CUDA 源码**: `csrc/attention/flash_attention.cu`
**目标**: 实现 Flash Attention v2 的 CUDA kernel，大幅降低 attention 的显存占用并提升速度。
**目标**: 实现 Flash Attention 的 CUDA kernel，大幅降低 attention 的显存占用并提升速度。
### 硬件适配说明
Flash Attention 已发展到第 4 代 (FA4, arxiv 2603.05451)，但各版本有明确的硬件依赖:
| 版本 | 目标架构 | 关键硬件特性 | RTX 5090 兼容 |
|------|---------|------------|--------------|
| FA2 | 通用 CUDA (SM75+) | 标准 shared memory + HMMA | **是** ✅ |
| FA3 | Hopper SM90 (H100) | TMA + WGMMA + warp specialization | 否 |
| FA4 | Blackwell SM100 (B200/B300) | TMEM + async MMA + 2-CTA mode | 否 |
**RTX 5090 (SM120, CC 12.0) 使用的是消费级 Blackwell 架构 (GB202)，与数据中心 Blackwell (B200, SM100) 是不同的硅片设计。SM120 物理上没有 TMEM (Tensor Memory) 子系统，因此 FA4 的 kernel 无法在 5090 上运行。这不是软件限制，是硬件级差异。**
因此本项目实现 **FA2 算法**，使用标准 CUDA (shared memory + HMMA)。FA2 的核心优化——online softmax tiling、O(1) 显存占用——在任何架构上都有效。
### 核心思想
@@ -1323,16 +1337,18 @@ Flash Attention 的解法:
- 将 Q, K, V 分成 tiles，在 SRAM (shared memory) 中计算
- 使用 **online softmax trick**: 边算边更新 running max 和 running sum
### 算法 (Forward Pass)
### 算法 (Forward Pass, FA2)
FA2 相比 FA1 的改进: 外层循环遍历 Q tiles (而非 K/V)，减少 HBM 读写次数。
```
Br, Bc = tile sizes for Q and K/V respectively
for each Q tile (q_start..q_start+Br):
for each Q tile (q_start..q_start+Br): ← 外层: Q tiles
load Q_tile [Br, D] to shared memory
initialize: O_tile = 0, l = 0, m = -inf // running sum and max
initialize: O_tile = 0, l = 0, m = -inf // running sum and max
for each K,V tile (kv_start..kv_start+Bc):
for each K,V tile (kv_start..kv_start+Bc): ← 内层: K/V tiles
load K_tile [Bc, D], V_tile [Bc, D] to shared memory
// Compute attention scores for this tile pair
@@ -1345,6 +1361,8 @@ for each Q tile (q_start..q_start+Br):
m_new = max(m, rowmax(S_tile)) // new running max
P_tile = exp(S_tile - m_new) // safe exp
l_new = exp(m - m_new) * l + rowsum(P_tile) // update running sum
// Rescale and accumulate output
O_tile = diag(exp(m - m_new)) * O_tile + P_tile @ V_tile
m = m_new
l = l_new
@@ -1356,9 +1374,12 @@ for each Q tile (q_start..q_start+Br):
### 实现要点
1. **Tile 大小选择**:
- 受限于 shared memory (5090 Blackwell CC 12.0: 需要实测确认 per-SM shared memory 上限)
- 需要同时存 Q_tile, K_tile, V_tile, S_tile
- 典型值: Br=Bc=128 for D=128, BF16
- 5090 SM120: shared memory per SM = 100 KB (需实测确认)
- 需同时存 Q_tile, K_tile, V_tile, S_tile
- BF16: Q_tile [Br, D] = Br × 128 × 2B; K_tile [Bc, D] = Bc × 128 × 2B
- S_tile [Br, Bc] 保持 FP32 = Br × Bc × 4B
- 推荐起步: Br=Bc=64, head_dim=128 → 共需 ~100KB shared memory
- 优化版: Br=Bc=128 需要更多 shared memory, 可能需要拆分
2. **Causal mask 优化**:
- 如果 K/V tile 完全在 Q tile 的"未来"（kv_start > q_end）→ 跳过整个 tile
@@ -1369,10 +1390,14 @@ for each Q tile (q_start..q_start+Br):
- Q, K, V 的加载用 BF16（节省 bandwidth）
- 最终 O 转回 BF16 写出
4. **与 Paged Attention 的结合**:
- Flash Attention 的 K/V tile 遍历逻辑需要适配间接寻址
- 每个 tile 查 block_table 得到物理地址
- 这是 "Flash-Decoding" / "FlashInfer" 的核心
4. **GQA 支持**:
- K/V heads 数量 < Q heads 时，kernel 中做 `kv_head = q_head / num_groups` 索引
- 不需要 repeat_kv 操作，直接在 kernel 内部解决
5. **Decode attention 特化**:
- Decode 时 Q 只有 1 行 (Br=1)，退化为 vector-matrix attention
- 可以写一个专门的 decode attention kernel (类似 FlashDecoding)
- 沿 KV sequence 维度做 parallel reduction
### 测试验收
@@ -1386,8 +1411,9 @@ for each Q tile (q_start..q_start+Br):
| 8192 | OOM? | MB | OOM? | ms |
| 32768 | OOM | MB | OOM | ms |
- [ ] 集成到 Qwen3-7B，端到端 decode latency 对比
- [ ] 集成到 Qwen3-8B，端到端 decode latency 对比
- [ ] Profile: `ncu` 分析 compute utilization, memory throughput
- [ ] GQA 支持: 无 repeat_kv 开销
---
@@ -1441,7 +1467,7 @@ ncu --target-processes all --set full ./target/release/xserv-server
### 测试验收
- [ ] 安装 vLLM，同一台机器跑 Qwen3-7B
- [ ] 安装 vLLM，同一台机器跑 Qwen3-8B
- [ ] Benchmark 对比:
| Metric | vLLM | xserv | Ratio |
@@ -1488,7 +1514,7 @@ ncu --target-processes all --set full ./target/release/xserv-server
- **无损**: rejection sampling 保证输出分布与纯 target model 一致
- **加速条件**: draft model 足够快且与 target 分布接近
- **Draft model 选择**: Qwen3-0.5B / Qwen3-1.5B 作为 Qwen3-7B 的 draft
- **Draft model 选择**: Qwen3-0.5B / Qwen3-1.5B 作为 Qwen3-8B 的 draft
### KV Cache 处理
@@ -1578,7 +1604,7 @@ Row Parallel: down_proj 按行切分
### 测试验收
- [ ] TP=2: Qwen3-7B 输出与单卡 (TP=1) 完全一致
- [ ] TP=2: Qwen3-8B 输出与单卡 (TP=1) 完全一致
- [ ] TP=4: 每卡权重显存占用约 1/4
- [ ] Scaling benchmark (同组 GPU 0-3):
@@ -1646,7 +1672,7 @@ tensor_fp8 = cast_to_fp8(tensor / scale)
| FP8 E4M3 | X.XX | +0.XX |
| INT8 weight-only | X.XX | +0.XX |
- [ ] 显存: FP8 权重占用约 BF16 的一半 (~7 GB for 7B model)
- [ ] 显存: FP8 权重占用约 BF16 的一半 (~8 GB for 8B model)
- [ ] 性能: FP8 GEMM throughput vs BF16 GEMM
---
@@ -1727,7 +1753,7 @@ Text → Tokenizer → Text Tokens ────────────→
| 里程碑 | Phase | 验收标准 |
|--------|-------|---------|
| ① GPT-2 推理 | 8 | CLI 输入 prompt, GPT-2 生成连贯文本, logits 与 PyTorch 一致 |
| ② Qwen3-7B 推理 | 10 | 7B 模型中英文对话, 多轮 chat template 正确 |
| ② Qwen3-8B 推理 | 10 | 8B 模型中英文对话, 多轮 chat template 正确 |
| ③ E2E API | 13 | HTTP streaming API, Python OpenAI SDK 可调用, 10 并发正确 |
| ④ 性能达标 | 15 | throughput >= 50% vLLM, profiling 报告完成 |
| ⑤ 多卡推理 | 17 | TP=2/4 同组 GPU 推理正确, scaling benchmark 完成 |