# PR #24998 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[fix] skip legacy minicpmv conv template for MiniCPM-V 4.6
- 合并时间：2026-05-12 15:27
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/24998

---

# 执行摘要

- 一句话：修复 MiniCPM-V 4.6 错误使用旧版 conv 模板
- 推荐动作：值得精读，是 SGLang 处理模型版本与对话模板匹配的典型案例。设计上采用双重检查（模型类型 + 正则路径），兼顾本地部署和 Hugging Face Hub 场景。

# 功能与动机

MiniCPM-V 4.6 模型使用自己的 `chat_template.jinja`（使用 `<|image_pad|>` 占位符），旧版 `minicpmv` conv 模板使用旧版占位符 `(<image>./</image>)`，匹配错误导致图像和视频路径出错。PR body 明确说明："Fix the image & video path by correctly using MiniCPM-V 4.6's own chat template, rather then mismatched `minicpmv` one."

# 实现拆解

1. **在 `match_minicpm` 函数开头添加模型类型检测**：通过 `get_model_type(model_path)` 获取模型类型，若为 `"minicpmv4_6"` 直接返回 `None`，避免匹配到旧版 `minicpmv` 模板。
2. **添加路径回退检测**：对于 Hugging Face Hub 路径（config.json 尚未本地加载），使用正则 `r"minicpm-(v|o)-4[._]6"` 匹配版本号，若命中则同样返回 `None`。
3. **调整执行顺序**：将原有的 `model_type = get_model_type(model_path)` 和 `return MODEL_TYPE_TO_TEMPLATE.get(model_type)` 语句前移到函数开头，仅在非 4.6 版本且路径不匹配时执行后续正则匹配。

关键文件：
- `python/sglang/srt/parser/conversation.py`（模块 解析器；类别 source；类型 core-logic；符号 match_minicpm）: 核心修改文件，`match_minicpm` 函数新增 MiniCPM-V 4.6 版本检测与跳过逻辑，防止错误匹配旧版 `minicpmv` 对话模板。

关键符号：match_minicpm

## 关键源码片段

### `python/sglang/srt/parser/conversation.py`

核心修改文件，`match_minicpm` 函数新增 MiniCPM-V 4.6 版本检测与跳过逻辑，防止错误匹配旧版 `minicpmv` 对话模板。

```python
# python/sglang/srt/parser/conversation.py 中的 match_minicpm 函数（改动后）
# MiniCPM-V 4.6+ uses its own chat_template.jinja with `<|image_pad|>` and
# must NOT fall back to the legacy `minicpmv` conv template (which encodes
# the old `(<image>./</image>)` placeholder used by 2.x/4.0/4.5).
model_type = get_model_type(model_path)
if model_type == "minicpmv4_6":
    return None
# For HF-hub paths (where config.json isn't on local disk yet), fall back
# to a path-version check: exclude 4.6 and later, match only legacy 2.x/4.0/4.5.
if re.search(r"minicpm-(v|o)-4[._]6", model_path, re.IGNORECASE):
    return None
match = re.search(r"minicpm-(v|o)", model_path, re.IGNORECASE)
if match:
    return f"minicpm{match.group(1).lower()}"
return MODEL_TYPE_TO_TEMPLATE.get(model_type)

```

# 评论区精华

该 PR 未产生 review 评论，直接获得批准。仅有的评论包括 bot 的配额提醒和作者触发的 CI 重试命令，合并者 mickqian 最终绕过 flaky CI 合并。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险较低。变更仅修改 `match_minicpm` 函数，新增的条件分支在检测到 4.6 版本时提前返回 `None`，不影响旧版本 MiniCPM-V（2.x/4.0/4.5）的正常匹配流程。但如果后续 MiniCPM-V 发布新版本（如 4.7），需再次更新匹配逻辑，否则可能同样错误匹配旧模板。
- 影响：影响范围有限，仅影响 MiniCPM-V 4.6 模型用户。修复后该模型能正确使用自带聊天模板，解决图像 / 视频路径编码问题。对系统其他模块无影响。
- 风险标记：暂无

# 关联脉络

- 暂无明显关联 PR