👁 87 次阅读

LangChain PydanticOutputParser 为何会随机抛出 OutputParserException？

来源：https://github.com/langchain-ai/langchain/issues/36603

现象描述

在 LangChain 框架中，当 LLM 返回的 JSON 中某个字段的值类型与 Pydantic 模型定义的类型不匹配时，PydanticOutputParser 会直接触发 OutputParserException，导致整条调用链中断。该 issue 的核心报错信息如下：

Traceback (most recent call last):
  File "/usr/src/Python/rag-agent/.venv/lib/python3.13/site-packages/langchain_core/output_parsers/pydantic.py", line 28, in _parse_obj
    return self.pydantic_object.model_validate(obj)
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^
  File "/usr/src/Python/rag-agent/.venv/lib/python3.13/site-packages/pydantic/main.py", line 716, in model_validate
    return cls.__pydantic_validator__.validate_python(
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        obj,
        ^^^^
    ...<5 lines>...
        by_name=by_name,
        ^^^^^^
    )
    ^
pydantic_core._pydantic_core.ValidationError: 1 validation error for EmailModel
required_changes
  Input should be a valid string [type=string_type, input_value=['Replace or properly sec... structural stability.'], input_type=list]
    For further information visit https://errors.pydantic.dev/2.12/v/string_type

具体场景为：用户的 EmailModel 中 violation_type 和 required_changes 字段定义为 str 类型，但 LLM 实际输出的是 JSON 数组（如 ["Electrical Wiring", "Fire Safety", "Structural Integrity"]）。Pydantic v2 在 model_validate 执行时以严格模式进行类型校验，list 与 str 不可自动转换，直接抛出 ValidationError。该 issue 当前状态为 open，标签包含 bug、core、langchain、external，28 条评论，10 个反应，最后更新于 2026-09-03。截至发稿，官方尚未合入修复方案。

背景原因

goingforstudying-ctrl 在讨论中明确指出根因位于 PydanticOutputParser._parse_obj() 方法，文件路径为 libs/core/langchain_core/output_parsers/pydantic.py 第 28 行：

return self.pydantic_object.model_validate(obj)

该行直接调用 Pydantic v2 的 model_validate 方法，该方法执行严格类型校验。当 LLM 返回的 JSON 中字段值类型与模型定义不一致时（如 list 对 str、str 对 list），不会触发任何类型自动转换，而是立即抛出 ValidationError。讨论中识别出两个相互交织的问题：

无类型自动转换：Pydantic v2 在 model_validate 调用中默认不执行 list ↔ str 之间的隐式转换，而 LLM 输出 JSON 时经常出现这种类型漂移。
无回退机制：_parse_obj 方法中不存在任何 try-except 回退逻辑，ValidationError 直接传播为 OutputParserException。

keenborder786 在讨论中提出，该问题的触发与底层模型的推理能力有关。以 gpt-oss:latest（通过 Ollama 部署）为例，该模型在结构化输出任务中无法稳定遵守 JSON Schema 中的字段类型约束，倾向于将单字符串字段输出为数组。而更强的模型（如事实原文所写 sonet 4.6）在同类任务中表现更为稳定，但仍不能保证 100% 的类型合规性。 khteh 认为这是框架层面的缺陷，不应通过更换更强模型来规避，主张维护者应深入调查并修复。

排查或量化方法

出现 OutputParserException 后，可通过以下路径快速定位：

检查报错栈帧中的 _parse_obj 行号：确认异常是否从 langchain_core/output_parsers/pydantic.py:28 抛出。若是，则为类型不匹配问题。
查看 ValidationError 中的具体字段信息：报错信息中会明确指出哪个字段、期望类型、实际输入类型。例如 Input should be a valid string [type=string_type, input_value=[...], input_type=list] 说明模型字段为 str 但收到的是 list。
打印 LLM 原始输出 JSON：在解析之前增加日志，观察 LLM 返回的 JSON 中各字段的实际值类型，与 Pydantic 模型定义逐字段比对。
使用 LangSmith 追踪：issue 中包含多个 LangSmith trace 链接（如 https://smith.langchain.com/public/5445f808-a5a8-4bff-94e3-219d993fd89e/r），可查看完整调用链中每一步的输入输出，确认异常发生的确切位置。

完整解决方案

由于 issue 仍为 open 状态，官方未提交修复。以下为社区讨论中提出的缓解方案：

方案一：调整 Pydantic 模型字段类型

将模型中可能输出为数组的字段从 str 改为 List[str]，使其与 LLM 实际输出格式一致。据 issue 讨论，社区给出的另一条等价路径是改写字段描述，明确写入 Do NOT return a list or array。khteh 反馈调整后问题仍复现。

from pydantic import BaseModel
from typing import List

class EmailModel(BaseModel):
    violation_type: List[str]     # 原为 str，改为 List[str]
    required_changes: List[str]    # 原为 str，改为 List[str]

该方案的局限性在于：如果 LLM 有时输出 str、有时输出 list，仅改为 List[str] 仍可能在输出 str 时触发反向类型错误。

方案二：在 Prompt 中强化类型约束

据 issue 讨论，keenborder786 建议通过 prompt 明确要求 LLM 将特定字段输出为字符串而非数组。该做法的效果取决于底层模型的指令遵循能力。对于较弱模型，此方案的有效性有限。

方案三：切换至更强推理能力的模型

