219 lines
7.3 KiB
Markdown
219 lines
7.3 KiB
Markdown
# nanovllm 状态泄漏调试计划
|
||
|
||
**Task**: 修复连续请求之间的状态泄漏，使 RULER 32K 测试准确率从 ~80% 提升到 100%
|
||
**Created**: 2026-01-20
|
||
**Updated**: 2026-01-21
|
||
**Status**: `in_progress`
|
||
**Reference**: [docs/ruler_32k_chunked_offload_issue.md](docs/ruler_32k_chunked_offload_issue.md)
|
||
|
||
---
|
||
|
||
## Root Cause Summary
|
||
|
||
**已确认问题**: 连续请求之间的状态泄漏
|
||
- **证据**: 单样本测试（每次重新初始化 LLM）准确率 100%，批量测试准确率 ~80%
|
||
- **差异**: 20% 的错误率来自状态泄漏
|
||
|
||
---
|
||
|
||
## 调试规范 (MUST FOLLOW)
|
||
|
||
### 1. 并行工作流（多 GPU + 异步 Task + 标志文件）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ GPU 0: 异步 Task - 当前版本测试 (v1) │
|
||
│ → 结果: /tmp/nanovllm_test_v1.json │
|
||
│ → 标志: /tmp/nanovllm_test_v1.done │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ GPU 1: 主 Agent - 调试/修复代码 │
|
||
│ → 状态对比验证 │
|
||
│ → 修改代码 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ GPU 2: 异步 Task - 新版本测试 (v2, 修复后) │
|
||
│ → 结果: /tmp/nanovllm_test_v2.json │
|
||
│ → 标志: /tmp/nanovllm_test_v2.done │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 主 Agent: 检查标志文件，读取结果，决定下一步 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**标志文件约定**：
|
||
- 结果文件: `/tmp/nanovllm_test_<version>.json`
|
||
- 完成标志: `/tmp/nanovllm_test_<version>.done`
|
||
|
||
### 2. 验证测试命令
|
||
|
||
```bash
|
||
# 批量测试 niah_single_1 (100 samples) - 作为验证手段
|
||
CUDA_VISIBLE_DEVICES=X PYTHONPATH=/home/zijie/Code/nano-vllm:$PYTHONPATH \
|
||
python tests/test_ruler.py --task niah_single_1 --enable-offload --json-output /tmp/result.json
|
||
|
||
# 完成后写标志文件
|
||
echo "done" > /tmp/nanovllm_test_done.flag
|
||
```
|
||
|
||
### 3. Phase 完成后报告
|
||
|
||
每个 Phase 完成后：
|
||
1. **更新 `progress.md`** - 记录测试结果和发现
|
||
2. **向用户报告** - 总结本 phase 的结果
|
||
3. **等待用户确认** - 不要自动开始下一个 phase
|
||
|
||
---
|
||
|
||
## 问题优先级（已更新）
|
||
|
||
| 优先级 | 问题 | 文件位置 | 状态 |
|
||
|--------|------|----------|------|
|
||
| **P0** | CPU cache 未清除 | `offload_engine.py:reset()` | 需要验证 |
|
||
| **P0** | Ring buffer slot 状态 | `offload_engine.py` | 需要验证 |
|
||
| **P1** | Sparse policy 状态 | `sparse/policy.py` | 待检查 |
|
||
| **P2** | HybridManager 跟踪变量 | `hybrid_manager.py` | 待检查 |
|
||
|
||
---
|
||
|
||
## Phase 0: 状态分析
|
||
|
||
**Status**: `completed`
|
||
**Objective**: 分析代码中的状态管理逻辑
|
||
|
||
### 发现
|
||
|
||
#### OffloadEngine.reset() 分析
|
||
**文件**: `nanovllm/kvcache/offload_engine.py:247-274`
|
||
|
||
| 组件 | reset() 是否清除 |
|
||
|------|-----------------|
|
||
| GPU ring buffer (k/v_cache_gpu) | Yes |
|
||
| Decode buffers (decode_k/v_buffer) | Yes |
|
||
| Prefill buffers (prefill_k/v_buffer) | Yes |
|
||
| Pending events | Yes |
|
||
| **CPU cache (k/v_cache_cpu)** | **No** |
|
||
| Ring buffer slot 状态 | 需要验证 |
|
||
|
||
#### HybridKVCacheManager.deallocate() 分析
|
||
**文件**: `nanovllm/kvcache/hybrid_manager.py:206-237`
|
||
|
||
- 释放 logical blocks
|
||
- 释放 CPU blocks
|
||
- 调用 `offload_engine.reset()`
|
||
- 只在 sequence 完成时调用
|
||
|
||
#### LLMEngine.generate() 分析
|
||
**文件**: `nanovllm/engine/llm_engine.py:84-142`
|
||
|
||
- 调用 `Observer.complete_reset()` 重置性能观察器
|
||
- **没有显式调用 KV cache 重置**
|
||
|
||
---
|
||
|
||
## Phase 1: 状态一致性验证
|
||
|
||
**Status**: `in_progress`
|
||
**Objective**: 对比 fresh-llm 模式和 batch 模式下的初始状态，找出差异
|
||
|
||
### 验证思路
|
||
|
||
```
|
||
fresh-llm 模式: 每个 request 新建 LLM → 状态必定干净 → 100% 准确
|
||
batch 模式: 复用 LLM 实例 → 状态可能残留 → ~80% 准确
|
||
|
||
差异 = 泄漏源
|
||
```
|
||
|
||
### Tasks
|
||
|
||
- [ ] 1.1 添加状态 dump 函数到代码中
|
||
- [ ] 1.2 运行 fresh-llm 模式，记录某个 sample (如 #40) 开始时的状态
|
||
- [ ] 1.3 运行 batch 模式，记录同一个 sample 开始时的状态
|
||
- [ ] 1.4 对比两个状态，找出差异项
|
||
|
||
### 需要检查的状态
|
||
|
||
| 组件 | 状态 | fresh-llm | batch | 差异? |
|
||
|------|------|-----------|-------|-------|
|
||
| OffloadEngine | k_cache_cpu.sum() | - | - | - |
|
||
| OffloadEngine | v_cache_cpu.sum() | - | - | - |
|
||
| OffloadEngine | k_cache_gpu.sum() | - | - | - |
|
||
| OffloadEngine | v_cache_gpu.sum() | - | - | - |
|
||
| OffloadEngine | decode_k_buffer.sum() | - | - | - |
|
||
| OffloadEngine | prefill_k_buffer.sum() | - | - | - |
|
||
| HybridManager | len(prefilled_blocks) | - | - | - |
|
||
| HybridManager | len(free_logical_ids) | - | - | - |
|
||
|
||
### 预期结果
|
||
|
||
找到具体哪些状态在 batch 模式下不为零（或不同），这些就是泄漏源。
|
||
|
||
---
|
||
|
||
## Phase 2: 修复泄漏源
|
||
|
||
**Status**: `pending`
|
||
**Objective**: 根据 Phase 1 的发现，修复具体的泄漏点
|
||
|
||
### Tasks
|
||
|
||
- [ ] 2.1 根据 Phase 1 确定的差异项，添加对应的清除逻辑
|
||
- [ ] 2.2 运行验证测试
|
||
|
||
---
|
||
|
||
## Phase 3: 验证修复效果
|
||
|
||
**Status**: `pending`
|
||
**Objective**: 确认修复后准确率达到 100%
|
||
|
||
### Tasks
|
||
|
||
- [ ] 3.1 运行 batch 模式测试 (niah_single_1)
|
||
- [ ] 3.2 对比修复前后准确率
|
||
- [ ] 3.3 运行其他 task (multikey) 验证
|
||
|
||
### Target
|
||
|
||
| Task | 修复前 | 修复后目标 |
|
||
|------|--------|-----------|
|
||
| niah_single_1 (batch) | ~80% | 100% |
|
||
| niah_single_1 (fresh-llm) | 100% | 100% (baseline) |
|
||
| multikey_1 | ~94% | 100% |
|
||
| multikey_2 | ~94% | 100% |
|
||
| multikey_3 | ~56% | >90% |
|
||
|
||
---
|
||
|
||
## Errors Encountered
|
||
|
||
| Error | Phase | Attempt | Resolution |
|
||
|-------|-------|---------|------------|
|
||
| (待记录) | - | - | - |
|
||
|
||
---
|
||
|
||
## Decision Log
|
||
|
||
| Decision | Reason | Phase |
|
||
|----------|--------|-------|
|
||
| 使用状态一致性对比验证 | 直接对比差异，不需要逐个猜测泄漏源 | 1 |
|
||
| 使用 fresh-llm 作为 baseline | 确认单样本测试 100% 通过 | 0 |
|
||
|
||
---
|
||
|
||
## Files to Modify
|
||
|
||
| File | Modification | Phase |
|
||
|------|--------------|-------|
|
||
| `nanovllm/kvcache/offload_engine.py` | 在 reset() 添加 CPU cache 清零 | 1 |
|
||
| `nanovllm/kvcache/offload_engine.py` | 添加 slot 状态重置 | 2 |
|
||
| `nanovllm/kvcache/sparse/policy.py` | 添加 reset() 如需要 | 3 |
|
||
|
||
---
|
||
|
||
## References
|
||
|
||
- [docs/ruler_32k_chunked_offload_issue.md](docs/ruler_32k_chunked_offload_issue.md) - 问题背景
|
||
- [docs/architecture_guide.md](docs/architecture_guide.md) - 架构参考
|
||
- [findings.md](findings.md) - 代码分析发现
|
||
- [progress.md](progress.md) - 进度日志
|