为何 OpenAI SDK 能满足你的需求
当人们搜索 Qwen API SDK 时,通常希望有一个能处理认证、重试、流式输出和类型化响应的客户端库。OpenAI SDK 已具备所有这些功能,且本服务实现了相同的 HTTP 接口:POST /v1/chat/completions、POST /v1/responses 和 GET /v1/models。任何允许覆盖 base URL 的客户端均可与其通信。
开始前需澄清一点:这不是阿里巴巴或任何模型供应商的官方 API,也不是将请求转发至他处的路由器。它是一个开放权重模型,由独立提供商运行,针对合法成人用途进行了优化,可实现无内容拒绝。您传入的唯一模型 ID 是 uncensored。
这使得迁移变得简单。如果你的项目已经通过 OpenAI SDK 调用托管聊天模型,只需更改三个值:base URL、API 密钥和模型名称。代码的其他部分无需更改。
安装并进行首次调用
安装 Python 或 Node 的官方包。无需添加任何服务特定的内容。
pip install openai
# Node: npm install openai
在 API 密钥页面创建密钥,然后导出它,使其不进入源代码。
export API_KEY="paste-your-key-here"
现在是最小可用 Python 脚本。客户端从环境变量读取密钥,并将请求发送到本服务而非 OpenAI。
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what a context window is in two sentences."},
],
temperature=0.7,
)
print(resp.choices[0].message.content)
print(resp.usage)
如果你偏好原始 HTTP,curl 中的相同请求如下所示:
curl https://api.uncensoredqwen.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say hello."}]}'使用 SDK 进行流式输出回复
设置 stream=True 并遍历 chunks。服务发送 SSE,并在流结束时报告 token 用量,无需二次调用即可记录成本。
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a short product description for a desk lamp."}],
stream=True,
stream_options={"include_usage": 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("\nTokens:", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)
请记住一点:流式请求会占用并发槽位,直到流结束。如果消费者处理缓慢或你忘记关闭流,你会比预期更早达到并发限制。
Node 中的相同模式:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredqwen.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Name three uses of JSON mode." }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}工具调用和 JSON 模式
你用于工具的 SDK 参数直接透传:tools、tool_choice、流式 tool_calls 以及带 role: "tool" 的消息结果。最小往返示例如下:
import os, json
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
tools = [{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Look up an order by id",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
},
}]
messages = [{"role": "user", "content": "Where is order A-1042?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
call = first.choices[0].message.tool_calls[0]
messages.append(first.choices[0].message)
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps({"status": "shipped"}),
})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
结构化输出时,传入 response_format={"type": "json_object"} 并在提示词中说明“以 JSON 回复”。JSON 模式要求模型输出 JSON,但代码仍需解析并验证字段名和类型。
采样设置如 temperature、top_p、stop、seed 及惩罚项均透传,现有调优设置可直接沿用。
处理 429 错误并读取标头
SDK 在 HTTP 429 时抛出速率限制异常,响应正文会告知你触发了哪种限制。完整密钥允许 8 个并发请求和每分钟 300 个请求。试用密钥允许 2 个并发请求和每分钟 60 个请求。
| 错误代码 | 含义 | 该做什么 |
|---|---|---|
rate_limited | 每分钟请求过多 | 分散调用或添加客户端限速器 |
concurrency | 同时请求过多 | 将工作池限制为 8(试用密钥为 2) |
429 且 Retry-After: 5 | 临时过载 | 等待 5 秒并重试 |
每个响应均包含 X-Request-Id、X-Balance-USD、X-RateLimit-Limit-Requests 和 X-RateLimit-Limit-Concurrency。使用 Python SDK 读取它们需使用原始响应包装器:
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "ping"}],
max_tokens=5,
)
print("Balance:", raw.headers.get("X-Balance-USD"))
print("Request id:", raw.headers.get("X-Request-Id"))
completion = raw.parse()
失败或被拒的请求不收费,因此 429 后的重试不会重复计费。关于 常见 Qwen API 错误 的现有文章涵盖了更多设置错误。
调用成本
定价为每 1M 输入 token $0.15,每 1M 输出 token $0.50,从预付额度中扣除。处理包含 2,000 个提示词 token 和 500 个完成 token 的请求:
- 输入:2,000 x $0.15 / 1,000,000 = $0.0003
- 输出:500 x $0.50 / 1,000,000 = $0.00025
- 总计:$0.00055
$0.50 的试用额度可覆盖约 900 次该规模的请求($0.50 / $0.00055 约为 909 次)。注册后,只需在密钥页面点击一次即可获取试用额度,无需绑定信用卡,有效期为 7 天;免费额度文章 解释了其运作方式。付费充值最低 $20 起,定价页面 列出了奖励层级和接受的支付方式。
上下文窗口为 100,000 token(提示词和补全合计),max_tokens 是可选的。若需控制成本上限,设置它是好习惯。
迁移现有项目
大多数读者带着已调用聊天模型的代码而来。简短的检查清单可确保切换过程平稳:
- 将
base_url(或 Node 中的baseURL)改为https://api.uncensoredqwen.com/v1。保留/v1后缀,不要自行添加/chat/completions,因为 SDK 会自动追加路径。 - 将密钥替换为你账户中的密钥。认证使用标准的
Authorization: Bearer头,SDK 会自动构建。 - 将模型名称替换为
uncensored。未知模型名称的请求会失败,请在代码库中搜索硬编码的名称。 - 移除服务未提供的功能请求字段,例如图像输入或嵌入调用。
- 运行一次
GET /v1/models调用作为冒烟测试。如果它列出了该模型,说明你的 URL 和密钥是正确的。
封装 OpenAI 客户端的框架通常以 openai_api_base 或 OPENAI_BASE_URL 等名称暴露这两个设置。如果工具提供基础 URL 的环境变量,你可以不修改源码即可切换整个应用。先用试用密钥测试,因为 2 个并发请求和每分钟 60 次的限制会很快暴露应用是否超出了计划的并行连接数。
上下文处理也值得再次审视。此处的上下文窗口为 100,000 个 token,由提示词和补全共享。如果你的旧设置将历史修剪为不同的大小,你可以放宽或收紧该修剪以匹配,但请注意在每一步重新发送长历史的成本。
生产代码的实用建议
- 将密钥移出仓库。 从环境变量或密钥存储中读取,如上述示例所示。
- 设置超时。 SDK 在客户端接受
timeout参数。流式生成长文本需要较大的读取超时。 - 限制你的工作进程。 将线程池或信号量的大小设置为你的并发限制,可在错误发生前避免大部分 429 错误。
- 记录请求 ID。 联系支持时,
X-Request-Id的值可用于标识调用。 - 关注余额。 从响应中读取
X-Balance-USD,或调用GET /v1/balance,以便在信用额度耗尽前停止批处理作业。
该模型仅支持文本。不支持图像、音频或视频生成,也不支持嵌入和微调,因此请勿依赖这些 SDK 方法。完整参数详情见 文档。提示词不用于训练。
