重點摘要
- 安裝 openai,然後建立 OpenAI(base_url=..., api_key=...),並將模型設定為 uncensored。
- 串流輸出、JSON 模式和工具呼叫使用標準參數,非同步運作方式相同。
- 使用訊號量將並行請求限制在 8,並讓 SDK 重試 429 回應。
- 從原始回應標頭讀取 X-Balance-USD,即可從程式碼監控你的額度。
最小運作範例
以下是最短且實用的 openai api proxy python 設定。它假設使用 Python 3.9 或更新版本、來自 API 金鑰頁面的金鑰、已透過 pip install openai 安裝套件,並將金鑰匯出為 UNCENSORED_API_KEY。
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.openaiapiproxy.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Give me a one-line product tagline for a hiking app."}],
temperature=0.8,
max_tokens=60,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)該端點相容 OpenAI,但它是獨立服務。它不是 OpenAI 或其他廠商的官方 API,且僅託管一個模型 uncensored。僅有兩個路由:POST /v1/chat/completions 和 GET /v1/models,因此請堅持使用 SDK 的聊天完成介面。
關於該程式碼的一些註解。金鑰來自環境變數而非字面常數,因此不會進入版本控制。回應上的 usage 物件包含帳單所依據的精確 token 計數,這對於記錄很有用。max_tokens 是選用的:省略它,完成可能會使用剩餘的上下文視窗,這對故事沒問題,但對有錯誤的迴圈則成本高昂。
串流接收到達的 token
串流輸出使用伺服器傳送事件。傳遞 stream=True 並迭代區塊。串流的最後一部分包含 token 使用量,因此請針對沒有 choices 的區塊進行防護。
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Tell a two-paragraph ghost story."}],
stream=True,
)
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if getattr(chunk, "usage", None):
usage = chunk.usage
print()
if usage:
print("tokens:", usage.prompt_tokens, usage.completion_tokens)一個運作細節:串流呼叫會佔用一個並行請求槽位,直到串流結束。如果你的程式碼提前跳出迴圈,請關閉串流(stream.close())以釋放槽位。
網頁應用程式通常將此迴圈包裝在生成器中,並將每個部分轉發給瀏覽器。使用 FastAPI 時,這意味著返回一個 StreamingResponse 來產生文字部分。在該設計中,將金鑰保留在伺服器上。瀏覽器與你的路由通訊,你的路由再與 API 通訊,因此金鑰不會暴露給客戶端程式碼。
非同步客戶端與受控並行請求
完整金鑰允許同時 8 個請求和每分鐘 300 個。試用金鑰允許 2 個和 60 個。如果你使用 asyncio.gather 啟動 200 個協同程式,你將收到代碼為 concurrency 的 429 錯誤。訊號量可以事先解決這個問題。
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY", max_retries=4)
gate = asyncio.Semaphore(8)
async def ask(prompt: str) -> str:
async with gate:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
max_tokens=200,
)
return r.choices[0].message.content
async def main():
prompts = [f"Write a title for chapter {i} of a sea adventure." for i in range(1, 41)]
results = await asyncio.gather(*(ask(p) for p in prompts))
for t in results:
print(t)
asyncio.run(main())在使用試用金鑰時,將訊號量大小設為 2。SDK 預設會以退避方式重試 429 回應,且 max_retries 可增加嘗試次數。對於暫時過載,服務會以 Retry-After: 5 回應 429,SDK 會予以遵循。
訊號量僅限制單一程序內的進行中請求。如果你執行多個工作程式,請將限制分配給它們:對於完整金鑰,四個工作程式應各自使用 2 的訊號量。每分鐘 300 個請求的限制由所有工作程式共享,因此對於大型離線作業,具有穩定速率的佇列比突發更好。8 MB 的主體限制對於聊天來說很少成為問題,但適用於每個請求。
JSON 模式與工具呼叫
兩者都透過正常參數運作。對於 JSON 模式,設定 response_format 並在提示詞中要求 JSON。
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Return JSON with keys name, mood and hook."},
{"role": "user", "content": "Invent a tavern keeper for a fantasy game."},
],
)
npc = json.loads(r.choices[0].message.content)
print(npc["name"])函式呼叫需要額外一步:你自行執行函式,並將輸出作為 tool 訊息返回。
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
tools = [{
"type": "function",
"function": {
"name": "roll_dice",
"description": "Roll a die with the given number of sides.",
"parameters": {
"type": "object",
"properties": {"sides": {"type": "integer"}},
"required": ["sides"],
},
},
}]
messages = [{"role": "user", "content": "Roll a twenty-sided die for me."}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message
if msg.tool_calls:
call = msg.tool_calls[0]
sides = json.loads(call.function.arguments)["sides"]
messages.append(msg)
messages.append({"role": "tool", "tool_call_id": call.id, "content": "14"})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
else:
print(msg.content)骰子的回傳值為了簡潔而硬編碼。在實際程式碼中,使用 sides 呼叫你的函式並傳送其結果。
關於工具的兩項額外細節。當你需要強制呼叫特定函式而非讓模型自行決定時,請使用 tool_choice。並保持工具描述具體:模型僅憑名稱與描述即可選擇函式,因此「擲出指定面數的骰子」比「骰子」更有效。若回覆包含多個函式呼叫,請全部執行,並在要求最終答案前,針對每個呼叫 ID 追加一條 tool 訊息。
錯誤、重試與對話歷史
SDK 會引發類型化異常,使錯誤處理簡短。429 會引發 openai.RateLimitError,網路故障會引發 openai.APIConnectionError,其他非成功狀態會引發 openai.APIStatusError。當你看到第一個異常時,SDK 已經重試過,因此到達你程式碼的是多次重試失敗的呼叫。
import time
import openai
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY", max_retries=2)
def chat(messages, attempts=4):
delay = 2.0
for n in range(attempts):
try:
r = client.chat.completions.create(model="uncensored", messages=messages)
return r.choices[0].message.content
except openai.RateLimitError as e:
wait = float(e.response.headers.get("Retry-After", delay))
time.sleep(wait)
delay *= 2
except openai.APIConnectionError:
time.sleep(delay)
delay *= 2
raise RuntimeError("gave up after repeated failures")
print(chat([{"role": "user", "content": "Name a color."}]))當服務發送 Retry-After 時程式碼會讀取它,這發生在暫時過載時(值為 5 秒)。當標頭缺失時,它會自行排程退避。注意迴圈並未捕獲所有錯誤:錯誤的請求在重試時不會改善,因此讓它傳播。
對話歷史是另一種狀態。API 不會為你儲存它,因此你的程式擁有訊息列表。一個運作良好的簡單策略:保留系統訊息,保留最後 N 個回合,當總數超過你選擇的大小時,要求模型將最舊的部分摘要為一條短訊息。
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
def compact(history, keep=6):
system, rest = history[0], history[1:]
if len(rest) <= keep:
return history
old, recent = rest[:-keep], rest[-keep:]
text = "\n".join(m["role"] + ": " + m["content"] for m in old)
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Summarize this conversation in 120 words:\n" + text}],
max_tokens=250,
)
summary = {"role": "system", "content": "Earlier in this conversation: " + r.choices[0].message.content}
return [system, summary] + recent摘要也會消耗 token,但它們能自行回本:否則每次輪次都會重新發送 20,000 token 的對話,現在只需幾千個 token。
讀取餘額與請求 ID
每個回應都包含 X-Request-Id 和 X-Balance-USD。SDK 預設隱藏標頭,但 with_raw_response 會暴露它們,同時仍提供你解析後的物件。
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "Say ok."}],
)
print("request id:", raw.headers.get("X-Request-Id"))
print("balance USD:", raw.headers.get("X-Balance-USD"))
completion = raw.parse()
print(completion.choices[0].message.content)記錄每次失敗的請求 ID。如果你需要透過 支援頁面聯繫團隊,該 ID 會直接指向該呼叫。
餘額標頭除了記錄外也很有用。排程工作可以在每個批次後讀取它,當額度低於你設定的閾值時停止,或發送訊息讓你儲值,以免使用者察覺。額度永不過期,因此沒有花費它的壓力。儲值金額為 $20 到 $500 的整數,因此如果你偏好,可以以較大的步驟重新補充。
不使用 SDK:使用 requests 或 httpx
如果你偏好避免依賴,API 足夠簡單,可以使用純淨的 HTTP 客戶端。
import requests
r = requests.post(
"https://api.openaiapiproxy.com/v1/chat/completions",
headers={"Authorization": "Bearer YOUR_KEY"},
json={
"model": "uncensored",
"messages": [{"role": "user", "content": "Name three sea shanty topics."}],
},
timeout=120,
)
r.raise_for_status()
print(r.json()["choices"][0]["message"]["content"])為長文本生成設定較長的逾時時間。模型可使用提示詞剩餘空間內的 100,000-token 上下文視窗,因此針對長篇小說的請求可能需要較長時間。
相同的方法也適用於串流輸出。在 JSON 主體中加入 "stream": true,將 stream=True 傳遞給 requests.post,並使用 iter_lines() 讀取回應。每個事件行都以 data: 開頭,後接 JSON,串流則以 data: [DONE] 標記結束。手動解析是一個很好的學習練習,不過對於生產環境程式碼,SDK 能以更少的邊界情況(例如部分行與重新連線)處理此作業。
在 Python 程式碼中管理預算
resp.usage 中的 token 計數可讓你計算每次呼叫的支出。價格為每 1M 輸入 token $0.15,每 1M 輸出 token $0.50。
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
def cost_usd(prompt_tokens: int, completion_tokens: int) -> float:
return prompt_tokens * 0.15 / 1_000_000 + completion_tokens * 0.50 / 1_000_000
r = client.chat.completions.create(model="uncensored", messages=[{"role": "user", "content": "Hi"}])
print(cost_usd(r.usage.prompt_tokens, r.usage.completion_tokens))
print(cost_usd(1_000_000, 200_000)) # 0.25第二行可以手動核對:1M 輸入 token 成本為 $0.15,200,000 輸出 token 成本為 0.2 x $0.50 = $0.10,總計 $0.25。失敗或遭拒的請求不會收費,因此你不需要扣除它們。儲值從 $20 起跳,定價頁面 列出了 $50、$100 和 $200 的贈金。
完整參數列表和錯誤代碼,請參閱 文件。
在工作程式中保持累計總計,以防止迴圈花費超過你計劃的 token 數量。一個每條短文本分類 400 個輸入 token 和 20 個輸出 token、共 50,000 條文本的批次工作,會使用 20M 輸入 token 和 1M 輸出 token。這成本為 20 x $0.15 + 1 x $0.50 = $3.50。如果你的計數器顯示工作成本是兩倍,表示有迴圈發生。
