【AI应用实战】用 FastAPI + SSE 做一个自己的 AI 聊天网页:流式输出、多轮对话与完整源码

想把大模型接进自己的网页,却被"接口怎么接、回复怎么逐字出现、上下文怎么带、密钥放哪里"劝退?下面从一个空目录搭建可本地启动的 AI 聊天网页。默认演示模式不用申请 API Key;换成 OpenAI 兼容接口后,就能把回复接到真实模型。

网页提交最近对话,FastAPI 校验并裁剪上下文,再向模型发起流式请求;模型返回的数据被转成浏览器可读的 SSE 事件,前端边读边显示。聊天记录保存在当前浏览器中。

从一次模型调用到可用的聊天网页

把大模型接入网页,最简单的做法是发送请求、等待完整结果,再一次性显示。但回答稍长时,用户只能盯着加载动画;如果还要保留上下文、管理密钥和保存聊天记录,就需要把一次 API 调用扩展成完整的前后端链路。

下面从空目录搭建一个轻量的 AI 聊天网页:FastAPI 负责校验请求并连接模型,SSE 负责逐段传送回复,浏览器边接收边渲染。项目使用 OpenAI Chat Completions 风格的模型接口,默认启用内置模拟回复,因此第一次启动不需要 API Key。连接真实模型时,只需配置服务端环境变量,并按服务商的兼容情况调整模型适配层。

最后会得到什么

  • 一个深色简洁的聊天页面,支持桌面和手机浏览。
  • FastAPI 后端,提供 POST /api/chat/stream 流式接口。
  • SSE(Server-Sent Events)逐段发送回复,浏览器收到一段就显示一段。
  • 携带最近的多轮对话,同时对条数和文本长度设限。
  • 浏览器本地保存最近聊天记录,刷新后可以继续查看,也可以一键清空。
  • 默认演示模式不需要模型密钥;切换真实接口时,密钥只放在服务端环境变量。
  • Docker Compose 启动方式和完整示例源码。

这里做的是一个学习用的最小项目,不带用户系统、数据库、配额计费或内容审核。后面会说明上线前还要补什么。

项目结构

text 复制代码
ai-chatbot-fastapi-demo/
├── app.py                  # FastAPI 接口、模拟模型、上游流式适配
├── requirements.txt
├── Dockerfile
├── compose.yaml
├── .env.example
└── static/
    ├── index.html
    ├── app.js               # 提交问题、解析 SSE、更新页面
    └── style.css

项目文件解压后目录名为 ai-chatbot-fastapi-demo。默认演示模式不需要配置大模型服务。

一、先把项目跑起来

需要 Python 3.11 或更新版本。进入项目目录:

bash 复制代码
python -m venv .venv

Windows PowerShell 激活虚拟环境:

powershell 复制代码
.venv\Scripts\Activate.ps1

macOS / Linux 激活方式:

bash 复制代码
source .venv/bin/activate

安装依赖并启动:

bash 复制代码
pip install -r requirements.txt
uvicorn app:app --reload

浏览器打开 http://127.0.0.1:8000。默认 MOCK_LLM=true,输入问题后会看到模拟文字分段到达。这个模式验证的是页面到后端的流式链路,不是在调用真实大模型,也不会产生模型费用。

项目也提供 Docker Compose:

bash 复制代码
docker compose up --build

二、先理解一次对话经过了哪里

普通的非流式接口通常是"等模型完整生成,再一次性返回"。如果回答要生成几秒,页面就只能一直转圈。流式方案把回复拆成一段段数据:模型生成一段、后端转发一段、浏览器显示一段。

这个项目里一次提问的过程是:

  1. 前端把当前问题和最近对话通过 fetch 发给 /api/chat/stream。
  2. FastAPI 检查最后一条消息是否为用户消息,裁剪历史,并限制上下文总字符数。
  3. 后端在 system prompt 前置后,请求模型兼容接口,并打开流式返回。
  4. 后端读取上游 SSE 中的 data: 行,抽出模型新生成的文本,再转成自己的事件格式。
  5. 浏览器从响应流中逐帧解析事件,使用 textContent 更新回复气泡。
  6. 对话放进当前浏览器的 localStorage,刷新页面仍可查看;清空按钮会删除这份本地记录。

