串流輸出帶來的優勢
若未啟用串流輸出,API 會等待模型完成整個回答後,才以單一 JSON 主體傳送。對於長回覆,這可能意味著螢幕空白好幾秒。啟用 stream: true 後,伺服器會將相同回答拆分為一系列小事件,每個事件僅包含回覆的幾個字元,你的 UI 即可即時顯示這些內容。
網路傳輸格式為標準 HTTP 回應上的伺服器發送事件(SSE)。每個事件是一行以 data: 開頭的資料,後接一個 JSON 區塊,串流輸出以 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 中的相同呼叫
Node 的官方 openai 套件中,串流為非同步迭代器。此範例使用 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 可幫你處理在區塊邊界處被切斷的事件,這是手寫解析器常見的錯誤。
讀取用量與餘額
用量資訊會在串流輸出結束時回報。這是應記錄的數字,用於成本追蹤,因為你的餘額是根據此數值扣款。輸入 token 每 100 萬個 $0.15,輸出 token 每 100 萬個 $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 個。
發布串流聊天前的檢查清單
- 防止最後一個區塊中的
choices為空。 - 緩衝部分文字,並在發生錯誤時儲存。
- 當瀏覽器斷開連線時中止上游請求。
- 將活躍串流限制在並行請求限制內。
- 記錄每個串流輸出的用量和請求 ID。
- 關閉伺服器前方任何反向代理的回應緩衝,否則 token 將以突波形式到達。
最後一點常讓許多首次部署出錯。例如 Nginx 預設會緩衝代理的回應,因此串流輸出在 localhost 上運作正常,但在生產環境中看起來像是凍結,直到針對該路由禁用緩衝為止。若需 JSON 輸出而非自由文本,請參見 JSON 模式 的說明。若要嘗試上述程式碼,建立 API 金鑰;新帳戶可以一鍵領取 $0.50 的免費試用額度,有效期為 7 天。儲值僅限加密貨幣(TRC20 上的 USDT 或 Base 上的 USDC),最低 $20。
