### 如何创建自定义输出解析器

在某些情况下，你可能希望实现一个自定义解析器，将模型输出结构化为自定义格式。有两种方法可以实现自定义解析器：

1. **使用 `RunnableLambda` 或 `RunnableGenerator`（推荐）**  
   这是大多数情况下的推荐方法，因为它更简单且与 LangChain 的 LCEL（LangChain Expression Language）无缝集成。

2. **继承解析器的基类**  
   这种方法更复杂，通常不推荐，除非你有特殊需求。

以下是如何使用这两种方法实现自定义解析器的详细说明。

---

### 方法 1：使用 `RunnableLambda` 或 `RunnableGenerator`

#### 示例 1：简单的解析器（非流式）

以下是一个简单的解析器，它将模型输出的字母大小写反转。例如，如果模型输出 `"Meow"`，解析器将返回 `"mEOW"`。

```python
from langchain_anthropic.chat_models import ChatAnthropic
from langchain_core.messages import AIMessage

# 定义模型
model = ChatAnthropic(model_name="claude-2.1")

# 定义解析函数
def parse(ai_message: AIMessage) -> str:
    """解析 AI 消息并反转大小写"""
    return ai_message.content.swapcase()

# 创建链
chain = model | parse

# 调用链
result = chain.invoke("hello")
print(result)  # 输出: 'hELLO!'
```

**注意**：LCEL 会自动将 `parse` 函数升级为 `RunnableLambda(parse)`。

---

#### 示例 2：流式解析器

如果你需要支持流式解析，可以使用 `RunnableGenerator`。以下是一个流式解析器的示例：

```python
from typing import Iterable
from langchain_core.messages import AIMessageChunk
from langchain_core.runnables import RunnableGenerator

# 定义流式解析函数
def streaming_parse(chunks: Iterable[AIMessageChunk]) -> Iterable[str]:
    for chunk in chunks:
        yield chunk.content.swapcase()

# 将解析函数包装为 RunnableGenerator
streaming_parse = RunnableGenerator(streaming_parse)

# 创建链
chain = model | streaming_parse

# 测试流式输出
for chunk in chain.stream("tell me about yourself in one sentence"):
    print(chunk, end="|", flush=True)
# 输出: i|'M| cLAUDE|,| AN| ai| ASSISTANT| CREATED| BY| aN|THROP|IC| TO| BE| HELPFUL|,| HARMLESS|,| AND| HONEST|.|
```

---

### 方法 2：继承解析器的基类

如果你需要更细粒度的控制，可以继承 `BaseOutputParser` 或 `BaseGenerationOutputParser`。以下是一个简单的布尔解析器示例：

#### 示例 1：继承 `BaseOutputParser`

```python
from langchain_core.exceptions import OutputParserException
from langchain_core.output_parsers import BaseOutputParser

class BooleanOutputParser(BaseOutputParser[bool]):
    """自定义布尔解析器"""

    true_val: str = "YES"
    false_val: str = "NO"

    def parse(self, text: str) -> bool:
        cleaned_text = text.strip().upper()
        if cleaned_text not in (self.true_val.upper(), self.false_val.upper()):
            raise OutputParserException(
                f"BooleanOutputParser 期望输出值为 {self.true_val} 或 {self.false_val}（不区分大小写）。"
                f"实际收到: {cleaned_text}."
            )
        return cleaned_text == self.true_val.upper()

    @property
    def _type(self) -> str:
        return "boolean_output_parser"

# 测试解析器
parser = BooleanOutputParser()
print(parser.invoke("YES"))  # 输出: True
print(parser.invoke("NO"))   # 输出: False
```

---

#### 示例 2：继承 `BaseGenerationOutputParser`

如果你需要解析原始模型输出（例如，包含元数据的 `Generation` 或 `ChatGeneration`），可以继承 `BaseGenerationOutputParser`。

```python
from typing import List
from langchain_core.exceptions import OutputParserException
from langchain_core.output_parsers import BaseGenerationOutputParser
from langchain_core.outputs import ChatGeneration, Generation

class StrInvertCase(BaseGenerationOutputParser[str]):
    """反转消息字符大小写的解析器"""

    def parse_result(self, result: List[Generation], *, partial: bool = False) -> str:
        if len(result) != 1:
            raise NotImplementedError("此解析器仅支持单个生成结果。")
        generation = result[0]
        if not isinstance(generation, ChatGeneration):
            raise OutputParserException("此解析器仅支持聊天生成结果。")
        return generation.message.content.swapcase()

# 测试解析器
chain = model | StrInvertCase()
print(chain.invoke("Tell me a short sentence about yourself"))
# 输出: 'hELLO! mY NAME IS cLAUDE.'
```

