ValueError: Failed to convert `generate_flags` into a valid JSON object.

问题场景

该问题发生于使用 transformers chat CLI 工具连接本地推理服务时。用户在执行类似以下命令时触发：

transformers chat http://127.0.0.1:9999/v1 some-model do_sample

其中 do_sample 本应写成 do_sample=true（或类似带 = 的键值对），却漏掉了 =。崩溃发生在参数解析阶段，尚未发起任何服务端连接。

报错原文

Traceback (most recent call last):
  File "/usr/local/bin/transformers", line 10, in <module>
    sys.exit(main())
  File "/usr/local/lib/python3.13/dist-packages/transformers/cli/transformers.py", line 37, in main
    app()
  ...
  File "/usr/local/lib/python3.13/dist-packages/transformers/cli/chat.py", line 362, in __init__
    config.update(**parse_generate_flags(generate_flags))
  File "/usr/local/lib/python3.13/dist-packages/transformers/cli/chat.py", line 614, in parse_generate_flags
    generate_flags_as_dict = {'"' + flag.split("=")[0] + '"': flag.split("=")[1] for flag in generate_flags}
IndexError: list index out of range

ValueError: Failed to convert `generate_flags` into a valid JSON object.
`generate_flags` = {generate_flags}
Converted JSON string = {generate_flags_string}

注意最后的 ValueError 信息中两个占位符 {generate_flags} 和 {generate_flags_string} 未被实际替换，原文即如此显示。

原因分析

Issue 报告者定位到三处独立缺陷，均集中在 transformers/cli/chat.py 的 parse_generate_flags 函数：

直接崩溃原因：第 614 行代码 flag.split("=")[1] 在参数不含 = 时索引越界。代码没有先检查 split 是否产生至少两个字段。

可能原因（静默数据截断）：同一行代码使用 split("=")[1] 而非 split("=", 1)[1]，导致值中若含第二个 =，其后续内容会被静默丢弃。例如 bad_key=a=b 会被解析为 {'bad_key': 'a'}，无任何报错或警告。

可能原因（错误信息不可读）：第 652 行的 ValueError 字符串缺少 f 前缀且未调用 .format()，导致两个命名占位符原样输出，无法辅助定位实际参数内容。

值得注意的是，代码中 !set 分支已包含对 = 存在性的校验，但 CLI 参数路径缺失了相同检查。

环境排查

• transformers 版本：5.16.1 及 GitHub main 分支均可复现，建议确认当前版本
• Python 版本：3.13.15（报告者环境）
• 操作系统：Linux 6.6.122+-x86_64（glibc 2.35）
• PyTorch / CUDA：2.11.0+cu128（CUDA），但报告者未使用 GPU 也能复现
• 显卡：Tesla T4（仅为环境信息，报错与硬件无关）
• 依赖版本（报告者环境）：huggingface_hub 1.28.0、safetensors 0.8.0、accelerate 1.14.0

解决步骤

1. 临时规避——检查参数格式：确认传给 transformers chat 的每个生成参数均包含 =。例如 do_sample 应改为 do_sample=true，max_new_tokens 应改为 max_new_tokens=100 等。
2. 临时规避——注意参数值内的 =：如果参数值本身可能包含 =（如提示词内容），旧版本会静默截断。建议用引号包裹整个参数并测试实际解析结果，或暂时避免在值中使用 =。
3. 可优先尝试——升级到已包含修复的版本：Issue 报告者确认修复已提交并附带测试，但截至 Issue 关闭时尚未发布正式版本。可关注 transformers 后续版本发布说明，或从 GitHub main 分支安装开发版验证修复效果。
4. 可优先尝试——迁移到官方推荐方案：Issue 维护者（@SunMarc）明确表示 transformers chat 维护不积极，建议改用 transformers serve 搭配第三方 UI 前端（如 Jan 或 PI ），以获得持续维护和更好体验。
5. 定位真实报错信息：如果遇到 ValueError 且其信息包含 {generate_flags} 和 {generate_flags_string} 字面量，说明命中了第 652 行的占位符未替换缺陷。无法从该信息获取实际参数内容，需自行检查命令行传入的参数。

验证方法

使用不带 = 的生成参数（如 transformers chat http://127.0.0.1:9999/v1 some-model do_sample）确认是否仍触发 IndexError。如果不再崩溃，说明问题已修复。同时传入含多个 = 的参数（如 --generate bad_key=a=b），检查解析结果是否为完整值 a=b（而非截断的 a），以确认数据截断问题也已解决。

参考来源

huggingface/transformers #48588

AI 工具推荐

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

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

了解 GamsGo AI

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