ValueError: Invalid JSON for field ‘picture_description_api’: 1 validation error for nullable[PictureDescriptionApi

快速结论：此报错通常出现在 Open WebUI 的 Docling Parameters 中配置了嵌套 JSON 对象（如 picture_description_api）时，Open WebUI 的 requests.post(data=...) 会错误地将嵌套对象的每个键拆分成独立的表单字段，导致 Docling 服务端收到零散的键字符串而不是完整的 JSON。优先排查是否将嵌套对象写成了 JSON 字符串。

适用环境：Open WebUI v0.10.2（已验证 v0.11.0 仍可复现）、Docker 安装、macOS 系统。

最快修复方案：在 Docling Parameters 中输入嵌套对象时，将其写为 JSON 字符串（需转义双引号），例如："picture_description_api": "{\"url\": \"http://...\", \"params\": {\"model\": \"...\"}, ...}"。该方案已由 Issue 作者在未打补丁的 v0.11.0 上验证通过。

注意事项：该方案无需修改 Open WebUI 代码；布尔值（如 do_picture_description: true）可直接传递，无需额外处理。

问题场景

用户在 Open WebUI 中使用 DoclingLoader 上传 PDF 文件时，Docling Parameters 字段中配置了嵌套的 JSON 对象（例如 picture_description_api，包含 url/params/timeout/prompt）以及布尔值 do_picture_description: true。上传后报错，Docling 容器日志显示 JSON 校验失败。

报错原文

ValueError: Invalid JSON for field 'picture_description_api': 1 validation error for nullable[PictureDescriptionApi]
Invalid JSON: expected value at line 1 column 1 [type=json_invalid, input_value='params', input_type=str]

（前端 SSE 流显示：{"status": "failed", "error": "Error calling Docling: Error calling Docling API: Internal Server Error - Internal Server Error"}）

原因分析

根本原因是 Open WebUI 后端 open_webui/retrieval/loaders/main.py 中 DoclingLoader.load() 方法将 data 参数以字典形式传给 requests.post()。当 data 字典的某个值本身也是字典时，requests 会遍历该内层字典，为每个键生成独立的表单字段（字段名均为外层键名）。例如：picture_description_api 会被拆成 picture_description_api=url、picture_description_api=params 等，导致 Docling 服务端接收到的是键名碎片（如 'params'、'timeout'），而非完整的 JSON 对象。布尔值 True 被转为字符串 "True" 后能被 Pydantic 正常解析，因此仅嵌套对象受影响。

环境排查

Open WebUI 版本（已确认影响 v0.10.2 和 v0.11.0）
Docling 部署方式（Docker 或其他）
Docling Parameters 字段中是否存在嵌套的 JSON 对象（如 picture_description_api、vlm_pipeline、table_structure 等）
如果直接向 Docling 服务的 /v1/convert/file 端点发送手动构造的多部分请求（curl）能正常工作，则基本确定为 Open WebUI 的 requests 序列化问题

解决步骤

在 Open WebUI 的 Docling Parameters 输入框中，将原本的嵌套 JSON 对象改写为 JSON 字符串（即对内部双引号进行转义）。
示例原写法（错误）：

{
  "do_picture_description": true,
  "picture_description_api": {
    "url": "http://host.docker.internal:11434/v1/chat/completions",
    "params": {"model": "qwen2.5vl:7b"},
    "timeout": 120,
    "prompt": "..."
  }
}

正确写法：

{
  "do_picture_description": true,
  "picture_description_api": "{\"url\": \"http://host.docker.internal:11434/v1/chat/completions\", \"params\": {\"model\": \"qwen2.5vl:7b\"}, \"timeout\": 120, \"prompt\": \"...\"}"
}

保存配置，重新上传测试 PDF。

验证方法

上传 PDF 后，检查浏览器开发者工具 → 网络 → SSE 流中是否返回 success 状态。同时检查 Docling 容器日志，确认不再出现 ValueError: Invalid JSON for field 'picture_description_api' 错误，并观察 Markdown 输出中是否包含由外部 VLM（如 Ollama）生成的图片描述。