从模型返回结构化数据指南

从模型返回结构化数据指南

1. 前提概念

开始之前，请确保你熟悉以下概念：

聊天模型 (Chat Models)
函数/工具调用 (Function/Tool Calling)

获取符合特定模式的模型输出通常很有用，例如从文本中提取数据以插入数据库或用于下游系统。本指南介绍了从模型获取结构化输出的几种策略。

2. 使用 .with_structured_output() 方法

这是获取结构化输出最简单、最可靠的方法。它适用于原生支持结构化输出（如工具/函数调用或 JSON 模式）的模型。

输入： 此方法接受一个模式 (Schema) 作为输入，该模式指定所需输出属性的名称、类型和描述。模式可以是：
- TypedDict 类
- JSON Schema 字典
- Pydantic 类
输出： 返回一个类似模型的可运行对象。
- 如果使用 TypedDict 或 JSON Schema，输出为字典。
- 如果使用 Pydantic 类，输出为 Pydantic 对象。

支持此方法的模型：

你可以在这里找到支持此方法的模型列表（请查找具有 "Structured Output" 徽章的模型）。

示例：生成结构化笑话

我们将让模型生成一个笑话，并将"铺垫" (setup) 与"笑点" (punchline) 分开。

环境设置 (以 TogetherAI + Mixtral 为例):

python 复制代码

# 安装必要的库
# pip install -qU langchain-openai typing_extensions

import getpass
import os
from langchain_openai import ChatOpenAI

# 设置 API 密钥
# 注意：示例中使用 TOGETHER_API_KEY，如果你使用 OpenAI，请设置 OPENAI_API_KEY
if "TOGETHER_API_KEY" not in os.environ:
    os.environ["TOGETHER_API_KEY"] = getpass.getpass("请输入 Together AI API 密钥：")

# 初始化聊天模型
llm = ChatOpenAI(
    base_url="https://api.together.xyz/v1",  # TogetherAI 的 API 地址
    api_key=os.environ["TOGETHER_API_KEY"],
    model="mistralai/Mixtral-8x7B-Instruct-v0.1", # 使用的特定模型
)

2.1 使用 Pydantic 类

传入所需的 Pydantic 类。Pydantic 的主要优点是会对模型生成的输出进行验证。如果缺少必需字段或字段类型错误，Pydantic 会引发错误。

python 复制代码

from typing import Optional
from pydantic import BaseModel, Field

# 定义 Pydantic 模型
class Joke(BaseModel):
    """讲给用户的笑话。"""
    setup: str = Field(description="笑话的铺垫")
    punchline: str = Field(description="笑话的笑点")
    rating: Optional[int] = Field(
        default=None, description="笑话的有趣程度，从 1 到 10"
    )

# 创建结构化输出的 LLM
structured_llm = llm.with_structured_output(Joke)

# 调用模型
result = structured_llm.invoke("给我讲个关于猫的笑话")
print(result)
# 输出示例: Joke(setup='为什么猫坐在电脑上？', punchline='因为它想监视鼠标！', rating=7)

提示: Pydantic 类的名称、文档字符串 (docstring)、参数名称和描述都很重要。它们通常会被添加到模型提示中，尤其是在使用函数/工具调用 API 时。

2.2 使用 TypedDict 或 JSON Schema

如果你不想使用 Pydantic，或者希望能够流式处理输出，可以使用 TypedDict。

要求:

核心库: langchain-core>=0.2.26
类型扩展: 强烈建议从 typing_extensions 导入 Annotated 和 TypedDict。

python 复制代码

from typing import Optional # 确保导入 Optional
from typing_extensions import Annotated, TypedDict

# 定义 TypedDict
class JokeTypedDict(TypedDict):
    """讲给用户的笑话。"""
    setup: Annotated[str, ..., "笑话的铺垫"]
    punchline: Annotated[str, ..., "笑话的笑点"]
    rating: Annotated[Optional[int], None, "笑话的有趣程度，从 1 到 10"]
    # 备选定义方式:
    # setup: str                    # 无默认值，无描述
    # setup: Annotated[str, ...]    # 无默认值，无描述
    # setup: Annotated[str, "foo"]  # 有默认值，无描述

