关键目录、关键对象与关键证据#

这一节把全书反复出现的源码位置、关键对象和调试证据面压缩成一张实际可用的索引，方便在排障时快速回到正确入口。

五类目录及其职责#

python/sglang/srt/
├── entrypoints/          # 门：HTTP 服务、OpenAI-compatible API、Engine 入口
│   ├── http_server.py        路由注册和请求分发
│   └── openai/
│       ├── protocol.py       ChatCompletionRequest → SamplingParams 转换
│       ├── serving_chat.py   /v1/chat/completions 处理
│       └── serving_completions.py  /v1/completions 处理
│
├── managers/             # 编排：三管理器和进程边界
│   ├── tokenizer_manager.py  API server 侧、状态持有、tokenize
│   ├── scheduler.py          batch 组织、admission、KV 分配
│   └── detokenizer_manager.py  token → text，流式回传
│
├── model_executor/       # 执行：forward pass 和模型
│   ├── model_runner.py       接收 ForwardBatch，执行前向，返回 logits
│   └── forward_batch_info.py ForwardBatch 定义（调度层→执行层的契约）
│
├── mem_cache/            # 缓存：KV 池和 RadixCache
│   ├── radix_cache.py        前缀复用的核心数据结构
│   ├── base_prefix_cache.py  RadixCache 的接口定义
│   └── memory_pool.py        ReqToTokenPool + TokenToKVPool 的物理分配
│
└── observability/        # 证据：metrics 上报和请求日志
    ├── prometheus_client.py  Prometheus metrics 注册和上报
    └── request_logger.py     请求级别的时间戳和日志

这五类目录对应的是整本书的五层架构：入口 → 编排 → 执行 → 缓存 → 证据。每当你不确定问题出在哪一层时，从这个结构出发能最快缩小范围。

请求路径上的核心对象#

这些对象在书里反复出现，每一个都代表请求在某个层次的状态快照：

从 ChatCompletionRequest 到 ForwardBatch 是一条完整的对象转换链。任何"这个信息有没有传到执行层"的问题，都可以通过追这条链的每一步来回答。

关键函数速查#

请求进入主链：

# HTTP 请求到 TokenizerManager
grep -n "async def generate_request\|async def tokenize" \
    python/sglang/srt/managers/tokenizer_manager.py | head -10

# TokenizerManager 发给 Scheduler
grep -n "send_to_scheduler\|loop_for_forward" \
    python/sglang/srt/managers/tokenizer_manager.py | head -10

批次组织：

# Scheduler 主循环
grep -n "async def event_loop\|def run_batch" \
    python/sglang/srt/managers/scheduler.py | head -10

# Admission 决策
grep -n "_get_next_batch_to_run\|get_new_prefill_batch" \
    python/sglang/srt/managers/scheduler.py | head -10

执行层：

# ModelRunner.forward 入口
grep -n "def forward\b" python/sglang/srt/model_executor/model_runner.py | head -5

# ForwardBatch 构造
grep -n "ForwardBatch.init_new\|@classmethod" \
    python/sglang/srt/model_executor/forward_batch_info.py | head -10

KV cache：

# RadixCache 的三个核心操作
grep -n "def match_prefix\|def insert\|def evict" \
    python/sglang/srt/mem_cache/radix_cache.py

三层证据面#

第一层：请求级时间戳（最细粒度）

ReqTimeStats 字段链：
arrival_time → tokenize_end_time → prefill_start_time
→ first_token_time → finish_time → response_sent_to_client_time

查看方法：开启 --log-requests，在日志里找 TTFT=、E2E= 这类格式的输出行。

第二层：系统级 Prometheus metrics（实时全局状态）

curl -s http://localhost:30000/metrics | grep -E \
    "num_running|num_waiting|token_usage|cache_hit|e2e_req_latency|ttft|gen_throughput"

关键指标速查：

• sglang:num_running_reqs：当前 running batch 大小
• sglang:token_usage：KV slots 占用率（> 0.9 时触发 OOM 保护）
• sglang:cache_hit_ratio：前缀复用命中率
• sglang:ttft_seconds_bucket：TTFT 分布直方图
• sglang:e2e_req_latency_seconds_bucket：端到端延迟分布

第三层：profiling 和 benchmark（性能根因）

# 用 torch profiler（需要 --enable-torch-profiler 启动参数）
# profiling 结果在 server 启动目录的 torch_profiler/ 子目录下

# 用 nsys 追踪 NCCL 通信（TP 相关性能问题）
nsys profile --trace cuda,nvtx python -m sglang.launch_server ...

# 压力 benchmark
python -m sglang.bench_serving --backend sglang --dataset-name random \
    --num-prompts 100 --request-rate 10 --port 30000

从症状到证据的决策路径#

症状出现
    │
    ├── 第 1 步：看 /metrics（30秒内能判断问题层次）
    │           num_running / num_waiting / token_usage / cache_hit_ratio
    │
    ├── 第 2 步：看请求日志（定位具体请求的时间分布）
    │           grep "TTFT=\|E2E=\|finish_reason=" server.log
    │
    ├── 第 3 步：grep 对应层次的核心符号（缩小到具体函数）
    │           见上面的"关键函数速查"
    │
    └── 第 4 步：如果是性能问题，再用 torch profiler 或 nsys

全书主脉络回顾#

这本书的四个部分和代码目录的对应关系：

理解了这张对应关系，任何一个从书里引出的问题，都能映射到对应的目录和对象，不需要从仓库顶层重新扫描。

小结#

这张索引的用途不是记忆，而是加速定向：

• 有症状时，先用 metrics 缩小层次，再去对应目录；
• 追某个功能时，先找对应的对象（从 ChatCompletionRequest 往下），再读转换函数；
• 验证改动时，先跑对应层次的测试，再补 benchmark。

把这三条用熟了，进仓库的代价会降低一个量级。