SGLang 多模态请求生命周期：以 Qwen2.5-VL 为例的架构级深度解析

本文档以 Qwen2.5-VL 为参考模型，提供对 SGLang 框架内多模态请求处理流程的终极详细剖析，深入到关键函数、数据结构转换和并发模型层面，旨在为开发者提供白板级的清晰理解。

核心流程图

1. 服务与适配层 (serving_chat.py)

• 作用：系统入口，将外部 OpenAI API 格式请求转换为 SGLang 内部数据结构。
• 输入：原始 HTTP POST 请求。
• 输出：GenerateReqInput 对象。
• 流程：
  • OpenAIServingChat 接收请求，调用 _process_messages 应用聊天模板。
  • 文本和媒体占位符（如 <|vision_start|>...<|vision_end|>）被统一格式化。
  • 原始媒体数据（如 URL 或 Base64 编码）完整保存在 GenerateReqInput.image_data 字段。

2. Tokenizer 与多模态处理器 (tokenizer_manager.py, qwen_vl.py)

• 作用：数据准备与模型适配的核心阶段。
• 输入：GenerateReqInput 对象。
• 输出：包含 input_ids、mm_items、mrope_positions 的字典。
• 关键流程：
  1. 并发数据加载与预处理
     并发加载图像数据，并调用 Qwen-VL 特有的 smart_resize 对图像进行缩放，满足模型输入尺寸要求。
  2. Token 化与即时扩展
     处理器将文本中的图片占位符直接替换为完整的特殊 Token 序列（如 <|vision_start|>...<|image_pad|>...<|vision_end|>），即 Token 扩展在 Tokenizer 阶段已完成。
  3. 计算 M-RoPE 位置编码
     生成扩展后的 input_ids 后，调用 MRotaryEmbedding.get_rope_index，依据输入 Token 和图像网格尺寸，计算精确的 mrope_positions，为后续文本与视觉特征融合提供基础。
  4. 最终组装
     将已扩展的 input_ids、包含 pixel_values 的 MultimodalDataItem 列表，以及 mrope_positions 一同打包，发送给调度器。

3. 调度器 (scheduler.py)

• 作用：高效请求批处理与缓存管理。
• 输入：包含 input_ids、mm_items、mrope_positions 的字典。
• 输出：ScheduleBatch 对象。
• 流程：
  1. 为每个请求创建 Req 与 MultimodalInputs 对象，跟踪状态。
  2. Radix Cache 缓存优化
     调用 pad_input_ids，将 input_ids 中的 <|image_pad|> 等特殊 Token 替换为对应 pixel_values 的哈希值。该哈希值作为缓存关键标识，实现相同图片请求的高效前缀匹配与缓存命中，即使文本内容不同。

4. 模型执行与特征注入 (model_runner.py, qwen2_5_vl.py)

• 输入：ForwardBatch 对象。
• 输出：logits。
• 流程：
  1. ModelRunner 创建的 ForwardBatch，包含 input_ids 及 mrope_positions。
  2. 调用 model.forward()，将 mrope_positions 作为关键参数传入。
  3. 双路径特征嵌入（M-RoPE 增强）
     • 文本路径：general_mm_embed_routine 获取整个 input_ids（含 <|vision_start|> 等特殊 Token）的常规词嵌入，并用 mrope_positions 应用 RoPE（旋转位置编码），确保文本和视觉部分获得精确位置信息。
     • 媒体路径：识别 <|image_pad|> 区域，调用 get_image_feature。Qwen2.5_VisionTransformer 将 pixel_values 转为高维视觉特征，VisionPatchMerger 对齐到语言模型嵌入维度。
  4. 精确注入：视觉特征嵌入覆盖 <|image_pad|> Token 对应的词嵌入位置，构建融合文本与视觉信息的完整输入序列。

5. 推理生成与输出

• 融合后的输入序列送入模型 Transformer 层，后续流程与纯文本模型一致：生成 logits，采样输出 Token，最终解码为文本返回用户。

附录：流程图 Mermaid 源码