---

### 总结

- **推荐方法**：使用 `RunnableLambda` 或 `RunnableGenerator`，因为它们更简单且与 LCEL 无缝集成。
- **高级方法**：继承 `BaseOutputParser` 或 `BaseGenerationOutputParser`，适用于需要更细粒度控制的场景。

希望这篇教程对你有所帮助！如果你有任何问题或需要进一步的帮助，请随时提问。

自定义解析

### 如何解析 YAML 输出

#### 前提条件
本教程假设你已经熟悉以下概念：

- 聊天模型
- 输出解析器
- 提示模板
- 结构化输出
- 将可运行对象串联在一起

不同提供商的 LLM（大型语言模型）通常根据其训练数据的不同而具有不同的优势。这也意味着某些模型在生成非 JSON 格式的输出时可能更“优秀”且更可靠。

本教程将介绍如何使用 YAML 格式来指定任意模式，并查询 LLM 以生成符合该模式的输出。

**注意**：请记住，大型语言模型是“有漏洞的抽象”！你需要使用具有足够能力的 LLM 来生成格式良好的 YAML。

#### 安装依赖
首先，我们需要安装必要的库：

```bash
%pip install -qU langchain langchain-openai
```

#### 设置 API 密钥
接下来，设置 OpenAI 的 API 密钥：

```python
import os
from getpass import getpass

if "OPENAI_API_KEY" not in os.environ:
    os.environ["OPENAI_API_KEY"] = getpass()
```

#### 定义数据模型
我们使用 Pydantic 和 `YamlOutputParser` 来定义数据模型，并为模型提供更多上下文，以便它知道应该生成什么类型的 YAML。

```python
from langchain.output_parsers import YamlOutputParser
from langchain_core.prompts import PromptTemplate
from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field

# 定义你期望的数据结构
class Joke(BaseModel):
    setup: str = Field(description="笑话的开头问题")
    punchline: str = Field(description="笑话的结尾答案")

# 初始化模型
model = ChatOpenAI(temperature=0)

# 定义一个查询，用于提示语言模型填充数据结构
joke_query = "给我讲个笑话。"

# 设置解析器，并将指令注入到提示模板中
parser = YamlOutputParser(pydantic_object=Joke)

prompt = PromptTemplate(
    template="回答用户查询。\n{format_instructions}\n{query}\n",
    input_variables=["query"],
    partial_variables={"format_instructions": parser.get_format_instructions()},
)

# 将提示、模型和解析器串联在一起
chain = prompt | model | parser

# 调用链并获取结果
result = chain.invoke({"query": joke_query})
print(result)
```

#### 解析器的格式指令
我们可以查看解析器的 `format_instructions`，这些指令会被添加到提示中：

```python
print(parser.get_format_instructions())
```

输出将包含如何格式化 YAML 的详细说明，确保输出符合指定的 JSON 模式。

#### 示例输出
假设模型返回了以下 YAML 格式的笑话：

```yaml
setup: "为什么自行车找不到回家的路？"
punchline: "因为它失去了方向感！"
```

解析器会自动解析 YAML 输出并创建一个包含数据的 Pydantic 模型。

#### 下一步
现在你已经学会了如何提示模型返回 YAML。接下来，你可以查看更广泛的指南，了解其他相关的结构化输出技术。

#### 总结
通过本教程，你学会了如何使用 `YamlOutputParser` 来解析 LLM 生成的 YAML 输出，并将其转换为 Pydantic 模型。这种方法在处理需要结构化输出的场景时非常有用，尤其是在 JSON 格式不适用的情况下。

希望这篇教程对你有所帮助！如果你有任何问题或需要进一步的帮助，请随时提问。

LLM格式化输出YAML

### 如何解析 XML 输出：使用 LangChain 和 Anthropic 的 Claude-2 模型

在本教程中，我们将学习如何使用 LangChain 和 Anthropic 的 Claude-2 模型生成 XML 格式的输出，并将其解析为更易用的格式。我们将逐步介绍如何设置环境、构建提示模板、调用模型并解析输出。