keenborder786 多次建议尝试 sonet-4.6 等更强模型。khteh 在 2026-04-23 提供了使用 sonet-4.6 的 LangSmith trace，但未明确反馈是否解决问题。

方案四：PR #38996（社区修复提案）

据 issue 讨论，社区用户 rkfshakti 准备了针对 PydanticOutputParser 类型强制转换问题的修复，提交为 PR #38996。修复思路为：在 Pydantic 校验之前，对 list 与 str 字段类型进行预转换。该 PR 目前处于请求维护者分配的处理阶段，尚未获得维护者合入确认。该 PR 的修复逻辑概括为：在 model_validate(obj) 调用前，检测模型字段类型定义与实际 JSON 值的类型差异，将不匹配的 list 与 str 进行转换后再传入 Pydantic。

参数或对比表格

维度	方案一（改字段类型）	方案二（强化 Prompt）	方案三（换模型）	方案四（PR #38996）
修改位置	应用层 Pydantic 模型	提示词工程	基础设施层模型选择	langchain-core 框架层
是否已合入	应用侧自行修改	应用侧自行修改	需切换部署	未合入，PR 待分配
覆盖场景	仅当 LLM 稳定输出 list 时有效	依赖模型指令遵循能力	降低概率但不消除	框架级类型转换，理论上覆盖所有 list ↔ str 场景
局限	LLM 输出类型不一致时仍可能失败	弱模型效果有限	成本高，且不能保证 100%	尚未获得官方合入

常见错误排查

1. 错误假设 Pydantic v1 行为：Pydantic v2 的 model_validate 默认执行严格校验，不会像 v1 那样对部分类型差异进行隐式转换。如果从 v1 迁移到 v2，原有代码中依赖隐式转换的逻辑会开始报错。 2. 仅修改字段类型而未验证 LLM 输出一致性：据 issue 讨论，khteh 将字段改为 List[str] 后问题仍复现，说明 LLM 可能在不同调用中返回不同类型，单一方向的类型修改无法覆盖所有情况。 3. 将模型输出不稳定归咎于框架：讨论中存在分歧，keenborder786 认为根因在于模型能力不足，khteh 认为框架应提供回退机制。两种视角均有合理性，实际场景中两者可能同时存在。 4. 忽略 PydanticOutputParser 缺少回退逻辑：即使字段类型和模型输出完全匹配，其他非类型相关的 ValidationError（如必填字段缺失、枚举值不匹配）仍会直接抛出异常，因为 _parse_obj 中没有异常捕获与重试逻辑。 5. 混淆 PR 合入与版本发布：PR #38996 的代码虽已提交，但尚未获得维护者合入，也不存在对应的发布记录。不能将社区 PR 视为已可用修复。

实践建议

在使用 Pydantic 模型定义结构化输出时，为每个字段添加 Optional 或设置 default 值，减少必填字段缺失导致的 ValidationError。
在调用结构化输出之前，对 LLM 返回的 JSON 进行预处理，检测字段类型差异并做转换，再传入 model_validate。该做法与 PR #38996 的修复思路一致，可在框架层未合入前作为临时方案。
对于关键业务场景，建议在解析外层增加 try-except 重试逻辑，在捕获 OutputParserException 后重新调用 LLM 生成，最多重试若干次。社区成员也提出「在解析时最好具备某种 retrying 机制」。
在 LangSmith 中追踪每次结构化调用的输入输出，积累 LLM 输出类型不一致的样本，评估是否需要更换模型或调整 prompt。
持续关注 PR #38996 的合入状态，在获得官方版本支持后及时升级 langchain-core。

FAQ

Q：为什么 Pydantic v2 不会自动将 list 转换为 str？ A：Pydantic v2 的 model_validate 方法在默认模式下执行严格类型校验。list 与 str 之间不存在隐式转换规则，这是 Pydantic v2 的设计决策，与 LangChain 无关。PydanticOutputParser._parse_obj() 直接调用 model_validate(obj) 而不做任何预转换，因此类型不匹配时直接抛出异常。 Q：该 issue 是否有官方修复？ A：截至 2026-09-03，issue #36603 仍为 open 状态，官方未合入修复。社区用户 rkfshakti 已提交 PR #38996，提议在 Pydantic 校验前对 list 与 str 字段类型进行预转换，但该 PR 尚未获得维护者合入。 Q：是否可以通过更换模型彻底解决？ A：据 issue 讨论，更强的模型（如 sonet-4.6）在结构化输出任务中表现更稳定，但仍不能保证 100% 的类型合规性。问题本质是 LLM 输出的非确定性加上 Pydantic 严格校验，更换模型只能降低触发概率，无法完全消除。 Q：PydanticOutputParser 是否支持自定义回退逻辑？ A：根据 issue 讨论中 goingforstudying-ctrl 的分析，_parse_obj 方法中不存在任何回退机制或异常捕获逻辑。该功能的具体实现尚未公开，用户如需自定义回退，需在调用层自行实现。 Q：从 Pydantic v1 迁移到 v2 后，原有结构化输出代码是否容易受影响？ A：是的。Pydantic v1 对部分类型差异有隐式转换行为，迁移到 v2 后严格校验模式下，原本静默通过的字段类型不匹配将变为显式报错。建议在迁移时逐字段核对模型定义与 LLM 实际输出的类型一致性。