系统讲解 Python 类型注解的基础与高级用法，涵盖变量、容器、函数参数及返回值、联合类型、生成器、TypedDict 等核心知识点。重点阐述类型注解在 FastAPI、LangChain 等大模型开发框架中的必要性，通过实际代码示例展示如何提升代码可读性、协作规范及静态检查能力，并介绍 mypy 工具的使用，旨在帮助开发者构建更稳健的 AI 工程化项目。
在 FastAPI、LangChain、LlamaIndex、RAG、大模型服务端 开发中，类型注解（Type Hints） 已经不是可选语法，而是：
类型注解是 Python 3.5+ 引入的静态类型标记，用于：
特点：
# 数字
name: str = "大模型开发者"
age: int = 25
score: float = 98.5
is_active: bool = True
nothing: None = None
prompt: str
temperature: float
max_tokens: int
stream: bool
from typing import Final
API_KEY: Final[str] = "sk-xxxxxx"
MODEL_NAME: Final[str] = "gpt-3.5-turbo"
Python 3.9+ 内置支持，无需从 typing 导入 List/Dict。
# 整数列表
ids: list[int] = [1001, 1002, 1003]
# 字符串列表
prompts: list[str] = ["介绍 AI", "写 Python 代码"]
# 浮点向量（大模型 Embedding 必用）
embedding: list[float] = [0.12, 0.35, 0.66, 0.92]
# 嵌套列表
matrix: list[list[float]] = [[1.0, 2.0], [3.0, 4.0]]
格式：dict[键类型，值类型]
# 简单字典
config: dict[str, str] = {"model": "gpt-3.5", "version": "v1"}
# 混合值类型（常用）
model_kwargs: dict[str, int | float | bool] = {"temperature": 0.7, "max_tokens": 1024, "stream": True}
元组是固定结构、固定位置类型。
# 固定结构：int + str
user: tuple[int, str] = (1001, "AI 用户")
# 任意长度同类型
numbers: tuple[int, ...] = (1, 2, 3, 4, 5)
# 混合结构
message: tuple[str, str, bool] = ("user", "你好", True)
unique_ids: set[int] = {101, 102, 103}
vocab: set[str] = {"AI", "大模型", "RAG"}
def generate_response(
prompt: str,
temperature: float,
max_tokens: int,
stream: bool
) -> str:
return f"生成结果：{prompt}"
def get_embedding(text: str) -> list[float]:
return [0.1, 0.2, 0.3]
def log_info(message: str) -> None:
print(f"[日志] {message}")
def chat(
prompt: str,
model: str = "gpt-3.5-turbo",
temperature: float = 0.7
) -> str:
...
def call_llm(*args: str, **kwargs: int | float) -> str:
...
# 可以是 int 或 str
user_id: int | str = 1001
# 可以是 float 或 None
score: float | None = None
from typing import Union
user_id: Union[int, str] = 1001
大模型项目90% 可选参数都用它。
from typing import Optional
# 等价于 system_prompt: str | None
system_prompt: Optional[str] = None
api_key: Optional[str] = None
from typing import Any
# 可以是任何类型
data: Any = "字符串"
data: Any = 123
data: Any = [1, 2, 3]
⚠️ 工程规范：尽量不要用 Any，会完全失去类型安全意义。
from typing import Iterator
def count_to_5() -> Iterator[int]:
for i in range(5):
yield i
格式：
Generator[产出类型，发送类型，返回类型]
from typing import Generator
# 大模型流式输出标准写法
def llm_stream() -> Generator[str, None, None]:
yield "我"
yield "是"
yield "AI"
yield "大模型"
ChatGPT、文心、通义千问流式返回都用这个类型。
用于函数作为参数传递的场景，如：
格式：
Callable[[参数类型...], 返回值类型]
from typing import Callable
# 回调：接收 str，返回 bool
CallbackFunc = Callable[[str], bool]
def process_result(result: str, callback: CallbackFunc) -> None:
callback(result)
用于简化复杂类型，统一项目规范。
# 向量别名
Embedding = list[float]
# 文档别名
Document = dict[str, str | Embedding]
# 消息列表
MessageList = list[dict[str, str]]
# 使用
emb: Embedding = [0.1, 0.2, 0.3]
doc: Document = {"content": "你好", "embedding": emb}
限定变量只能是几个固定值，传错直接报错。
from typing import Literal
# 模型名称只能是这三种
ModelType = Literal["gpt-3.5", "gpt-4", "qwen", "ernie"]
# 设备类型
Device = Literal["cpu", "cuda", "mps"]
def run_llm(model: ModelType, device: Device = "cpu") -> None:
...
用于注解结构固定的字典，如：
from typing import TypedDict
class ChatMessage(TypedDict):
role: str # user / assistant / system
content: str
name: Optional[str] # 必须严格按结构写，少字段/错类型都会报错
msg: ChatMessage = {"role": "user", "content": "你好"}
class LLMConfig(TypedDict, total=False):
model: str
temperature: float
max_tokens: int
class LLMModel:
# 类属性注解
model_name: str
temperature: float
def __init__(self, model_name: str, temperature: float = 0.7):
self.model_name = model_name
self.temperature = temperature
Python 3.11+
from typing import Self
class LLMBuilder:
def set_prompt(self, prompt: str) -> Self:
self.prompt = prompt
return self
def set_temperature(self, t: float) -> Self:
self.temp = t
return self
class BaseLLM:
pass
def create_llm(llm_class: type[BaseLLM]) -> BaseLLM:
return llm_class()
async 函数直接注解最终返回值即可。
import asyncio
async def async_llm_call(prompt: str) -> str:
await asyncio.sleep(1)
return f"异步回复：{prompt}"
用于永远抛出异常、永远不结束的函数。
from typing import NoReturn
def raise_error() -> NoReturn:
raise RuntimeError("大模型调用失败")
用于定义接口规范，类似 Java/TypeScript 接口。
from typing import Protocol
class EmbeddingModel(Protocol):
def encode(self, text: str) -> list[float]:
...
任何实现 encode 方法的类都被视为 EmbeddingModel。
from typing import (
Optional,
Literal,
TypedDict,
Generator,
)
ModelName = Literal["gpt-3.5", "gpt-4", "qwen"]
class ChatMessage(TypedDict):
role: str
content: str
name: Optional[str]
def chat_completion(
messages: list[ChatMessage],
model: ModelName = "gpt-3.5",
temperature: float = 0.7,
stream: bool = False
) -> Generator[str, None, None] | str:
if stream:
yield "回复"
else:
return "完整回复"
安装：
pip install mypy
运行检查：
mypy your_code.py --strict
作用：
str, int, float, bool, Nonename: strdef fn(a: int) -> strlist[T]dict[K, V]tuple[T1, T2, ...]set[T]T | None / Optional[T]T1 | T2AnyGenerator[Yield, Send, Return]Callable[[P], R]TypedDictLiteralProtocol
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online