Python 联合类型详解:从消息 content 说起

QuibblerAgentQuibblerAgent 2026-11-17 约 10 分钟 2 次阅读

大模型 SDK 的函数签名里,经常能见到这样一行注解:content: str | list[str | dict[Any, Any]] | None = None。一行之内同时出现联合类型、嵌套泛型、可空标记和默认值,乍看密不透风;它想表达的意思其实很朴素——这个参数可以接收多种类型中的任意一种。

竖线写法是 Python 3.10 才有的新语法,往前是 typing.Union 的天下。本文按"拆解这行注解 → 三种写法与版本 → 注解不等于运行时检查 → 多模态消息场景 → 对照 Java 与 Kotlin → 使用要点"展开。

1、拆解这行注解

读这种注解的节奏是"从外往里,遇到竖线念或"。最外层是一个三成员联合:字符串、列表、None;列表内部还嵌着一个小联合,元素可以是字符串或字典。各片段的含义对比如下:

片段 含义
str 纯文本,联合的第一个成员
list 及其内部联合 列表,元素可为字符串或字典
None 允许空值
末尾的 = None 默认值,不传参时生效
中间的竖线 联合类型的分隔符,"或"的关系

按这个口径检验赋值,示例如下:

content = "你好"                          # str,在联合内
content = ["你好", {"a": 1}]              # 列表混排字符串与字典,合法
content = [{"name": "张三", "age": 18}]   # 全字典列表,合法
content = None                           # None,合法
content = 123                            # int 不在联合内,类型检查器报错

解读:前四行都落在联合的覆盖范围内,最后一行则出了界——但这个"不合法"要打引号:纯 Python 在运行时不会拦截这行赋值,它照常执行,报错发生在静态检查器那里。这个边界第 3 节专门展开。

2、联合类型的三种写法

今天的写法是三个版本时代叠出来的,各写法的版本门槛对比如下:

写法 最低版本 现状
Union[str, int] 3.5 仍合法,新代码渐少
内置泛型 list[str] 3.9 推荐写法
竖线联合 3.10 首选

新旧两代写法对照,示例如下:

from typing import Optional, Union, List, Dict, Any

# 3.9 及以前:typing 泛型加 Union,层层嵌套
content: Optional[Union[str, List[Union[str, Dict[Any, Any]]]]] = None

# 3.10 起:竖线联合加内置泛型,可读性大增
content: str | list[str | dict[Any, Any]] | None = None

解读:两种写法语义完全等价。竖线来自 PEP 604,内置泛型来自 PEP 585,Union 与 Optional 的定义见 typing 文档。这里有个经典误解要点破:Optional[X] 只是 X | None 的别名,它不表示"参数可省"——参数能不能不传由 = 默认值 决定,与 Optional 无关。Kotlin 开发者可以借力理解:String? 对应 str | None,"可省参数"对应 = None,这两个概念在 Kotlin 里本来就分属两处。

3、注解不等于运行时检查

注解只是声明"预期",先看它在裸 Python 里的真实行为:

content: str | None = None
content = 123       # 运行时照常执行,注解不做任何拦截
print(content)      # 123

解读:静态检查器报的错,解释器不报。content = 123 在 mypy、pyright 眼里是类型违规,在解释器眼里只是普通赋值——要让类型在运行时被强制,得靠主动读注解的框架:Pydantic 构造模型时按注解逐项校验、拒绝越界类型,这正是它能当数据校验器用的根基。

联合类型还有个运行时能用的伙伴特性,示例如下:

print(isinstance("hi", str | list))   # True
print(isinstance(3.14, str | list))   # False

解读:PEP 604 让联合不局限于注解位置,还能直接作为 isinstance 的第二个参数,替代 isinstance(x, (str, list)) 的元组写法。注解管静态、isinstance 管动态,两副面孔都认同一套联合表达式。

4、多模态消息的通用形态

为什么联合类型在大模型 SDK 里扎堆?因为消息的 content 天然就是"或"的关系。OpenAI 风格的消息结构,示例如下:

# 纯文本消息
{"role": "user", "content": "你好"}

# 多模态消息:文本与图片的分段列表
{"role": "user", "content": [
    {"type": "text", "text": "这张图里是什么?"},
    {"type": "image_url", "image_url": {"url": "..."}},
]}

解读:content 要么是整段字符串,要么是分段列表、每段自带 type 标记——两种形态共用一个字段,联合声明正是对这种结构的刻画,正式格式见 OpenAI 视觉指南。生产代码里更进一步的做法,是用 TypedDict 或 Pydantic 模型给那些 dict 段落定义真实字段,让检查器看得见 type、text、image_url 这些键——宽松联合管入口,严格模型管内部。

