快速结论:该报错通常出现在把 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 未提供,如仍复现可一并记录用于反馈。
解决步骤
- 确认当前 LiteLLM 版本是否包含 PR #51720;不含则升级到包含该修复的发布版本。
- 升级后使用 Issue 中的复现脚本重新对比
ref.encode_with_unstable与rust.encode_with_unstable,分别输入"\ud800"和"x\udc80",观察两者是否抛出相同的UnicodeEncodeError。 - 用同一脚本对比
is_special_token在-1、2**32、100257上的返回值,确认越界输入返回False且合法特殊 token 仍返回True。 - 若升级后仍存在差异,记录版本号与完整输出,在 Issue 中追加反馈。
验证方法
运行对比脚本后,两处边界行为应与 tiktoken 一致:encode_with_unstable 对孤立代理字符抛出 UnicodeEncodeError;is_special_token(-1) 与 is_special_token(4294967296) 返回 False,is_special_token(100257) 返回 True。同时确认常规 encode、decode 与 token 计数行为未出现回归。
参考来源
修复 PR:BerriAI/litellm #51720
AI 工具推荐
想把多个 AI 模型放在一个入口?
GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。
推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。
这个方案解决了吗?
可以继续搜索完整报错,或查看同一工具的其他排查指南。


