执行摘要

此 PR 是 Ngram 重构系列的第二部分，将推测解码参数 branch-length 统一重命名为 max-trie-depth，覆盖文档、代码和测试文件。变更旨在提高参数名称的准确性，不影响功能逻辑，但用户需更新 CLI 配置。作为常规维护性重构，风险较低，建议开发者关注以保持代码库一致性。

功能与动机

动机源于 Ngram 重构系列（PR body 中提及 'Part of Ngram refactoring series'），目的是改进代码清晰度和一致性。具体地，将参数名称从 'branch-length' 改为 'max-trie-depth'，以更准确地描述其在 trie 数据结构中控制最大深度的角色，避免术语歧义。

实现拆解

实现按模块拆解如下：

• 文档模块：更新三个 Markdown 文件（server_arguments.md、speculative_decoding.md、ascend_npu_support_features.md），修改参数描述和默认值表。
• 服务器参数模块：在 server_args.py 中，重命名 ServerArgs 类字段和 add_cli_args 函数中的 CLI 参数。
• Ngram C++ 核心模块：修改 cpp_ngram/ 目录下的多个文件：
  • ngram.cpp：更新构造函数参数验证和错误消息。
  • param.h：调整 Param 结构体字段。
  • trie.cpp：修改 Trie::insert 方法中的长度计算逻辑。
  • ngram_corpus_binding.cpp：更新 Python 绑定字段。
• Python 包装器模块：调整 ngram_corpus.py 和 ngram_worker.py 中的初始化参数和内部引用。
• 测试模块：更新 test_ngram_corpus.py 中的测试用例，确保重命名后测试通过。

关键代码变更示例（从 ngram.cpp）：

// 之前：if (!(param_.branch_length > 1))
// 之后：if (!(param_.max_trie_depth > 1))
throw std::runtime_error("param_.max_trie_depth must be greater than 1...");

评论区精华

无实质性 review 讨论。仅有的评论是 Issue 中的 /tag-and-rerun-ci 命令，用于触发 CI 测试，表明变更被直接接受，没有争议或设计权衡。

风险与影响

风险：

• 重命名不彻底可能导致代码或文档不一致，但 PR 覆盖了所有相关文件，并通过单元测试降低了风险。
• 用户脚本可能因 CLI 参数名称变更而中断，需更新配置，但文档已同步指导。
• C++ 错误消息更新可能影响调试体验，但逻辑不变。

影响：

• 对用户：CLI 参数名称变更（从 --speculative-ngram-branch-length 到 --speculative-ngram-max-trie-depth），默认值保持 18，功能不变。
• 对系统：内部变量重命名提高可读性，无性能或安全影响。
• 对团队：作为重构系列的一部分，需与其他 PR（如 #21186）协调，确保演进一致性。

关联脉络

此 PR 是 Ngram 重构系列的一部分，与近期 PR #21186（修复 Ngram 同步问题）直接相关，两者都涉及 cpp_ngram 模块，反映了团队在优化推测解码功能时的持续演进。从历史 PR 看，Ngram 相关变更频繁，表明该模块正处于活跃维护阶段，旨在提升性能和稳定性。