要点
- 安装 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 的 chat completions 接口。
关于该代码的一些说明。密钥来自环境变量而非字面量,因此不会进入版本控制。响应上的 usage 对象包含计费所依据的确切 token 计数,这对日志记录很有用。max_tokens 是可选的:如果不设置,补全可能会使用窗口剩余部分,这对故事生成没问题,但对存在 bug 的循环来说成本很高。
流式输出到达的 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())以释放槽位。
Web 应用通常将此循环包装在生成器中,并将每个片段转发给浏览器。使用 FastAPI 时,这意味着返回一个 StreamingResponse 以生成文本部分。在此设计中,密钥应保留在服务器端。浏览器与你的路由通信,你的路由与 API 通信,因此密钥永远不会暴露给客户端代码。
异步客户端与受控并发
完整密钥允许同时发起 8 个请求,每分钟 300 个。试用密钥允许同时发起 2 个,每分钟 60 个。如果你使用 asyncio.gather 启动 200 个协程,你将收到错误码 429,错误类型为 concurrency。信号量可在问题发生前解决该问题。
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,向 requests.post 传递 stream=True,并使用 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 的奖金。
完整参数列表和错误代码,请参阅 文档。
在任务中保持运行总数,以便循环不会花费超过你计划的金额。一个对 50,000 个短文本进行分类的批处理任务,每个文本使用 400 个输入 token 和 20 个输出 token,将使用 20M 输入 token 和 1M 输出 token。这需要 20 x $0.15 + 1 x $0.50 = $3.50。如果你的计数器显示任务花费了两倍于此的金额,说明出现了循环。
