🎯 课程主题

掌握 Pydantic 高级特性中的可选字段（Optional）、默认值（Default）、枚举类型（Enum/Literal）的使用方法及平台差异。

📝 核心知识点

1. 可选字段 Optional

  • 概念说明：使用 Optional[类型] 声明字段为可选的。当输入信息中未提及该字段时，值为 None。
  • 关键细节：
    • 不加 Optional 时，缺少的 int 字段会被默认赋值为 0（令人困惑）
    • 加上 Optional[int] 后，缺少的字段值为 None（语义更明确）
    • 例如：信息为"张三是一名软件工程师"（未提年龄），Optional[int] 的 age 为 None，普通 int 的 age 为 0

2. 默认值 Field(default=...)

  • 概念说明：通过 Field(default=值) 为字段设置默认值，当模型未提供该字段时使用默认值。
  • 关键细节（平台差异是核心）：
    • CloseAI 平台（如 GPT-4o-mini）：不支持 Field(default=...)，默认值会被忽略
    • OpenRouter 平台（同款 GPT-4o-mini）：支持 Field(default=...)，默认值生效

注意区分 Field(default=10) （设置默认值）和 Prompt 中写"默认值为10"（提示词诱导），这是两个完全不同的概念。

3. 枚举类型 Enum

  • 概念说明：当字段只能从有限值中选取时，定义枚举类型约束取值范围。
  • 两种实现方式：
    • 方式一：class Priority(str, Enum) 继承 Enum，定义 LOW/MEDIUM/HIGH 常量
    • 方式二：使用 Literal["低", "中", "高"] 直接指定字面量
  • 关键细节：两种方式都能达到约束目的，任选其一；枚举方式更规范，Literal 更简洁

🏗️ 架构与工作流

💻 代码实战

可选字段示例

from typing import Optional
from pydantic import BaseModel, Field

class Person(BaseModel):
    """人物的信息"""
    name: str = Field(description="姓名")
    age: Optional[int] = Field(description="年龄")  # 可选字段
    occupation: str = Field(description="职业")

# 输入未提及年龄
result = structured_model.invoke("张三是一名软件工程师")
print(result.age)  # None（而非 0）

默认值示例

class Person(BaseModel):
    name: str = Field(description="姓名")
    age: int = Field(default=10, description="年龄")  # 默认值为10
    occupation: str = Field(description="职业")

# OpenRouter 平台：未提年龄时 age=10
# CloseAI 平台：未提年龄时 age=0（默认值被忽略）

枚举类型示例

from enum import Enum
from pydantic import BaseModel, Field

class Priority(str, Enum):
    LOW = "低"
    MEDIUM = "中"
    HIGH = "高"

class CustomerInfo(BaseModel):
    """客户信息"""
    name: str = Field(description="姓名")
    phone: str = Field(description="电话")
    email: Optional[str] = Field(description="邮箱")
    issue: str = Field(description="问题描述")
    priority: Priority = Field(description="紧急程度")

# 使用 Literal 的等价写法
from typing import Literal

class CustomerInfo(BaseModel):
    priority: Literal["低", "中", "高"] = Field(description="紧急程度")

⚠️ 常见问题与避坑指南

  • Optional 与默认值的区别：Optional[int] 的 None 是类型层面"可空"，Field(default=10) 是值层面"缺省赋值"，两者可组合使用
  • CloseAI 不支持默认值：生产环境如依赖默认值行为，需选择 OpenRouter 或其他支持的平台
  • 不要用 Field(default=10) 和 Prompt 诱导混淆：前者是真实默认值机制，后者只是提示词技巧
  • OpenRouter 使用门槛：需要充值（最低10美金）和科学上网；CloseAI 平台无需此限制

💡 个人总结与延伸

这三个特性在实际项目中非常实用：Optional 让模型可以"跳过"未提及的信息、Enum 约束了自由文本的取值空间、默认值则提供了兜底方案。最关键的是平台差异——同样的 GPT-4o-mini 模型，在 CloseAI 和 OpenRouter 上对默认值的支持竟然不同。这提醒我们：API 网关的实现细节也会影响 LangChain 特性，选型时需要充分测试。

最近更新:
Contributors: yangwenguang