# 创建结构化输出的 LLM
structured_llm_typeddict = llm.with_structured_output(JokeTypedDict)

# 调用模型
result_typeddict = structured_llm_typeddict.invoke("给我讲个关于猫的笑话")
print(result_typeddict)
# 输出示例: {'setup': '为什么猫坐在电脑上？', 'punchline': '因为它想监视鼠标！', 'rating': 7}

或者，你可以传入一个 JSON Schema 字典。这不需要导入或类定义，但会稍微冗长一些。

python 复制代码

# 定义 JSON Schema
json_schema = {
    "title": "joke",
    "description": "讲给用户的笑话。",
    "type": "object",
    "properties": {
        "setup": {
            "type": "string",
            "description": "笑话的铺垫",
        },
        "punchline": {
            "type": "string",
            "description": "笑话的笑点",
        },
        "rating": {
            "type": "integer",
            "description": "笑话的有趣程度，从 1 到 10",
            "default": None, # 注意：此默认值仅用于模式定义，模型不生成时不会自动填充
        },
    },
    "required": ["setup", "punchline"], # 指定必需字段
}

# 创建结构化输出的 LLM
structured_llm_json = llm.with_structured_output(json_schema)

# 调用模型
result_json = structured_llm_json.invoke("给我讲个关于猫的笑话")
print(result_json)
# 输出示例: {'setup': '为什么猫坐在电脑上？', 'punchline': '因为它想监视鼠标！', 'rating': 7}

2.3 在多个模式之间选择

创建一个包含联合类型 (Union) 属性的父模式，让模型从中选择。

python 复制代码

from typing import Union
from pydantic import BaseModel, Field # 确保导入

# 定义不同的 Pydantic 模型
class Joke(BaseModel):
    """讲给用户的笑话。"""
    setup: str = Field(description="笑话的铺垫")
    punchline: str = Field(description="笑话的笑点")
    rating: Optional[int] = Field(
        default=None, description="笑话的有趣程度，从 1 到 10"
    )

class ConversationalResponse(BaseModel):
    """以对话方式回应。要友好且乐于助人。"""
    response: str = Field(description="对用户查询的对话式回应")

# 定义包含联合类型的父模型
class FinalResponse(BaseModel):
    final_output: Union[Joke, ConversationalResponse]

# 创建结构化输出的 LLM
structured_llm_union = llm.with_structured_output(FinalResponse)

# 调用模型 - 示例 1 (请求笑话)
result_joke = structured_llm_union.invoke("给我讲个关于猫的笑话")
print(result_joke)
# 输出示例: FinalResponse(final_output=Joke(setup='为什么猫坐在电脑上？', punchline='因为它想监视鼠标！', rating=7))

# 调用模型 - 示例 2 (对话式查询)
result_convo = structured_llm_union.invoke("你今天怎么样？")
print(result_convo)
# 输出示例: FinalResponse(final_output=ConversationalResponse(response="我只是一堆代码，所以我没有感情，但我在这里准备好帮助你！今天我能帮你什么吗？"))

或者，如果模型支持，可以直接使用工具调用让模型在选项间选择（设置更复杂，但可能性能更好）。

2.4 流式处理

当输出类型为字典时（即模式为 TypedDict 或 JSON Schema），可以流式传输输出。

注意： 当前流式输出产生的是聚合块，而非逐字增量。

python 复制代码

from typing import Optional # 确保导入 Optional
from typing_extensions import Annotated, TypedDict

# 使用之前定义的 TypedDict: JokeTypedDict
# class JokeTypedDict(TypedDict): ...

structured_llm_typeddict = llm.with_structured_output(JokeTypedDict)

print("流式输出：")
for chunk in structured_llm_typeddict.stream("给我讲个关于猫的笑话"):
    print(chunk)

# 输出示例 (逐步构建的字典块):
# {}
# {'setup': ''}
# {'setup': 'Why'}
# ...
# {'setup': '为什么猫坐在电脑上？', 'punchline': '因为它想监视鼠标！', 'rating': 7}

