[Bug]: OpenAIEncoding differs from tiktoken.Encoding in encode_with_unstable (lone surrogates) and is_special_token (ids outside u32)

该报错通常出现在把 LiteLLM 的 Rust 版 OpenAIEncoding 当作 tiktoken.Encoding 的替代品做行为对比或兼容性测试时,只有两个边界场景不一致: encode_with_unstable 遇到孤立代理字符(lone surrogate),以及 is_speci

快速结论:该报错通常出现在把 LiteLLM 的 Rust 版 OpenAIEncoding 当作 tiktoken.Encoding 的替代品做行为对比或兼容性测试时,只有两个边界场景不一致:encode_with_unstable 遇到孤立代理字符(lone surrogate),以及 is_special_token 接收超出 u32 范围的整数。优先排查方向是对比测试中是否触及这两个边界输入。

适用环境:LiteLLM 1.110.0rc2 与 1.109.1(两者输出一致);SDK 方式部署,无代理;设置 LITELLM_LOCAL_MODEL_COST_MAP=True;对比对象为 tiktoken 0.14.0,编码 cl100k_base。Issue 未说明操作系统、Python、CUDA 或显卡信息。

最快修复方案:升级到包含 PR #51720 的 LiteLLM 发布版本。该 PR 已被合并,但 Issue 中报告者表示会在包含该 PR 的下一个版本中重新对比验证,尚未公布验证结果。

注意事项:Issue 正文明确指出这只是两个次要边界差异:常规的 encode、decode、token 计数及其他已测方法结果与 tiktoken 一致。因此正常分词和计数场景不受影响,无需因该差异修改常规调用逻辑。

问题场景

用户通过 LiteLLM SDK 使用 litellm_core_utils/tokenizer.py 中的 OpenAIEncoding(Rust 支持的 tiktoken.Encoding 仿制类),并用 OpenAIEncoding.from_tiktoken("cl100k_base") 与 tiktoken.get_encoding("cl100k_base") 逐方法做等价性比对,目的是确认该类能否直接替代 tiktoken.Encoding。

比对中发现两处不一致:对含孤立代理字符的字符串调用 encode_with_unstable 时,tiktoken 抛出 UnicodeEncodeError,而 LiteLLM 返回结果;对 -1 或 2**32 等超出 0..2**32-1 的整数调用 is_special_token 时,tiktoken 返回 False,而 LiteLLM 抛出 OverflowError。

报错原文

[Bug]: OpenAIEncoding differs from tiktoken.Encoding in encode_with_unstable (lone surrogates) and is_special_token (ids outside u32)

tiktoken encode_with_unstable('\ud800') UnicodeEncodeError: 'utf-8' codec can't encode character '\ud800' in position 0: surrogates not allowed
litellm  encode_with_unstable('\ud800') ([], [[5809], [10178], [24378], [52063], [58432], [99921]])
tiktoken encode('\ud800') [5809]
litellm  encode('\ud800') [5809]

tiktoken encode_with_unstable('x\udc80') UnicodeEncodeError: 'utf-8' codec can't encode character '\udc80' in position 1: surrogates not allowed
litellm  encode_with_unstable('x\udc80') ([87], [[5809], [10178], [24378], [52063], [58432], [99921]])
tiktoken encode('x\udc80') [87, 5809]
litellm  encode('x\udc80') [87, 5809]

tiktoken is_special_token(-1) False
litellm  is_special_token(-1) OverflowError: out of range integral type conversion attempted
tiktoken is_special_token(4294967296) False
litellm  is_special_token(4294967296) OverflowError: out of range integral type conversion attempted
tiktoken is_special_token(100257) True
litellm  is_special_token(100257) True

原因分析

最可能的原因是 Rust 侧实现与 tiktoken 在边界处理上的语义差异,而不是分词算法本身的问题:

  • encode_with_unstable:tiktoken 在内部对原始字符串做 UTF-8 编码,因此孤立代理字符会直接触发 UnicodeEncodeError;LiteLLM 的实现似乎会先替换代理字符再处理,所以返回了结果。普通的 encode 两边都会替换代理字符,因此结果一致。
  • is_special_token:参数在传入 Rust 前需要转换为 u32,超出范围的整数导致转换失败并抛出 OverflowError;而 tiktoken 对越界整数直接返回 False。

上述具体实现细节属于基于报错行为的推断,Issue 未披露修复 PR #51720 的具体改动内容。

环境排查

  • 确认 LiteLLM 版本:Issue 在 1.110.0rc2 与 1.109.1 上均复现,需确认是否已包含 PR #51720。
  • 确认 tiktoken 版本:Issue 使用 0.14.0 做对比。
  • 确认对比是否使用 cl100k_base 编码。
  • 确认部署方式为 SDK 且设置了 LITELLM_LOCAL_MODEL_COST_MAP=True,排除代理转发路径干扰。
  • Python 版本、操作系统、CUDA、显卡等信息 Issue 未提供,如仍复现可一并记录用于反馈。

解决步骤

  1. 确认当前 LiteLLM 版本是否包含 PR #51720;不含则升级到包含该修复的发布版本。
  2. 升级后使用 Issue 中的复现脚本重新对比 ref.encode_with_unstable 与 rust.encode_with_unstable,分别输入 "\ud800" 和 "x\udc80",观察两者是否抛出相同的 UnicodeEncodeError。
  3. 用同一脚本对比 is_special_token 在 -1、2**32、100257 上的返回值,确认越界输入返回 False 且合法特殊 token 仍返回 True。
  4. 若升级后仍存在差异,记录版本号与完整输出,在 Issue 中追加反馈。

验证方法

运行对比脚本后,两处边界行为应与 tiktoken 一致:encode_with_unstable 对孤立代理字符抛出 UnicodeEncodeError;is_special_token(-1) 与 is_special_token(4294967296) 返回 False,is_special_token(100257) 返回 True。同时确认常规 encode、decode 与 token 计数行为未出现回归。

参考来源

BerriAI/litellm #51601

修复 PR:BerriAI/litellm #51720

GamsGo AI

AI 工具推荐

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

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

了解 GamsGo AI

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

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 36045

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注