执行摘要

此PR为Ngram推测解码引入了多SAM（后缀自动机）动态HTTP API支持，允许用户在运行时通过新增的HTTP端点（添加、移除、列出）管理外部语料库，无需重启服务器。实现包括C++层多SAM存储、非阻塞后台加载和预算平均分配，保持向后兼容。这是一个有意义的改进，增强了系统灵活性，但需关注并发限制和预算分配风险。

功能与动机

动机源于Ngram推测解码的灵活性不足问题：之前仅支持通过启动参数--speculative-ngram-external-corpus-path静态加载单个外部SAM，用户无法在运行时动态调整语料库。根据PR body，此变更是Ngram重构系列（Issue #21052）的一部分，跟随PR #21425，旨在提升用户体验和系统适应性。关键表述："Users may want to add/remove corpora at runtime without restarting the server."

实现拆解

实现按模块拆解如下：

关键代码片段示例（来自ngram.cpp）：

void Ngram::batchMatch(...) {
    // 计算预算分配
    const size_t num_sams = sams_.size();
    const size_t total_sam_budget = num_sams > 0 ? std::min(param_.external_sam_budget, total_draft_token_num) : size_t{0};
    const size_t per_sam_budget = num_sams > 0 ? total_sam_budget / num_sams : size_t{0};
    const size_t trie_budget = total_draft_token_num - (per_sam_budget * num_sams);
    // 后续合并各 SAM 结果
}

评论区精华

Review讨论由gemini-code-assist[bot]发起，重点包括：

• 异常处理bug：在ngram_corpus.py中，异常时调用clear_external_corpus()会清除所有语料库，reviewer指出这是错误行为，建议专用清理。结论：添加FIXME注释，但未完全解决。

• 预算分配计算：reviewer发现trie_budget计算可能错误，整数除法余数被分配给trie。提交中已调整，但分配逻辑仍需关注。引用原话："The difference (total_sam_budget % num_sams) is currently given to the trie, which might not be the intended behavior."

• Mutex保护注释：reviewer建议恢复注释以明确保护范围。结论：已更新注释，增强可维护性。

• 字符串连接性能：reviewer指出list_external_corpora中循环连接字符串可能低效。结论：改用换行符分隔，但性能优化未实施。

风险与影响

风险：

1. 并发加载限制：C++代码中FIXME标记单staging slot，不支持并发加载，可能导致竞争或阻塞。
2. 预算分配不均：SAM预算平均分配可能忽略语料库特性，影响草案生成质量。
3. HTTP API安全：端点依赖可选认证，配置不当可能引发未授权访问。
4. 回归风险：核心batchMatch逻辑变更可能影响推测解码正确性和性能。

影响：

• 用户：获得动态管理能力，提升使用灵活性。
• 系统：非阻塞加载减少干扰，但多SAM增加内存开销；HTTP API扩展服务器功能。
• 团队：新增模块增加维护负担，但设计模式借鉴现有组件，降低学习成本。

关联脉络

此PR是Ngram推测解码演进的关键一步：

• 直接关联：PR #21425引入了外部语料库加载基础，此PR在其上扩展为动态多SAM管理。
• 系列关联：PR #22180、#22199等同属Ngram优化系列，聚焦性能改进和测试，反映团队持续投入推测解码功能增强。
• 趋势：从静态加载到动态API，显示系统向更灵活、可运维方向演进，支持运行时调整以适应多变场景。