流式输出带来的好处
不使用流式输出时,API 会保留整个答案直到模型完成,然后作为单个 JSON 主体发送。对于长回复,这可能意味着空白屏幕持续数秒。使用 stream: true 时,服务器将同一回复作为一系列小事件发送,每个事件携带回复的几个字符,你的 UI 可以即时打印它们。
传输格式是普通 HTTP 响应上的 server-sent events (SSE)。每个事件是以 data: 开头的一行,后跟 JSON chunk,流式传输以 data: [DONE] 结束。你很少手动解析这个,因为 OpenAI SDK 会为你处理。如果你想查看原始字节,开发者概览 展示了端点布局,API 文档 列出了每个参数。
在编写代码前有两件事值得决定。首先,谁读取流式输出:是与你的服务器对话的浏览器,还是仅你的服务器。其次,连接中途断开时如何处理。本页面其余部分涵盖这两点。
Python:使用 OpenAI SDK 流式输出
使用 pip install openai 安装 SDK,使用我们的 base URL 创建客户端,并传入 stream=True。模型 ID 为 uncensored。
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredllmapi.com/v1",
api_key="YOUR_KEY",
)
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a four-line poem about rain."}],
stream=True,
)
text = []
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
piece = chunk.choices[0].delta.content
text.append(piece)
print(piece, end="", flush=True)
if getattr(chunk, "usage", None):
usage = chunk.usage
print()
print("tokens:", usage)
注意守卫 chunk.choices and ...。携带使用量的最后一个 chunk 可能有空的 choices 列表,对其索引访问会引发错误。将片段收集到列表中并在末尾拼接,在长回复中比重复字符串拼接更便宜。
Node:JavaScript 中的相同调用
对于官方的 openai Node 包,流式输出是异步迭代器。此示例使用 ES 模块。
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredllmapi.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Name three uses for a stream." }],
stream: true,
});
let full = "";
let usage = null;
for await (const chunk of stream) {
const piece = chunk.choices?.[0]?.delta?.content;
if (piece) {
full += piece;
process.stdout.write(piece);
}
if (chunk.usage) usage = chunk.usage;
}
console.log("\nusage:", usage);
如果不想用 SDK,fetch 也可以:发送带有 stream: true 的相同 JSON 主体,然后用 TextDecoder 读取 response.body 并按空行拆分。SDK 可避免处理在 chunk 边界被截断的事件,这是手写解析器的常见 bug。
读取使用量和余额
使用量在流式传输结束时报告。这是用于成本跟踪的日志数字,因为余额是根据它扣费的。每 1M 输入 token $0.15 和每 1M 输出 token $0.50,包含 1,200 个输入 token 和 800 个输出 token 的回复成本为 1,200 x 0.15 / 1,000,000 + 800 x 0.50 / 1,000,000 = $0.00018 + $0.0004 = $0.00058。
每个响应还包含带有剩余额度的 X-Balance-USD 头,因此你可以在不发起第二次请求的情况下显示低余额警告。你也可以定时调用 GET /v1/balance。失败或拒绝的请求不收费,这意味着第一个 token 之前的错误不收费。
相同的响应头包括 X-Request-Id。将其存储在你的每个流式输出日志行旁边。如果流式输出行为异常,该 ID 是你提供给支持人员以便查找请求的内容。
断流及处理方法
流式输出会中断。手机从 Wi-Fi 切换到移动数据,代理关闭空闲连接,用户关闭标签页。从一开始就计划好。
保留部分文本
随着片段到达将其追加到缓冲区,并在循环结束或抛出异常时保存缓冲区。如果流式输出失败,你有一个可用的半回复。显示它,并提供重试按钮,而不是丢弃它。
重试或继续
最简单的恢复方式是重新发送原始请求。对于短回复,这没问题。对于长回复,你可以将保存的部分文本作为助手消息发送,并要求模型从停止处继续。结果可能与第一个流式输出原本会产生的结果不匹配,因此请将其视为尽力而为,如果精确度很重要,请在 UI 中标记。
关闭已放弃的连接
流式请求会占用其并发槽位,直到流结束。完整密钥允许同时发起 8 个请求,试用密钥仅允许 2 个。如果你的服务器持续读取已离开用户的流,该槽位将保持忙碌状态。当客户端断开连接时取消请求。在 Python 中,调用 stream.close();在 Node 中,调用 stream.controller.abort()。
将流式输出中继到浏览器
切勿将 API 密钥放入浏览器代码。通常做法是在你自己的服务器上设置一个小接口,使用 stream: true 调用 API 并将每个片段转发到页面。在 Node 中使用 Express 时,设置 Content-Type: text/event-stream,将每个片段写为 data: ... 后跟空行,并在请求的 close 事件上监听以中止上游调用。在页面上,EventSource 处理 GET 端点,而带读取器的 fetch 处理 POST 主体,这是在发送消息历史时所需的。
将消息历史保留在你的服务器或请求主体中,并在对话变长时修剪最旧的轮次。上下文窗口为 100,000 个 token(提示词加补全),这能容纳大量聊天,但长期运行的会话最终会达到限制。
流式输出时的速率限制
限制为完整密钥每分钟 300 个请求和 8 个并发请求,试用密钥每分钟 60 个和 2 个并发。超出限制返回 HTTP 429。错误代码告诉你触发了哪个限制:rate_limited 表示每分钟请求过多,concurrency 表示同时请求过多。在临时过载时,API 还返回带有 Retry-After: 5 头的 429。
由于 429 在任何 token 流式输出之前到达,请在开始读取之前处理它。一个小重试包装器就足够了:
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.uncensoredllmapi.com/v1", api_key="YOUR_KEY")
def open_stream(messages, tries=4):
for n in range(tries):
try:
return client.chat.completions.create(
model="uncensored", messages=messages, stream=True
)
except RateLimitError as e:
wait = 5 if n == 0 else 5 * (n + 1)
time.sleep(wait)
raise RuntimeError("still rate limited")
对于拥有许多用户的聊天应用,concurrency 错误的真正修复是在你端添加一个小队列,允许同时不超过 8 个活跃流。
上线流式聊天前的检查清单
- 防止最后一个 chunk 中的空
choices。 - 缓冲部分文本并在错误时持久化。
- 当浏览器断开连接时中止上游请求。
- 将活跃流式输出数量限制在你的并发限制内。
- 记录每个流式输出的使用量和请求 ID。
- 关闭服务器前任何反向代理的响应缓冲,否则 token 将以突发方式到达。
最后一点常导致首次部署失败。例如,Nginx 默认缓冲代理响应,因此流在 localhost 上正常工作,但在生产环境中直到禁用该路由的缓冲前看起来是冻结的。如需 JSON 输出而非自由文本,请参阅 JSON 模式 的说明。要尝试上述代码,创建 API 密钥;新账户可一键领取 $0.50 试用额度,有效期 7 天。充值仅限加密货币(TRC20 上的 USDT 或 Base 上的 USDC),最低 $20。
