系列 《Python 在 AI-Infra:从语言机制到生产交付》 第 9 / 15 篇 进阶
系列总览 — 为什么这样组织、读它需要什么、读完能做什么 · 幻灯片 — 整个系列的精华,一份可分享的 deck
学习地图 — AI-Infra 工程师学习地图 第 1 / 14 个系列
上一篇:类型系统(中)——类型信息的分发与消费下一篇:并发、异步与任务协作
前两篇沿着”类型信息如何流动”展开:《类型表达与 typing 工具箱》讲怎么写(typing 工具箱),《类型信息的分发与消费》讲怎么分发、谁消费(存根、mypy、运行时读注解)。本篇的组织轴切换——不再讨论类型信息本身,而是讨论用这些能力去构建什么:数据契约。
所谓数据契约,就是对”一组数据长什么样”的正式约定。在 AI Infra 里它无处不在:推理服务的请求体与响应体、训练任务的配置文件、模型仓库里的元数据、Worker 之间传递的消息。Java 工程师熟悉的 Bean Validation、Jackson、@ConfigurationProperties 在这里对应的是 @dataclass、Pydantic BaseModel、BaseSettings——但它们不是一一对应的翻译,而是同一份类型注解的三种消费方式,各有适用位置。
本篇围绕的核心问题是:
什么时候用
@dataclass、什么时候上 Pydantic、什么时候TypedDict就够?校验该发生在哪里,序列化与配置怎么跟着契约走?1
答案的骨架是中篇末尾那句话——边界要校验,内部要干净:外部数据进门时用 Pydantic 解析和校验,内部可以用不自动校验的 @dataclass 传递,由 mypy 检查代码中的类型使用。内部对象若仍会被修改,业务不变量还需要由接口和测试维护,注解不会替程序兜底。
一、总览
本篇沿着一份推理配置的生命周期展开:启动代码读取配置,Pydantic 解析并校验,调度器消费内部对象,API 或运维工具再把它导出。先看数据在哪一步跨过边界,再选承载它的类型。
1. 在三篇地图上的位置
本篇讲图里最下面那格。它使用前两格的能力,但组织轴不同:前两格沿着”类型信息如何流动”,这一格沿着”程序的数据结构如何设计”。
2. 一份推理配置从输入到消费
后面的例子用 model_name="llama-3"、max_tokens="32" 这组配置:文件或 HTTP 请求带来的 "32" 还是字符串,调度器需要的是受范围约束的整数;服务端口则由 Settings() 在启动时从环境变量等来源取得。
%% 图:推理配置在启动入口、请求入口与内部调度之间的数据流
flowchart TB
FILE["配置文件 dict / HTTP JSON<br/>max_tokens 是字符串 32"] --> LOAD["启动代码 / FastAPI<br/>调用 model_validate 或请求校验"]
ENV["环境变量 / .env / 默认值<br/>PORT 等启动参数"] --> SET["启动时调用 Settings()<br/>先选择来源,再解析并校验"]
LOAD --> VALID{"Pydantic 校验通过?"}
SET --> VALID
VALID -- "否" --> FAIL["构造失败或请求校验错误<br/>启动代码 / API 处理异常"]
VALID -- "是" --> MODEL["内存中的配置模型<br/>max_tokens / PORT 为整数"]
MODEL -- "显式构建内部数据" --> DC["dataclass / 引擎参数对象<br/>调度器读取已检查的字段"]
MODEL -- "model_dump / model_dump_json" --> OUTPUT["dict / JSON<br/>交给 API、日志或配置文件写入代码"]
- 读取不等于校验:JSON / YAML 解析器只负责读出数据;
BaseModel才按字段约束检查它。 - 模型不自动落盘:对象存在进程内存里,
model_dump_json()返回字符串;写文件或发响应仍由调用方完成。 - 转换内部结构是一次设计选择:需要方法、内部状态或大量轻量实例时用 dataclass;没有性能或职责上的收益时,也可以继续传递已经校验的模型。
3. 本文的章节安排
| 章 | 主题 | 内容 |
|---|---|---|
| 二 | 工程落地:数据契约设计 | dataclass、Pydantic、序列化与 Schema、BaseSettings、选型指南 |
| 三 | 附录 | 类型工具选择决策树;Java 与 Python 数据契约对照 |
| 四 | 本文小结 | |
| 五 | 自测 | 3 道题 |
二、工程落地:数据契约设计
同样是数据契约,输入来源和消费方不同,校验位置也不同:
- 请求体:
/v1/chat/completions收到的 JSON 应该有哪些字段、什么类型、什么取值范围; - 配置项:从
.env、YAML 读进来的一堆字符串,怎么变成强类型的配置对象; - 模型元数据:模型名、量化方式、并行度、KV cache 配置在进程间传递时的形状;
- 内部数据结构:一次推理请求在引擎内部流转时携带的上下文。
在 Java 里这件事由多个技术栈拼起来:Lombok / record 消除模板代码,Bean Validation 做校验,Jackson 做序列化,@ConfigurationProperties 做配置绑定。Python 则高度收敛——@dataclass 和 Pydantic 两个工具覆盖了绝大部分场景。看一眼 Pydantic 模型的定义:
from pydantic import BaseModel, Field
from typing import Annotated, Literal
class InferenceConfig(BaseModel):
model_name: str
backend: Literal["cuda", "rocm", "cpu"]
max_tokens: Annotated[int, Field(ge=1, le=32768)] = 2048
temperature: Annotated[float, Field(ge=0.0, le=2.0)] = 1.0
top_p: float = 1.0
这一个类定义同时做了三件事:
- 静态类型检查:mypy/pyright 能检查代码中对
InferenceConfig字段的使用; - 运行时校验:通过普通构造或
model_validate()进入模型的数据,会按约束解析、转换并校验(ge=1、le=32768); - 文档 / Schema 生成:把模型用于 FastAPI 路由后,框架将其 Schema 纳入 OpenAPI 文档。
这就是”数据契约”的价值——一处声明,三处受益。而它能成立,靠的正是《类型信息的分发与消费》第四章讲的机制。
config = InferenceConfig.model_validate(
{"model_name": "llama-3", "backend": "cuda", "max_tokens": "32"}
)
print(config.max_tokens, type(config.max_tokens).__name__) # 32 int
这里使用 Python 3.10–3.12 的常见写法,Pydantic API 均按 v2;BaseSettings 来自独立的 pydantic-settings 包。
前置阅读:如果你想先搞清楚
@dataclass和 Pydantic 怎么读到类型注解、exec代码生成和元类分别在什么时机介入,见《类型信息的分发与消费》第四章「类型信息消费层(下):动态消费」的”框架如何消费注解”一节。本章只讲用法与取舍。
1. dataclass:标准库的数据类
从原生 __init__ 到 @dataclass
最传统的写法是显式定义构造函数:
class User:
def __init__(self, id: int, name: str, email: str):
self.id = id
self.name = name
self.email = email
问题很明显:大量 self.x = x 的模板代码。字段一多就难以维护,而且还要手写 __repr__、__eq__ 才能方便调试和比较。
Python 3.7 引入的数据类消除了这些样板。它利用类变量类型标注(PEP 526)语法:
from dataclasses import dataclass
@dataclass
class User:
id: int
name: str
email: str
实例化方式不变,但 __init__、__repr__、__eq__ 都自动有了:
user = User(id=1, name="Alice", email="alice@example.com")
print(user) # User(id=1, name='Alice', email='alice@example.com')
print(user == User(1, "Alice", "alice@example.com")) # True
与 Java 对照:数据载体与 record
Lombok @Data 为普通类生成访问器、比较等方法;Java 16 正式引入的 record 则是另一种数据载体(Java 14、15 为预览)。下面是可单独保存为 User.java 的 Java 16+ 定义:
public record User(Long id, String name, String email) {}
使用 Lombok 的项目也可以保留普通类(下面是另一份 User.java,需要 Lombok 依赖和注解处理器):
import lombok.Data;
@Data
public class User {
private Long id;
private String name;
private String email;
}
默认的 Python dataclass 可以修改字段,不等于 record;两者也都不会仅凭字段类型声明完成外部 JSON 的解析和业务校验。
__post_init__ 手工校验及其局限
@dataclass 不按字段注解做运行时类型校验——它主要把注解当作生成方法的字段清单,也会特殊识别 ClassVar、InitVar 等标记。所以下面这行不会报错:
user = User(id="abc", name=123, email=None) # 静默通过
如果需要校验,可以借助 __post_init__ 钩子(自动生成的 __init__ 完成字段赋值后调用):
from dataclasses import dataclass
import re
@dataclass
class User:
id: int
name: str
email: str
def __post_init__(self):
# 1. 手动校验类型
if not isinstance(self.id, int):
raise TypeError("id 必须是 int 类型")
# 2. 手动用正则校验邮箱
if not re.match(r"^[\w\.-]+@[\w\.-]+\.\w+$", self.email):
raise ValueError("邮箱格式不正确")
这条路能走通,但代价很快显现:
- 逐字段手写:每个字段的类型、范围、格式都要自己
if; - 不做类型转换:外部传进来的
"123"不会变成123,只能自己转; - 错误不聚合:第一个
raise就中断了,用户看不到全部问题; - 与注解脱节:注解写
int,校验逻辑另写一遍,两边可能不一致。
与 Java 对照:载体声明不自动校验
Java record 可以在构造器里手写校验,但仅声明 record 或使用 Lombok @Data 不会自动校验外部输入。Bean Validation 与 Python 的 Pydantic 都是在载体之外安排约束和执行时机,触发方式有所不同。
frozen 与 slots
两个常用参数:
from dataclasses import dataclass
# frozen=True:阻止普通字段赋值;默认 eq=True 时还会生成 __hash__
@dataclass(frozen=True)
class ModelKey:
model_name: str
revision: str
key = ModelKey("llama-3", "main")
# key.revision = "dev" # 报错:FrozenInstanceError
cache: dict[ModelKey, object] = {key: ...} # 可以做 dict 的 key
# slots=True(3.10+):用槽位存储属性,省去 __dict__
@dataclass(slots=True)
class RequestContext:
request_id: str
model_name: str
deadline: float
frozen=True 限制的是字段重新赋值,不是深度不可变。字段若是列表,仍能 append();默认生成的哈希若遇到列表字段,也会抛 TypeError。上面的 ModelKey 全部使用字符串,所以适合作为字典键。slots=True 在本例没有基类实例字典时省去 __dict__;有基类提供字典时不能照搬这个结论。
与 Java 对照:浅层不可变与实例存储
Java record 的组件引用不能重新赋值,但引用指向的列表仍然能变;这一点与 frozen=True 的浅层限制相近。两者都不自动保证跨线程共享安全。slots=True 则用于控制 Python 实例的属性存储,没有对应的 Java 声明开关。
__slots__的内存收益取决于对象数量和字段类型,详见《Python 内存管理与优化》。
2. Pydantic:带校验的数据模型
Pydantic 是 FastAPI 常用的运行时数据校验库,把数据建模、类型转换、校验和导出放在同一模型上。它覆盖了 Java record、Bean Validation、Jackson 的部分职责,具体触发条件仍需分别理解。
BaseModel 基础与类型强制转换
from pydantic import BaseModel, EmailStr
class User(BaseModel):
id: int
name: str
email: EmailStr
与 @dataclass 最大的差别是它真的会校验,并且会转换:
# 自动校验 + 类型转换(coercion)
user = User(id="1", name="Alice", email="alice@example.com")
print(user.id, type(user.id)) # 1 <class 'int'> ← 字符串 "1" 被转成了 int
# 校验失败时抛出详细错误
User(id="abc", name="Bob", email="not-an-email")
# pydantic_core.ValidationError: 2 validation errors for User
# id
# Input should be a valid integer, unable to parse string as an integer
# email
# value is not a valid email address
注意两点:一是 EmailStr 需要安装可选依赖 email-validator(可用 pip install 'pydantic[email]');二是普通字段校验能聚合多个错误,而不是遇到第一个就中断——这正是《类型信息的分发与消费》第四章提到的”收集所有错误路径”。
Field:默认值与约束
Field() 用来表达注解本身表达不了的约束(范围、长度、正则):
from pydantic import BaseModel, EmailStr, Field
class User(BaseModel):
id: int
email: EmailStr
# 1. 基础默认值:不传时默认为 "user"
role: str = "user"
# 2. 完全可选字段:允许为 None,不传时默认就是 None
bio: str | None = None
# 3. 业务边界约束
name: str = Field(default="Anonymous", min_length=2, max_length=20)
age: int = Field(default=18, ge=0, le=120)
约束也可以写在 Annotated 里,这是 Pydantic v2 更推荐的形式,因为它让类型和元数据分离得更干净(见《类型表达与 typing 工具箱》第二章「类型信息提供层(上):类型表达」的 Annotated 一节):
from typing import Annotated
from pydantic import BaseModel, Field
class UserProfile(BaseModel):
name: Annotated[str, Field(min_length=2, max_length=20)] = "Anonymous"
age: Annotated[int, Field(ge=0, le=120)] = 18
与 Java 对照:谁触发 Bean Validation
下列 Java 16+ record 需要 Jakarta Validation API;真正执行校验还需要 Hibernate Validator 等实现:
import jakarta.validation.constraints.*;
public record User(
@NotNull Long id,
@Size(min = 2, max = 20) String name,
@Email @NotBlank String email,
@Min(0) @Max(120) Integer age
) {}
new User(...) 本身不触发 Bean Validation。可以显式调用 validator.validate(user),也可以交给 Spring MVC 等集成在请求入口触发;@Valid 还用于级联校验,不是通用的“开启切面”开关。
Pydantic 的普通构造路径默认校验,但可以绕过:model_construct() 用于已可信数据;model_copy(update=...) 的更新值不重新校验;字段赋值默认也不重校验,需要时开启 ConfigDict(validate_assignment=True)。默认还允许部分类型转换,严格边界可使用 model_validate(raw, strict=True)。这些都是库行为,不是 Python 注解的语言保证。
ValidationError 与错误聚合
Pydantic 抛出的 ValidationError 是结构化的,可以直接转成 API 响应:
from pydantic import BaseModel, EmailStr, Field, ValidationError
class User(BaseModel):
id: int
email: EmailStr
age: int = Field(ge=0, le=120)
try:
User(id="abc", email="bad", age=200)
except ValidationError as e:
print(e.error_count()) # 3
for err in e.errors():
print(err["loc"], err["type"], err["msg"])
# ('id',) int_parsing Input should be a valid integer...
# ('email',) value_error value is not a valid email address
# ('age',) less_than_equal Input should be less than or equal to 120
loc 是字段路径,嵌套模型时会是 ("items", 0, "name") 这样的元组,能精确定位到出错位置。FastAPI 会把请求校验错误包装成响应;模型其他位置抛出的 ValidationError 不会都自动变成 HTTP 422。
AI-Infra 实例
# 结构摘录:省略 vLLM 的导入、基类定义与路由依赖,不是独立脚本
# vLLM: vllm/entrypoints/openai/protocol.py
class ChatCompletionRequest(OpenAIBaseModel):
model: str
messages: list[ChatCompletionMessageParam]
temperature: float | None = None
max_tokens: int | None = None
stream: bool | None = False
# FastAPI 路由直接使用 Pydantic 模型
@app.post("/v1/chat/completions")
async def create_chat_completion(request: ChatCompletionRequest):
# FastAPI 已按请求模型完成输入校验
...
与 Java 对照:请求体、校验与文档
Spring MVC 常用 @RequestBody 解析 JSON、@Valid 触发校验,再由 springdoc 生成文档。FastAPI 集中读取函数签名和 Pydantic 模型来组织这些步骤,框架仍需注册路由,并维护模型未表达的业务约束。
3. 序列化、反序列化与 Schema 生成
数据契约不只是”在内存里长什么样”,还包括怎么进来、怎么出去、怎么被外部理解。这是 Pydantic 相比 @dataclass 的另一个主要优势。
model_dump 与 model_dump_json
config = InferenceConfig(model_name="llama-3", backend="cuda")
print(config.model_dump()) # 导出成 Python 字典
print(config.model_dump_json()) # 导出成 JSON 字符串
print(config.model_dump(exclude={"top_p"})) # 排除字段
print(config.model_dump(exclude_defaults=True)) # 排除值等于默认值的字段
{'model_name': 'llama-3', 'backend': 'cuda', 'max_tokens': 2048, 'temperature': 1.0, 'top_p': 1.0}
{"model_name":"llama-3","backend":"cuda","max_tokens":2048,"temperature":1.0,"top_p":1.0}
{'model_name': 'llama-3', 'backend': 'cuda', 'max_tokens': 2048, 'temperature': 1.0}
{'model_name': 'llama-3', 'backend': 'cuda'}
另外两个常用选项:exclude_unset=True 排除没有显式设置的字段,mode="json" 把 datetime、UUID 等转成 JSON 可序列化的形式。
@dataclass 也能序列化,但要自己动手,且不处理嵌套的非 JSON 原生类型:
from dataclasses import asdict, dataclass
from datetime import datetime
import json
@dataclass
class Event:
created_at: datetime
try:
json.dumps(asdict(Event(datetime(2026, 1, 25))))
except TypeError as exc:
print(type(exc).__name__) # TypeError
与 Java 对照:对象转 JSON
model_dump_json() 的用途接近 Jackson 的 ObjectMapper.writeValueAsString();字段选择可以用模型配置或导出参数表达。model_dump() 默认返回 Python 对象,可能仍含 datetime,不等于已经得到 JSON。
model_json_schema 与 OpenAPI
import pprint
pprint.pprint(InferenceConfig.model_json_schema(), width=88, sort_dicts=False)
{'properties': {'model_name': {'title': 'Model Name', 'type': 'string'},
'backend': {'enum': ['cuda', 'rocm', 'cpu'],
'title': 'Backend',
'type': 'string'},
'max_tokens': {'default': 2048,
'maximum': 32768,
'minimum': 1,
'title': 'Max Tokens',
'type': 'integer'},
'temperature': {'default': 1.0,
'maximum': 2.0,
'minimum': 0.0,
'title': 'Temperature',
'type': 'number'},
'top_p': {'default': 1.0, 'title': 'Top P', 'type': 'number'}},
'required': ['model_name', 'backend'],
'title': 'InferenceConfig',
'type': 'object'}
注意 Literal["cuda", "rocm", "cpu"] 被翻译成了 JSON Schema 的 enum,Field(ge=1, le=32768) 变成了 minimum/maximum。FastAPI 把这些 Schema 组合进 OpenAPI,再提供 /docs 页面;自定义 Python 校验逻辑未必都能表达成 JSON Schema,不能认为文档包含了全部运行时规则。
与 Java 对照:Schema 生成
springdoc 可以读取 Java 类型和部分 Bean Validation 约束生成 Schema,需要额外描述时再加 Swagger 注解。两边都应检查生成结果,自定义校验规则不会自动完整翻译成跨语言契约。
解析 YAML / JSON 配置文件
AI-Infra 项目大量使用 YAML 配置(vLLM 的引擎参数、DeepSpeed 的并行策略、训练任务的超参)。裸读 YAML 得到的是一个 dict[str, Any],类型信息全丢——这正是数据契约要解决的问题。
model_validate() 尝试把读出的数据解析为模型;字段不满足约束时抛出 ValidationError:
import yaml
from pydantic import BaseModel, Field
from typing import Literal
class ParallelConfig(BaseModel):
tensor_parallel_size: int = Field(default=1, ge=1)
pipeline_parallel_size: int = Field(default=1, ge=1)
class ServingConfig(BaseModel):
model_name: str
dtype: Literal["float16", "bfloat16", "float32"] = "bfloat16"
max_model_len: int = Field(default=4096, ge=1)
parallel: ParallelConfig = Field(default_factory=ParallelConfig)
with open("serving.yaml") as f:
raw = yaml.safe_load(f) # dict[str, Any],无类型保障
config = ServingConfig.model_validate(raw) # 校验 + 转换 + 嵌套构建
对应的 serving.yaml:
model_name: meta-llama/Llama-3-8B
dtype: bfloat16
max_model_len: 8192
parallel:
tensor_parallel_size: 4
这样做的收益:
- 嵌套自动构建:
parallel那一段 dict 自动变成ParallelConfig实例,不用手工递归; - 拼写错误立刻暴露:YAML 里写成
dtype: bf16会在启动时报错,而不是等到加载权重时才崩; - 启动即失败:配置错误在进程启动的一瞬间抛出,不会浪费几分钟加载模型后才失败——这对动辄几十 GB 权重的推理服务尤其重要;
- IDE 补全:后续代码写
config.parallel.tensor_parallel_size有完整提示。
如果 YAML 中有多余字段,默认会被忽略;想让它报错(防止配置项拼错被静默吞掉),在对应模型上加 extra="forbid"。下面是配置片段,字段沿用上面的定义;嵌套字段也要拒绝额外键时,ParallelConfig 也需要同样的配置:
from pydantic import ConfigDict
class ServingConfig(BaseModel):
model_config = ConfigDict(extra="forbid")
...
反过来,把模型写回 YAML:
yaml.safe_dump(config.model_dump(mode="json"))
4. BaseSettings:配置即契约
配置是数据契约的一个特例:数据源是环境变量和 .env 文件,内容全是字符串,需要解析成强类型对象。pydantic-settings 提供的 BaseSettings 专门做这件事。
基本用法与 .env
from pydantic import PostgresDsn
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
# 1. 强类型声明
APP_NAME: str = "Awesome App" # 环境变量没配时用默认值
DEBUG: bool = False # 自动把 "True"、"true"、"1" 解析为 True
PORT: int = 8000 # 自动把 "8000" 解析为数字 8000
# 还可以使用 Pydantic 的高级类型,自动校验 URL 格式
DATABASE_URL: PostgresDsn
# 2. 配置读取行为
model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
# 实例化时自动读取环境变量和 .env 文件
settings = Settings()
print(settings.APP_NAME)
print(settings.PORT) # int,不是 str
对应的 .env:
DEBUG=True
PORT=9000
DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
优先级、前缀与 Fail-Fast
- 大小写不敏感(默认):类里定义
PORT,环境变量写成port=1234也能识别。 - 优先级(由高到低):
- 实例化时显式传入的值(
Settings(PORT=5000)) - 操作系统环境变量(
export PORT=...) .env文件中的值- secrets 目录中的文件值(配置
secrets_dir后) - 类中定义的默认值
- 实例化时显式传入的值(
- 前缀支持:项目复杂时为防止环境变量冲突可加前缀,在
SettingsConfigDict中设env_prefix="APP_",则APP_PORT映射到PORT。 - Fail-Fast:在启动入口执行
settings = Settings(),必填配置缺失或无法解析的值(比如PORT="hello")会抛异常;不吞掉异常,就能在连接外部服务前停止启动。
最后这一条是配置契约最重要的性质:把配置错误从运行期挪到启动期。
用上面的 Settings 和 .env 走一遍:假设启动命令是 export PORT=7000; python app.py,代码里写的是 Settings()(没有显式传值)。每个字段独立地从高到低找第一个有值的来源,然后把字符串转换成声明的类型:
| 字段 | 显式传入 | 环境变量 | .env |
类默认值 | 最终取值 |
|---|---|---|---|---|---|
APP_NAME |
— | — | — | "Awesome App" |
"Awesome App"(默认值) |
DEBUG |
— | — | True |
False |
True(.env 里的字符串 "True" 转成 bool) |
PORT |
— | 7000 |
9000 |
8000 |
7000(环境变量盖过 .env,字符串转成 int) |
DATABASE_URL |
— | — | postgresql://… |
无(必填) | 按 PostgresDsn 校验通过后的 URL |
本例没有配置 secrets 目录。若删掉 .env 里的 DATABASE_URL,其他来源也没有这个值,Settings() 就抛 ValidationError(Field required);只要启动代码不吞掉它,就能在连接数据库前失败。以上为未启用 CLI、未自定义来源的默认顺序,来源可以通过 settings_customise_sources() 调整。
来源选择和类型校验是两步。把例子中的环境变量改成 PORT=hello,即使 .env 仍有合法的 9000,也不会退回去重试:
%% 图:Settings 的来源覆盖与校验失败路径
flowchart TB
INIT["显式传值<br/>本例没有 PORT"] --> PICK["按优先级合并来源<br/>高优先级覆盖同名字段"]
ENV["环境变量<br/>PORT = hello"] --> PICK
DOT[".env<br/>PORT = 9000"] --> PICK
DEFAULT["类默认值<br/>PORT = 8000"] --> PICK
PICK --> RAW["选中的 PORT 是 hello<br/>其余候选值已被覆盖"]
RAW --> CHECK{"能解析为 int?"}
CHECK -- "否" --> ERROR["抛 ValidationError<br/>不回退到 .env 或默认值"]
CHECK -- "是" --> SETTINGS["构建 Settings 对象<br/>交给服务启动代码"]
多环境配置
指定多个 .env 文件,右边的覆盖左边的:
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
DB_HOST: str
API_KEY: str
model_config = SettingsConfigDict(
env_file=(".env.base", ".env.production"),
env_file_encoding="utf-8",
)
或者根据环境变量动态选择配置文件(类似 Spring Profile):
import os
from pydantic_settings import BaseSettings, SettingsConfigDict
# 先从系统环境获取当前运行环境,默认 development
run_env = os.getenv("ENV", "development")
class Settings(BaseSettings):
DEBUG: bool
DATABASE_URL: str
# 动态加载 .env.development 或 .env.production
model_config = SettingsConfigDict(
env_file=f".env.{run_env}",
env_file_encoding="utf-8",
)
settings = Settings()
对比 Spring @ConfigurationProperties
两者目的相同——把松散的配置字符串映射为强类型对象——但实现差异明显:
| 特性 | Pydantic BaseSettings | Spring @ConfigurationProperties |
|---|---|---|
| 底层核心技术 | 类型注解运行时解析 | 反射、Setter 或构造器注入 |
| 配置来源 | 显式传值、环境变量、默认值;.env / secrets 需配置启用,JSON / YAML 需自定义来源 |
Spring Boot 常用 .properties、.yml / .yaml 与环境变量 |
| 框架耦合度 | 完全独立,任何脚本都能直接实例化 | 深度绑定 Spring 容器,需为 Bean |
| 前缀映射机制 | 扁平化为主,env_prefix="APP_" 匹配 APP_PORT |
天然层级嵌套,prefix = "app" 匹配 app.database.url |
| 校验触发时机 | 实例化时立即校验 | 容器启动阶段,需配合 @Validated |
| 宽松绑定 | 较严格,主要靠大小写不敏感 | 极宽松,server.port、server_port、SERVER_PORT 都能映射 |
5. 选型指南:dataclass vs Pydantic vs TypedDict
三者对比
| 特性 | TypedDict | dataclass | Pydantic |
|---|---|---|---|
| 运行时类型 | 普通 dict |
自定义类实例 | 自定义类实例 |
| 运行时校验 | 无 | 无(除非手写 __post_init__) |
普通构造默认校验;绕过路径见上文 |
| 类型转换 | 无 | 无 | 默认允许部分转换("1" → 1),可开启严格模式 |
| 类型检查 | 静态 | 静态 | 静态 + 运行时 |
| 性能开销 | 零(就是 dict) | 极低 | 有(校验成本) |
| 序列化 | 本身是 dict;值仍须能被 JSON 编码 | 需 asdict(),特殊类型另处理 |
内置 model_dump_json() |
| Schema 生成 | 无 | 无 | model_json_schema() |
| 适用场景 | 已经是 dict 的数据 | 内部数据传递 | 系统边界、外部输入 |
决策树
%% 图:数据契约选型决策树:外部数据用 Pydantic,内部传递用 dataclass,只约束形状用 TypedDict
flowchart TB
Q0{"这组数据从哪来?"}
Q0 -->|"外部:HTTP / JSON / YAML / 环境变量"| Q1{"来自环境变量或 .env?"}
Q1 -->|"是"| S["Pydantic BaseSettings"]
Q1 -->|"否"| M["<b>Pydantic BaseModel</b><br/>进门时解析并校验一次"]
Q0 -->|"内部:模块之间传递"| Q2{"需要什么性质?"}
Q2 -->|"限制字段赋值:仍需检查字段可变性"| F["@dataclass(frozen=True) / NamedTuple"]
Q2 -->|"可变状态"| D["@dataclass"]
Q2 -->|"实例数量极大、内存敏感"| SL["@dataclass(slots=True)"]
Q0 -->|"已有 dict:输入已可信或已校验"| Q3{"只想约束形状、不改运行时行为?"}
Q3 -->|"是"| TD["TypedDict"]
Q3 -->|"否,要校验值"| M
classDef q fill:#fff7e0,stroke:#c98a00,color:#222
classDef a fill:#eef4fb,stroke:#5b8dc9,color:#222
class Q0,Q1,Q2,Q3 q
class S,M,F,D,SL,TD a
核心原则:边界校验一次,内部自由传递
在系统边界用 Pydantic 校验一次,内部传递 @dataclass 对象。
这正是《类型信息的分发与消费》第四章「静态与运行时的协作边界」中信任边界(Trust Boundary)模式在数据建模上的体现,对应第一章的输入分支。校验结论只覆盖当时检查的值和约束;后续修改、跨进程消息或另一套外部接口,可能形成新的边界。
例如把前面的 InferenceConfig 转成调度器只读的参数:
from dataclasses import dataclass
@dataclass(frozen=True, slots=True)
class SamplingOptions:
max_tokens: int
temperature: float
config = InferenceConfig.model_validate(
{"model_name": "llama-3", "backend": "cuda", "max_tokens": "32"}
)
options = SamplingOptions(config.max_tokens, config.temperature)
print(options.max_tokens, options.temperature) # 32 1.0
API 层用 Pydantic、引擎内部选轻量结构是常见做法,但不能据此断言某个引擎的所有配置都是 dataclass 或完全没有校验;实现还可能使用 attrs、msgspec.Struct 和显式业务检查。
反过来的两种常见错误:
- 内部到处用 Pydantic:每次构造对象都跑一遍校验,在每 token 都要构造对象的推理热路径上会成为可观的开销;
- 边界用 dataclass:外部脏数据长驱直入,错误在很深的调用栈里才暴露,排查成本极高。
attrs 同样是成熟选择,支持转换器、校验器等能力;已有项目依赖它时,不必为了统一工具而迁移。选型要看现有模型能力和热路径的实际成本。
三、附录:选型决策树与 Java 数据契约对照
1. 类型工具选择决策树
| 问题 | 条件 | 选用 |
|---|---|---|
| 需要定义数据结构? | 数据来自外部(API/JSON/YAML/用户输入) | Pydantic BaseModel |
数据来自环境变量 / .env |
Pydantic BaseSettings |
|
| 数据本身就是 dict,只想约束形状 | TypedDict |
|
| 内部传递,需要限制字段重新赋值 | @dataclass(frozen=True) / NamedTuple(浅层限制) |
|
| 内部传递,实例数量极大 | @dataclass(slots=True) |
|
| 内部传递,其他 | @dataclass |
|
| 需要定义接口? | 你控制实现类的代码 | ABC(抽象基类) |
| 你不控制实现类的代码 | Protocol |
|
| 需要约束参数值? | 几个固定字符串 | Literal |
| 枚举类型 + 穷尽检查 | Enum + assert_never |
|
| 数值范围 / 格式 | Annotated + Pydantic Field |
|
| 需要泛型? | 简单的”输入输出类型一致” | TypeVar |
| 自定义泛型容器 | Generic[T] |
|
| 装饰器保留签名 | ParamSpec |
|
| 函数有多种调用方式? | — | @overload |
| 需要运行时类型检查? | 数据建模 + 校验 | Pydantic |
| 函数级防御 | beartype | |
| 简单分支判断 | isinstance |
2. Java 与 Python 数据契约对照
| 场景 | Java | Python |
|---|---|---|
| 限制字段重新赋值的载体 | record |
@dataclass(frozen=True)(两者都非深度不可变) |
| 减模板代码 | Lombok @Data / @Value / @Builder |
@dataclass |
| 运行时字段校验 | Bean Validation + @Valid(需显式触发) |
Pydantic BaseModel(默认触发) |
| JSON 序列化 / 反序列化 | Jackson ObjectMapper |
Pydantic model_dump_json() / model_validate_json() |
| API Schema 生成 | springdoc 读取类型与约束 | model_json_schema();FastAPI 集成到 OpenAPI |
| 配置绑定 | Spring @ConfigurationProperties |
Pydantic BaseSettings |
| 字典类型约束 | Map<K,V> + DTO |
TypedDict |
| 轻量返回值 | record / 匿名类 |
NamedTuple |
| 可替换接口 | interface |
Protocol |
| 枚举 | enum |
enum.Enum / Literal |
| 实现机制 | 编译期改 AST(Lombok)/ 运行时反射(Validator) | 运行时 exec 代码生成(dataclass)/ 元类 + Rust(Pydantic) |
这张表是跨主题速查。配置绑定使用独立包 pydantic-settings;接口、枚举等也不是 Pydantic 的专属能力,各工具的触发条件仍按正文对应小节理解。
四、本文小结
回头看这三篇,Python 的类型系统其实是一条链路:注解把类型意图写下来,存根和 py.typed 把它分发出去,mypy 和 Pydantic 在两端各自消费它,最后落到数据契约上变成可执行的约束。
Java 的编译期类型检查由语言工具链完成,JSON 解析和 Bean Validation 仍需各自的运行时框架;Python 的注解本身不强制检查,由静态工具和 Pydantic 等库分别消费。Pydantic v2 构建校验 Schema 并交给 pydantic-core 执行,这仍然是库提供的约束,不是把注解变成了 Python 语言的强制类型系统。
对 AI-Infra 工程来说,实践上最值得记住的就三条:
- 注解要写,哪怕暂时不上 mypy——它首先是给人读的;
- 边界要校验,用 Pydantic 挡住所有外部输入,让错误在启动时或入口处暴露;
- 热路径要干净,内部传递用
@dataclass,不要在每 token 的循环里反复做运行时检查。
再遇到 AI Infra 源码中的类型注解,就不会觉得是天书了。关键不是一次记住所有工具,而是理解每个工具解决的问题——在真实代码中遇到时能查到、能读懂、能用对。
五、自测
-
@dataclass与 PydanticBaseModel各该用在什么位置?为什么?答案
dataclass适合内部轻量数据传递,默认不做字段类型校验,但对象构造和访问仍有成本;Pydantic 适合系统边界(配置、请求、外部输入),提供解析、校验和结构化错误。是否转换内部结构应看职责和测量结果,避免在每 token 的循环里无谓地重复校验。 -
为什么“注解要写,哪怕暂时不上 mypy”?
答案
注解首先是给人读的接口文档,其次是让 IDE 能补全与跳转,再次是让将来上 mypy 时不必回头补;而边界上的 Pydantic 校验直接依赖注解生成。不写注解的代价在读别人代码时才显现。
-
Settings里声明PORT: int = 8000,.env写着PORT=9000,启动前又export PORT=hello。Settings()的结果是什么?答案
抛
ValidationError;启动代码未捕获时进程退出。环境变量的优先级高于.env,所以PORT取到的是字符串"hello";它无法转换成int,校验失败。.env里的9000和默认值8000不会被当作”后备”再试一次——取值和校验是两步,先定来源,再校验。
-
原则是边界要校验,内部要干净:外部数据进门(HTTP 请求、配置文件、环境变量、消息)用 Pydantic 解析并校验,内部按需改用
@dataclass(或attrs)传递,靠 mypy 检查类型使用。TypedDict适合给已有且可信的dict加静态形状约束,不执行运行时校验。校验结论依赖对象之后未被非法修改;新的外部入口仍要重新建立信任。序列化由契约类的model_dump/asdict派生,配置由BaseSettings读取并校验,避免另写一套字段清单。 ↩
系列 《Python 在 AI-Infra:从语言机制到生产交付》 第 9 / 15 篇 进阶
系列总览 — 为什么这样组织、读它需要什么、读完能做什么 · 幻灯片 — 整个系列的精华,一份可分享的 deck
学习地图 — AI-Infra 工程师学习地图 第 1 / 14 个系列
上一篇:类型系统(中)——类型信息的分发与消费下一篇:并发、异步与任务协作
下一个系列:C++ 在 AI-Infra:从对象模型到算子扩展 进阶 · 10 篇,约 9.5 小时
本文由 arganzheng 创作,采用 CC BY 4.0 许可协议。在保留原文作者、署名以及完整原文链接(https://arganzheng.life/python-data-contract-design-dataclass-pydantic-and-settings.html)的前提下,欢迎各种形式的转载、翻译或商业引用。
COMMENTS
评论存放在 GitHub Discussions, 用 GitHub 账号登录即可发表,支持 Markdown。 想针对正文某句话说?选中那段文字,点浮出的「评论」即可划线评论;觉得哪里写错了,发表时勾上「同时提交 Issue」。 有人回复你时 GitHub 会按你的通知设置发邮件,不用守在这里。