PR分析报告：增强Ngram多SAM支持

执行摘要

此PR（#22294）针对Ngram推测解码的多SAM功能进行了多项行为修复和增强，包括加载失败时保留现有语料库、HTTP API错误处理、分布式结果聚合和全局token预算管理。作为Ngram重构系列（Issue #21052）的一部分，它提升了多SAM支持的稳定性和资源控制，对使用动态语料库加载的用户有积极影响，建议关注其预算实施和并发处理模式。

功能与动机

PR动机源于多SAM支持在#22203引入后的一些行为问题。根据PR body，目标是'修复和改进多SAM支持的行为'，具体解决以下痛点：加载失败时现有语料库被意外清除、HTTP API在非Ngram模式下崩溃、DP rank结果未聚合导致不一致，以及缺乏全局token预算控制可能导致资源超支。这些改进是Ngram重构路线图的一部分，旨在提供更健壮的外部语料库管理。

实现拆解

实现方案按模块层次拆解：

• C++核心层：在ngram.cpp中添加Ngram::resetStagingSam()方法，用于重置暂存SAM而不影响已加载语料库；finishExternalCorpusLoad()添加重复corpus_id检查，抛出std::runtime_error。通过FFI在ngram_corpus_ffi.cpp中暴露为cancel_external_corpus_load()。
• Python包装层：在ngram_corpus.py中，load_external_corpus_named添加token预算检查，超限时抛出ValueError；失败时调用cancel_external_corpus_load()而非clear_external_corpus()。在cpp_ngram/ngram_corpus.py中，添加_corpus_token_counts和_total_loaded_tokens跟踪，实现commit_external_corpus_load()提交计费。
• HTTP处理器层：在tokenizer_communicator_mixin.py中，为add_external_corpus、remove_external_corpus和list_external_corpora添加早期检查：若speculative_algorithm != "NGRAM"，返回错误消息而非崩溃。同时，调用_Communicator.merge_results()聚合所有DP rank的成功状态和消息。
• 外部语料管理器：在external_corpus_manager.py中，加载成功后调用commit_corpus_load更新计费；添加FIXME注释指出移除语料库期间有pending load是未定义行为。
• 测试更新：test_ngram_corpus.py添加新测试如test_remove_frees_token_budget和test_error_on_load_preserves_existing_corpora，确保预算管理和错误场景覆盖。

评论区精华

Review讨论中，hnyls2002提出了两个核心问题：

1. NgramCorpus.load_external_corpus_named有部分替换处理但API未定义，建议要么拒绝重复corpus_id要么明确支持替换。
2. NGRAMWorker.remaining_corpus_token_budget是死代码，无调用者。

作者kpham-sgl在Issue评论中回应：移除了替换路径，要求用户先remove再add以替换语料库，并移除了死代码。结论是设计更清晰，但留下了并发边界条件的FIXME。

风险与影响

技术风险：

1. 并发风险：external_corpus_manager.py中的FIXME指出，移除语料库期间有pending load可能导致数据不一致，需后续PR解决。
2. 预算保守性：cpp_ngram/ngram_corpus.py中作者注释提到remaining_token_budget可能过时（例如移除后未及时更新），使预算检查比实际更严格，可能拒绝有效加载，但这是为性能权衡的可接受行为。
3. 错误处理覆盖：HTTP API添加了早期检查，但网络超时或大语料库处理等边缘情况可能仍需完善。

影响分析：

• 用户影响：多SAM管理更可靠，错误反馈更清晰，资源控制防止意外超支。
• 系统影响：全局token预算提升资源管理，聚合DP rank结果确保分布式一致性。
• 团队影响：代码清理（移除死代码）和测试增强提升可维护性。

关联脉络

此PR是Ngram重构系列的关键一环。相关PR包括：

• #22203：引入了多SAM的动态HTTP API，是本PR的直接前置。
• #21052：定义了Ngram推测解码的路线图Issue，本PR是其'新特性'部分的一部分。
  • 历史PR如#20393、#21181等也涉及Ngram重构，但本PR专注于多SAM的行为修复。

整体来看，sglang仓库正持续优化推测解码功能，本PR展示了在动态语料库管理中的错误处理和资源控制演进，为后续SAM eviction等特性奠定了基础。