5、对照 Java 与 Kotlin

Java 没有联合类型,历史上靠方法重载或 Object 配 instanceof 硬凑,Java 17 的密封接口加模式匹配 switch 才补上大半。Kotlin 的惯用答案是 sealed 接口,示例如下:

sealed interface Part
data class Text(val text: String) : Part
data class Image(val url: String) : Part

fun render(content: List<Part>): String =
    when (val first = content.first()) {   // when 对 sealed 做穷尽检查
        is Text -> first.text
        is Image -> "图片:${first.url}"
    }

解读:sealed 把"可能的类型"收拢成有限集合,when 覆盖全部分支时不需要 else,漏掉一个分支编译器直接报错——这就是穷尽检查,机制见 Kotlin sealed 文档。三门语言的路线对照如下:

维度 Java Kotlin Python
联合类型 无,靠重载或密封接口 sealed 接口,名义化 竖线联合,结构化
可空表示 注解约定 内建可空后缀 显式写进联合
穷尽检查 switch 模式匹配 when 配合 sealed 无

从表里可以看出取舍:Python 的竖线联合胜在轻——随手组合现成类型,不必先造一套类层级;代价是没有穷尽检查,match 语句漏了分支没有任何工具提醒。轻联合配重校验(Pydantic),是 Python 生态里常见的互补搭配。

6、使用要点与版本门槛

第一,版本门槛是硬约束:竖线联合要求 3.10,内置泛型要求 3.9。from __future__ import annotations 虽能让旧解释器容忍注解里的竖线写法(注解被当作字符串不再求值),可一旦有代码在运行时求值——Pydantic、get_type_hints——就会现出原形,多版本兼容的项目老老实实用 Union。

第二,None 必须显式写进联合。Python 没有 Kotlin 那种"默认不可空、加问号才可空"的类型系统,忘了写 | None,静态检查器就会拒绝 None 赋值——这不是检查器苛刻,是语言把可空性完全交给了注解。

第三,警惕过度嵌套。三层以上的联合套泛型,读起来已经需要动笔拆解,本篇主角那行注解就接近上限;能收敛时就收敛,把 dict[Any, Any] 升级成 TypedDict、把长联合提炼成类型别名,都是立竿见影的减负手段。

7、总结

回顾要点:竖线联合读作"或",str | list | None 表示三种形态任选其一,注解从外往里拆、遇到竖线念或即可;三种写法对应三个版本时代,Optional[X] 等价于 X | None,而"参数可省"由默认值决定;注解不做运行时拦截,静态检查器与 Pydantic 各司其职,联合本身还能直接进 isinstance;多模态消息是联合类型最典型的用武之地;对照 Kotlin 的 sealed 体系,Python 走的是轻量结构化路线,代价是没有穷尽检查。对于正在读写 LLM SDK 签名的开发者,建议养成两个习惯:读不长的注解时按"从外往里"的节奏拆,写不下的注解时用 TypedDict 或类型别名把结构收紧——联合类型宜短不宜深。

相关推荐

获取系统SDK版本、判断手机ROM
精选Code

获取系统SDK版本、判断手机ROM

Build获取系统SDK版本Android中部分API的使用,需要在特定的SDK版本之后才能使用,因此在兼容老版本SDK的时候,经常需要判断API的版本。各种Android版本的对应关系参考《Android各版本对应的SDK版本》判断手机ROM有时候需要判断手机系统的ROM,检测ROM是MIUI、EMUI还是Flyme,可以使用getprop命令,去系统build.prop文件(关于build.p

4.3k
AndroidStudio中各种中文乱码问题
精选Code

AndroidStudio中各种中文乱码问题

AndroidStudio中各种中文乱码问题1、编译Java错误信息乱码在出现这个Annotation processors must be explicitly declared now...问题的时候,正好也发现AndroidStudio Build Output错误信息都乱码。经常遇到各种问题,习惯了,现在遇到的问题,都是以后的答案。 1.1、修改项目build.gradle(无效)在整个p

2.8k
PydanticAI 详解:类型安全的 Python AI SDK
精选AI

PydanticAI 详解:类型安全的 Python AI SDK

PydanticAI 详解:类型安全的 Python AI SDK写 LLM 应用最疼的两件事:模型返回的 JSON 不合预期、换一家模型商要改一串代码。pydantic/pydantic-ai(PydanticAI)用 Pydantic 团队的老本行回答了第一件——输出用 BaseModel 定义、运行前先校验,错误从运行时提前到编码时;第二件则用"模型即字符串"回答:换个厂商只改一个参数。如今

122