2.5 使用少量示例 (Few-Shot Prompting)

对于复杂模式，在提示中添加少量示例很有帮助。

方法一：添加到系统消息

python 复制代码

from langchain_core.prompts import ChatPromptTemplate

system = """你是一个搞笑的喜剧演员。你的专长是敲门笑话 (knock-knock jokes)。
返回一个包含铺垫（对"谁在那儿？"的回答）和最终笑点（对"<铺垫> 谁？"的回答）的笑话。

以下是一些笑话示例：
示例用户: 给我讲个关于飞机的笑话
示例助手: {{"setup": "为什么飞机从不累？", "punchline": "因为它们有休息的翅膀！", "rating": 2}}

示例用户: 再给我讲个关于飞机的笑话
示例助手: {{"setup": "货物 (Cargo)", "punchline": "汽车 (Car) go 'vroom vroom'，但飞机 (plane) go 'zoom zoom'！", "rating": 10}}

示例用户: 现在讲个关于毛毛虫的
示例助手: {{"setup": "毛毛虫 (Caterpillar)", "punchline": "毛毛虫爬得很慢，但看我变成蝴蝶然后抢尽风头！", "rating": 5}}
"""

prompt = ChatPromptTemplate.from_messages([
    ("system", system),
    ("human", "{input}")
])

# 使用之前定义的 TypedDict: JokeTypedDict
# class JokeTypedDict(TypedDict): ...
structured_llm_typeddict = llm.with_structured_output(JokeTypedDict) # 假设我们用 TypedDict

# 构建包含少量示例的链
few_shot_structured_llm = prompt | structured_llm_typeddict

# 调用模型
result_few_shot = few_shot_structured_llm.invoke({"input": "关于啄木鸟有什么好笑的？"})
print(result_few_shot)
# 输出示例: {'setup': '啄木鸟 (Woodpecker)', 'punchline': '啄木鸟是谁？找不到树的啄木鸟只是一只头疼的鸟！', 'rating': 7}

方法二：使用显式工具调用 (如果模型支持)

检查模型的 API 参考是否使用工具调用。

python 复制代码

from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
from langchain_core.prompts import ChatPromptTemplate # 确保导入

# 定义 Pydantic 模型 (假设使用 Pydantic 输出)
# class Joke(BaseModel): ...

structured_llm_pydantic = llm.with_structured_output(Joke) # 假设我们用 Pydantic

examples = [
    HumanMessage("给我讲个关于飞机的笑话", name="示例用户"),
    AIMessage(
        content="", # 对于工具调用，内容通常为空
        name="示例助手",
        tool_calls=[
            {
                "name": "Joke", # 工具名称应与 Pydantic 类名匹配 (或在 with_structured_output 中指定)
                "args": {
                    "setup": "为什么飞机从不累？",
                    "punchline": "因为它们有休息的翅膀！",
                    "rating": 2,
                },
                "id": "tool_call_1", # 唯一的调用 ID
            }
        ],
    ),
    # 大多数工具调用模型期望 AIMessage 后跟随 ToolMessage
    ToolMessage("工具调用成功", tool_call_id="tool_call_1"), # 内容可以为空或表示成功/结果
    # 有些模型可能还期望 ToolMessage 后有 AIMessage

    HumanMessage("再给我讲个关于飞机的笑话", name="示例用户"),
    AIMessage(
        content="",
        name="示例助手",
        tool_calls=[
            {
                "name": "Joke",
                "args": {
                    "setup": "货物 (Cargo)",
                    "punchline": "汽车 (Car) go 'vroom vroom'，但飞机 (plane) go 'zoom zoom'！",
                    "rating": 10,
                },
                "id": "tool_call_2",
            }
        ],
    ),
    ToolMessage("工具调用成功", tool_call_id="tool_call_2"),

    HumanMessage("现在讲个关于毛毛虫的", name="示例用户"),
    AIMessage(
        content="",
        name="示例助手",
        tool_calls=[
            {
                "name": "Joke",
                "args": {
                    "setup": "毛毛虫 (Caterpillar)",
                    "punchline": "毛毛虫爬得很慢，但看我变成蝴蝶然后抢尽风头！",
                    "rating": 5,
                },
                "id": "tool_call_3",
            }
        ],
    ),
    ToolMessage("工具调用成功", tool_call_id="tool_call_3"),
]

