Python LLM API 工作流:分步设置
将 OpenAI SDK 指向新的基础 URL,使用模型 ID uncensored,并逐层添加重试、并发运行和工具调用。
更新于

要点
- 安装 openai,将 base_url 设置为 https://api.veo3apis.com/v1,并使用模型 uncensored。
- 处理 429 错误:等待 Retry-After 标头;失败的请求不收费。
- 根据密钥类型调整线程池:完整密钥使用 8 个工作线程,试用密钥使用 2 个。
- 从响应标头中读取 X-Balance-USD 以跟踪每次运行的花费。
简短版本
要构建 llm api workflow python 脚本,请安装官方 OpenAI SDK,将基础 URL 设置为 https://api.veo3apis.com/v1,将你的密钥作为 API 密钥使用,并调用模型 uncensored。其他一切保持不变。该服务与 OpenAI 兼容,因此 SDK 中你已知的每种模式都有效:普通聊天调用、流式输出、JSON 模式和工具调用。
本文逐步构建一个小型工作流。你从单次调用开始,然后依次添加环境变量、重试包装器、并发执行器、工具调用和余额跟踪等功能。每一层都很简短,你可以在满足需求的任意一层停止。
该模型是一个由独立提供商运行的开放权重模型。它不是任何大型供应商的官方 API,也不是路由器,因此只有一个模型 ID 需要记住。它仅处理文本。没有图像、音频或视频生成,没有嵌入,也没有微调。
安装 SDK 并进行首次调用
你需要 Python 3.9 或更高版本。安装 SDK:
pip install openai
在通过 Google 或电子邮件和密码注册后,从 API 密钥页面创建密钥。该页面还提供一键领取 $0.50 试用额度的功能,有效期 7 天,每人限领一次,无需信用卡。然后运行最小的调用:
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "List three uses for a hosted text API."},
],
)
print(resp.choices[0].message.content)
print(resp.usage)
如果这打印文本和使用对象,则身份验证、路由和模型 ID 均正确。SDK 将你的密钥作为 Authorization: Bearer 发送,请求发送到 POST /v1/chat/completions。你可以使用 client.models.list() 检查你的密钥可以看到哪些模型 ID,该调用会执行 GET /v1/models。
原始 curl 版本在从没有 Python 的服务器进行调试时很有用:
curl https://api.veo3apis.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "uncensored", "messages": [{"role": "user", "content": "Say hello."}]}'
将配置保留在一个客户端中
在脚本中硬编码密钥是将其泄露到存储库的最快方法。从环境变量中读取两个值,并在一个地方创建客户端,以便工作流的每一步都共享它。
import os
from openai import OpenAI
client = OpenAI(
base_url=os.environ.get("LLM_BASE_URL", "https://api.veo3apis.com/v1"),
api_key=os.environ["LLM_API_KEY"],
max_retries=0,
timeout=120,
)
MODEL = "uncensored"
def ask(system: str, user: str, **kwargs) -> str:
resp = client.chat.completions.create(
model=MODEL,
messages=[
{"role": "system", "content": system},
{"role": "user", "content": user},
],
**kwargs,
)
return resp.choices[0].message.content
这里的两个选择是刻意为之。max_retries=0 关闭 SDK 的内置重试,以便下一部分中的重试逻辑是唯一的,这使得行为更容易推理。120 秒超时为长完成留出了空间;上下文窗口为 100,000 个 token,用于提示词加完成,而大答案需要时间才能流式输出。采样参数如 temperature、top_p、stop、seed 和惩罚通常通过 **kwargs 传递。
重试正确的错误
每个实际工作流迟早都会遇到速率限制。完整密钥允许每分钟 300 个请求和同时 8 个。试用密钥允许每分钟 60 个和同时 2 个。超过任一限制,API 将返回 HTTP 429。错误代码告诉你遇到了哪个限制:rate_limited 针对每分钟请求数,concurrency 针对同时请求过多。在临时过载期间,API 还会发送带有 Retry-After: 5 标头的 429。
所有三种情况都有相同的解决方法:等待,然后重试。此包装器尊重标头,并在标头缺失时退避。
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
import time
from openai import RateLimitError, APIConnectionError, APIStatusError
def call_with_retry(messages, tries=5, **kwargs):
delay = 2
for attempt in range(tries):
try:
return client.chat.completions.create(
model="uncensored", messages=messages, **kwargs
)
except RateLimitError as err:
wait = err.response.headers.get("Retry-After")
time.sleep(int(wait) if wait else delay)
delay = min(delay * 2, 30)
except APIConnectionError:
time.sleep(delay)
delay = min(delay * 2, 30)
except APIStatusError as err:
if err.status_code < 500:
raise
time.sleep(delay)
delay = min(delay * 2, 30)
raise RuntimeError("request failed after retries")
仅重试可能更改的错误。400 意味着你的请求格式错误,再次发送它将同样失败,因此包装器会重新引发除 429 之外的任何客户端错误。失败或拒绝的请求不收费,因此重试不会额外花费。
并行运行多个输入
对于多个输入的循环,线程池就足够了。SDK 客户端在线程间共享是安全的。根据密钥类型调整池大小:完整密钥使用 8 个工作线程,试用密钥使用 2 个。
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
import time
from concurrent.futures import ThreadPoolExecutor
from openai import RateLimitError
def summarize(text: str) -> str:
for _ in range(5):
try:
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "Summarize the text in two sentences."},
{"role": "user", "content": text},
],
max_tokens=150,
)
return resp.choices[0].message.content.strip()
except RateLimitError as err:
time.sleep(int(err.response.headers.get("Retry-After", "5")))
return ""
documents = ["First long text...", "Second long text...", "Third long text..."]
with ThreadPoolExecutor(max_workers=8) as pool:
summaries = list(pool.map(summarize, documents))
for s in summaries:
print(s)
池大小不等于请求速率。八个工作线程每个在半秒内完成调用,每分钟将产生 960 个请求,远超 300。如果你的调用很快,添加一个小睡眠或令牌桶限制器,以便你保持在每分钟限制以下。如果你的调用很慢,并发是你首先遇到的限制。流式请求在其流完成之前保持其槽位。
结构化输出和工具调用
两个功能将聊天调用转变为其他代码可以依赖的工作流步骤。JSON 模式保证输出可解析。工具调用让模型请求你的代码执行某操作,然后使用返回的答案。
JSON 模式
将 response_format 设置为 JSON 对象,并在提示词中描述键。
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
import json
resp = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Reply with JSON: {\"title\": string, \"tags\": [string]}"},
{"role": "user", "content": "A short post about nightly backups."},
],
)
post = json.loads(resp.choices[0].message.content)
print(post["title"], post["tags"])
工具调用
使用 tools 声明工具,可选地使用 tool_choice 强制选择,自己运行函数,并使用 role: "tool" 将结果作为消息发送回去。
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
import json
tools = [{
"type": "function",
"function": {
"name": "word_count",
"description": "Count the words in a piece of text.",
"parameters": {
"type": "object",
"properties": {"text": {"type": "string"}},
"required": ["text"],
},
},
}]
messages = [{"role": "user", "content": "How many words are in 'the quick brown fox'?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message
if msg.tool_calls:
messages.append(msg)
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
result = {"words": len(args["text"].split())}
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)
else:
print(msg.content)
在读取之前始终检查 tool_calls 是否存在。模型可能会直接回答,你的代码应处理这两种结果。
将步骤链接为管道
实际工作流很少在一次调用后停止。常见形状是草稿、审查、重写:第一次调用生成一些内容,第二次根据检查表批评它,第三次应用批评。每个步骤都是一个单独的请求,具有自己的系统消息,这使得指令简短且故障易于定位。
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
def step(system: str, user: str, temperature: float = 0.7) -> str:
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": system},
{"role": "user", "content": user},
],
temperature=temperature,
max_tokens=800,
)
return resp.choices[0].message.content.strip()
topic = "a changelog entry for a new export feature"
draft = step("Write the requested text in under 120 words.", topic)
review = step(
"List at most three concrete problems with this text: vague wording, missing detail, wrong tone.",
draft,
temperature=0.2,
)
final = step(
"Rewrite the text so it fixes every listed problem. Reply with the text only.",
"TEXT:\n" + draft + "\n\nPROBLEMS:\n" + review,
)
print(final)
注意审查步骤中较低的温度设置。审查过程应在每次运行时保持一致,而草稿生成则受益于一定的多样性。如果你针对大量输入运行该管道,请将整个三步函数放入上一节中的线程池工作器内,以便每个工作器从头到尾处理一个项目,从而遵守 8 个并发请求的上限。
保留中间结果。当最终文本出错时,草稿和审查结果能告诉你哪一步失败了,这样你只需修复一个系统提示词,而不必重写整个管道。将每个步骤连同输入、三个输出和请求 ID 一起写入 JSON-lines 文件可以轻松实现这一点,如果过程中途停止,它还能提供恢复点。
跟踪余额和请求 ID
每条响应都包含值得记录的请求头:X-Request-Id 在联系支持团队时用于标识调用,X-Balance-USD 显示剩余预付额度,两个 X-RateLimit-Limit 请求头报告你的 API 密钥的请求和并发限制。SDK 默认隐藏请求头;使用原始响应包装器来读取它们。
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "Reply with the single word ready."}],
max_tokens=10,
)
print("request id:", raw.headers.get("X-Request-Id"))
print("balance usd:", raw.headers.get("X-Balance-USD"))
print("req limit:", raw.headers.get("X-RateLimit-Limit-Requests"))
print("concurrency limit:", raw.headers.get("X-RateLimit-Limit-Concurrency"))
resp = raw.parse()
print(resp.choices[0].message.content)
定价为每百万输入 token $0.15,每百万输出 token $0.50,因此一次包含 1,000 输入和 500 输出 token 的调用花费 $0.00015 + $0.00025 = $0.0004。运行 5,000 次此类调用的工作流花费 $2.00。在运行的开始和结束时打印余额,你将知道每个批次的成本,无需任何额外工具。有关费率和充值奖金,请参阅 定价页面;有关每个支持的参数,请阅读 API 文档。
另一个值得采用的习惯:除非你需要,否则将提示词保留在日志之外。发送到此 API 的提示词不用于训练,但你的日志文件由你负责。
排查新设置的问题
大多数首次运行的问题来自少数几个原因。
- 调用挂起或连接错误。 检查基础 URL。它必须以
/v1结尾,SDK 自己附加/chat/completions。路径加倍是常见错误。 - 身份验证错误。 密钥缺失、截断或包含复制粘贴的多余空格或换行符。打印其长度,而不是密钥本身,并将其与密钥页面显示的内容进行比较。
- 未找到模型。 模型 ID 为
uncensored,小写。调用模型接口以查看你的密钥确切可以使用什么。 - 小型脚本中持续出现 429 错误。 你可能使用的是试用密钥,它允许 2 个并发请求和每分钟 60 个请求。将工作线程池减少到 2 个,或者充值以获取完整密钥。
- 截断答案。 较低的
max_tokens会提前结束回复。提高它,或将其移除,让完成使用窗口的其余部分。 - 请求过大。 请求体限制为 8 MB,上下文窗口为 100,000 个 token(包含提示词和补全部分)。将大输入拆分为片段,并将它们作为单独的调用进行处理。
当服务端出现异常时,请将 X-Request-Id 的值发送给网站上的联系人。请求 ID 能让运维人员准确定位你的调用,这比描述你看到的内容更有用。
更多指南
问答
我需要特殊的 SDK 吗?
不需要。设置基础 URL 和你的密钥后,官方 OpenAI Python SDK 即可使用。
我应该使用哪个模型 ID?
使用 uncensored。你可以通过 GET /v1/models 列出可用 ID。
有多少个请求可以并发运行?
完整密钥允许 8 个并发请求和每分钟 300 个请求。试用密钥允许 2 个和 60 个。
Python SDK 是否支持流式输出?
可用。传入 stream=True 并迭代 chunks。使用情况会在流结束时报告。