跳转到主要内容

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 的数据

盯着结果确认三件事:

  1. async def 定义的是协程函数,调用它得到的不是返回值,而是一个协程对象(coroutine)——一张「还没开工的任务单」。
  2. 调用不等于执行。这个设计你在 16-迭代器与生成器 见过同款:调用生成器函数只拿到生成器,第一次 next() 才启动;协程同理,要被 await 或事件循环驱动才会跑。
  3. 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)。
普通 defasync def
调用后发生什么立刻执行,拿到返回值不执行,拿到协程对象
结果怎么拿调用即是await(或事件循环驱动)之后
体内能用 await不能能
心智模型一口气跑完可在 await 处反复暂停—恢复

5. 事件循环与 asyncio.run()

**事件循环(event loop)**就是服务员的大脑:一个不断转圈的调度器,加一块任务看板。它反复做三件事:

  1. 从「可继续」队列挑一个任务执行;
  2. 任务跑到 await 挂起,控制权回到循环手上——它立刻去挑下一个能跑的任务;
  3. 某个挂起任务的 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. 三个任务时长 1.0 / 0.5 / 0.2 秒,用 gather 并发。先预测:完成顺序的打印是什么?结果列表是什么顺序?再运行验证。
  2. 修复下面的代码,让它打印两份数据(而不是两个协程对象);修完再想:这样并发了吗?要并发该怎么改?
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())
  1. 写异步生成器 countdown(n):产出 n, n-1, …, 1,每个数之间 await asyncio.sleep(0.2);用 async for 消费并打印。
  2. 体验 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('乙炸了')