system = """你是一个搞笑的喜剧演员。你的专长是敲门笑话。
返回一个包含铺垫（对"谁在那儿？"的回答）和最终笑点（对"<铺垫> 谁？"的回答）的笑话。"""

prompt_tool_call = ChatPromptTemplate.from_messages(
    [
        ("system", system),
        ("placeholder", "{examples}"), # 占位符用于插入示例
        ("human", "{input}")
    ]
)

# 构建包含少量示例的链
few_shot_structured_llm_tool = prompt_tool_call | structured_llm_pydantic

# 调用模型
result_tool_few_shot = few_shot_structured_llm_tool.invoke({"input": "鳄鱼", "examples": examples})
print(result_tool_few_shot)
# 输出示例: Joke(setup='鳄鱼 (Crocodile)', punchline='待会见，鳄鱼 (Crocodile)！过会见，短吻鳄 (alligator)！', rating=7)

2.6 (高级) 指定结构化输出的方法

对于支持多种方式（如工具调用和 JSON 模式）的模型，可以使用 method= 参数指定方法。

JSON 模式 (JSON mode):

如果使用 method="json_mode"，你仍需在模型提示中告知模型期望的 JSON 格式。传递给 with_structured_output 的模式仅用于解析输出，不会像工具调用那样传递给模型。检查模型的 API 参考以确认是否支持 JSON 模式。

python 复制代码

# 注意：这里传递 None 给模式，因为模式信息需要在提示中提供
structured_llm_json_mode = llm.with_structured_output(None, method="json_mode")

# 在提示中明确要求 JSON 输出和结构
result_json_mode = structured_llm_json_mode.invoke(
    "给我讲个关于猫的笑话，用包含 `setup` 和 `punchline` 键的 JSON 格式回应"
)
print(result_json_mode)
# 输出示例: {'setup': '为什么猫坐在电脑上？', 'punchline': '因为它想监视鼠标！'}

2.7 (高级) 获取原始输出

LLM 在生成复杂结构化输出时可能不完美。传递 include_raw=True 可以避免解析错误时引发异常，并允许你自行处理原始输出。输出格式将变为包含原始消息、解析后的值（如果成功）和任何解析错误的字典。

python 复制代码

# 使用 Pydantic 类 Joke
# class Joke(BaseModel): ...

structured_llm_raw = llm.with_structured_output(Joke, include_raw=True)
raw_output_result = structured_llm_raw.invoke("给我讲个关于猫的笑话")
print(raw_output_result)

# 输出示例 (结构可能因模型和版本而异):
# {
#  'raw': AIMessage(content='', additional_kwargs={...}, ... tool_calls=[{'name': 'Joke', 'args': {'setup': '为什么猫坐在电脑上？', 'punchline': '因为它想监视鼠标！', 'rating': 7}, 'id': '...', 'type': 'tool_call'}]),
#  'parsed': Joke(setup='为什么猫坐在电脑上？', punchline='因为它想监视鼠标！', rating=7), # 或者解析后的字典
#  'parsing_error': None
# }

3. 直接提示和解析模型输出

当模型不支持 .with_structured_output()（即没有工具调用或 JSON 模式支持）时，需要：

直接提示模型使用特定格式。
使用输出解析器 (Output Parser) 从原始模型输出中提取结构化响应。

3.1 使用 PydanticOutputParser

此解析器用于解析被提示以匹配给定 Pydantic 模式的聊天模型输出。将 format_instructions 添加到提示中。

python 复制代码

from typing import List
from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.prompts import ChatPromptTemplate
from pydantic import BaseModel, Field

