Qwen3 模型原生支持 32,768 个 token 的上下文长度。对于超出此限制的长文本，官方推荐使用 YaRN (Yet another RoPE-based Neural network scaling) 扩展技术。YaRN 是一种基于旋转位置编码（RoPE）的扩展方法，已验证可将上下文长度扩展至 131,072 个 token，并被 transformers、llama.cpp、vllm 和 sglang 等多个推理框架支持。

要启用 YaRN，需配置以下关键参数：

• rope_scaling: 一个配置 RoPE 缩放策略的字典。
• rope_type: 字符串类型，指定缩放类型。启用 YaRN 时，其值为 "yarn"。
• factor: 浮点数，定义上下文窗口扩展的倍数。例如，4.0 表示将原始长度扩展四倍。
• original_max_position_embeddings: 整数，表示模型的原始最大上下文长度，对于 Qwen3，其值为 32768。
• max_model_len: 整数，最终设置的模型最大上下文长度，应与 factor 的乘积相匹配。

解决方案：两种配置方式

根据官方文档，有以下两种主要方法来启用 YaRN。

1. 修改模型配置文件（推荐）

这是最直接且不易出错的方法，完全规避了命令行参数解析的复杂性。

1. 定位文件: 打开 Qwen3 模型目录下的 config.json 文件。

2. 添加配置: 在文件中添加或修改 rope_scaling 字段，并设置 max_model_len。

   JSON

   "rope_scaling": {
       "rope_type": "yarn",
       "factor": 4.0,
       "original_max_position_embeddings": 32768
   },
   "max_model_len": 131072

这种方法配置一次即可永久生效，特别适用于生产环境部署。

2. 命令行参数传递

对于不同的推理框架，命令行参数的格式有所不同。

• vLLM:

  Bash

  VLLM_USE_MODELSCOPE=true vllm serve ... --rope-scaling '{"rope_type":"yarn","factor":4.0,"original_max_position_embeddings":32768}' --max-model-len 131072

• sglang:

  Bash

  SGLANG_USE_MODELSCOPE=true python -m sglang.launch_server ... --json-model-override-args '{"rope_scaling":{"rope_type":"yarn","factor":4.0,"original_max_position_embeddings":32768}}'

• llama.cpp:

  Bash

  llama-server ... --rope-scaling yarn --rope-scale 4 --yarn-orig-ctx 32768

命令行参数的格式因框架而异，需特别注意。

推荐模型参数与最佳实践

在启用 YaRN 长文本支持后，为了获得最佳推理效果，还需关注以下生成参数和最佳实践：

采样参数

• 对于思考模式（enable_thinking=True），使用 Temperature=0.6、TopP=0.95、TopK=20 和 MinP=0。不要使用贪婪解码，因为它可能导致性能下降和无尽的重复。
• 对于非思考模式（enable_thinking=False），我们建议使用 Temperature=0.7、TopP=0.8、TopK=20 和 MinP=0。
• 对于支持的框架，您可以将 presence_penalty 参数调整在 0 到 2 之间以减少无尽的重复。然而，使用较高的值偶尔会导致语言混杂和模型性能轻微下降。

其他重要提示

• 性能考量: 大部分开源框架都实现了静态 YaRN。我们建议仅在需要处理长上下文时才启用 YaRN，因为它可能影响处理较短文本时的性能。
• factor 调整: 官方建议根据典型上下文长度调整 factor，例如，若应用场景的上下文长度通常为 65,536 个 token，则将 factor 设置为 2.0。
• 版本兼容性: 若遇到 Unrecognized keys in rope_scaling 警告，请升级 transformers 至 4.51.0 或更高版本。
• 显存需求: 扩展上下文长度会显著增加显存消耗。处理 131,072 个 token 的文本可能需要比原生长度多占用 30-40% 的显存。
• 输出长度: 对于大多数查询，建议设置 32,768 个 token 的输出长度。对于复杂问题，最大输出长度可设置为 38,912，为模型提供足够的空间生成详细回答。

版权属于：DeepFal

本文链接：https://blog.deepfal.cn/index.php/archives/951/

转载时须注明出处及本声明