基于Playwright的ChatGPT网页版API封装：从零到稳定服务

我给团队做内部工具的时候，发现一个比较尴尬的局面：业务方希望系统里能直接调用对话式AI能力，但需求形态很轻，量也不大，正儿八经去申请官方接口反而要等流程、配权限、跟计费模型纠缠。后来我干脆换了个思路——直接把对话网页版当作后端引擎，用浏览器自动化工具驱动它，再包一层HTTP服务对外输出。这就是“基于Playwright的ChatGPT网页版API封装”这套方案的由来。

这篇文章我会从方案选型、核心原理、代码实现一直讲到部署排错，把我实际踩过的坑和后来固定下来的稳定套路全部分享出来。它不一定适合高并发业务，但对内部工具、个人自动化脚本、中小规模集成场景来说，是一个成本低、见效快的务实选择。如果你是刚接触浏览器自动化的工程师，这篇也能帮你理解怎么把一次性的UI操作变成一套可持续运行的服务。

1. 为什么选Playwright，以及这套封装到底解决什么问题

1.1 什么样的场景需要把网页版做成API

先别急着写代码，我们把“要不要做这件事”想清楚。需要把网页版封装成API的常见场景，通常是这么几种：第一类是内部自动化，比如工单系统要把问题描述发给模型，再把回答回填到工单里，人工操作太繁琐，需要程序代劳。第二类是功能验证和原型开发，你手里有一个想法，想快速验证“对话能力接入业务”之后的效果，还没到申请专项预算的阶段。第三类是某些数据源只在网页版交互里能拿到，或者需要结合页面上的额外按钮、文件上传等能力，接口形态反而满足不了。

这三种场景有一个共同点：请求量不大，对响应时延有一定容忍度，但对可用性和部署成本敏感。我自己接的工单系统就是典型，一天可能只有几百次调用，而且分布在上班时间。为了这种量级去构造一整套完整方案，明显是杀鸡用牛刀。把网页版当作远程人肉操作的对象，用Playwright模拟人的行为，再把结果通过HTTP透传出来，投入产出比非常高。

需要提醒的是，这个方案不是用来替代正式商业接口的。如果业务量成长到每分钟几十次调用，或者需要严格的SLA，网页封装很快会变成瓶颈，那时候就必须切换到更正式的接入方式。它更适合作为过渡方案、内部辅助方案，以及你在没有任何现成接口时可快速搭建的应急通道。

1.2 浏览器自动化方案怎么选：Playwright的优势

浏览器自动化领域，长期以来的选择主要是Selenium、Puppeteer和Playwright。我在过去几年里这三种都实际用过，可以坦白说一句：Selenium胜在生态老、资料多，但它需要自己处理WebDriver和浏览器版本之间的匹配，这在容器化部署时很容易折磨人。Puppeteer在Node生态里很好用，功能也强，但默认锚定Chromium，如果你希望将来能换浏览器内核或者做跨浏览器验证，就得多写一层适配。

Playwright之所以在这类封装项目里成为我的首选，核心理由是三个。第一是自动等待机制。传统方案里你经常要手动sleep等元素出现，而Playwright内置了元素可见性、可交互性的等待逻辑，代码会自己等UI就绪，大幅降低“没睡够导致偶发失败”的概率。第二是context隔离能力。一个浏览器实例可以开出多个互不干扰的上下文，每个上下文拥有独立的cookies、localStorage和缓存，这正好用来管理多个登录会话。第三是多语言支持。官方提供Python和Node等语言的SDK，而且API设计非常统一，后续换语言重写的成本很低。

如果用一个表格来看，可能会更直观：

我不否认Selenium在Web应用测试里的地位，但在“把网页版封装成稳定API服务”这个目标上，Playwright的自动等待和Context隔离确实让我省掉了大量脏活。再加上它能和FastAPI这类Python服务无缝衔接，整个技术栈可以非常干净。

1.3 整体架构可以拆成三层加一道闸门