为什么用 SSE?因为这是"服务器不断推送文本,浏览器只需要接收"的场景。浏览器用 EventSource 时,默认以 GET 建立连接,不适合直接带 JSON 请求体;本例因此使用 fetch 发 POST,再用 ReadableStream 读取响应。FastAPI 的 StreamingResponse 可以将生成器产出的内容连续发送给客户端。具体行为可参考 FastAPI StreamingResponse 文档 和 MDN Fetch 流式读取说明。

三、FastAPI:校验输入并把回复转成 SSE

请求结构保持简单:每条消息只能是 user 或 assistant,文本长度有限,单次最多带 20 条消息。Pydantic 先做基本结构校验,接口再判断最后一条是不是用户输入。

python 复制代码
class Message(BaseModel):
    role: Literal["user", "assistant"]
    content: str = Field(min_length=1, max_length=6000)


class ChatRequest(BaseModel):
    messages: list[Message] = Field(min_length=1, max_length=20)


def sse(payload: dict[str, str]) -> str:
    return f"data: {json.dumps(payload, ensure_ascii=False)}\n\n"

SSE 的关键是每个事件以空行结束 。本例在 JSON 外包一层 data: ...,再追加两个换行。ensure_ascii=False 让中文以 UTF-8 文本发送,而不是转成一长串 Unicode 转义。

接口入口先把最近 12 条消息送去模型。浏览器可以保留更长的本地记录,但每次请求不会无限携带全部历史,这能控制上下文体积,也避免页面开很久后请求越来越大。

python 复制代码
@app.post("/api/chat/stream")
async def chat_stream(request: ChatRequest):
    messages = recent_messages(request.messages)
    if not messages or messages[-1]["role"] != "user":
        raise HTTPException(status_code=422, detail="最后一条消息必须来自用户。")
    if sum(len(item["content"]) for item in messages) > 18000:
        raise HTTPException(status_code=413, detail="本次上下文过长,请清理较早的对话。")

    generator = mock_stream() if MOCK_LLM else provider_stream(messages)
    return StreamingResponse(
        generator,
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache, no-transform",
            "X-Accel-Buffering": "no",
        },
    )

recent_messages 会对文本做 strip(),只取末尾 12 条。再限制总字符数不是完整的 token 计费,也不能替代模型上下文长度检查;它只是一个简单的边界,真正上线时应按目标模型的 tokenizer 和价格规则管理 token。

StreamingResponse 的内容来自异步生成器。模拟模式每次吐出几个字符,真实模式则逐行读取模型上游的数据:

python 复制代码
async for line in response.aiter_lines():
    if not line.startswith("data:"):
        continue
    data = line[5:].strip()
    if data == "[DONE]":
        break
    event = json.loads(data)
    choices = event.get("choices") or []
    if not choices:
        continue
    delta = choices[0].get("delta") or {}
    content = delta.get("content")
    if isinstance(content, str) and content:
        yield sse({"type": "token", "content": content})

真实服务的流式格式可能有差异:有些会先发 role,有些会发工具调用或 usage,有些接口路径也不相同。代码只取 choices[0].delta.content 的文本片段;接其他服务时,优先对照供应商的接口文档,改 provider_stream() 即可,前端的 SSE 协议不用跟着改。

如果上游返回错误,前端不应该看到 Authorization 头、完整错误响应或密钥。示例只把通用错误事件发回浏览器,详细异常留在后端日志里。真实部署还应给日志加脱敏规则,避免把用户问题或供应商响应原样写进长期日志。

四、浏览器端:别把网络分块当成事件边界

前端用 fetch 发请求:

javascript 复制代码
const response = await fetch("/api/chat/stream", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Accept": "text/event-stream" },
  body: JSON.stringify({ messages: history.slice(-20) }),
});