#### 前提条件
在开始之前，确保你已经熟悉以下概念：
- 聊天模型（Chat Models）
- 输出解析器（Output Parsers）
- 提示模板（Prompt Templates）
- 结构化输出（Structured Output）
- 将多个可运行组件链接在一起（Chaining Runnables）

此外，不同的大型语言模型（LLM）在处理特定数据时可能有不同的优势。某些模型在生成 XML 格式的输出时可能更为可靠。本教程将使用 Anthropic 的 Claude-2 模型，该模型在生成 XML 标签方面表现优异。

#### 安装依赖
首先，我们需要安装必要的 Python 包：

```bash
%pip install -qU langchain langchain-anthropic
```

#### 设置 API 密钥
接下来，设置 Anthropic 的 API 密钥：

```python
import os
from getpass import getpass

if "ANTHROPIC_API_KEY" not in os.environ:
    os.environ["ANTHROPIC_API_KEY"] = getpass("请输入你的 Anthropic API 密钥：")
```

#### 调用模型生成 XML 输出
我们从一个简单的请求开始，要求模型生成 Tom Hanks 的简短电影作品列表，并将每部电影用 `<movie>` 标签包裹。

```python
from langchain_anthropic import ChatAnthropic
from langchain_core.output_parsers import XMLOutputParser
from langchain_core.prompts import PromptTemplate

# 初始化模型
model = ChatAnthropic(model="claude-2.1", max_tokens_to_sample=512, temperature=0.1)

# 定义查询
actor_query = "生成 Tom Hanks 的简短电影作品列表。"

# 调用模型生成 XML 输出
output = model.invoke(
    f"""{actor_query}
请将每部电影用 <movie></movie> 标签包裹。"""
)

print(output.content)
```

输出结果可能如下：

```xml
<movie>Splash</movie>
<movie>Big</movie>
<movie>A League of Their Own</movie>
<movie>Sleepless in Seattle</movie>
<movie>Forrest Gump</movie>
<movie>Toy Story</movie>
<movie>Apollo 13</movie>
<movie>Saving Private Ryan</movie>
<movie>Cast Away</movie>
<movie>The Da Vinci Code</movie>
```

#### 使用 XMLOutputParser 解析输出
虽然模型生成了 XML 格式的输出，但我们希望将其解析为更易用的格式。我们可以使用 `XMLOutputParser` 来添加默认的格式指令，并将输出的 XML 解析为字典。

```python
# 初始化 XMLOutputParser
parser = XMLOutputParser()

# 获取格式指令
format_instructions = parser.get_format_instructions()

# 构建提示模板
prompt = PromptTemplate(
    template="""{query}\n{format_instructions}""",
    input_variables=["query"],
    partial_variables={"format_instructions": format_instructions},
)

# 将提示模板、模型和解析器链接在一起
chain = prompt | model | parser

# 调用链并解析输出
output = chain.invoke({"query": actor_query})
print(output)
```

输出结果可能如下：

```python
{'filmography': [{'movie': [{'title': 'Big'}, {'year': '1988'}]}, {'movie': [{'title': 'Forrest Gump'}, {'year': '1994'}]}, {'movie': [{'title': 'Toy Story'}, {'year': '1995'}]}, {'movie': [{'title': 'Saving Private Ryan'}, {'year': '1998'}]}, {'movie': [{'title': 'Cast Away'}, {'year': '2000'}]}]}
```

#### 自定义 XML 标签
我们还可以通过指定自定义标签来进一步定制输出。你可以根据需要添加或替换默认的格式指令。

```python
# 初始化 XMLOutputParser 并指定自定义标签
parser = XMLOutputParser(tags=["movies", "actor", "film", "name", "genre"])

# 获取格式指令
format_instructions = parser.get_format_instructions()

# 构建提示模板
prompt = PromptTemplate(
    template="""{query}\n{format_instructions}""",
    input_variables=["query"],
    partial_variables={"format_instructions": format_instructions},
)

# 将提示模板、模型和解析器链接在一起
chain = prompt | model | parser

# 调用链并解析输出
output = chain.invoke({"query": actor_query})
print(output)
```

输出结果可能如下：

```python
{'movies': [{'actor': [{'name': 'Tom Hanks'}, {'film': [{'name': 'Forrest Gump'}, {'genre': 'Drama'}]}, {'film': [{'name': 'Cast Away'}, {'genre': 'Adventure'}]}, {'film': [{'name': 'Saving Private Ryan'}, {'genre': 'War'}]}]}]}
```