这套封装服务的整体结构，我习惯拆成三层。最底层是浏览器控制层，负责Chromium的启动、页面创建、浏览器关闭这些基础生命周期。中间层是会话管理层，维护一个“会话ID到浏览器上下文”的映射，记住每个会话当前处于什么状态。最上层是API服务层，对外提供标准HTTP接口，解析请求参数，把业务请求转译成页面操作，再把页面结果翻译成API响应。

在请求进入之前，还有一道并发控制闸门。我们不能让所有请求同时涌进同一个浏览器页面，那会造成操作互相踩踏。所以服务里必须有一个信号量或队列，把超过阈值的请求暂时挂起，等前面的操作完成后再放行。我一直强调，这个做法比“每次请求都临时启动浏览器”要正确得多。临时启动浏览器意味着每次都经历冷启动，慢且费内存，长期跑下去一定会出问题。

正确姿势是：浏览器常驻后台，服务启动时就创建好浏览器实例，之后按需创建上下文和页面。这套结构听上去不复杂，但真正稳定运行起来，需要把登录态、页面等待、流式输出这些细节处理到位。下面我逐个拆开讲。

2. 核心原理拆解：会话保持、页面驱动与流式响应捕获

2.1 登录态保持是第一个关键

网页版封装第一个要解决的问题，就是登录态。如果每次服务重启都要重新扫码或输入账号密码，这套东西就失去了自动化价值。Playwright对此提供了非常顺手的API：storageState。

操作过程分两步走。第一次运行时，我们启动一个带界面的浏览器，手动完成登录，然后把当前上下文里的cookies和localStorage整体导出成一个JSON文件。后续每次创建新上下文时，直接加载这个JSON文件，新页面就像刚登录过一样。可以把这个文件理解成一张“登录态快照”，你不用关心里面存放的具体字段，Playwright自己知道怎么存、怎么恢复。

第一次导出登录态的脚本大概长这样：

from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch(headless=False) context = browser.new_context() page = context.new_page() page.goto("https://chat.example.com") input("请在浏览器里完成登录，登录成功后回到终端按回车") context.storage_state(path="sessions/state.json") browser.close()

后续启动服务时，创建上下文就变成一行：

context = await browser.new_context(storage_state="sessions/state.json")

登录态不是永恒的，cookie会过期，token有刷新机制。所以上线后我额外加了一个巡检任务：每天定时打开一个测试页面，如果发现页面跳到登录页而不是对话页，就触发告警，日志里提示“需要重新执行登录脚本”。这个告警机制很重要，否则登录态悄悄过期后，整个服务会大面积超时，而你根本不知道从哪里排查起。

2.2 页面驱动：不要依赖sleep，要用状态感知

浏览器自动化让很多人觉得“玄学”的原因，在于页面元素的波动性。你昨天写的选择器，也许今天页面一改版就失效了。Playwright的自动等待解决了一部分问题，但业务层面的等待逻辑还得自己写，而且必须写得有弹性。

我总结的三板斧是：等待元素可见、等待元素内容变化、等待按钮状态翻转。比如等到输入框可见后再填内容，等待页面出现“停止生成”按钮后确认消息已被接收，再等这个按钮消失来确认生成结束。整个过程不应该有固定的sleep，因为模型生成时长是波动的，几秒到几十秒都有可能，固定等待时间一定会造成浪费或误判。

这里有一份核心交互的伪实现：

await input_box.fill(message) await page.keyboard.press("Enter") stop_button = page.get_by_role("button", name="停止") await stop_button.wait_for(state="visible", timeout=30_000) await stop_button.wait_for(state="detached", timeout=180_000) response = await page.locator(".markdown").last.inner_text()

注意，我把“停止生成按钮的出现和消失”当作消息生命周期的状态标记。这个思路在实际项目中非常稳定，因为它不依赖具体的响应内容，只依赖UI的状态切换。你可以把“停止”文案改成“Stop generating”，把选择器收敛到一个配置文件里，免得哪天页面改版后到处翻找硬编码。

2.3 流式响应捕获：把页面增量变成SSE推送

