# PR #37430 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Docs] Add docs for context extension using the yarn method
- 合并时间：2026-04-24 23:26
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/37430

---

# 执行摘要

此 PR 新增了 context extension 文档，介绍如何使用 YaRN 方法通过 `--hf-overrides` 配置 `rope_parameters` 来扩展模型上下文长度。提供了离线推理和 OpenAI 兼容在线服务的示例，并清晰标注了参数区别，解决了用户对 `--rope-scaling` 弃用的困惑。

# 功能与动机

用户在使用 Qwen 模型进行上下文扩展时，发现旧的 `--rope-scaling` 参数已失效，需要迁移到 `--hf-overrides` 方式（关联 issue #37886）。此文档旨在提供清晰的迁移指南和示例。

# 实现拆解

1. **创建文档文件**：在 `docs/features/context_extension.md` 新增文档，开头使用 `!!! note` 警告声明 `--rope-scaling` 已弃用。
2. **离线推理示例**：引用 `examples/offline_inference/context_extension.py`，展示如何使用 YaRN 和 `rope_parameters` 扩展上下文。
3. **OpenAI 在线服务示例**：提供 `vllm serve` 命令和客户端 Python 代码，演示服务端配置和客户端调用。
4. **关键参数解释**：列出常用参数（`rope_type`、`factor`、`original_max_position_embeddings`），并特别标注 `max_model_len` 为 vLLM 专属参数，避免用户混淆。

# 评论区精华

> **gemini-code-assist[bot]**：建议在文档中添加 `--rope-scaling` 弃用提示。
> **hmellor**：指出 blockquote 不是 mkdocs 标准语法，应使用 `!!! note`。
> **DarkLight1337**：强调参数说明应链接到 Hugging Face 官方文档，且 `max_model_len` 是 vLLM 特有参数。

所有反馈均已采纳，文档最终通过审核。

# 风险与影响

- **风险**：文档描述若不准确可能误导用户。但经过 review 修正后风险较低。
- **影响**：帮助用户顺利迁移到新配置，提升用户体验。影响范围主要为使用 Qwen 等模型进行上下文扩展的用户。

# 关联脉络

此 PR 由 issue #37886 驱动，是文档完善的一部分。未来可能需跟进更多模型或 rope_type 的文档。