#### 流式输出解析
`XMLOutputParser` 还支持流式输出解析。以下是一个示例：

```python
for s in chain.stream({"query": actor_query}):
    print(s)
```

输出结果可能如下：

```python
{'movies': [{'actor': [{'name': 'Tom Hanks'}]}]}
{'movies': [{'actor': [{'film': [{'name': 'Forrest Gump'}]}]}]}
{'movies': [{'actor': [{'film': [{'genre': 'Drama'}]}]}]}
{'movies': [{'actor': [{'film': [{'name': 'Cast Away'}]}]}]}
{'movies': [{'actor': [{'film': [{'genre': 'Adventure'}]}]}]}
{'movies': [{'actor': [{'film': [{'name': 'Saving Private Ryan'}]}]}]}
{'movies': [{'actor': [{'film': [{'genre': 'War'}]}]}]}
```

#### 下一步
现在你已经学会了如何提示模型生成 XML 输出并解析它。接下来，你可以查看更广泛的指南，了解如何获取结构化输出的其他相关技术。

希望这篇教程对你有所帮助！如果你有任何问题或建议，欢迎随时反馈。

LLM格式化输出XML

### 如何解析 JSON 输出  

#### 前提条件  
在阅读本教程之前，你需要对以下概念有一定的了解：  
- 聊天模型（Chat Models）  
- 输出解析器（Output Parsers）  
- 提示模板（Prompt Templates）  
- 结构化输出（Structured Output）  
- 将可运行对象链接在一起（Chaining Runnables Together）  

#### 为什么需要解析 JSON 输出？  
虽然一些模型提供商支持内置的方式返回结构化输出，但并非所有提供商都支持。我们可以使用输出解析器来帮助用户通过提示指定任意的 JSON 模式，查询模型以生成符合该模式的输出，并最终将该模式解析为 JSON。  

**注意**：大语言模型是“有漏洞的抽象”！你需要使用具有足够能力的 LLM 来生成格式良好的 JSON。  

`JsonOutputParser` 是一个内置选项，用于提示并解析 JSON 输出。虽然它在功能上与 `PydanticOutputParser` 类似，但它还支持流式返回部分 JSON 对象。  

以下是一个示例，展示如何与 Pydantic 结合使用，方便地声明预期的模式：  

---

#### 安装依赖  
```bash
%pip install -qU langchain langchain-openai
```

---

#### 示例代码  
```python
import os
from getpass import getpass

# 设置 OpenAI API 密钥
if "OPENAI_API_KEY" not in os.environ:
    os.environ["OPENAI_API_KEY"] = getpass()

from langchain_core.output_parsers import JsonOutputParser
from langchain_core.prompts import PromptTemplate
from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field

# 初始化模型
model = ChatOpenAI(temperature=0)

# 定义期望的数据结构
class Joke(BaseModel):
    setup: str = Field(description="笑话的开头问题")
    punchline: str = Field(description="笑话的结尾答案")

# 定义查询
joke_query = "Tell me a joke."

# 设置解析器并将指令注入提示模板
parser = JsonOutputParser(pydantic_object=Joke)

prompt = PromptTemplate(
    template="Answer the user query.\n{format_instructions}\n{query}\n",
    input_variables=["query"],
    partial_variables={"format_instructions": parser.get_format_instructions()},
)

# 构建链
chain = prompt | model | parser

# 调用链
result = chain.invoke({"query": joke_query})
print(result)
```

---

#### 输出示例  
```json
{
    "setup": "Why couldn't the bicycle stand up by itself?",
    "punchline": "Because it was two tired!"
}
```

---

#### 解析器的格式指令  
`parser.get_format_instructions()` 返回的指令如下：  
```plaintext
The output should be formatted as a JSON instance that conforms to the JSON schema below.

As an example, for the schema {"properties": {"foo": {"title": "Foo", "description": "a list of strings", "type": "array", "items": {"type": "string"}}}, "required": ["foo"]}
the object {"foo": ["bar", "baz"]} is a well-formatted instance of the schema. The object {"properties": {"foo": ["bar", "baz"]}} is not well-formatted.

Here is the output schema:
```json
{
    "properties": {
        "setup": {"title": "Setup", "description": "question to set up a joke", "type": "string"},
        "punchline": {"title": "Punchline", "description": "answer to resolve the joke", "type": "string"}
    },
    "required": ["setup", "punchline"]
}
```

你可以尝试在提示的其他部分添加自己的格式化提示，以增强或替换默认指令。  

---

#### 流式输出  
`JsonOutputParser` 支持流式返回部分 JSON 对象。以下是一个流式输出的示例：  

```python
for s in chain.stream({"query": joke_query}):
    print(s)
