Python
20 异步编程入门
async/await 的直觉模型,看懂流式 API 部署代码
- Python
- 进阶
目标:建立「等待 IO 时让出控制权、去干别的」这套直觉模型,能读懂并写出
async def/await/gather/TaskGroup/async for,最终看懂 LangChain 书第 10 章 FastAPI +astream的流式部署代码——那是全书唯一一段异步代码。这也是本教程唯一使用 async 写法的一章。
1. 为什么需要:等待的那几秒,CPU 在发呆
假设你要调三个接口:用户信息、订单记录、推荐列表,每次网络往返 2 秒。入门课的写法(11-实战小项目 里 requests 就是这么用的):
import time
def fetch(name):
time.sleep(2) # 模拟一次网络请求:往返要 2 秒
return f"{name} 的数据"
start = time.perf_counter()
for name in ["用户信息", "订单记录", "推荐列表"]:
fetch(name) # 一个等完 2 秒,才轮到下一个
print(f"总耗时 {time.perf_counter() - start:.1f} 秒") # 总耗时 6.0 秒
问题在于:time.sleep(2) 的 2 秒里 CPU 几乎什么都没干——请求已发出,它在等远端把数据送回来。等待不消耗算力,CPU 在发呆;而且三个请求互不依赖,第二个根本不必等第一个。
异步的全部承诺就一句话:等待的时候,去干别的。第一个请求发出后不等它,立刻发第二、第三个;谁的数据先回来先处理谁。三段 2 秒的等待重叠起来,总耗时接近 2 秒,而不是 6 秒。
2. 直觉模型:一个服务员,三桌客人
想象一家餐厅只有一个服务员,坐着三桌客人:
- 同步服务员:给 1 号桌点完单,走到厨房窗口站着等菜,菜好了端给 1 号桌,这才想起 2 号桌——三桌依次点单、依次上菜,就是上面的 6 秒。
- 异步服务员:给 1 号桌点完单,小票往窗口一夹,转身去 2 号桌,点完又去 3 号桌;哪桌菜好了铃一响,顺手端过去——一个人同时照看三桌,就是 2 秒。
把比喻翻译成术语:
| 餐厅 | 异步程序 |
|---|---|
| 唯一的服务员 | 唯一的主线程(单线程,没加人手) |
| 三桌客人 | 三个任务(三个网络请求) |
| 站在窗口干等菜 | 同步等待:time.sleep(2) 卡住不动 |
| 小票一夹、转身下一桌 | await:挂起当前任务,交出控制权 |
| 「3 号桌菜好了」的铃声 | IO 完成,任务变回「可继续」,调度器重新安排 |
| 菜没好也得猛剁馅的活 | CPU 密集任务:转身也没用,只有他会剁 |
最后两行是伏笔:服务员擅长「插空」别人的等待;活儿本身占满他的手时,异步帮不上忙(§8 细说)。还要记住:全程只有一个服务员——异步没让 Python 变快,只是不让它发呆。
3. 实测:串行 3 秒 vs 并发 1 秒
把网络请求换成 sleep 做实验(等待的性质完全一样),同步、异步各跑三个 1 秒的任务,用 time.perf_counter() 计时:
import asyncio
import time
def fetch_sync():
time.sleep(1) # 同步等 1 秒:卡住不放
return "数据"
async def fetch():
await asyncio.sleep(1) # 异步等 1 秒:挂起,控制权交出去
return "数据"
start = time.perf_counter() # 同步版:一个等完才轮到下一个
for _ in range(3):
fetch_sync()
print(f"同步串行:{time.perf_counter() - start:.2f} 秒")
async def main(): # 异步版:三个任务同时放出去
start = time.perf_counter()
await asyncio.gather(fetch(), fetch(), fetch())
print(f"异步并发:{time.perf_counter() - start:.2f} 秒")
asyncio.run(main())
同步串行:3.01 秒
异步并发:1.00 秒
(Python 3.14 / macOS 实测。)gather 下节细讲,先把它当成「把三个任务同时放出去」的按钮。为什么是 1 秒?三个任务几乎同时启动,各自的 1 秒同时流逝——省下的 2 秒不是算得更快,而是三段「发呆时间」重叠了。服务员的比喻整段兑现。
4. async def 与 await:两个新关键字
import asyncio
async def fetch(name):
print(f"{name}:开始")
await asyncio.sleep(1)
print(f"{name}:结束")
return f"{name} 的数据"
coro = fetch("A") # 注意:函数体一行都没执行!
print(coro)
result = asyncio.run(fetch("B")) # 这里才真正执行,并拿到返回值
print(result)
# <coroutine object fetch at 0x10294d080>
# B:开始
# B:结束
# B 的数据
盯着结果确认三件事:
async def定义的是协程函数,调用它得到的不是返回值,而是一个协程对象(coroutine)——一张「还没开工的任务单」。- 调用不等于执行。这个设计你在 16-迭代器与生成器 见过同款:调用生成器函数只拿到生成器,第一次
next()才启动;协程同理,要被await或事件循环驱动才会跑。 await的语义:等这个结果;等待期间把控制权交还事件循环,让它去推进别的任务;结果就绪后从await的下一行继续。await xxx表达式的值,就是协程函数return的值。
三条使用规则(前两条是语法/类型层面的硬约束):
await只能写在async def体内,写在别处直接SyntaxError: 'await' outside function;await后面必须跟「可等待对象」:协程、Task(§6)、Future。await 5得到TypeError: 'int' object can't be awaited;- 拿到协程对象的唯一正确姿势是
await它或交给并发 API,别 print、别丢弃(坑 1 见 §9)。
普通 def | async def | |
|---|---|---|
| 调用后发生什么 | 立刻执行,拿到返回值 | 不执行,拿到协程对象 |
| 结果怎么拿 | 调用即是 | await(或事件循环驱动)之后 |
体内能用 await | 不能 | 能 |
| 心智模型 | 一口气跑完 | 可在 await 处反复暂停—恢复 |
5. 事件循环与 asyncio.run()
**事件循环(event loop)**就是服务员的大脑:一个不断转圈的调度器,加一块任务看板。它反复做三件事:
- 从「可继续」队列挑一个任务执行;
- 任务跑到
await挂起,控制权回到循环手上——它立刻去挑下一个能跑的任务; - 某个挂起任务的 IO 完成了(数据到了、计时到了),把它移回「可继续」队列。
「IO 完成了」由操作系统和底层网络库通知,概念上知道有个铃就行,内部细节本章不展开。整个流程:
asyncio.run(main()) → 建循环
循环转圈:挑任务 → 执行到 await → 挂起 → 转头跑别的任务
→ 某任务 IO 完成 → 回到「可继续」队列 → 再被挑中
直到 main 结束 → 关循环
asyncio.run(main()) 一站式完成「建循环 → 把 main 协程跑到结束 → 关循环」。两条纪律:它是程序唯一的异步入口,整个程序只在最外层调一次;循环转着时再调会得到 RuntimeError: asyncio.run() cannot be called from a running event loop。Web 框架场景下你不会自己调它——uvicorn/FastAPI 启动时就建好了循环,你的代码只是被它调度(§10)。
6. 让任务真正并发:gather 与 TaskGroup
一个高频误用:听说 async 快,就写了三个 await——await 是「就地等这个结果」,依次 await 就是排队:
async def main():
a = await fetch("A") # 干等 A 完成,才开始 B
b = await fetch("B") # 干等 B,才开始 C ← 还是串行!约 3 秒
要并发,得一次性把多个协程交给事件循环同时挂起。两种写法:
写法一:asyncio.gather——打包放出去,await 一次等全组:
import asyncio
async def fetch(name, seconds):
await asyncio.sleep(seconds)
print(f"{name} 完成")
return f"{name} 的数据"
async def main():
print(await asyncio.gather(
fetch("慢任务", 1.0), fetch("中任务", 0.6), fetch("快任务", 0.3),
))
asyncio.run(main())
# 快任务 完成 ← 完成按真实结束时间:最快的最先
# 中任务 完成
# 慢任务 完成
# ['慢任务 的数据', '中任务 的数据', '快任务 的数据'] ← 结果顺序永远按传参顺序
总耗时约 1 秒(取最慢者)。变体:默认组里任何一个任务抛异常,gather 立刻把它抛出来;传 return_exceptions=True 则不炸,异常对象原地占在结果列表里,适合「多个可独立失败的查询」:
async def job(name):
await asyncio.sleep(0.3)
if name == "坏任务":
raise ValueError("炸了")
return f"{name} OK"
async def main():
results = await asyncio.gather(
job("甲"), job("坏任务"), job("乙"), return_exceptions=True
)
print([f"捕获: {r!r}" if isinstance(r, Exception) else r for r in results])
asyncio.run(main())
# ['甲 OK', "捕获: ValueError('炸了')", '乙 OK']
写法二:asyncio.TaskGroup(3.11+,官方推荐)——结构化并发:async with 块退出时保证组内任务全部收尾;任何一个失败,其余任务自动取消,整组抛 ExceptionGroup,用 3.11 新语法 except* 接:
import asyncio
async def job(name, seconds):
await asyncio.sleep(seconds)
if name == "坏任务":
raise ValueError("出错了")
print(f"{name} 完成")
async def main():
async with asyncio.TaskGroup() as tg:
tg.create_task(job("慢任务", 1.0)) # 还要 1 秒才完
tg.create_task(job("坏任务", 0.2)) # 0.2 秒后爆炸
try:
asyncio.run(main())
except* ValueError as eg: # 专捕 ExceptionGroup 里的 ValueError
print("整组失败,捕获到:", eg.exceptions[0])
# 整组失败,捕获到: ValueError('出错了')
注意「慢任务 完成」没有打印:坏任务 0.2 秒爆炸的瞬间,TaskGroup 就把还在睡的慢任务取消,然后整组退出——不留孤儿任务在后台默默跑。gather 默认不取消幸存者(首个异常抛出时其余继续跑),要自己收拾残局;TaskGroup 自动料理,这就是「推荐」的理由。顺带认识一个概念:create_task(coro) 把协程登记成正式的 Task,登记即刻排上调度,不必等到被 await——「同时放出去」的底层机制。
| 写法 | 效果 | 一个任务失败时 |
|---|---|---|
依次 await | 串行,无并发 | 只影响自己,但本来也没并发 |
gather(...) | 并发;结果按传参序 | 默认立刻抛首个异常,其余不取消;return_exceptions=True 收集为结果 |
async with TaskGroup | 并发;出块保证全部结束 | 其余任务自动取消,整组抛 ExceptionGroup(except* 接) |
最后一句辨析请背下来:并发不是并行。并发是一个人交替处理多桌(服务员看多桌),并行是多个 CPU 同时干活(雇多个服务员)。asyncio 只提供前者——它重叠的是「等待」,不是「计算」。
7. async for 与 async with:流式场景的主角
16 章讲过:for 背后是 __iter__/__next__ 协议,生成器用 yield 按需吐数据。流式输出有个新麻烦:下一个 token 要等网络。普通 next() 一等就是阻塞——事件循环被按住,全场停摆。所以 Python 给迭代器和上下文管理器各做了一套异步版协议,语法是 async for 和 async with。
async def 里出现 yield,就成了异步生成器函数——await(等待)与 yield(交出)同框。这是 LLM 流式输出的标准形态:
import asyncio
async def token_stream(words):
for w in words:
await asyncio.sleep(0.3) # 模拟「等网络送来下一个 token」
yield w # 交出一个 token,暂停
async def main():
async for token in token_stream(["你", "好", "呀"]):
print(token, end=" ", flush=True)
print()
asyncio.run(main())
# 你 好 呀 ←(实测)每隔 0.3 秒陆续蹦出一个字,不是 0.9 秒后一起出现
async for的语义 = 普通 for + 「取下一个值」这步是await:值没到就挂起让出控制权,值到了进循环体。事件循环始终活着,别的任务随时插进来——服务端同时给多个用户蹦字的前提。- 两套协议不通用:普通
for遍历异步生成器,TypeError: 'async_generator' object is not iterable。
async with 是 19-文件与上下文管理器进阶 里 with 的异步版:进入、退出也可能要等 IO(建立/断开连接),对应魔术方法 __aenter__/__aexit__。你已用过一次——§6 的 async with asyncio.TaskGroup()。手写一个看清门道:
import asyncio
class WebSession:
async def __aenter__(self):
await asyncio.sleep(0.1) # 模拟握手建连
print("连接已建立")
return self
async def __aexit__(self, exc_type, exc, tb):
await asyncio.sleep(0.1) # 模拟挥手断连
print("连接已关闭")
async def main():
async with WebSession():
print("用连接干活")
asyncio.run(main())
# 连接已建立
# 用连接干活
# 连接已关闭
读异步库时 async with aiohttp.ClientSession() as session: 就是这套协议。本章认识即可,重点记 async for——LangChain 流式部署的主角。
8. 什么时候用异步,什么时候别碰
判断只问一个问题:程序的时间主要花在「等外部东西」还是「算东西」?
| IO 密集 | CPU 密集 | |
|---|---|---|
| 典型任务 | HTTP 请求、查数据库、调 LLM API、读写大文件 | 图像处理、压缩解压、纯计算循环 |
| 大部分时间 CPU 在干嘛 | 发呆等数据 | 满负荷计算 |
| 异步收益 | 大:多段等待可重叠 | 零:没空让出,让出了也没人替它算 |
| 想提速该用 | asyncio | 多进程(multiprocessing / 进程池) |
三条务实建议:日常脚本同步就好——一次只做一件事、没有可重叠的等待,异步纯属增加复杂度;异步的主场是服务端——FastAPI 用一个事件循环服务成百上千个并发请求,每个请求都在等数据库、等 LLM,异步让它们互相填补空隙(§10 看到确切形状);CPU 密集想提速走多进程——§2 剁馅隐喻的兑现,异步帮不上。
9. 常见坑
坑 1:忘写 await——拿到协程对象还当结果用。 最阴的地方:调用处不报错,程序照常跑,结果悄悄是错的:
import asyncio
async def fetch():
await asyncio.sleep(0.5)
return "数据"
async def main():
result = fetch() # ❌ 忘了 await:只造出协程对象,没执行
print(result) # 打印的不是 "数据",是协程对象
asyncio.run(main())
# <coroutine object fetch at 0x1041a2080>
# sys:1: RuntimeWarning: coroutine 'fetch' was never awaited
原因:协程对象从头到尾没人驱动,解释器退出时发现它白创建了,补一条 RuntimeWarning(18-异常处理、调试与测试:警告不是异常,不中断程序,很容易漏看)。修法:result = await fetch()。口诀:输出里见到 coroutine ... object 字样,等于那个位置少了一个 await。
坑 2:async 函数里用 time.sleep,一个等待阻塞全场。 事件循环只有一条执行线,谁同步卡住,所有任务陪葬:
import asyncio
import time
async def blocker():
time.sleep(1) # ❌ 同步等待:循环被按住,谁都动不了
async def sleeper():
await asyncio.sleep(1) # 异步等待:挂起,让别的任务跑
async def run(make_job):
start = time.perf_counter()
await asyncio.gather(make_job(), make_job(), make_job())
print(f"{make_job.__name__}: {time.perf_counter() - start:.2f} 秒")
asyncio.run(run(blocker)) # blocker: 3.01 秒 ——「并发」名存实亡(实测)
asyncio.run(run(sleeper)) # sleeper: 1.00 秒
修法:异步代码里一切「会等的」调用都换 async 版——asyncio.sleep、异步网络库、异步文件库。混进一个同步等待,§3 的 1 秒就退回 3 秒。
坑 3:在顶层直接 await。 学完 await 最自然的冲动,是在模块顶层写 await main():
import asyncio
async def main():
await asyncio.sleep(1)
await main() # ❌ SyntaxError: 'await' outside function
原因:await 的让出机制只有在事件循环里的协程中才有意义,语法层面直接禁止。修法就是本章所有例子的固定骨架——asyncio.run(main())。同族错误:在 async 函数里再调 asyncio.run,得到 RuntimeError: asyncio.run() cannot be called from a running event loop(§5 的纪律)。
坑 4:事件循环里混同步重活。 比如在 async 端点里调用同步的重函数(解析超大 JSON、图像缩放、FAISS.load_local)——它一跑几秒,这几秒里所有并发请求一起卡住,与坑 2 同病:循环只有一条线。修法(认识即可):重活丢线程池 await asyncio.to_thread(重函数, 参数),让循环腾出手;或者把重活挪出服务进程。
10. 在 LangChain 里的样子
先交代事实:LangChain 书其余章节全是同步写法——chain.invoke(...)、for chunk in chain.stream(...)(16 章的生成器方案)。唯一必须异步的地方,是把 chain/agent 部署成 Web 服务:FastAPI 端点天生 async,流式输出又叠加 async for(FastAPI 本身的安装、启动、路由、请求体见补充章 FastAPI速成,本章只负责异步部分)。摘编自 langchain-book-python/10-流式API与部署.md:
# server.py(摘编)
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
from rag_agent import get_agent
app = FastAPI()
class ChatRequest(BaseModel):
question: str
session_id: str
# FAISS 加载和 embedding 客户端初始化开销大,启动时构建一次(坑 4 的预防针)
agent = get_agent()
@app.post("/chat")
async def chat(req: ChatRequest):
async def token_stream():
try:
# stream_mode="messages":逐 token 产出 (message, metadata)
async for message, metadata in agent.astream(
{"messages": [{"role": "user", "content": req.question}]},
{"configurable": {"thread_id": req.session_id}},
stream_mode="messages",
):
if message.content:
yield message.content # token 到达即转手
except Exception as e:
yield f"Error: {e}"
return StreamingResponse(
token_stream(), media_type="text/plain; charset=utf-8"
)
逐段解读,每一段都能在本章找到原型:
async def chat(req):FastAPI 的异步端点。uvicorn 启动时建好事件循环(替代asyncio.run的角色,§5),服务所有用户的请求;A 用户等 LLM 吐字时挂起,循环转头处理 B 用户——「等待时去干别的」在 Web 服务上兑现为并发能力。async def token_stream():async def + yield = 异步生成器函数(§7)。调用它不执行函数体,只造出一个 async 生成器交给StreamingResponse——驱动它的活儿由框架的事件循环代劳。async for message, metadata in agent.astream(...):astream是stream的异步版,逐 token 产出元组;async for每等下一个 token 就让出控制权(§7),绝不阻塞其他用户的请求。if message.content: yield ...:token 到达即 yield 转手,uvicorn 拿到就往网络写,浏览器实时蹦字。16 章的「生成器流水线」,本章给它换上异步引擎。except Exception as e: yield f"Error: {e}":异常不能往外抛——HTTP 响应头一旦发出就改不了状态码,抛了只会让连接悬挂;所以把错误也当一条普通消息 yield 出去,保证流「有始有终」。agent = get_agent()放在模块顶层:贵且只此一份的初始化做一次,别塞进每个请求(坑 4 的预防针)。
这段代码是本章所有零件的总装:协程函数(async def)、异步生成器(async def + yield)、异步迭代(async for)、事件循环(uvicorn 的循环替代 asyncio.run)。读懂它,LangChain 书再无语法障碍;更多惯用法汇总见 22-读懂LangChain:语法桥。
小练习
- 三个任务时长 1.0 / 0.5 / 0.2 秒,用
gather并发。先预测:完成顺序的打印是什么?结果列表是什么顺序?再运行验证。 - 修复下面的代码,让它打印两份数据(而不是两个协程对象);修完再想:这样并发了吗?要并发该怎么改?
import asyncio
async def fetch(name):
await asyncio.sleep(0.3)
return f"{name} 的数据"
async def main():
a = fetch("A")
b = fetch("B")
print(a, b)
asyncio.run(main())
- 写异步生成器
countdown(n):产出 n, n-1, …, 1,每个数之间await asyncio.sleep(0.2);用async for消费并打印。 - 体验 TaskGroup 的自动取消:任务甲 1 秒后成功,任务乙 0.3 秒后
raise RuntimeError。预测甲的打印会不会出现?用except*捕获验证。
练习答案
# 练习 1
import asyncio
async def fetch(name, seconds):
await asyncio.sleep(seconds)
print(f"{name} 完成")
return f"{name} 的数据"
async def main():
print(await asyncio.gather(
fetch("甲", 1.0), fetch("乙", 0.5), fetch("丙", 0.2)
))
asyncio.run(main())
# 丙 完成
# 乙 完成
# 甲 完成
# ['甲 的数据', '乙 的数据', '丙 的数据'] ← 完成按结束时间,结果按传参顺序
# 练习 2:a、b 都漏了 await,print 出来是两个协程对象并伴随 RuntimeWarning。
async def main():
a = await fetch("A")
b = await fetch("B")
print(a, b) # A 的数据 B 的数据 —— 但依次 await 是串行,约 0.6 秒
async def main(): # 要并发(约 0.3 秒):一次放出去
a, b = await asyncio.gather(fetch("A"), fetch("B"))
print(a, b)
asyncio.run(main()) # (fetch 用题目里那个)
# 练习 3
import asyncio
async def countdown(n):
for x in range(n, 0, -1):
await asyncio.sleep(0.2) # 每个数都等一下:异步生成器
yield x
async def main():
async for x in countdown(3):
print(x)
asyncio.run(main())
# 3 2 1(每隔 0.2 秒出现一个)
# 练习 4:甲的打印不会出现——乙 0.3 秒爆炸时,TaskGroup 立刻取消还在睡的甲
import asyncio
async def good_job():
await asyncio.sleep(1.0)
print("甲成功") # 永远不执行:0.3 秒时已被取消
async def bad_job():
await asyncio.sleep(0.3)
raise RuntimeError("乙炸了")
async def main():
async with asyncio.TaskGroup() as tg:
tg.create_task(good_job())
tg.create_task(bad_job())
try:
asyncio.run(main())
except* RuntimeError as eg:
print("捕获:", eg.exceptions[0])
# 捕获: RuntimeError('乙炸了')