ValueError: substring not found

问题场景

用户在实例化 StopStringCriteria 时触发此问题，通常是在调用 transformers.generation.stopping_criteria.StopStringCriteria 构造函数时。Issue 提供了最小复现脚本：使用 PreTrainedTokenizerFast 包装一个仅包含中文字符（如“你”“好”）的词级（word-level）词表，然后尝试设置停用字符串（如“你好”）。任何无法对 ASCII 校验探针完成解码往返的词级词表都会触发此问题，包括非拉丁语系词表和缺少探针字母的全 ASCII 词表。

报错原文

File ".../stopping_criteria.py", line 373, in clean_tokenizer_vocab
    token_string = token_string[token_string.index(static_prefix) + len(static_prefix) :]
ValueError: substring not found

原因分析

StopStringCriteria 在验证停用字符串时，会通过重新解码固定的 ASCII 探针前缀加上每个词表 token，然后剥离前缀来清理词表（即 _clean_tokenizer_vocab 方法）。当分词器的 token 无法完成这个解码往返时，str.index 会抛出裸的 ValueError: substring not found。该模块原本已经设计了一个针对此情况的诊断信息（提到停用字符串无法匹配包含特殊字符的词表），但往返失败路径从未到达该诊断信息，因为异常先从 str.index 冒出来了。

环境排查

• 确认 Transformers 版本是否为 5.16.0.dev0 或包含 stopping_criteria.py 中 _clean_tokenizer_vocab 方法的版本。
• 确认分词器类型：是否使用 PreTrainedTokenizerFast 包装的后端分词器。
• 确认词表模型：是否为 WordLevel 模型，以及词表是否包含无法用 ASCII 探针前缀往返解码的字符。
• 检查词表是否包含探针字母（拉丁字符），如果全 ASCII 词表缺少特定字母也可能触发。

解决步骤

1. 定位到 src/transformers/generation/stopping_criteria.py 中 _clean_tokenizer_vocab 方法，找到约第 373 行的 token_string.index(static_prefix) 调用。
2. 在该调用处增加异常捕获，当 str.index 抛出 ValueError（substring not found）时，改为抛出预期的 ValueError 诊断信息，说明停用字符串无法匹配包含特殊字符的词表。
3. （可优先尝试）使用 Issue 中的最小复现脚本作为回归测试用例，验证修复是否生效。
4. 提交 PR 到 huggingface/transformers 仓库，并在描述中引用本 Issue（#48320）。

验证方法

运行 Issue 描述中的最小复现脚本。修复前会看到 ValueError: substring not found；修复后应看到预期的诊断信息，明确指出停用字符串无法匹配包含特殊字符的词表。如果修复已合并，可在新版本中运行相同脚本确认行为符合预期。

参考来源

huggingface/transformers #48320

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。