# PR #38510 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[New Model]: add support for telechat3
- 合并时间：2026-04-03 08:26
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/38510

---

# 执行摘要

- 一句话：新增 TeleChat3 模型支持，扩展 vLLM 模型库。
- 推荐动作：建议工程师精读 telechat3_scaling_rope.py 中的 TeleChat3RoPEScaledRotaryEmbedding 类实现，关注其如何继承和修改 YaRN 方法，以及 get_rope 函数中的参数传递逻辑，这对理解 vLLM 的 RoPE 扩展机制有参考价值。

# 功能与动机

根据 PR body，TeleChat3 是由中国电信人工智能研究院开发的大型语言模型，基于国内计算力。最接近的已支持模型是 llama，因此需要新增支持以扩展模型库。

# 实现拆解

实现分为四个部分：
1) 在 `vllm/model_executor/layers/rotary_embedding/` 下新增 `telechat3_scaling_rope.py` 文件，定义继承自 YaRNScalingRotaryEmbedding 的 TeleChat3RoPEScaledRotaryEmbedding 类；
2) 修改 `__init__.py` 中的 `get_rope` 函数，添加 'scaling_type == "telechat3-yarn"' 分支以实例化新类；
3) 在 `vllm/model_executor/models/registry.py` 中注册 TeleChat3ForCausalLM，映射到 llama 架构；
4) 更新文档 `docs/models/supported_models.md` 和测试示例 `tests/models/registry.py`。

关键文件：
- `vllm/model_executor/layers/rotary_embedding/telechat3_scaling_rope.py`（模块 rotary_embedding）: 新增 TeleChat3 特定的旋转位置编码类，是核心实现。
- `vllm/model_executor/layers/rotary_embedding/__init__.py`（模块 rotary_embedding）: 修改工厂函数以支持新 scaling_type，关键集成点。
- `vllm/model_executor/models/registry.py`（模块 model_registry）: 注册新模型，影响模型加载。
- `docs/models/supported_models.md`（模块 documentation）: 更新文档，用户可见。
- `tests/models/registry.py`（模块 testing）: 添加测试示例，确保模型可用性。

关键符号：TeleChat3RoPEScaledRotaryEmbedding.__init__, get_rope ( 修改分支 )


# 评论区精华

review 中，gemini-code-assist[bot] 指出两个关键问题：一是 TeleChat3RoPEScaledRotaryEmbedding 的 __init__方法签名缺少 mscale 和 mscale_all_dim 参数，会导致 TypeError；二是模型注册表条目未按字母顺序排列。作者随后修复了这些问题。此外，jeejeelee 询问是否可以使用 DeepseekScalingRotaryEmbedding 代替，作者回应 TeleChat3 的旋转编码与 YaRN 类似，只有 mscale 计算方式不同，因此选择继承 YaRN 类。

- 构造函数签名错误 (correctness): 作者应修复签名以匹配工厂函数传递的参数。
- 模型注册表顺序 (style): 作者修复了顺序问题。
- RoPE 变体重用 (design): 选择继承 YaRNScalingRotaryEmbedding，保持代码复用。

# 风险与影响

- 风险：主要风险包括：
 1) 新 RoPE 类的构造函数签名错误，可能导致运行时崩溃，但 review 中已识别并修复；
 2) 模型注册错误可能影响加载，但基于 Llama 架构，风险较低；
 3) 缺少对 TeleChat3 特定参数的完整测试覆盖，可能隐藏兼容性问题。
 - 影响：影响范围：对用户，增加了 TeleChat3 模型的支持，扩展了可部署模型选项；对系统，新增 RoPE 变体，不影响现有功能，但增加了代码维护复杂性；对团队，遵循了 vLLM 新增模型的标准模式，易于后续集成。
 - 风险标记：构造函数签名错误 , 缺少测试覆盖

# 关联脉络

- PR #38826 feat(models): implement Google Gemma 4 architecture support (MoE, Multimodal, Reasoning, Tool-Use): 同为新增模型支持 PR，涉及模型注册和 RoPE 变体。
- PR #38788 [Model] Add support for Cheers multimodal model: 新增模型支持，扩展模型库。