繁中 ▾
取得 API 金鑰

Python LLM API 工作流程:逐步設定

將 OpenAI SDK 指向新的 Base URL,使用模型 ID uncensored,並一次一層地加入重試、並行執行和函式呼叫。

更新於

發光的區塊管線,資料立方體分流至並行車道,代表 Python LLM 工作流程

重點摘要

  • 安裝 openai,將 base_url 設為 https://api.veo3apis.com/v1 並使用模型 uncensored。
  • 收到 429 時請等待 Retry-After;失敗的請求不會計費。
  • 根據金鑰設定執行緒池大小:完整金鑰設為 8 個工作執行緒,試用金鑰設為 2 個。
  • 從回應標頭讀取 X-Balance-USD 以追蹤每次執行的花費。

簡短版本

要建立 llm api workflow python 腳本,請安裝官方 OpenAI SDK,將 base 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 的上限。若呼叫速度快,請加入短暫睡眠或 token 桶限制器,以保持在每分鐘上限內。若呼叫速度慢,則會先觸及並行限制。串流請求會佔用槽位直到串流結束。

結構化輸出與工具呼叫

兩個功能可將聊天呼叫轉為其他程式碼可依賴的工作流程步驟。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 個請求的上限。

保留中間結果。當最終文字錯誤時,草稿與審查會告訴你哪個步驟失敗,你只需修正一個系統訊息即可,無需重寫整個管線。將每個步驟寫入 JSON-lines 檔案(包含輸入、三個輸出與請求 ID)可輕鬆實現此目的,若過程中途停止,這也能作為恢復點。

追蹤餘額與請求 ID

每個回應都包含值得記錄的標頭:X-Request-Id可在你聯繫支援時識別該次呼叫,X-Balance-USD顯示剩餘的預付額度,而兩個X-RateLimit-Limit標頭則報告你的金鑰的速率限制與並行請求限制。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 的提示詞不會用於訓練,但你的日誌檔案由你自行負責。

新設定的疑難排解

大多數首次執行的問題來自少數幾個原因。

  • 呼叫掛起或連線錯誤。 檢查 Base URL。它必須以 /v1 結尾,SDK 會自行附加 /chat/completions。路徑重複是常見錯誤。
  • 驗證錯誤。 金鑰遺失、截斷或從複製貼上產生多餘的空格或換行。請列印金鑰長度而非金鑰本身,並與金鑰頁面顯示的內容進行比較。
  • 找不到模型。 模型 ID 為 uncensored,為小寫。呼叫模型端點以查看你的金鑰確可使用哪些模型。
  • 小型腳本持續收到 429。 你可能使用的是試用金鑰,它允許 2 個並行請求與每分鐘 60 個請求。將池大小降至 2 個工作執行緒,或儲值以獲取完整金鑰。
  • 回答被截斷。 較低的 max_tokens 會導致回應提前結束。提高該值,或移除它以讓完成部分使用剩餘的上下文視窗。
  • 請求過大。 主體限制為 8 MB,上下文視窗為 100,000 token(包含提示詞與回應)。將大型輸入拆分為多個部分並作為獨立呼叫處理。

當服務端出現異常時,請將 X-Request-Id 的值提供給網站上的聯絡窗口。請求 ID 讓操作人員能準確找到您的呼叫記錄,這比描述您看到的內容更有用。

01

問答

我需要特殊的 SDK 嗎?

否。只要設定 Base URL 和金鑰,官方 OpenAI Python SDK 即可運作。

我該使用哪個模型 ID?

使用 uncensored。你可以使用 GET /v1/models 列出可用的 ID。

可以並行執行多少個請求?

完整金鑰允許 8 個並行請求與每分鐘 300 個請求。試用金鑰允許 2 個並行請求與每分鐘 60 個請求。

Python SDK 支援串流輸出嗎?

是的。傳入 stream=True 並遍歷資料塊。用量會在串流結束時回報。

只需填寫表單即可取得金鑰

建立帳號、複製金鑰、更改基本 URL。這就是整個設定過程。

取得 API 金鑰閱讀文件