执行摘要

此 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 的文档。