```

输出示例：  
```json
{}
{'setup': ''}
{'setup': 'Why'}
{'setup': 'Why couldn'}
{'setup': "Why couldn't"}
{'setup': "Why couldn't the"}
{'setup': "Why couldn't the bicycle"}
{'setup': "Why couldn't the bicycle stand"}
{'setup': "Why couldn't the bicycle stand up"}
{'setup': "Why couldn't the bicycle stand up by"}
{'setup': "Why couldn't the bicycle stand up by itself"}
{'setup': "Why couldn't the bicycle stand up by itself?"}
{'setup': "Why couldn't the bicycle stand up by itself?", 'punchline': ''}
{'setup': "Why couldn't the bicycle stand up by itself?", 'punchline': 'Because'}
{'setup': "Why couldn't the bicycle stand up by itself?", 'punchline': 'Because it'}
{'setup': "Why couldn't the bicycle stand up by itself?", 'punchline': 'Because it was'}
{'setup': "Why couldn't the bicycle stand up by itself?", 'punchline': 'Because it was two'}
{'setup': "Why couldn't the bicycle stand up by itself?", 'punchline': 'Because it was two tired'}
{'setup': "Why couldn't the bicycle stand up by itself?", 'punchline': 'Because it was two tired!'}
```

---

#### 不使用 Pydantic  
你也可以在不使用 Pydantic 的情况下使用 `JsonOutputParser`。这会提示模型返回 JSON，但不提供关于模式的具体信息。  

```python
joke_query = "Tell me a joke."

parser = JsonOutputParser()

prompt = PromptTemplate(
    template="Answer the user query.\n{format_instructions}\n{query}\n",
    input_variables=["query"],
    partial_variables={"format_instructions": parser.get_format_instructions()},
)

chain = prompt | model | parser

result = chain.invoke({"query": joke_query})
print(result)
```

输出示例：  
```json
{
    "response": "Sure! Here's a joke for you: Why couldn't the bicycle stand up by itself? Because it was two tired!"
}
```

---

#### 下一步  
现在你已经学会了如何解析 JSON 输出。接下来，你可以查看以下指南：  
- [如何让模型返回结构化输出](https://example.com)  
- [如何创建自定义聊天模型](https://example.com)  

希望这篇教程对你有帮助！如果有任何问题，欢迎留言讨论~ 🚀
```

LLM 格式化输出Json

### 如何从模型中返回结构化数据

在实际应用中，我们经常需要让模型返回符合特定结构的数据。比如，从文本中提取信息并插入到数据库中，或者用于其他下游系统。本文将介绍几种从模型中获取结构化输出的策略。

#### 使用 `.with_structured_output()` 方法

**支持的模型**  
你可以在这里找到支持该方法的模型列表。

这是获取结构化输出最简单且最可靠的方法。`with_structured_output()` 方法利用了模型的原生 API（如工具/函数调用或 JSON 模式），并在此基础上实现结构化输出。

该方法接受一个模式（schema）作为输入，该模式指定了输出属性的名称、类型和描述。方法返回一个类似模型的 `Runnable`，但它输出的不是字符串或消息，而是与给定模式对应的对象。模式可以是一个 `TypedDict` 类、JSON Schema 或 Pydantic 类。如果使用 `TypedDict` 或 JSON Schema，`Runnable` 将返回一个字典；如果使用 Pydantic 类，则返回一个 Pydantic 对象。

**示例：生成笑话并分离笑点和笑料**

首先，我们选择一个聊天模型并安装必要的库：

```bash
pip install -qU "langchain[groq]"
```

然后，设置 API 密钥并初始化模型：

```python
import getpass
import os

if not os.environ.get("GROQ_API_KEY"):
  os.environ["GROQ_API_KEY"] = getpass.getpass("Enter API key for Groq: ")

from langchain.chat_models import init_chat_model

llm = init_chat_model("llama3-8b-8192", model_provider="groq")
```