# 定义 Pydantic 模型
class Person(BaseModel):
    """关于一个人的信息。"""
    name: str = Field(..., description="这个人的名字")
    height_in_meters: float = Field(
        ..., description="这个人的身高，以米表示。"
    )

class People(BaseModel):
    """文本中所有人的身份信息。"""
    people: List[Person]

# 设置解析器
parser = PydanticOutputParser(pydantic_object=People)

# 创建提示模板，包含格式说明
prompt_parser = ChatPromptTemplate.from_messages(
    [
        (
            "system",
            "回答用户查询。将输出包裹在 `json` 标签中。\n{format_instructions}", # 指示模型输出 JSON
        ),
        ("human", "{query}"),
    ]
).partial(format_instructions=parser.get_format_instructions()) # 注入格式说明

# 查看发送给模型的完整提示内容
query = "安娜 23 岁，她身高 6 英尺"
# print(prompt_parser.invoke({"query": query}).to_string())
# 输出会包含系统消息、格式说明和用户查询

# 构建链：提示 -> 模型 -> 解析器
chain_parser = prompt_parser | llm | parser

# 调用链
result_parser = chain_parser.invoke({"query": query})
print(result_parser)
# 输出示例: People(people=[Person(name='安娜', height_in_meters=1.8288)]) # 6英尺约等于1.8288米

3.2 自定义解析

使用 LangChain 表达式语言 (LCEL) 创建自定义提示和解析器函数。

python 复制代码

import json
import re
from typing import List, Dict, Any # 增加导入 Dict, Any
from langchain_core.messages import AIMessage
from langchain_core.prompts import ChatPromptTemplate
from pydantic import BaseModel, Field # 确保导入

# 定义 Pydantic 模型 (同上)
# class Person(BaseModel): ...
# class People(BaseModel): ...

# 创建提示模板，要求 JSON 输出并提供 Schema
prompt_custom = ChatPromptTemplate.from_messages(
    [
        (
            "system",
            "回答用户查询。将你的答案输出为符合给定 Schema 的 JSON：\n"
            "```json\n{schema}\n```\n"
            "确保将答案包裹在 ```json 和 ``` 标签中。",
        ),
        ("human", "{query}"),
    ]
).partial(schema=People.schema_json(indent=2)) # 获取 Pydantic 模型的 JSON Schema

# 自定义解析函数，用于从模型输出中提取 JSON
def extract_json(message: AIMessage) -> List[Dict[str, Any]]: # 修改返回类型提示
    """从包含 ```json ... ``` 标签的文本中提取 JSON 内容。"""
    text = message.content
    # 正则表达式匹配 ```json ... ``` 块
    pattern = r"```json(.*?)```"
    matches = re.findall(pattern, text, re.DOTALL)

    parsed_json = []
    errors = []
    for match in matches:
        try:
            # 解析 JSON 字符串
            parsed = json.loads(match.strip())
            parsed_json.append(parsed)
        except json.JSONDecodeError as e:
            errors.append(f"解析失败的块: {match.strip()}, 错误: {e}")
            # 可以选择记录错误或采取其他处理方式

    if not parsed_json and errors:
         # 如果没有成功解析的 JSON 但有错误，可以抛出异常
         raise ValueError(f"无法从模型输出中解析 JSON。原始输出: {text}\n错误: {errors}")
    elif not parsed_json:
         # 如果没有找到匹配项
         raise ValueError(f"在模型输出中未找到 ```json ... ``` 块。原始输出: {text}")

    # 通常我们期望只有一个 JSON 块，但这里返回列表以处理多个匹配的情况
    return parsed_json


# 查看发送给模型的提示
query_custom = "安娜 23 岁，她身高 6 英尺"
# print(prompt_custom.format_prompt(query=query_custom).to_string())

# 构建链：提示 -> 模型 -> 自定义解析函数
chain_custom = prompt_custom | llm | extract_json

# 调用链
result_custom = chain_custom.invoke({"query": query_custom})
print(result_custom)
# 输出示例: [{'people': [{'name': '安娜', 'height_in_meters': 1.8288}]}]

4. 参考文献

LangChain 官方教程：www.langchain.com.cn/