Venice API 替代方案 Python:OpenAI SDK 設定
您可以透過變更 base URL、金鑰和模型名稱,使用官方 OpenAI Python SDK 來呼叫此 API。以下提供每個常見任務的有效程式碼。

重點摘要
- 安裝 openai 套件,將 base_url 設為 https://api.veniceapialternative.com/v1 並將模型設為 uncensored。
- 串流輸出、函式呼叫和 JSON 模式均可透過標準 SDK 呼叫運作。
- 將並行工作保持在每個金鑰的 8 個並行請求以下(試用金鑰為 2 個)。
- 429 代表 rate_limited、concurrency 或暫時過載;請退避並重試。
安裝並進行首次呼叫
對於 Venice API 替代方案 Python 設定,您不需要特殊的程式庫。該服務使用 OpenAI 聊天格式,因此標準 SDK 即可運作。使用 pip install openai 安裝,然後取得金鑰。新用戶在透過 Google 或電子郵件與密碼註冊後,可在 API 金鑰頁面領取 $0.50 的試用額度。不需要信用卡。
將金鑰儲存在環境變數中,而非原始碼檔案。接著建立帶有 Base URL 的客戶端,並呼叫 uncensored 模型:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are a concise writing assistant."},
{"role": "user", "content": "Give me three opening lines for a noir story."},
],
temperature=0.8,
)
print(resp.choices[0].message.content)
print(resp.usage)
SDK 會自動傳送 Authorization: Bearer <key>。usage 物件會顯示提示詞與完成的 token,你稍後將用它來追蹤成本。如果呼叫因身份驗證錯誤而失敗,請檢查金鑰是否沒有尾端換行符號,且 Base URL 以 /v1 結尾。
temperature、top_p、stop 和 seed 參數,以及頻率懲罰和存在懲罰都會傳遞給模型,因此您可以以相同的方式調整採樣。如果您希望模型使用視窗中剩餘的任何空間,請省略 max_tokens;如果您希望對回覆長度和成本設下硬性上限,則設定它。
使用 models 端點檢查連線
在建立任何內容之前,請確認端點可達。第二種支援的方法 GET /v1/models 列出金鑰可用的內容:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
for m in client.models.list():
print(m.id, m.id == "uncensored")
你應該會看到 uncensored。這是唯一的模型 ID,也是你在每個請求中作為 model 傳遞的值。如果你正在移植一個從多個模型名稱中選擇的應用程式,請將選擇邏輯替換為常數。沒有其他需要選擇的內容。
完整的參數參考資料位於 文件頁面。僅支援文字聊天:不支援影像、音訊、嵌入或微調,因此請從您遷移的程式碼中移除這些呼叫。
串流回應
串流輸出會隨產生返回 token,這讓聊天介面感覺更快。設定 stream=True 並遍歷區塊。用量資訊會在串流結束時到達,因此請檢查沒有 choices 的區塊:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Describe a rainy harbor town in 120 words."}],
stream=True,
)
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):
print("\n", chunk.usage)
容量規劃的一個細節很重要:串流請求會在其串流結束前佔用其並行槽位。如果使用者開啟串流後離開而未關閉它,該槽位會保持忙碌。當使用者離開時,請在用戶端側關閉串流,並設定請求逾時。
工具呼叫與 JSON 模式
函式呼叫遵循 OpenAI 格式。您在 tools 中描述函式,模型回傳 tool_calls,您執行函式並使用 role: "tool" 將結果傳回:
import json
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_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 the next encounter."}]
first = client.chat.completions.create(
model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)
msg = first.choices[0].message
if msg.tool_calls:
call = msg.tool_calls[0]
args = json.loads(call.function.arguments)
result = {"value": 14, "sides": args["sides"]}
messages.append(msg)
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
生產環境中應使用 try/except 解析 function.arguments,因為模型偶爾會產生格式錯誤的 JSON。若需結構化輸出且不使用工具,JSON 模式會很有幫助:
import json
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Reply with a JSON object with keys name, mood and hook."},
{"role": "user", "content": "Invent a tavern keeper for a fantasy campaign."},
],
)
print(json.loads(r.choices[0].message.content))
在提示詞中告知模型您希望取得的鍵。JSON 模式會使輸出成為有效的 JSON,但它無法猜測您的結構描述。
處理 429 錯誤與速率限制
完整金鑰允許 8 個並行請求和每分鐘 300 個請求。試用金鑰允許 2 個並行和每分鐘 60 個。超過限制時,您會收到 HTTP 429,且錯誤程式碼會告訴您是哪一個:
rate_limited:每分鐘請求過多。請減慢速度。concurrency:進行中的請求過多。請等待一些請求完成。- 帶有
Retry-After: 5標頭的 429:暫時過載。等待 5 秒鐘後重試。
SDK 預設已會重試幾次,並遵循 Retry-After。對於更複雜的情況,請新增你自己的封裝程式並讀取限制標頭。你可以透過 with_raw_response 取得原始回應:
import os
import time
import openai
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
max_retries=0,
)
def ask(prompt, attempts=4):
for n in range(attempts):
try:
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
)
print("balance:", raw.headers.get("X-Balance-USD"),
"request id:", raw.headers.get("X-Request-Id"))
return raw.parse().choices[0].message.content
except openai.RateLimitError as e:
wait = int(e.response.headers.get("Retry-After", 2 ** n))
time.sleep(wait)
raise RuntimeError("still rate limited after retries")
print(ask("Name three plot twists for a heist story."))
在每次失敗時記錄 X-Request-Id。如果你聯繫 支援,該 ID 讓他們能找到確切的呼叫。X-Balance-USD 標頭讓你能夠無需額外請求即可取得剩餘額度。失敗和被拒絕的請求不會計費。
在不超過上限的情況下並行執行請求
對於批次作業,請使用非同步用戶端,並設定以金鑰上限為大小的訊號量(semaphore)。完整金鑰的上限為 8。若你也從同一個金鑰服務即時使用者,請保留一些緩衝空間。
import asyncio
import os
from openai import AsyncOpenAI
client = AsyncOpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
gate = asyncio.Semaphore(6)
async def summarize(text):
async with gate:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Summarize in one sentence: " + text}],
max_tokens=80,
)
return r.choices[0].message.content
async def main():
docs = ["First long text ...", "Second long text ...", "Third long text ..."]
for line in await asyncio.gather(*(summarize(d) for d in docs)):
print(line)
asyncio.run(main())
發送速率對於每分鐘上限也很重要。以 6 個並行工作執行緒、每次呼叫 4 秒計算,你每分鐘會發送約 90 個請求,遠低於 300 的上限。若你的呼叫速度很快,請加入短暫的延遲或令牌桶,以免在突發情況下超過上限。
遷移現有的 Python 專案
大多數遷移作業比人們預期的要小。如果你的程式碼已經建立了 OpenAI(...) 客戶端,你只需更改兩個建構子引數和一個字串。如果你從環境變數讀取設定,你通常可以完全不用更動程式碼:openai 套件會讀取 OPENAI_API_KEY 和 OPENAI_BASE_URL,因此在你的終端機或 .env 檔案中設定這兩個變數,即可讓整個程式指向新的端點。
然後在專案中搜尋這些項目,因為它們通常是造成中斷的來源:
- 硬編碼的模型名稱。 將每個舊名稱替換為
uncensored。使用 grep 搜尋model=可找到大部分。 - 對其他端點的呼叫。 影像、音訊、嵌入和微調呼叫在此沒有對應項目。將它們路由到提供這些服務的服務,或將其移除。
- 供應商特定的額外功能。 屬於您舊供應商的額外請求欄位或自訂標頭可能會導致錯誤。將其簡化為純淨的 OpenAI 格式。
- Token 預算。 視窗為 100,000 個 token(提示詞加補全)。如果您為了適應較小的視窗而刪減了歷史記錄,您現在可以保留更多內容,但請注意成本,因為每次輪次中保留的每則訊息都會再次收費。
提示詞值得重新測試。對一個模型有效的系統提示詞在另一個模型上可能會產生不同的語氣,因此在發布之前,請執行您最重要的十個提示詞,並將輸出與您的預期進行比較。
常見問題與解決方案
當人們從 Python 連線到新的 OpenAI 相容端點時,最常出現的錯誤簡短列表:
- 第一次呼叫時出現 404。 Base URL 缺少
/v1,或者有多餘的路徑段。它應為https://api.veniceapialternative.com/v1。 - 401 或身份驗證錯誤。 金鑰錯誤、從複製的
.env行中仍帶有引號,或從未匯出到執行 Python 的殼層中。 - 大型輸入時請求掛起。 最大主體為 8 MB。將巨大的檔案貼到提示詞中可能會在達到 token 限制之前就超過它。請分割文字。
- 測試期間隨機出現 429。 試用金鑰只有 2 個並行請求。同時觸發五個的測試執行器會觸發限制。請以序列方式執行測試,或儲值並使用完整金鑰。
- 答案被截斷。 檢查
finish_reason。值為length表示輸出達到了您的max_tokens設定或填滿了視窗。 - 每次執行的結果不同。 如果需要測試的可重複輸出,請傳遞
seed和較低的temperature。
如果仍有問題,請將 X-Request-Id 值連同呼叫時間一起傳送給 支援。
在程式碼中估算成本
價格為每 1M 輸入 token $0.15,每 1M 輸出 token $0.50。一個小型輔助程式可將任何用量區塊轉換為美元:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
def cost_usd(usage):
return (usage.prompt_tokens * 0.15 + usage.completion_tokens * 0.50) / 1_000_000
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a limerick about a lighthouse."}],
)
print(round(cost_usd(r.usage), 6))
一次呼叫包含 2,000 個提示詞 token 和 500 個補全 token,會回傳 0.00055。執行 1,000 次,您將花費 $0.55。$0.50 的試用額度可涵蓋約 909 次此類呼叫。試用期後,儲值從 $20 開始,額度永不過期;定價頁面 列出了獎金等級。如果您的應用程式來自具有自身陷阱的聊天機器人專案,常見 API 錯誤 文章涵蓋了其中幾個也適用於此的情況。
更多指南
問答
我需要哪個 Python 套件?
官方 openai 套件。使用 pip 安裝,將 base_url 設為 https://api.veniceapialternative.com/v1, 並使用模型 uncensored。不需要其他用戶端程式庫。
SDK 支援串流輸出嗎?
支援。傳入 stream=True 並遍歷區塊。用量會在串流結束時回報。
為什麼會收到 429 錯誤?
你達到了每分鐘請求次數上限(rate_limited)、同時開啟的請求過多(concurrency),或是服務短暫過載並返回 Retry-After: 5。請退避並重試。
我可以執行多少個並行請求?
完整金鑰允許 8 個並行請求和每分鐘 300 個請求。試用金鑰允許 2 個並行和每分鐘 60 個請求。
我可以使用 LangChain 或其他 OpenAI 相容的工具嗎?
任何允許你設定 OpenAI 相容 Base URL 和金鑰的客戶端都應該可以運作。使用相同的 Base URL 與模型名稱 uncensored。