用户等待模型生成时，最怕的是界面像卡住一样没有反馈。网页版本身是流式输出的，我们封装成API时也可以把这种流式体验暴露出来，而不是傻等全部生成完再返回。

实现流式响应有两种思路。第一种是定时轮询页面结果区的文本，比较前后两轮的差异，把新增的文本块通过SSE推给客户端。这个方法跟具体网络协议无关，只要页面把文本渲染进DOM，就一定能读到，维护成本最低。第二种是拦截浏览器的网络请求，直接从接口响应里解析流式数据。这样做性能更好，但耦合度高，因为你要了解页面对应的具体请求协议，一旦页面改版，解析逻辑很容易失效。

我实际选择了第一种。轮询间隔设在200毫秒左右，可以接受，代码也简单。有一个坑要注意：流式生成过程中，结果区往往会出现临时标记字符，比如一个跳动的小方块，或者重复的空格。处理方式是先对比新旧文本，提取出纯增量部分，再对增量内容做一次黑名单字符过滤。把黑名单做成可配置的，而不是写死，这是我在多次页面改版后总结出来的教训。

3. 从零搭建：项目结构、核心代码与接口说明

3.1 一个尽量精简的项目结构

搭建项目时，我不喜欢把代码堆在一个文件里。这里给出一个我长期使用的目录结构，看起来足够干净，也方便扩展：

chatapi/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI入口 │ ├── chat_session.py # 浏览器封装核心类 │ ├── session_pool.py # 会话池和并发控制 │ └── config.py # 路径、超时、选择器配置 ├── sessions/ │ └── state.json # 登录态快照 ├── requirements.txt └── Dockerfile

依赖方面，我常用这几个包：

fastapi==0.110.0 uvicorn[standard]==0.29.0 playwright==1.42.0 sse-starlette==1.8.2 python-dotenv==1.0.1

版本号只是参考组合。安装时最需要留意的是Playwright和浏览器二进制之间的配套关系，一般通过playwright install安装的浏览器版本会跟pip包版本自动匹配。

3.2 会话封装类应该做成什么样

会话封装是服务最核心的类。它要负责持有自己的页面，内部用锁保证同一时间只有一个请求在操作页面，并提供关闭方法释放资源。

简化版本的实现思路如下：

import asyncio from playwright.async_api import Page, BrowserContext class ChatSession: def __init__(self, ctx: BrowserContext, base_url: str): self.ctx = ctx self.page: Page | None = None self.base_url = base_url self._lock = asyncio.Lock() async def open(self): self.page = await self.ctx.new_page() await self.page.goto(self.base_url, wait_until="domcontentloaded") async def ask(self, message: str, timeout: int = 120) -> str: async with self._lock: input_box = self.page.locator("textarea") await input_box.wait_for(state="visible") await input_box.fill(message) await self.page.keyboard.press("Enter") stop_button = self.page.get_by_role("button", name="停止") try: await stop_button.wait_for(state="visible", timeout=15_000) except Exception: pass await stop_button.wait_for(state="detached", timeout=timeout * 1000) response = await self.page.locator(".markdown").last.inner_text() return response async def close(self): if self.page: await self.page.close() if self.ctx: await self.ctx.close()

这里的textarea和.markdown都是示例选择器，实际项目里应该放进配置。我甚至在类里加了一个兜底逻辑：如果ask任何一步抛异常，先截图保存到本地，再抛出业务错误。这样无人值守时，第二天一看截图就知道问题出在哪一步。

3.3 对外API：普通返回和流式返回两种形态

API层用FastAPI实现非常顺手。一个普通JSON接口，一个SSE流式接口，两者共用同一个会话池。

普通接口的代码骨架：

from fastapi import FastAPI from pydantic import BaseModel from app.session_pool import session_pool app = FastAPI() class ChatRequest(BaseModel): session_id: str = "default" message: str timeout: int = 120 class ChatResponse(BaseModel): session_id: str reply: str @app.post("/v1/chat", response_model=ChatResponse) async def chat(req: ChatRequest): session = await session_pool.get(req.session_id) reply = await session.ask(req.message, req.timeout) return ChatResponse(session_id=req.session_id, reply=reply)

