ValueError: Local $ref ‘#/$defs/Widget~1Info’ could not be resolved from $defs.` The same failure occurs for names containing `~` and for percent-encoded fragment characters.

当 Dify Agent 的结构化输出 schema 在根 $defs 中使用带 / 、 ~ 或百分号编码字符的定义名,并通过 JSON Pointer 转义形式(如 Widget~1Info )引用时,契约构建会报 ValueError: Local $ref '#/$defs/Widget~1I

快速结论:当 Dify Agent 的结构化输出 schema 在根 $defs 中使用带 /、~ 或百分号编码字符的定义名,并通过 JSON Pointer 转义形式(如 Widget~1Info)引用时,契约构建会报 ValueError: Local $ref '#/$defs/Widget~1Info' could not be resolved from $defs.。较常出问题的是本地 $ref 解析逻辑没有按 JSON Pointer 规则解码,而把它当成字面量 `$defs` 键名去查找。

适用环境:Dify 自托管(源码方式),版本为 main 分支 commit f318dd01;问题定位在 dify-agent/src/dify_agent/layers/output/output_layer.py 的 _inline_local_defs_refs()。Issue 未提供操作系统、Python、CUDA 或显卡信息。

最快修复方案:暂无确认的一步修复方案。Issue 讨论中给出的临时绕过方式是改 schema:把定义名改为不含特殊字符的 WidgetInfo,引用同步改为 #/$defs/WidgetInfo,避开解码路径。该绕过为推测性方案,可优先尝试。

注意事项:改名会改变 schema 结构,可能影响下游依赖定义名的逻辑;绕过方案作者也说明未实际执行复现。真正的修复需要让解析器按 JSON Pointer 解释片段,并同时处理 /、~、百分号编码字符,以及定义名中字面量 ~1 的情况,避免双重反转义。

问题场景

用户在 Dify Agent 中配置结构化输出(structured-output)schema,根 $defs 里有一个带特殊字符的定义名,例如 Widget/Info,并在属性中用 JSON Pointer token Widget~1Info 引用它。在构建结构化输出契约或启动 Agent 运行该 schema 时触发报错。

报错原文

ValueError: Local $ref '#/$defs/Widget~1Info' could not be resolved from $defs.

Issue 正文同时说明:名称中包含 ~ 以及包含百分号编码片段字符时,也会出现同样的失败。

原因分析

Discussion 指出问题定位在 dify-agent/src/dify_agent/layers/output/output_layer.py 的 _inline_local_defs_refs():该函数去掉前缀 #/$defs/ 后,直接把剩余文本当作 $defs 的键名查找。因此 Widget~1Info 被当作字面键名,而不是先按 JSON Pointer 规则反转义成 Widget/Info。该路径上缺少百分号解码和 JSON Pointer 反转义,属于可能原因。

环境排查

  • 确认 Dify 是否为源码自托管部署,并核对当前代码是否包含 dify-agent 中 output_layer.py 的相关实现。
  • 检查结构化输出 schema 的根 $defs 键名是否包含 /、~ 或百分号编码字符。
  • 检查对应的 $ref 是否使用了 JSON Pointer 转义(如 ~1 表示 /、~0 表示 ~)。
  • Issue 未提供 Python、CUDA、PyTorch、显卡或依赖版本信息,无需据此核对。

解决步骤

  1. 先确认报错来自本地 $ref 解析:在 schema 中找到形如 #/$defs/... 的引用和对应 $defs 键名。
  2. 作为临时绕过(可优先尝试,未经验证):把定义名改为仅含普通字符的名称,例如 WidgetInfo。
  3. 同步更新所有引用该定义的位置,例如将 "$ref": "#/$defs/Widget~1Info" 改为 "$ref": "#/$defs/WidgetInfo",使引用与字面键名一致。
  4. 重新构建结构化输出契约或启动 Agent 运行,确认不再触发该 ValueError。
  5. 如需根本解决,需等待或提交代码修复:让解析器把 fragment 作为 JSON Pointer 解码,而不是直接用作定义名;回归测试应覆盖 /、~、百分号编码字符,以及定义名中字面量 ~1 的场景,防止双重反转义。

验证方法

使用改名后的 schema 重新构建结构化输出契约并执行一次 Agent 运行,确认不再出现 could not be resolved from $defs 错误,且引用对象的结构(如 id 字段及其 required 约束)按预期生效。若要保持原始定义名,则需在修复后的代码上验证 Widget~1Info、含 ~ 的名称及百分号编码引用均可正确解析。

参考来源

langgenius/dify #46263

GamsGo AI

AI 工具推荐

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

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

了解 GamsGo AI

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

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 35370

发表回复

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