[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 相关: Structured Output

Output Parser

一句话定义

Output Parser 是将 LLM 的文本输出解析为结构化数据的组件。LLM 输出的是字符串，但程序需要的是对象、列表、枚举等结构化数据。

它解决什么问题

LLM 输出的 JSON 可能：

• 包含多余的文本（“这是结果：\njson\n{...}\n”）
• 格式不完全正确（少了逗号、多了注释）
• 类型不对（应该是数字但输出了字符串）

Output Parser 负责从这些”不完美”的输出中提取结构化数据。

核心原理

Python 实现

class OutputParser:
    def parse(self, text: str) -> any:
        raise NotImplementedError

class JSONOutputParser(OutputParser):
    def parse(self, text: str) -> dict:
        # 1. 尝试直接解析
        try:
            return json.loads(text)
        except json.JSONDecodeError:
            pass

        # 2. 尝试提取 JSON 块
        json_match = re.search(r'```json\n(.*?)\n```', text, re.DOTALL)
        if json_match:
            try:
                return json.loads(json_match.group(1))
            except json.JSONDecodeError:
                pass

        # 3. 尝试找到第一个 { 和最后一个 }
        start = text.find('{')
        end = text.rfind('}')
        if start != -1 and end != -1:
            try:
                return json.loads(text[start:end+1])
            except json.JSONDecodeError:
                pass

        raise ParseError(f"Failed to parse JSON from: {text[:100]}...")

class PydanticOutputParser(OutputParser):
    def __init__(self, model: type[BaseModel]):
        self.model = model

    def parse(self, text: str) -> BaseModel:
        data = JSONOutputParser().parse(text)
        return self.model(**data)

与 Structured Output 的关系

# 方式 1: Output Parser（后处理）
response = await llm.chat("输出 JSON: ...")
result = parser.parse(response.content)  # 可能失败

# 方式 2: Structured Output（原生支持）
response = await llm.chat("...", response_format={"type": "json_schema", ...})
result = response.content  # 一定是合法 JSON

Structured Output 更可靠，但不是所有模型都支持。Output Parser 是通用的降级方案。

常见坑

1. 不做容错: LLM 输出稍微不标准就解析失败
2. 不做类型校验: JSON 解析成功但字段类型不对
3. 错误信息不清楚: 解析失败时不知道 LLM 输出了什么

参考资料

• Structured Output
• Pydantic Schema