1. 为什么你需要一个流式 MCP 服务器?
如果你正在开发一个AI应用,比如一个智能聊天助手、一个代码生成工具,或者一个需要实时反馈的文档分析系统,你肯定遇到过这样的问题:用户问了一个复杂的问题,模型吭哧吭哧“思考”了十几秒,最后才吐出一个完整的答案。在这段等待时间里,用户盯着空白的屏幕,心里可能在想:“是不是卡了?还是出错了?” 这种体验非常糟糕。
我几年前做第一个AI项目时,就踩过这个坑。当时我们的后端用同步接口,模型生成一段长文本需要近20秒,前端页面就跟死了一样。后来我们引入了流式响应,让答案像打字一样一个字一个字地“流”出来,哪怕总时间没变,用户的感知体验却好了十倍不止——他们能立刻看到系统在“工作”,有反馈,心里就踏实。
这就是 Streamable HTTP 的核心价值。它不是一项高深莫测的技术,你可以把它理解为服务器和客户端之间的一条“数据水管”。服务器这边一边处理(比如模型一边推理),一边把处理好的片段通过这根水管实时推送给客户端。客户端则像接水一样,收到一段就展示一段。对于需要长时间运行或实时更新的任务,这几乎是提升用户体验的必选项。
而 MCP(Model Context Protocol),你可以把它看作在这根“数据水管”上传输的“货物包装标准”。它定义了一套规则,约定了客户端和服务器之间应该如何打招呼(初始化)、如何发送指令(方法调用)、如何报告进度、如何传递上下文信息。有了这个协议,你的AI服务就不再是一个黑盒,客户端能清楚地知道当前处理状态,也能更结构化地与模型交互。
所以,把 FastAPI、Streamable HTTP 和 MCP 结合起来,你得到的就是一个现代化、高性能、体验优秀的实时AI服务后端架构。FastAPI 凭借其原生的异步支持和简洁的语法,是实现这类流式服务的绝佳选择。接下来,我就带你从协议设计开始,一步步搭建一个完整的、支持多端接入的流式 MCP 服务器。
2. 动手之前:理解核心协议与设计思路
在敲代码之前,我们得先把“游戏规则”定好。直接照搬别人的协议可能不适合你的业务,所以我们先从设计自己的 MCP 协议开始。别担心,这并不复杂,我们可以参考 JSON-RPC 2.0 的格式,因为它结构清晰、广泛支持。
我们的 MCP 协议主要围绕几个核心交互展开:
- 会话初始化:客户端和服务器建立连接,互相告知“我能做什么”(能力协商)。
- 方法调用:客户端请求服务器执行某个任务,比如
generateText、analyzeDocument。 - 流式响应:对于耗时任务,服务器通过 Server-Sent Events (SSE) 流式返回中间结果和最终结果。
- 进度跟踪:在流式响应中,携带进度令牌,让客户端能精确知道任务处理到了哪一步。
- 会话管理:通过一个唯一的
session_id来关联同一用户的所有请求,维持对话上下文。
这里我画一个简单的交互流程图来帮你理解(我们用文字描述):客户端首先发送一个 initialize 请求,服务器创建一个会话并返回 session_id。之后客户端的每个请求都带上这个 session_id。当客户端调用一个如 generate 的流式方法时,服务器会返回一个 SSE 流的端点地址,客户端监听这个流,服务器则把生成的文本片段、中间状态或进度信息,源源不断地推送到这个流中。
一个典型的请求体看起来是这样的:
{
"jsonrpc": "2.0",
"id": 123,
"method": "generate",
"params": {
"prompt": "请用Python写一个快速排序函数",
"stream": true,
"_meta": {
"progressToken": "progress_abc"
}
}
}
响应可能是立即返回的 JSON,也可能是开启一个流。对于流式响应,我们选择 SSE 而不是 WebSocket,原因在于 SSE 是纯粹的服务器推送,基于 HTTP,更简单轻量,自动处理重连,对于这种单向数据流(服务器->客户端)的场景非常适合。
设计协议时,一个我踩过的坑是版本管理。一定要在初始化请求里带上 protocolVersion 字段。这样当你的协议未来升级时,服务器可以识别旧版客户端,并做出兼容性处理,避免直接报错导致服务不可用。
3. 搭建 FastAPI 服务器核心骨架
理论说得差不多了,我们开始动真格的。首先创建一个新的项目目录,并设置虚拟环境,这是保持环境干净的好习惯。
mkdir mcp-streaming-server
cd mcp-streaming-server
python -m venv venv
# 激活虚拟环境
# Windows: venv\Scripts\activate
# Mac/Linux: source venv/bin/activate
接下来安装核心依赖。FastAPI 是我们的框架,Uvicorn 是高性能的异步服务器,pydantic 用于数据验证(FastAPI 自带,但明确一下有好处)。
pip install fastapi uvicorn pydantic
现在,创建 server.py 文件,我们来构建服务器的核心。第一步是基础的 FastAPI 应用和跨域处理。因为我们的客户端很可能是独立的前端应用,所以必须处理 CORS。
from fastapi import FastAPI, Request, HTTPException, Depends
from fastapi.responses import StreamingResponse, JSONResponse
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from typing import Optional, Dict, Any
import asyncio
import uuid
import json
import time
app = FastAPI(title="MCP Streaming Server", version="1.0.0")
# 关键:配置CORS,允许前端访问
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # 生产环境应替换为具体的前端域名
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
expose_headers=["Mcp-Session-Id"] # 允许前端JS读取这个自定义头
)
这里有个细节:expose_headers 非常重要。默认情况下,浏览器的 JavaScript 只能访问一些基本的响应头(如Content-Type)。如果我们不把 Mcp-Session-Id 暴露出来,前端即使收到了,也无法通过 response.headers.get('Mcp-Session-Id') 读到它,会话管理就会失败。
接下来,我们需要一个地方来存储会话状态。在真实的生产环境中,你可能会用 Redis 或数据库。但为了演示,我们先用一个内存字典。注意,这个字典需要是线程安全或异步环境安全的,这里简单处理。
# 内存中的会话存储(生产环境请使用Redis等)
sessions: Dict[str, Dict[str, Any]] = {}
# Pydantic模型,用于定义请求/响应结构
class RPCRequest(BaseModel):
jsonrpc: str = "2.0"
id: Optional[int] = None
method: str
params: Optional[Dict[str, Any]] = None
class InitializeParams(BaseModel):
protocolVersion: str
capabilities: Dict[str, Any]
clientInfo: Dict[str, str]
定义数据模型能让 FastAPI 自动帮我们做请求验证和文档生成,减少很多低级错误。现在,让我们实现第一个核心端点:初始化。
4. 实现会话管理与初始化端点
初始化是握手环节。客户端告诉服务器:“嗨,我来了,这是我的协议版本和能力。” 服务器则回复:“好的,这是你的会话ID,这是我的能力。”
我们创建一个 /initialize 的 POST 端点。
@app.post("/initialize")
async def initialize_session(request: Request, rpc_req: RPCRequest):
if rpc_req.method != "initialize":
raise HTTPException(status_code=400, detail="Method must be 'initialize'")
params = rpc_req.params
if not params:
raise HTTPException(status_code=400, detail="Missing params")
# 这里可以校验 protocolVersion,做版本兼容逻辑
client_version = params.get("protocolVersion", "unknown")
print(f"Client connected with version: {client_version}")
# 生成唯一的会话ID
session_id = str(uuid.uuid4())
# 初始化会话存储,可以存放用户上下文、模型状态等
sessions[session_id] = {
"created_at": time.time(),
"client_info": params.get("clientInfo", {}),
"context": [] # 用于存储对话上下文
}
# 构建成功响应
response_data = {
"jsonrpc": "2.0",
"id": rpc_req.id,
"result": {
"sessionId": session_id,
"serverInfo": {
"name": "MCP-Streaming-Server",
"version": "1.0",
"protocolVersion": "2024-11-05"
},
"capabilities": { # 告诉客户端服务器支持什么
"streaming": True,
"methods": ["generate", "analyze", "chat"],
"supportsProgress": True
}
}
}
# 关键:将会话ID放在响应头中返回
return JSONResponse(content=response_data, headers={"Mcp-Session-Id": session_id})
你可能注意到,我们把 session_id 放在了响应头里,而不是响应体里。这是一种常见的 RESTful 实践,尤其是对于这种“会话”概念的资源。客户端在后续所有请求中,都需要在 Mcp-Session-Id 头里带上这个 ID。
那如果客户端没带会话ID就访问其他接口怎么办?我们需要一个依赖项来校验它。
from fastapi import Header
async def get_session(session_id: Optional[str] = Header(None, alias="Mcp-Session-Id")):
if not session_id:
raise HTTPException(status_code=401, detail="Mcp-Session-Id header is required")
if session_id not in sessions:
raise HTTPException(status_code=404, detail="Session not found or expired")
return session_id, sessions[session_id]
@app.post("/rpc")
async def handle_rpc(request: Request, session_info: tuple = Depends(get_session)):
session_id, session_data = session_info
# 获取原始的JSON体,因为我们可能要根据method动态处理
body = await request.json()
method = body.get("method")
# 根据不同的方法路由到不同的处理逻辑
if method == "generate":
return await handle_generate(session_id, session_data, body)
elif method == "chat":
return await handle_chat(session_id, session_data, body)
else:
raise HTTPException(status_code=404, detail=f"Method '{method}' not supported")
这样,我们就有了一个带基础会话管理的 RPC 入口。接下来,就是最精彩的部分:实现流式响应。
5. 核心魔法:实现流式响应与进度反馈
流式响应的本质,是服务器生成一个异步生成器,这个生成器每次 yield 一段数据,FastAPI 的 StreamingResponse 会把这些数据按照指定的格式(如 text/event-stream)发送给客户端。
我们来实现一个 handle_generate 函数,模拟一个流式文本生成。
async def handle_generate(session_id: str, session_data: dict, rpc_body: dict):
params = rpc_body.get("params", {})
prompt = params.get("prompt", "")
stream = params.get("stream", False)
progress_token = params.get("_meta", {}).get("progressToken")
if not stream:
# 非流式响应:直接处理并返回完整结果(模拟)
await asyncio.sleep(2) # 模拟处理耗时
result = {"text": f"这是对‘{prompt}’的完整回复(非流式)。"}
return JSONResponse(content={"jsonrpc": "2.0", "id": rpc_body.get("id"), "result": result})
# 流式响应:返回一个 StreamingResponse
async def event_stream():
# 首先,可以立即返回一个“开始”事件
if progress_token:
yield f"event: progress\ndata: {json.dumps({'token': progress_token, 'value': 0})}\n\n"
# 模拟分块生成文本
simulated_chunks = [
"让我们来思考一下这个问题。",
"首先,我们需要理解核心需求。",
"然后,我们可以分步骤实现。",
"最后,进行测试和优化。",
"完成!"
]
for i, chunk in enumerate(simulated_chunks):
await asyncio.sleep(1) # 模拟每块生成需要1秒
# 1. 发送进度更新
if progress_token:
progress = (i + 1) / len(simulated_chunks)
yield f"event: progress\ndata: {json.dumps({'token': progress_token, 'value': progress})}\n\n"
# 2. 发送文本块
yield f"data: {json.dumps({'chunk': chunk, 'index': i})}\n\n"
# 3. 发送最终结果事件,标记流结束
yield f"event: result\ndata: {json.dumps({'text': '所有内容生成完毕。'})}\n\n"
# 4. 可选的:发送一个 [DONE] 事件,某些前端库需要
# yield "event: done\ndata: [DONE]\n\n"
# 关键:media_type 必须设置为 text/event-stream
return StreamingResponse(
event_stream(),
media_type="text/event-stream",
headers={"Mcp-Session-Id": session_id, "Cache-Control": "no-cache"}
)
这段代码里有几个关键点:
event_stream是一个异步生成器:它用async def定义,里面用yield返回数据块。await asyncio.sleep模拟了IO或模型计算耗时。- SSE 格式:每个
yield返回的字符串必须遵循 SSE 格式。data:开头后面跟数据,以两个换行符\n\n结束。我们还可以定义自定义事件,如event: progress。 - 进度反馈:通过
progress事件,携带一个progressToken和进度值value,客户端可以用这个来更新进度条。 - 最终标记:使用
event: result或[DONE]来明确告诉客户端流式传输已结束。
现在,我们的服务器已经具备了流式响应的能力。用 uvicorn server:app --reload 启动服务器,它将在 http://127.0.0.1:8000 运行。
6. 打造一个健壮的 Python 客户端
服务器准备好了,我们需要一个能对话的客户端。我们先从 Python 客户端开始,因为它常用于自动化脚本、后端服务间调用或测试。
创建一个 client.py 文件。我们将使用 httpx 库,因为它对异步和流式请求的支持比 requests 更原生、更友好。
pip install httpx
import httpx
import asyncio
import json
class MCPClient:
def __init__(self, base_url="http://127.0.0.1:8000"):
self.base_url = base_url
self.session_id = None
self.client = httpx.AsyncClient(timeout=30.0) # 设置一个较长的超时
async def initialize(self):
"""初始化会话"""
init_request = {
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {
"roots": {"listChanged": True},
"sampling": {}
},
"clientInfo": {
"name": "PythonDemoClient",
"version": "1.0.0"
}
}
}
try:
response = await self.client.post(f"{self.base_url}/initialize", json=init_request)
response.raise_for_status()
result = response.json()
self.session_id = response.headers.get("Mcp-Session-Id")
print(f"[初始化成功] 会话ID: {self.session_id}")
print(f"服务器能力: {result.get('result', {}).get('capabilities')}")
return result
except httpx.HTTPStatusError as e:
print(f"初始化请求失败: {e}")
return None
async def call_method(self, method: str, params: dict, stream=False):
"""调用RPC方法"""
if not self.session_id:
print("错误:请先调用 initialize() 初始化会话。")
return None
request_data = {
"jsonrpc": "2.0",
"id": 2, # ID应递增,这里简化为固定值
"method": method,
"params": params
}
headers = {"Mcp-Session-Id": self.session_id}
if stream:
# 流式请求:我们使用 /rpc 端点,服务器返回StreamingResponse
async with self.client.stream('POST', f"{self.base_url}/rpc", json=request_data, headers=headers) as response:
print(f"[流式响应开始] 状态码: {response.status_code}")
async for line in response.aiter_lines():
if line.startswith('data:'):
# 解析SSE的data字段
data_str = line[5:].strip()
if data_str:
try:
data = json.loads(data_str)
print(f"收到数据块: {data}")
except json.JSONDecodeError:
print(f"收到文本块: {data_str}")
elif line.startswith('event:'):
event_type = line[6:].strip()
print(f"收到事件: {event_type}")
# 空行是SSE的分隔符,忽略
else:
# 非流式请求
response = await self.client.post(f"{self.base_url}/rpc", json=request_data, headers=headers)
result = response.json()
print(f"[非流式响应] 结果: {result}")
return result
async def close(self):
"""关闭客户端连接"""
await self.client.aclose()
async def main():
client = MCPClient()
try:
# 1. 初始化
await client.initialize()
# 2. 发送一个非流式请求
print("\n--- 测试非流式请求 ---")
await client.call_method("chat", {"message": "你好,世界!"}, stream=False)
# 3. 发送一个流式请求
print("\n--- 测试流式请求 ---")
await client.call_method(
"generate",
{
"prompt": "解释一下人工智能",
"stream": True,
"_meta": {"progressToken": "test_progress_123"}
},
stream=True
)
finally:
await client.close()
if __name__ == "__main__":
asyncio.run(main())
这个客户端类做了几件重要的事:
- 封装会话管理:自动在
initialize中获取并存储session_id,并在后续请求的 header 中自动携带。 - 区分流式与非流式调用:
call_method根据stream参数决定如何处理。对于流式请求,它使用httpx的stream上下文管理器和aiter_lines()来异步迭代服务器推送的每一行数据。 - 解析 SSE:它按照 SSE 格式解析每一行,区分
data:和event:,并尝试解析 JSON 数据。
运行这个客户端,你会看到它先初始化,然后收到一个即时回复,最后开始接收流式的文本块和进度事件,体验非常直观。
7. 构建一个交互式的前端 Web 客户端
对于最终用户,一个网页界面是最直观的。我们将创建一个简单的 index.html,使用原生 JavaScript 的 EventSource API 来接收 SSE 流,并用 fetch API 发送 RPC 请求。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>MCP 流式客户端演示</title>
<style>
* { box-sizing: border-box; }
body { font-family: 'Segoe UI', system-ui, sans-serif; margin: 0; padding: 20px; background: #f5f7fa; color: #333; }
.container { max-width: 900px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 6px 16px rgba(0,0,0,0.08); padding: 30px; }
h1 { color: #2d3748; border-bottom: 2px solid #4299e1; padding-bottom: 10px; }
.control-panel { background: #edf2f7; padding: 20px; border-radius: 8px; margin-bottom: 25px; }
.btn { padding: 12px 24px; margin: 0 10px 10px 0; border: none; border-radius: 6px; cursor: pointer; font-weight: 600; transition: all 0.2s; }
.btn-primary { background: #4299e1; color: white; }
.btn-primary:hover { background: #3182ce; }
.btn-success { background: #48bb78; color: white; }
.btn-success:hover { background: #38a169; }
.btn-danger { background: #f56565; color: white; }
.btn-danger:hover { background: #e53e3e; }
.input-group { margin-bottom: 15px; }
label { display: block; margin-bottom: 5px; font-weight: 500; }
input[type="text"], textarea { width: 100%; padding: 10px; border: 1px solid #cbd5e0; border-radius: 6px; font-size: 16px; }
textarea { height: 100px; resize: vertical; font-family: monospace; }
.status { padding: 15px; border-radius: 6px; margin: 15px 0; }
.status-info { background: #bee3f8; color: #2c5282; }
.status-error { background: #fed7d7; color: #c53030; }
.messages { border: 1px solid #e2e8f0; border-radius: 8px; padding: 20px; max-height: 500px; overflow-y: auto; background: #fafafa; }
.message { padding: 12px 16px; margin-bottom: 10px; border-left: 4px solid #4299e1; background: white; border-radius: 4px; }
.message.server { border-left-color: #48bb78; }
.message.event { border-left-color: #ed8936; }
.progress-bar { width: 100%; height: 8px; background: #e2e8f0; border-radius: 4px; overflow: hidden; margin-top: 5px; }
.progress-fill { height: 100%; background: #4299e1; width: 0%; transition: width 0.3s ease; }
</style>
</head>
<body>
<div class="container">
<h1>🤖 MCP 流式交互演示</h1>
<p>这是一个与后台 FastAPI MCP 服务器交互的演示界面。点击“初始化会话”开始。</p>
<div class="control-panel">
<div class="input-group">
<label for="promptInput">输入你的请求:</label>
<textarea id="promptInput" placeholder="例如:请用Python写一个二分查找算法...">请介绍一下你自己。</textarea>
</div>
<button class="btn btn-primary" onclick="initializeSession()">初始化会话</button>
<button class="btn btn-success" onclick="sendMessage(false)">发送请求(非流式)</button>
<button class="btn btn-success" onclick="sendMessage(true)">发送请求(流式)</button>
<button class="btn btn-danger" onclick="closeSession()">关闭会话</button>
<div id="progressContainer" style="display:none; margin-top:15px;">
<div>处理进度:<span id="progressText">0%</span></div>
<div class="progress-bar"><div id="progressFill" class="progress-fill"></div></div>
</div>
</div>
<div id="statusArea"></div>
<h3>消息流</h3>
<div class="messages" id="messageArea">
<!-- 消息会动态添加到这里 -->
</div>
</div>
<script>
const serverBaseUrl = 'http://127.0.0.1:8000';
let currentSessionId = null;
let eventSource = null;
let currentProgressToken = null;
function logMessage(content, type = 'info') {
const messageArea = document.getElementById('messageArea');
const msgDiv = document.createElement('div');
msgDiv.className = `message ${type}`;
msgDiv.innerHTML = `<strong>[${new Date().toLocaleTimeString()}]</strong> ${content}`;
messageArea.appendChild(msgDiv);
messageArea.scrollTop = messageArea.scrollHeight; // 自动滚动到底部
}
function setStatus(message, isError = false) {
const statusArea = document.getElementById('statusArea');
statusArea.innerHTML = `<div class="status ${isError ? 'status-error' : 'status-info'}">${message}</div>`;
}
function updateProgress(token, value) {
if (token !== currentProgressToken) return;
const percent = Math.round(value * 100);
document.getElementById('progressText').textContent = `${percent}%`;
document.getElementById('progressFill').style.width = `${percent}%`;
document.getElementById('progressContainer').style.display = 'block';
}
async function initializeSession() {
setStatus('正在初始化会话...');
const initRequest = {
jsonrpc: "2.0",
id: 1,
method: "initialize",
params: {
protocolVersion: "2024-11-05",
capabilities: { streaming: true },
clientInfo: { name: "WebDemoClient", version: "1.0.0" }
}
};
try {
const resp = await fetch(`${serverBaseUrl}/initialize`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(initRequest)
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();
currentSessionId = resp.headers.get('Mcp-Session-Id');
setStatus(`会话初始化成功!会话ID: ${currentSessionId}`);
logMessage(`会话已建立。服务器信息: ${JSON.stringify(data.result.serverInfo)}`, 'server');
// 初始化后可以开始监听SSE(如果需要)
// startSSEListener();
} catch (error) {
setStatus(`初始化失败: ${error.message}`, true);
}
}
async function sendMessage(useStream = false) {
if (!currentSessionId) {
setStatus('请先初始化会话!', true);
return;
}
const prompt = document.getElementById('promptInput').value.trim();
if (!prompt) {
setStatus('请输入请求内容!', true);
return;
}
const method = useStream ? 'generate' : 'chat';
const requestId = Date.now(); // 简单生成唯一ID
const progressToken = useStream ? `progress_${requestId}` : null;
currentProgressToken = progressToken;
const requestBody = {
jsonrpc: "2.0",
id: requestId,
method: method,
params: {
prompt: prompt,
stream: useStream,
...(useStream && { _meta: { progressToken: progressToken } })
}
};
setStatus(`正在发送${useStream ? '流式' : ''}请求...`);
logMessage(`客户端 -> 发送请求: ${JSON.stringify(requestBody)}`);
if (useStream) {
// 流式请求:使用 /rpc 端点,并处理SSE
handleStreamingRequest(requestBody);
} else {
// 非流式请求
try {
const resp = await fetch(`${serverBaseUrl}/rpc`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Mcp-Session-Id': currentSessionId
},
body: JSON.stringify(requestBody)
});
const data = await resp.json();
setStatus('请求完成!');
logMessage(`服务器 -> 完整响应: ${JSON.stringify(data.result)}`, 'server');
} catch (error) {
setStatus(`请求失败: ${error.message}`, true);
}
}
}
function handleStreamingRequest(requestBody) {
// 先关闭之前的SSE连接
if (eventSource) {
eventSource.close();
eventSource = null;
}
// 使用EventSource监听流(注意:EventSource只支持GET,我们需要用fetch模拟POST流)
// 更通用的做法是使用fetch的ReadableStream,这里为了演示简单,我们假设服务器对GET也支持(实际项目请用fetch)
// 这里我们改用fetch API来读取流
fetch(`${serverBaseUrl}/rpc`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Mcp-Session-Id': currentSessionId
},
body: JSON.stringify(requestBody)
}).then(response => {
const reader = response.body.getReader();
const decoder = new TextDecoder();
function readStream() {
reader.read().then(({done, value}) => {
if (done) {
logMessage('流式传输结束。', 'event');
document.getElementById('progressContainer').style.display = 'none';
return;
}
const chunk = decoder.decode(value);
// 处理SSE格式的数据行
const lines = chunk.split('\n');
for (const line of lines) {
if (line.startsWith('data:')) {
const dataStr = line.substring(5).trim();
if (dataStr) {
try {
const data = JSON.parse(dataStr);
logMessage(`数据块: ${data.chunk || JSON.stringify(data)}`, 'server');
} catch {
logMessage(`文本块: ${dataStr}`, 'server');
}
}
} else if (line.startsWith('event:')) {
const eventType = line.substring(6).trim();
logMessage(`事件: ${eventType}`, 'event');
} else if (line.startsWith('{')) {
// 可能是不符合SSE格式的JSON直接输出(非流式回退)
try {
const data = JSON.parse(line);
logMessage(`直接响应: ${JSON.stringify(data)}`, 'server');
} catch(e) { /* 忽略 */ }
}
}
readStream(); // 继续读取下一块
}).catch(error => {
setStatus(`读取流失败: ${error.message}`, true);
});
}
readStream();
}).catch(error => {
setStatus(`流式请求失败: ${error.message}`, true);
});
}
function closeSession() {
if (eventSource) {
eventSource.close();
eventSource = null;
logMessage('SSE连接已关闭。', 'event');
}
currentSessionId = null;
setStatus('会话已重置。请重新初始化。');
document.getElementById('progressContainer').style.display = 'none';
}
</script>
</body>
</html>
这个前端页面包含了所有核心功能:
- 会话管理:初始化、关闭。
- 双模式请求:可以选择流式或非流式发送请求。
- 实时消息展示:用不同的颜色和样式区分服务器消息、客户端消息和事件。
- 进度条可视化:当服务器发送
progress事件时,页面上的进度条会实时更新。 - 健壮的流处理:使用
fetchAPI 的ReadableStream来处理 POST 请求的流式响应,这比EventSource(仅支持GET)更灵活通用。
将这段代码保存为 index.html,用浏览器打开(注意,由于CORS,你可能需要从 http://localhost 或 http://127.0.0.1 访问,或者使用 python -m http.server 启动一个简单的本地服务器)。点击按钮,你就能看到一个完整的、可交互的流式AI客户端了。
8. 部署、优化与踩坑指南
把代码跑起来只是第一步。要真正用在生产环境,还有不少坑要填。这里分享几个我实战中总结的经验。
部署注意事项:
- 生产级ASGI服务器:开发时用
uvicorn --reload很方便,但生产环境一定要用更稳定的服务器,如uvicorn搭配gunicorn(使用uvicorn.workers.UvicornWorker),或者hypercorn。并且要设置合适的 worker 数量。# 使用gunicorn的例子 gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 server:app - 会话存储:内存字典
sessions在服务器重启或多进程时会丢失。生产环境必须用外部存储,比如 Redis。把sessions字典的操作换成 Redis 的set/get,并设置合理的过期时间。 - 超时与心跳:SSE连接可能会因为代理或负载均衡器的超时设置而断开。一个常见的做法是,在流式生成器中定期发送一个注释行(以
:开头的行,SSE规范中这是注释)作为心跳,保持连接活跃。async def event_stream(): # ... 你的业务逻辑 # 每隔15秒发送一个心跳 heartbeat_task = asyncio.create_task(_send_heartbeat()) try: # 生成数据 yield data finally: heartbeat_task.cancel() async def _send_heartbeat(): while True: await asyncio.sleep(15) yield ": heartbeat\n\n" # SSE注释行,不会触发客户端事件 - CORS 安全:生产环境下,绝对不要使用
allow_origins=["*"]。应该配置为具体的前端域名列表。 - 日志与监控:记录重要的操作日志,并监控流式连接的活跃数量、错误率等指标。
常见问题与调试:
- 前端收不到流数据:首先打开浏览器开发者工具的“网络”标签页,查看对
/rpc的请求。响应类型应该是text/event-stream,状态码是200。查看响应体,应该能看到持续到达的数据。如果连接很快关闭,检查服务器端代码是否有未处理的异常。 Mcp-Session-Id头丢失:确保服务器响应头设置了Access-Control-Expose-Headers: Mcp-Session-Id(FastAPI的CORSMiddleware通过expose_headers参数设置),并且前端fetch请求能正确读取。- 流式响应中途停止:检查服务器生成器函数中是否有
return语句提前退出,或者await的协程被意外取消。使用try...finally块来确保资源清理。 - 性能问题:如果流式生成的内容很大,注意不要一次性加载所有数据到内存再
yield。应该采用“处理一块,发送一块”的模式。对于AI文本生成,这通常意味着从模型推理循环中直接yield每个新生成的token。
最后,这个架构的扩展性很好。你可以很容易地在这个基础上添加更多功能,比如:
- 身份认证:在
get_session依赖项中加入JWT或API Key验证。 - 速率限制:使用
slowapi等库为不同接口设置请求频率限制。 - 更复杂的协议:在
params里支持文件上传、工具调用(function calling)、上下文管理等。 - 多模型路由:根据请求参数,将请求路由到后端不同的AI模型服务。
我从一个简单的同步接口改造到现在的流式架构,最大的感受是用户体验的提升是实实在在的。虽然底层复杂度增加了,但用 FastAPI 的异步和流式响应特性来实现,代码依然能保持相当的清晰度。希望这个从协议设计到多端实现的完整 walkthrough,能帮你顺利搭建起自己的实时AI服务。如果在实现过程中遇到具体问题,多看看服务器日志和网络请求,大部分问题都能定位。
292



被折叠的 条评论
为什么被折叠?



