执行摘要

此 PR 修复了 Rust 前端 detokenizer 在遇到超出 tokenizer 词表但仍在模型词表中的 prompt token id 时抛 500 错误的问题。变更仅发生在 DecodeStream 的 prefix seeding 路径，通过新增 decode_prompt_context 方法过滤无法映射的 id 后重试解码，确保流程继续而不影响 generated token 的严格校验。

功能与动机

vLLM 允许用户传入预标记化的 prompt token ids，这些 id 可能位于 [tokenizer_vocab_size, model_vocab_size) 范围内。引擎 embedding 层可以正常嵌入这些 id，但 Rust 前端 detokenizer 使用 prompt ids 作为 streaming 解码的左上下文时，若 tokenizer 无法将 id 映射回 token 文本，DecodeStream::seed_prefix 会返回 TokenizerError，导致整个请求以 500 失败（见 Issue 评论）。Python 前端已容忍此情况，本 PR 使 Rust 前端行为一致。

实现拆解

1. 新增 decode_prompt_context 方法

• 文件：rust/src/tokenizer/src/incremental.rs:75-92
• 逻辑：先尝试正常调用 tokenizer.decode()；若失败（返回 TokenizerError），则通过 id_to_token 过滤掉无法映射的 id，再用剩余 id 子集重新解码。
• 返回值：(String, Vec<u32>)，解码文本和实际参与解码的 id 列表。
• 意义：将容错限制在 prompt context 路径，不改变 Tokenizer trait 的接口语义。

2. 改造 seed_prefix 方法

• 变更：原版本直接调用 tokenizer.decode()；新版本调用 decode_prompt_context。
• 额外检查：在后缀试探循环中增加了 context_ids.len() >= SAFE_SUFFIX_MIN 条件，确保过滤后至少还有 4 个 token，避免上下文不足。
• 全量 fallback：同样使用过滤后的 ids 更新 self.ids，确保后续 push_token 操作基于清理后的 id 列表。

3. 添加 prefix_seeded 标志

• 动机：因为 seed_prefix 现在可能修改 self.ids（移除部分 id），原逻辑依赖 self.prefix.is_empty() 判断是否已 seed 不再可靠。新增布尔标志 prefix_seeded 在 new() 中初始化为 prompt_token_ids.is_empty()，在 seed_prefix 成功或跳过时置为 true。
• push_token 入口条件：从 self.prefix.is_empty() 改为 !self.prefix_seeded。

4. 添加单元测试

• 在模块内置 tests 子模块中新增多个测试用例：
  • prompt_context_filters_unknown_ids：验证 suffix 路径下过滤未知 id 后仍能成功 seed。
  • prompt_context_seed_keeps_enough_suffix：确保过滤后 id 数量不少于最小值。
  • generated_unknown_ids_still_return_decode_error：验证 generated id 仍严格报错。
  • 使用 StrictByteBackend 和 TestTokenizer（#47125）进行隔离测试。

rust/src/tokenizer/src/incremental.rs

唯一变更文件，包含所有核心逻辑修改和单元测试。新增 decode_prompt_context 方法实现过滤重试，改造 seed_prefix 和 push_token，添加 prefix_seeded 状态标志。

/* 关键的 decode_prompt_context 方法 —— 前端容错的核心 */
/// Decode prompt-only context for prefix seeding.
///
/// Prompt ids may come from the model vocabulary rather than the local
/// tokenizer vocabulary. For this seeding path, ids that cannot be mapped
/// back to raw token text are dropped before retrying strict decode. This
/// tolerance is intentionally limited to prompt context; generated ids are
/// decoded later through the normal strict path.
fn decode_prompt_context(&self, ids: &[u32]) -> Result<(String, Vec<u32>)> {
    // 先尝试正常解码，如果成功就直接返回
    match self.tokenizer.decode(ids, self.skip_special_tokens) {
        Ok(decoded) => Ok((decoded, ids.to_vec())),
        Err(error) => {
            // 解码失败时，过滤掉 tokenizer 无法映射的 id
            let filtered = ids
                .iter()
                .copied()
                .filter(|&id| self.tokenizer.id_to_token(id).is_some())
                .collect::<Vec<_>>();
            // 如果过滤前后长度相同，说明所有 id 都无法映射，返回原始错误
            if filtered.len() == ids.len() {
                return Err(error);
            }
            // 用过滤后的 id 子集重新解码，并返回过滤后的列表
            self.tokenizer
                .decode(&filtered, self.skip_special_tokens)
                .map(|decoded| (decoded, filtered))
        }
    }
}
​
/* seed_prefix 中的关键改动：调用 decode_prompt_context 并检查过滤后长度 */
fn seed_prefix(&mut self) -> Result<()> {
    let prompt_len = self.ids.len();
    if prompt_len > SAFE_SUFFIX_MIN {
        let max_try = SAFE_SUFFIX_MAX.min(prompt_len - 1);
        for suffix_len in SAFE_SUFFIX_MIN..=max_try {
            let start = prompt_len - suffix_len;
            // 原版直接 decode，现改为通过 decode_prompt_context
            let (decoded, context_ids) = self.decode_prompt_context(&self.ids[start..])?;
            // 额外检查过滤后 id 数量不少于最小值，确保上下文稳定
            if !decoded.contains('\u{FFFD}') && context_ids.len() >= SAFE_SUFFIX_MIN {
                self.prefix = decoded;
                self.ids = context_ids;
                self.prefix_index = self.ids.len();
                return Ok(());
            }
        }
    }
    // 全量 fallback 同样使用过滤后的 ids
    let (decoded, context_ids) = self.decode_prompt_context(&self.ids)?;
    self.ids = context_ids;
    if !decoded.ends_with('\u{FFFD}') {
        self.prefix = decoded;
        self.prefix_index = self.ids.len();
    }
    Ok(())
}

评论区精华

设计范围争议：作者起初在 Tokenizer::decode 层面放宽校验（commit 1），reviewer @BugenZhao 建议“limits the tolerance to prompt-context seeding in DecodeStream”，避免弱化 generated token 校验。作者采纳后重写，最终 PR 只修改 DecodeStream。

错误格式化惯例：codex review 指出测试中 error.to_string() 应改用 ToReportString（违反 AGENTS.md 规则），该建议未被采纳或讨论。

风险与影响

• 风险：低。过滤逻辑仅在解码失败时触发，不改变正常路径。过滤后 id 数量减少可能轻微影响 prefix seeding 质量，但有 >= SAFE_SUFFIX_MIN 保护。
• 影响：之前 500 错误的请求现在能正常完成。影响使用预标记化 prompt 的用户（如 benchmark 工具），无兼容性问题。

关联脉络

• PR #44680：限制了 prompt_token_ids 上界为 max(tokenizer_vocab, model_vocab)，使得超词表 id 能通过校验并被传入 detokenizer，直接导致了本 PR 修复的需求。
• PR #47125：引入 TestTokenizer 简化测试，本 PR 最终 commit 切换使用该工具。
• 功能演进：两 PR 共同确保了 Rust 前端在处理边界 prompt token id 时的健壮性，与 Python 前端行为对齐。