基于 FastAPI 和服务器发送事件的无审查聊天机器人后端
本指南通过小型 FastAPI 后端转发流式模型输出。将密钥保留在服务器上,按会话隔离对话历史,并在显示回复为完成之前处理中断的流。

更新于Unfiltered AI
要点
- 像 Unfiltered AI 这样的专用推理提供商在单一模型上提供一致的无审查行为,避免了聚合路由的随机性。
- 像 OpenRouter 这样的聚合器提供对多个模型的访问,但根据具体模型版本的不同,其内容过滤的严格程度可能会有所差异。
- Unfiltered AI 在专用硬件上使用开放权重模型,上下文窗口为 100k,价格为每百万 token $0.15/$0.50。
- 对于严格的 NSFW 或角色扮演一致性,专用的无审查 LLM API 消除了为绕过通用过滤器而进行复杂提示词工程的需求。
系统结构图示
想象三个并排的方框和它们之间的两个箭头。左侧是 browser。中间是你的 FastAPI 进程。右侧是位于 https://api.unfilteredaiapi.com/v1 的 模型端点。左侧箭头携带一条用户消息,返回一小段文本帧的流。右侧箭头携带完整的对话,返回服务器发送的事件。中间的方框只做三件事:持有 API 密钥,管理对话状态,并将一种流格式转换为另一种格式。
将密钥保留在中间方框是该层存在的原因。发送到浏览器的密钥意味着向所有打开开发者工具的人公开。第二个原因是状态:浏览器仅发送新文本和会话 ID,而服务器决定回放多少历史记录。随着对话变长,这一决策变得重要,memory 文章对此进行了深入探讨。
此处所有内容均使用标准的 chat-completions 格式并设置 stream: true,因此只需安装 fastapi、uvicorn 和 httpx 即可,无需其他依赖。
右侧箭头接收的内容
开启流式输出后,响应是一系列行。每个有效行都以 data: 开头,后跟一个 JSON 块,其 choices[0].delta.content 包含几个字符。最后一行是 data: [DONE]。在此之前的 usage 数据块会自动添加;它包含 token 计数,且没有 choices 条目,因此中继必须先检测这种情况再进行索引。
将流视为三个阶段:模型读取提示词时的静默开始阶段、片段稳定流动阶段,以及包含使用量和哨兵值的简短尾声。下面的中继服务镜像了这些阶段。它在片段到达时转发它们,将它们累积为一个字符串,并在流结束时将该字符串写入会话存储。
中继接口
核心是一个名为 stream_reply 的异步生成器。FastAPI 的 StreamingResponse 会消费该生成器,并将每个生成的字符串刷新给客户端。两个路由封装了同一个生成器:一个用于 fetch 的 POST 请求,一个用于 EventSource 的 GET 请求。
# app.py
import json
import os
import uuid
import httpx
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
API_URL = "https://api.unfilteredaiapi.com/v1/chat/completions"
SYSTEM = {"role": "system", "content": "You are Corvin, a patient narrator of dark, adult-oriented fiction."}
app = FastAPI()
sessions: dict[str, list[dict]] = {} # session id -> message list
class Turn(BaseModel):
session_id: str
text: str
def sse(data, event=None):
head = f"event: {event}\n" if event else ""
return f"{head}data: {json.dumps(data)}\n\n"
async def stream_reply(session_id: str, text: str):
history = sessions.setdefault(session_id, [])
history.append({"role": "user", "content": text})
payload = {
"model": "uncensored",
"messages": [SYSTEM] + history,
"stream": True,
"max_tokens": 700,
}
headers = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
parts: list[str] = []
async with httpx.AsyncClient(timeout=httpx.Timeout(10.0, read=120.0)) as client:
async with client.stream("POST", API_URL, headers=headers, json=payload) as r:
if r.status_code != 200:
body = (await r.aread()).decode()
history.pop() # do not keep a turn that got no answer
yield sse({"status": r.status_code, "body": body}, event="error")
return
async for line in r.aiter_lines():
if not line.startswith("data: "):
continue
raw = line[6:]
if raw == "[DONE]":
break
chunk = json.loads(raw)
if not chunk.get("choices"): # the final usage chunk
continue
piece = chunk["choices"][0]["delta"].get("content")
if piece:
parts.append(piece)
yield sse(piece)
history.append({"role": "assistant", "content": "".join(parts)})
yield sse({}, event="done")
@app.post("/session")
def new_session():
return {"session_id": uuid.uuid4().hex}
@app.post("/chat")
async def chat(turn: Turn):
return StreamingResponse(
stream_reply(turn.session_id, turn.text),
media_type="text/event-stream",
headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
)
@app.get("/chat/stream") # for EventSource, which only does GET
async def chat_get(session_id: str, text: str):
return StreamingResponse(
stream_reply(session_id, text),
media_type="text/event-stream",
headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
)从上到下阅读生成器。它首先追加用户消息,以便模型可以看到它。如果上游状态不是 200,它会再次移除该消息并发出 error 事件,从而保持历史记录中不包含未完成的轮次。成功时,它将每个片段作为 JSON 字符串发出,这样换行符和引号才能在帧结构中保留。当循环结束时,它存储助手文本并发出 done 事件。
这两个标头很重要。Cache-Control: no-cache 防止中间商缓存流,而 X-Accel-Buffering: no 告诉类 nginx 的代理立即透传字节。
选择会话存储
示例中的字典是最简单的存储方式:每个会话 ID 对应一个消息列表。它有三个直白的局限性。重启时会消失,在多个工作进程之间不共享,并且会无限增长。根据哪个局限性最先造成问题来选择下一步。
- 单进程、短会话:保留字典,添加一个时间到期的清理机制,删除闲置一小时的会话。
- 多个工作进程:将消息列表移至共享键值存储,以会话 ID 为键,JSON 数组为值。按会话序列化访问,以防止两个并发请求交错。
- 持久化历史记录:将每轮对话写入以会话和序列号键控的数据库行,并在需要时加载尾部数据。
无论你选择什么,都将其隐藏在两个函数 load(session_id) 和 append(session_id, message) 之后,这样 stream_reply 永远不会知道数据存在哪里。此外,像 /session 路由那样在服务器上生成会话 ID,并将它们视为难以猜测的秘密。
使用 fetch 的浏览器端
左侧箭头处浏览器需读取流式 POST 主体。fetch 将其作为可读流暴露,TextDecoderStream 将字节转换为文本。帧之间由空行分隔,因此客户端会缓冲传入文本并提取完整帧。
<!doctype html>
<meta charset="utf-8">
<title>Chat</title>
<div id="log"></div>
<form id="f"><input id="t" autocomplete="off" size="50"><button>Send</button></form>
<script>
const sid = localStorage.getItem("sid") ?? (() => {
const id = crypto.randomUUID().replaceAll("-", "");
localStorage.setItem("sid", id);
return id;
})();
const log = document.getElementById("log");
function line(text) {
const p = document.createElement("p");
p.textContent = text;
log.append(p);
return p;
}
document.getElementById("f").addEventListener("submit", async (e) => {
e.preventDefault();
const box = document.getElementById("t");
const text = box.value.trim();
if (!text) return;
box.value = "";
line("You: " + text);
const out = line("");
const res = await fetch("/chat", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ session_id: sid, text }),
});
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buf = "";
while (true) {
const { value, done } = await reader.read();
if (done) break;
buf += value;
let cut;
while ((cut = buf.indexOf("\n\n")) >= 0) {
const frame = buf.slice(0, cut);
buf = buf.slice(cut + 2);
if (frame.startsWith("event: done")) continue;
if (frame.startsWith("event: error")) { out.textContent += " [request failed]"; continue; }
if (frame.startsWith("data: ")) out.textContent += JSON.parse(frame.slice(6));
}
}
});
</script>页面使用 textContent 写入,而非 innerHTML,因此模型输出无法向你的页面注入标记。这是一个小习惯,但当模型生成任意虚构内容时,回报巨大。
在编写前端之前测试中继服务
首先单独测试中间的框。命令行客户端将浏览器排除在方程之外,因此你看到的任何问题都属于中继。-N 标志关闭 curl 的输出缓冲;否则你会看到整个回复一次性到达,并错误地认为流式输出已损坏。
uvicorn app:app --port 8000 &
SID=$(curl -s -X POST localhost:8000/session | python3 -c "import sys,json; print(json.load(sys.stdin)['session_id'])")
curl -N -X POST localhost:8000/chat -H "Content-Type: application/json" \
-d "{\"session_id\": \"$SID\", \"text\": \"Open with a storm.\"}"你应该看到以 data: 开头的行,每行携带一个引用的片段,然后是最终的 event: done 帧。使用相同的会话 ID 发送第二条消息,并要求叙述者继续;如果它从停止的地方继续,说明存储有效。如果所有行一次性到达,说明你和进程之间的某个地方正在缓冲,通常的嫌疑对象是开启了响应缓冲的反向代理。
一旦通过此测试,浏览器页面只需读取相同的帧即可。站点首页 和 文档 列出了请求字段,如果你希望通过中继传递更多采样选项,可以参考这些字段。
EventSource 变体及其权衡
浏览器的 EventSource API 为你处理解析和重连,但它只能发出 GET 请求。这就是后端拥有第二个路由的原因。代价是用户的文本通过 URL 传输,而 URL 往往会出现在你运行的机器的访问日志中。对于私密对话,优先使用 POST 和 fetch 方法。
const q = new URLSearchParams({ session_id: sid, text: "Describe the harbour at dusk." });
const src = new EventSource("/chat/stream?" + q);
const out = document.getElementById("log").appendChild(document.createElement("p"));
src.onmessage = (ev) => { out.textContent += JSON.parse(ev.data); };
src.addEventListener("done", () => src.close()); // without this, EventSource reconnects
src.addEventListener("error", () => src.close());注意 done 监听器。当服务器关闭事件流时,EventSource 会假设网络故障并重连,这将再次发送相同的消息。在 done 和 error 时自行关闭源可以打破此循环。
故障模式及需规避的限制
再次遍历箭头,询问每处可能在哪里出错。右侧:401 表示密钥错误,402 表示余额已用完,403 表示请求被阻止,429 表示此密钥每分钟超过了 300 个请求,503 且带有 upstream_busy 表示应在几秒后重试。中继服务将所有这些情况作为带有状态附加值的单个 error 事件呈现,以便浏览器选择消息。
客户端在流式传输过程中断开连接会取消生成器,部分助手文本永远不会被保存。这通常是正确的行为;如果你倾向于保留部分回复,请将它们存储在 finally 块中。
对于成本规划,假设一轮对话发送 3,000 个输入 token 并返回 600 个。按每百万 token $0.15 和 $0.50 计算,这是 $0.00075 加上 $0.0006,每轮约 $0.00135,因此一千轮的成本接近 $1.35。这些数字是假设值;请检查使用量 chunk 以获取你的实际数字。关于速率限制,请参阅 定价,关于选择概览,请阅读 聊天机器人 API 比较。
更多指南
问答
为什么不建议直接从浏览器调用模型?
API 密钥会对所有访问者可见。小型中继服务可保护密钥私密,并让你控制历史记录和速率限制。
流式输出是否包含 token 使用情况?
是的。系统会自动追加最终的使用量 chunk,且其中没有 choices 条目,因此在提取文本时应跳过缺少该条目的 chunk。
何时应使用 EventSource 而不是 fetch?
当 GET 可接受且需要内置重连功能时使用 EventSource。对于 POST 请求体,请使用 fetch,这样可确保私密文本不会出现在 URL 中。
一个 API 密钥能支持多少用户?
每个密钥的速率限制为每分钟 300 个请求,所有用户共享此额度,因此请在中继服务中为每个用户添加冷却时间。