流式接口用sse-starlette输出：

from sse_starlette.sse import EventSourceResponse import json @app.post("/v1/chat/stream") async def chat_stream(req: ChatRequest): async def event_gen(): session = await session_pool.get(req.session_id) async for chunk in session.ask_stream(req.message): yield {"data": json.dumps({"delta": chunk}, ensure_ascii=False)} yield {"data": "[DONE]"} return EventSourceResponse(event_gen())

ask_stream方法本质上就是对第2.3节流式逻辑的封装，这里我特意做了异步生成器接口，让事件流在底层是自然的。两个接口都保留，是因为消费方需求不一样：服务端程序对接时JSON更省事，前端页面展示时SSE打字机效果更友好。

4. 部署落地：容器化、资源控制与长期运行观察

4.1 Docker镜像和浏览器依赖的坑

容器化部署会遇到一个经典问题：Chromium启动失败，报一堆二进制依赖缺失。原因很简单，容器基础镜像太干净了，缺共享库。我第一次踩坑时卡了大半天，后来学聪明了，直接在Dockerfile里把常见依赖全装上。

一个稳定可行的Dockerfile长这样：

FROM python:3.11-slim RUN apt-get update && apt-get install -y --no-install-recommends \ libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \ libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \ libgbm1 libpango-1.0-0 libcairo2 libasound2 \ curl ca-certificates \ && rm -rf /var/lib/apt/lists/* RUN pip install --no-cache-dir -r requirements.txt \ && playwright install --with-deps chromium WORKDIR /app COPY . /app CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8900"]

容器内启动Chromium时，同一外加两个参数比较稳妥：--no-sandbox和--disable-dev-shm-usage。第一个是因为容器内缺乏完整的用户命名空间，沙箱机制容易启动失败；第二个是因为容器默认的/dev/shm只有64MB，多开几个标签页就可能崩掉。这两个参数我在每个项目里都写进了启动配置，一次懒省事都没法长期忍住。

4.2 浏览器实例与内存控制的三个方向

Chromium本身就是内存大户。我实际观察过，一个常驻实例加三四个活跃页面，内存冲到五六百MB很常见。所以要长期稳定运行，资源控制必须有套路。

我用的三个手段可以分享。第一，全局信号量限制并发请求数，超出的请求排队等待，而不是一口气全塞给浏览器。第二，会话池设置TTL，每个session如果超过30分钟没有活跃请求，就关闭它对应的context。这是最有效的内存释放方式。第三，定时巡检进程内存，超过阈值后主动重启整个浏览器实例并重建会话池。

阈值设置需要拿捏。设太低，可能一天重启好几次，每次重启都有冷启动延迟；设太高，内存压力又大。在我那个每天几百次调用的场景里，阈值设在1.2GB左右比较合适，你可以根据实际可用内存调整。

4.3 健康检查与自动恢复

我给服务加了一个/healthz接口，检查两件事：浏览器进程是否还活着，以及能否正常打开对话页面。只有这两个条件都满足，接口才返回200。容器编排系统如果发现这个接口连续几次失败，就自动重启容器。这比只看进程是否存活要实际得多。

另外还加了一套后台任务：每隔15分钟用测试会话发一条极短的消息，验证整条链路能跑通，连续两次失败就触发告警。这套机制帮我扛过了几次官方页面改版初期的无人值守时段。页面一改版，选择器失效，链路检查立刻报警，我才能马上介入处理，不至于等用户报障才知道出问题。

5. 外部系统集成实战：调用方式与会话映射

5.1 最简单的HTTP调用方式

服务发布后，调用方根本不需要关心内部是浏览器还是纯API。对业务系统来说，这只是一个标准的HTTP JSON接口。

用curl调用长这样：

curl -X POST http://127.0.0.1:8900/v1/chat \ -H "Content-Type: application/json" \ -d '{"session_id": "ticket-12345", "message": "请用三点总结这个工单"}'

返回结果就是一个JSON：

{ "session_id": "ticket-12345", "reply": "1. ... 2. ... 3. ..." }

我在实际项目中，把它接进了工单系统：工单提交后，系统自动把描述字段发送给这个接口，模型返回的分析备注再插入工单的备注区。整个过程对终端用户完全透明，接入成本极低。你甚至可以只在配置中心里加一个URL，不需要给调用方提供任何SDK。

5.2 多轮对话靠session_id映射

一个容易忽略的重点是session_id参数的语义。如果你每次都传不同的session_id，服务就会为每个ID新建一个页面和上下文，相当于每次都是新对话，模型不会记得之前的上下文。所以多轮对话的应用必须让同一个业务实体复用同一个session_id。

我在会话池里维护了一个字典，把session_id映射到ChatSession对象。每次请求来时，先查池子，不存在则新建。池子里的session有生命周期管理，超过空闲时间会被自动回收。调用方需要在业务实体删除时，主动调用注销接口清理映射，避免空闲会话占着内存不放。

5.3 权限控制要做的几件小事

如果服务只跑在内网，权限管控可以轻一点，但基本校验不能省。至少要做四件事：API密钥校验、按调用方限流、字段长度限制、超时上限限制。实现上很直接，FastAPI里写一个依赖函数就能全局生效。

from fastapi import Header, HTTPException async def verify_api_key(x_api_key: str = Header(...)): if x_api_key != settings.api_key: raise HTTPException(status_code=401, detail="invalid key")

这套手段不是要防什么高级攻击，而是防止内部误用。比如某个同事写了个循环，把所有工单一次性灌进来，如果没有限流，浏览器瞬间就会被压垮。有了这层保护，至少能保证服务只被预期的方式使用。

6. 常见故障与排查实录

6.1 高频问题速查表

在实际运行中，最常遇到的故障大概是这些：

这张表里的每一项，我都在真实环境里遇到过至少一次。比如流式文本重复，当时是因为页面在输出时会先渲染一个历史回声，我直接按全文切片把上一轮内容又推了一遍，后来改成“只追加后半段新增字符”才解决。

6.2 调试三件套：截图、视频、追踪

网页封装类服务最痛苦的地方在于“看不见现场”。为了让自己能远程排障，我把调试能力做成了基础设施。第一步，任何异常分支都调用page.screenshot保存现场图；第二步，关键会话开启视频录制，方便回放操作过程；第三步，使用Playwright的Tracing功能，把操作的完整时间轴导出，配合Trace Viewer查看每个步骤的耗时常。

我觉得最有价值的是Trace。比如你说不清楚“为什么发送消息后卡了40秒”，打开Trace时间轴，一眼就能看到是哪一步等待耗掉了时间。纯靠日志猜，效率低一个数量级。所以建议在开发阶段就把tracing能力内置到服务里，哪怕只是触发条件式开启。

6.3 我总结的三条维护经验

第一，页面相关的所有选择器、按钮文案、超时时间，一律收敛到配置文件里，绝不散落在业务代码中。页面每次改版，运营人员只需要改配置文件，不需要改动核心逻辑，大大压缩修复时间。

第二，这类封装服务适合做辅助能力，不建议承担核心SLA。它受限于页面自身的加载速度、渲染机制和产品体验升级节奏，天然有不确定性。业务量上来之后，就要认真考虑往正式接口或更稳定的商业化能力迁移。这个判断要有意识，不然等到它瓶颈爆发时才迁移，整个团队都会被拖进急救状态。

第三，要提前设计降级方案。我接工单系统时特别设置了一条规则：封装服务连续超时超过阈值，工单流程自动跳过AI分析，绝不阻塞主流程。集成任何不稳定能力，都必须先想明白“它挂了业务怎么办”。有降级，才有资格谈稳定。

这套Playwright封装方案，我前前后后迭代过好几轮，从最开始每次请求都临时开浏览器，到后来常驻实例加会话池管理，稳定性提升非常明显。如果你也要做类似的事，希望这篇能帮你绕开我已经踩过的坑。