最容易踩的坑在于:浏览器的 reader.read() 每次拿到的是网络分块 ,它不保证刚好对应一条 SSE 事件,也不保证一条事件只落在一个分块里。比如某条 JSON 事件可能在 { "type": 中间被切开;如果每读一次就直接 JSON.parse,就会偶发报错。

正确做法是保留一个 buffer,每次把新字节解码后追加进去,再按 SSE 事件边界(空行)切分。剩下的不完整部分留到下一次读取:

javascript 复制代码
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { value, done } = await reader.read();
  buffer += decoder.decode(value || new Uint8Array(), { stream: !done });

  while (true) {
    const match = /\r?\n\r?\n/.exec(buffer);
    if (!match) break;
    const frame = buffer.slice(0, match.index);
    buffer = buffer.slice(match.index + match[0].length);
    handleEvent(frame);
  }
  if (done) break;
}

还有一个很实际的安全习惯:模型文本和用户输入都作为普通文本展示,更新气泡时使用 textContent。不要把模型回复直接拼到 innerHTML,否则遇到 HTML 或脚本片段时,会把纯文本显示变成潜在的脚本注入入口。这个简化页面不解析 Markdown,所以代码围栏会原样显示;如果要加 Markdown 渲染,需要选用经过维护的解析器,并对输出做安全处理。

五、多轮对话和聊天记录放在哪里

模型本身不会因为上次调用过就自动记得对话。本项目通过每次请求都带上最近若干轮消息,构成上下文:

text 复制代码
system: 你是一个清晰可靠的中文技术助手......
user: 我准备学习 FastAPI,先学什么?
assistant: 可以先从路由、请求模型和响应开始......
user: 给我一个周末练习安排。

越长的历史意味着更大的请求体、更多输入 token 和更高费用,所以示例限制请求条数与总字符数,只截取最近 12 条给模型。真实应用可以进一步做摘要记忆、按会话保存、按 token 预算裁剪,或者让用户新建一段对话。

这份示例把聊天内容存在浏览器 localStorage,是为了少引入数据库,让读者先看清主要链路。它有几个边界:记录只在当前浏览器和当前站点可见,不会跨设备同步;同一台电脑的其他使用者可能读到这份历史;清理浏览器站点数据会删掉记录。因此不要在共享设备上保存密码、个人隐私或公司敏感内容。生产产品通常要有账号隔离、服务端会话存储、保留期限和用户删除入口。

六、把真实模型接进来

复制 .env.example 为 .env,再由 Docker Compose 读取。示意配置如下:

dotenv 复制代码
MOCK_LLM=false
LLM_BASE_URL=https://你的服务商地址/v1
LLM_MODEL=你的模型名称
LLM_API_KEY=你的密钥

然后重新启动:

bash 复制代码
docker compose up --build

不要把真实密钥写进 static/app.js、HTML、浏览器 localStorage 或截图里。浏览器代码是公开的,用户可以通过开发者工具查看;模型请求由后端代发,密钥放在服务端环境变量中。.env 已被加入 .gitignore,但忽略规则不是保险箱:部署平台应使用自己的 Secret 管理功能,密钥泄露后及时轮换。

这个示例默认调用 {LLM_BASE_URL}/chat/completions,Authorization 使用 Bearer Token,消息体里带 stream: true。并非所有厂商都完全兼容这一约定。连不上时依次检查:

  1. 容器/服务器能否访问 LLM_BASE_URL,是否需要代理或专有网络。
  2. Base URL 是否已经包含版本路径,代码是否又拼接了重复路径。
  3. 模型名称和 API Key 是否匹配,服务是否要求额外请求头。
  4. 上游是否真的返回 SSE,数据字段是否是 choices[].delta.content。
  5. 反向代理是否缓冲了响应,导致内容攒到最后才发给浏览器。

若使用 Nginx 等反向代理,要确认流式路由没有被代理缓冲;项目响应里设置了 X-Accel-Buffering: no,但最终还要检查代理、网关和 CDN 的配置。浏览器看到"最后一下全出来",常常不是模型没流式生成,而是中间某一层把数据攒住了。

七、上线之前还缺什么