**使用 Pydantic 类**  
如果我们希望模型返回一个 Pydantic 对象，只需传入所需的 Pydantic 类。使用 Pydantic 的主要优势是，模型生成的输出将被验证。如果缺少任何必填字段或字段类型错误，Pydantic 将抛出错误。

```python
from typing import Optional
from pydantic import BaseModel, Field

class Joke(BaseModel):
    """笑话内容"""
    setup: str = Field(description="笑话的开头")
    punchline: str = Field(description="笑话的笑点")
    rating: Optional[int] = Field(default=None, description="笑话的有趣程度，1到10分")

structured_llm = llm.with_structured_output(Joke)
structured_llm.invoke("讲一个关于猫的笑话")
```

输出示例：

```python
Joke(setup='为什么猫坐在电脑上？', punchline='因为它想盯着鼠标！', rating=7)
```

**使用 TypedDict 或 JSON Schema**  
如果你不想使用 Pydantic，或者不想验证参数，或者希望能够流式传输模型输出，可以使用 `TypedDict` 类来定义模式。我们还可以使用 LangChain 支持的 `Annotated` 语法来指定字段的默认值和描述。

```python
from typing import Optional
from typing_extensions import Annotated, TypedDict

class Joke(TypedDict):
    """笑话内容"""
    setup: Annotated[str, ..., "笑话的开头"]
    punchline: Annotated[str, ..., "笑话的笑点"]
    rating: Annotated[Optional[int], None, "笑话的有趣程度，1到10分"]

structured_llm = llm.with_structured_output(Joke)
structured_llm.invoke("讲一个关于猫的笑话")
```

输出示例：

```python
{'setup': '为什么猫坐在电脑上？', 'punchline': '因为它想盯着鼠标！', 'rating': 7}
```

**使用 JSON Schema**  
我们也可以直接传入一个 JSON Schema 字典。这种方式不需要导入任何类，且能清晰地展示每个参数的文档，但会稍微冗长一些。

```python
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"],
}

structured_llm = llm.with_structured_output(json_schema)
structured_llm.invoke("讲一个关于猫的笑话")
```

输出示例：

```python
{'setup': '为什么猫坐在电脑上？', 'punchline': '因为它想盯着鼠标！', 'rating': 7}
```

**在多个模式之间选择**  
最简单的让模型在多个模式之间选择的方法是创建一个包含 `Union` 类型属性的父模式。

**使用 Pydantic**  
```python
from typing import Union

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]

structured_llm = llm.with_structured_output(FinalResponse)
structured_llm.invoke("讲一个关于猫的笑话")
```

输出示例：

```python
FinalResponse(final_output=Joke(setup='为什么猫坐在电脑上？', punchline='因为它想盯着鼠标！', rating=7))
```

**使用 TypedDict**  
```python
from typing import Optional, Union
from typing_extensions import Annotated, TypedDict

class Joke(TypedDict):
    """笑话内容"""
    setup: Annotated[str, ..., "笑话的开头"]
    punchline: Annotated[str, ..., "笑话的笑点"]
    rating: Annotated[Optional[int], None, "笑话的有趣程度，1到10分"]

class ConversationalResponse(TypedDict):
    """以对话方式回应。保持友好和乐于助人。"""
    response: Annotated[str, ..., "对用户查询的对话式回应"]

class FinalResponse(TypedDict):
    final_output: Union[Joke, ConversationalResponse]

structured_llm = llm.with_structured_output(FinalResponse)
structured_llm.invoke("讲一个关于猫的笑话")
```

输出示例：

```python
{'final_output': {'setup': '为什么猫坐在电脑上？', 'punchline': '因为它想盯着鼠标！', 'rating': 7}}
```

**流式传输**  
当输出类型为字典时（即模式为 `TypedDict` 类或 JSON Schema 字典），我们可以流式传输结构化模型的输出。

```python
from typing_extensions import Annotated, TypedDict

class Joke(TypedDict):
    """笑话内容"""
    setup: Annotated[str, ..., "笑话的开头"]
    punchline: Annotated[str, ..., "笑话的笑点"]

structured_llm = llm.with_structured_output(Joke)
for chunk in structured_llm.stream("讲一个关于猫的笑话"):
    print(chunk)
```

输出示例：

```python
{'setup': '为什么猫坐在电脑上？', 'punchline': '因为它想盯着鼠标！'}
```

