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 参数,以及频率和存在惩罚,都会透传给模型,因此你可以用与在其他地方相同的方式调整采样。如果你希望模型使用上下文窗口中剩余的 token 配额,请省略 max_tokens;如果你希望对回复长度和成本设置硬性上限,则设置该参数。
通过模型接口检查连接
在构建任何内容之前,确认端点可达。第二种支持的方法 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 标头可让你在不发起额外请求的情况下获取剩余额度。失败和被拒绝的请求不会收费。
在不触及上限的情况下并行运行请求
对于批处理作业,请使用异步客户端,并设置与你的密钥限制相匹配的信号量。对于完整密钥,上限为 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。如果你的调用很快,添加一个小的 sleep 或令牌桶,以免在突发时超过上限。
迁移现有 Python 项目
大多数迁移比人们预期的要小。如果你的代码已经构建了 OpenAI(...) 客户端,你只需更改两个构造函数参数和一个字符串。如果你从环境变量读取设置,你通常可以避免触碰代码:openai 包读取 OPENAI_API_KEY 和 OPENAI_BASE_URL,因此在你的 shell 或 .env 文件中设置这两个值会将整个程序指向新接口。
然后在你的项目中搜索这些项,因为它们是通常的故障来源:
- 硬编码的模型名称。 将每个旧名称替换为
uncensored。通过 grep 查找model=可以找到大多数。 - 对其他接口的调用。 图像、音频、嵌入和微调调用在这里没有等效项。将它们路由到提供这些服务的服务,或移除它们。
- 供应商特定的额外功能。 属于你旧供应商的额外请求字段或自定义标头可能导致错误。将它们剥离为纯 OpenAI 格式。
- Token 预算。 上下文窗口为 100,000 个 token(提示词加补全)。如果你为了适应较小的窗口而修剪了历史,你现在可以保留更多,但请注意成本,因为每条保留的消息在每次对话中都会再次付费。
提示词值得重新测试。对一种模型有效的系统提示词在另一种模型上可能会给出不同的语气,因此在发布之前,运行你最重要的十个提示词,并将输出与你期望的进行比较。
常见问题及其修复
当人们从 Python 连接新的 OpenAI 兼容接口时,最常见的错误简短列表:
- 首次调用 404。 base URL 缺少
/v1,或者有多余的路径段。它应完全读作https://api.veniceapialternative.com/v1。 - 401 或身份验证错误。 密钥错误,仍然包含从复制的
.env行中带来的引号,或者从未导出到运行 Python 的 shell 中。 - 请求在大输入时挂起。 最大请求体为 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 并迭代 chunks。使用情况会在流结束时报告。
为什么会出现 429 错误?
要么你超过了每分钟请求限制(rate_limited),要么同时打开了太多请求(concurrency),要么服务短暂过载并发送了 Retry-After: 5。稍后重试。
我可以运行多少并发请求?
完整密钥允许 8 个并发请求和每分钟 300 个请求。试用密钥允许 2 个并发和每分钟 60 个请求。
我可以使用 LangChain 或其他兼容 OpenAI 的工具吗?
任何允许设置兼容 OpenAI 的 base URL 和密钥的客户端都应能正常工作。使用相同的 base URL 和模型名称 uncensored。