一个能跑通的 Demo 和一个能承载真实用户的服务,中间还有不少工程工作。至少要考虑:

  • **认证与限流:**防止匿名接口被刷,按用户或 IP 控制并发和调用额度。
  • **费用控制:**限制输入 token、输出 token、最大生成时长和每个账号的日预算。
  • **数据与隐私:**决定是否保存会话、保存多久、谁能访问,以及如何删除。
  • **可靠性:**请求超时、取消任务、上游重试策略、并发连接上限和服务降级。
  • **可观测性:**记录请求 ID、耗时、首 token 时间、错误类别和用量;不要把 API Key 打进日志。
  • **内容安全:**按产品面向的人群设计输入输出策略,给用户反馈和举报入口。
  • **部署配置:**HTTPS、跨域规则、代理缓冲、环境变量注入、健康检查与容器资源限制。

不要把 system prompt 当作访问控制机制。它只能影响模型倾向,不能代替服务器端权限校验。比如某个用户只允许看自己的订单,订单查询必须先在后端验证身份和数据归属,不能只在 prompt 里要求模型"不要看别人的订单"。

八、几个常见问题

Q:我没有模型 API Key,能不能看效果?

可以。默认演示模式会返回一段模拟文字,用来观察提交、SSE 传输和逐段渲染。要得到真实回答才需要连接模型服务。

Q:为什么用了 SSE,页面还是等很久才显示?

检查上游模型是否启用流式、后端是否逐段 yield、反向代理是否缓冲,还要看前端是否真的边读边更新 DOM。任何一层攒数据,都会让"流式"看起来像普通响应。

Q:刷新后还能看到之前的对话吗?

可以,本地演示把记录存进当前浏览器的 localStorage。它不是云端备份,也不适合存放敏感信息。

Q:可以接本地模型吗?

可以,前提是本地模型服务提供兼容的 HTTP Chat Completions 接口,且运行 FastAPI 的机器能访问那个地址。如果字段格式不同,只调整 provider_stream() 的请求和解析逻辑。

Q:为什么不直接用前端 AI SDK?

前端 SDK 可以减少重复代码,但也可能隐藏请求体、SSE 边界和上下文裁剪等细节。了解这些基础环节后,再使用成熟 SDK 构建复杂产品,会更容易排查传输问题和确认安全边界。

总结

这个项目虽然只有一个页面和一个 FastAPI 服务,却把 AI 聊天应用最核心的一圈串起来了:接收多轮消息、限制上下文、调用模型、逐段转发、前端消费响应流、保留本地历史。把这条链路弄清楚后,再加入用户体系、知识库、工具调用或语音输入,就有了一个可以逐步扩展的起点。

如果你是第一次做 AI 应用,建议按这个顺序动手:先在演示模式看懂前后端数据流,再接入一个自己能访问的模型服务,最后才考虑数据库、登录和部署。不要一上来堆很多功能,先确认每一段数据究竟在哪里产生、经过什么校验、会被谁看到。

完整项目目录:ai-chatbot-fastapi-demo/。依赖和启动方式见项目内 README。

相关推荐
世冠科技24 分钟前
世冠科技GCEAgent重磅发布,开启复杂装备AI原生智能研发新范式
人工智能·科技·ai-native
轻松,带微笑35 分钟前
AI竞争进入下半场:微软押注专业模型,通用大模型不再是唯一答案
人工智能·microsoft
哈尔滨张谦蛋39 分钟前
兰州大学 · 甘肃省可穿戴装备重点实验室 · 2027年博士招生
人工智能·深度学习
MysTic_Zhong1 小时前
【3】核心引擎:LangGraph 编排与多路召回重排
人工智能·agent
vivo互联网技术1 小时前
研发数字人 Agent:从 0 到 1 的架构与实践
人工智能·agent·mcp
练习两年半的攻城狮1 小时前
企业级 AI Agent 架构知识点讲解(一):从知识型到业务型,从 LangGraph 到生产落地
人工智能·架构
the局外人1 小时前
Python 实战检索优化:BM25、向量与重排
数据库·后端·python
__underline__1 小时前
冷门Python知识点006篇:Python 类体里的名字,能被"凭空造出来"
后端·python