**（高级）原始输出**  
LLM 在生成结构化输出时并不完美，尤其是当模式变得复杂时。你可以通过传递 `include_raw=True` 来避免抛出异常，并自行处理原始输出。这将更改输出格式，包含原始消息输出、解析后的值（如果成功）以及任何错误。

```python
structured_llm = llm.with_structured_output(Joke, include_raw=True)
structured_llm.invoke("讲一个关于猫的笑话")
```

输出示例：

```python
{'raw': AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'call_f25ZRmh8u5vHlOWfTUw8sJFZ', 'function': {'arguments': '{"setup":"为什么猫坐在电脑上？","punchline":"因为它想盯着鼠标！","rating":7}', 'name': 'Joke'}, 'type': 'function'}]}, response_metadata={'token_usage': {'completion_tokens': 33, 'prompt_tokens': 93, 'total_tokens': 126}, 'model_name': 'gpt-4o-2024-05-13', 'system_fingerprint': 'fp_4e2b2da518', 'finish_reason': 'stop', 'logprobs': None}, id='run-d880d7e2-df08-4e9e-ad92-dfc29f2fd52f-0', tool_calls=[{'name': 'Joke', 'args': {'setup': '为什么猫坐在电脑上？', 'punchline': '因为它想盯着鼠标！', 'rating': 7}, 'id': 'call_f25ZRmh8u5vHlOWfTUw8sJFZ', 'type': 'tool_call'}], usage_metadata={'input_tokens': 93, 'output_tokens': 33, 'total_tokens': 126}),
 'parsed': {'setup': '为什么猫坐在电脑上？', 'punchline': '因为它想盯着鼠标！', 'rating': 7},
 'parsing_error': None}
```

**直接提示和解析模型输出**  
并非所有模型都支持 `.with_structured_output()`，因为并非所有模型都支持工具调用或 JSON 模式。对于这些模型，你需要直接提示模型使用特定格式，并使用输出解析器从原始模型输出中提取结构化响应。

**使用 PydanticOutputParser**  
以下示例使用内置的 `PydanticOutputParser` 来解析聊天模型的输出，并提示其匹配给定的 Pydantic 模式。

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

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 = ChatPromptTemplate.from_messages([
    ("system", "回答用户查询。将输出包装在 `json` 标签中\n{format_instructions}"),
    ("human", "{query}"),
]).partial(format_instructions=parser.get_format_instructions())

# 查看发送给模型的信息
query = "安娜23岁，身高6英尺"
print(prompt.invoke({"query": query}).to_string())

# 调用模型
chain = prompt | llm | parser
chain.invoke({"query": query})
```

输出示例：

```python
People(people=[Person(name='安娜', height_in_meters=1.8288)])
```

**自定义解析**  
你还可以使用 LangChain 表达式语言（LCEL）创建自定义提示和解析器，使用普通函数解析模型输出。

```python
import json
import re
from typing import List
from langchain_core.messages import AIMessage
from langchain_core.prompts import ChatPromptTemplate
from pydantic import BaseModel, Field

class Person(BaseModel):
    """个人信息"""
    name: str = Field(..., description="姓名")
    height_in_meters: float = Field(..., description="身高，以米为单位")

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

# 提示模板
prompt = ChatPromptTemplate.from_messages([
    ("system", "回答用户查询。输出你的答案作为 JSON，并匹配以下模式：\`\`\`json\n{schema}\n\`\`\`。确保将答案包装在 \`\`\`json 和 \`\`\` 标签中"),
    ("human", "{query}"),
]).partial(schema=People.schema())

# 自定义解析器
def extract_json(message: AIMessage) -> List[dict]:
    """从包含 JSON 的字符串中提取 JSON 内容。"""
    text = message.content
    pattern = r"\`\`\`json(.*?)\`\`\`"
    matches = re.findall(pattern, text, re.DOTALL)
    try:
        return [json.loads(match.strip()) for match in matches]
    except Exception:
        raise ValueError(f"解析失败: {message}")

# 查看发送给模型的信息
query = "安娜23岁，身高6英尺"
print(prompt.format_prompt(query=query).to_string())

# 调用模型
chain = prompt | llm | extract_json
chain.invoke({"query": query})
```

输出示例：

```python
[{'people': [{'name': '安娜', 'height_in_meters': 1.8288}]}]
```

通过以上方法，你可以灵活地从模型中获取结构化数据，并根据需求进行进一步处理。