繁中 ▾
取得 API 金鑰

LLM Models API 代理工具呼叫指南

代理是一個迴圈:模型選擇工具,你的程式碼執行它,結果回傳,模型決定下一步。以下是該迴圈的實作版本,以及你需要規劃的限制與成本。

更新於

等距迴圈,球體穿過中央終端機周圍的工具區塊,說明代理工作流程
01

重點摘要

  • 端點支援工具、tool_choice、串流輸出的 tool_calls 以及 role: tool 的結果。
  • 限制你的迴圈、驗證工具參數,並在收到 429 時短暫等待後重試。
  • 對於完整金鑰,請將並行工作數保持在 8 或以下;串流會佔用其槽位直到結束。
  • 具有上下文增長的六步驟代理運行,成本約為半美分。

代理需要 API 提供什麼

若你正在選擇用於代理的 LLM models API,檢查清單比行銷宣傳的更短。你需要可靠的工具呼叫、足夠大的上下文視窗來容納進行中的對話記錄、可預測的速率限制,以及不會因多次呼叫而懲罰迴圈的價格。

此 API 透過標準 OpenAI 介面涵蓋這些功能。它支援 tools 與 tool_choice,在正常與串流回應中回傳 tool_calls,並接受帶有 role: "tool" 的訊息作為工具結果。JSON 模式可透過 response_format 取得。上下文視窗為 100,000 token(提示詞加補完),模型 ID 為 uncensored。

由於框架端僅需 OpenAI 客戶端,大多數允許設定 Base URL 的代理庫都能運作。將它們指向 https://api.llmmodelsapi.com/v1,提供你的金鑰並指定模型。設定細節請見 文件,並可從 金鑰頁面取得金鑰。

兩個限制影響設計。首先,模型僅處理文字,因此任何影像、音訊或檔案處理必須在你的工具中進行,並以文字形式回傳。其次,此端點沒有嵌入功能,如果你的代理進行檢索,向量搜尋需要另一個來源。

讓迴圈穩定的系統提示詞

大多數代理失敗來自模糊的指示,而非 API。好的系統提示詞會告訴模型它是誰、有哪些工具、何時停止以及最終答案的格式。以下是研究助手的範例。

你是一名研究助理。你可以呼叫工具 search_notes 與 read_note。僅在你需要尚未擁有的資訊時呼叫工具。最多使用五次工具呼叫。當你擁有足夠資訊時,回覆簡短答案並列出所使用的筆記 ID。若筆記中沒有答案,請明確指出。

注意它做到了什麼。它列出了工具、設定了呼叫預算、定義了停止條件,並允許模型表示它不知道。最後一點很重要,因為被迫回答的代理會編造內容。

設定較低的 temperature 用於工具呼叫。數值約在 0.2 到 0.4 之間,可讓工具名稱和參數格式保持穩定。如果你的代理程式最後也會撰寫創意文字,你可以僅針對最後一次呼叫提高 temperature。seed 參數會直接傳遞,這在你除錯時想要重現執行結果很有幫助。

對於成人小說與角色扮演代理,相同的模式同樣有效:將人格、場景規則與工具放入系統訊息。該模型經過調校,可在合法成人用途下不拒絕內容地回答。涉及未成年人的性內容仍被禁止。

Python 最小代理迴圈

下方的迴圈只有一個工具,即字典查找,代表你的真實資料。當模型回覆未包含工具呼叫時,或達到固定步驟數時,迴圈停止。

import json
from openai import OpenAI

client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY")

NOTES = {
    "n1": "Invoice 114 was paid on March 3.",
    "n2": "Invoice 115 is overdue by 12 days.",
}

def search_notes(query):
    return [{"id": k, "text": v} for k, v in NOTES.items() if query.lower() in v.lower()]

TOOLS = [{
    "type": "function",
    "function": {
        "name": "search_notes",
        "description": "Search internal notes by keyword",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}]

SYSTEM = "You are a research assistant. Use search_notes when needed, at most five calls. Then answer briefly."

def run(question, max_steps=6):
    messages = [
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": question},
    ]
    for step in range(max_steps):
        resp = client.chat.completions.create(
            model="uncensored",
            messages=messages,
            tools=TOOLS,
            temperature=0.3,
            max_tokens=500,
        )
        msg = resp.choices[0].message
        messages.append(msg)
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            try:
                args = json.loads(call.function.arguments)
                result = search_notes(args["query"])
            except Exception as exc:
                result = {"error": str(exc)}
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result),
            })
    return "Stopped: step limit reached."

print(run("Which invoice is overdue?"))

有三個細節值得注意。步驟限制可防止迷惘的模型不斷迴圈執行,直到你的預算耗盡。try 區塊會將格式錯誤的參數字串轉換為錯誤訊息,讓模型可以讀取並修正。每個工具結果都會附上對應的 tool_call_id 回傳,這樣模型才知道每個答案屬於哪次呼叫。

處理 429 回應與並行請求

代理具有突發性。規劃器可能同時發出五個子任務,每個子任務執行自己的迴圈。這就是速率限制出現的地方。

完整金鑰允許 8 個並行請求與每分鐘 300 個請求。試用金鑰允許 2 個與 60 個。超過限制時,API 會回傳 HTTP 429。錯誤程式碼告訴你觸及了哪個限制:rate_limited 表示每分鐘請求數,concurrency 表示同時過多。在暫時過載時,你也會收到 429,並帶有 Retry-After: 5 標頭。

將所有這些視為可重試。等待標頭中的秒數,若無則等待幾秒後再次發送請求。失敗的請求不會計費,因此重試不花錢。一個小型封裝即可達成此目的。

import time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY", max_retries=0)

def chat_with_retry(**kwargs):
    for attempt in range(5):
        try:
            return client.chat.completions.create(model="uncensored", **kwargs)
        except RateLimitError as err:
            wait = 5
            if err.response is not None:
                wait = int(err.response.headers.get("retry-after", 5))
            time.sleep(wait)
    raise RuntimeError("Still rate limited after 5 attempts")

要從根本上避免 429 錯誤,請限制你的工作池。Semaphore 設為 8 符合完整金鑰的限制。如果你將串流回應傳送至使用者介面,請記住串流會佔用並行槽位直到最後一個 token 到達,因此如果客戶端讀取長答案的速度很慢,會一直佔用槽位。讀取 X-RateLimit-Limit-Requests 和 X-RateLimit-Limit-Concurrency 標頭,可讓你的程式碼根據所使用的金鑰進行調整。

上下文、記憶體與執行成本

迴圈的每個步驟都會重新發送完整的對話記錄。這是聊天 API 的工作方式,這意味著輸入 token 會隨著每次工具呼叫而增長。考慮一個六步驟的運行,提示詞從 2,000 token 開始,每步驟增加 1,000,每步驟有 300 個輸出 token。

  • 輸入 token:2,000 + 3,000 + 4,000 + 5,000 + 6,000 + 7,000 = 27,000
  • 輸出 token:6 x 300 = 1,800
  • 輸入成本:27,000 x 0.15 / 1,000,000 = $0.00405
  • 輸出成本:1,800 x 0.50 / 1,000,000 = $0.0009
  • 總計:每次執行 $0.00495

一千次此類執行成本為 $4.95。這足夠便宜,讓代理可以分步驟思考,但增長值得關注。擁有 100,000 token 的空間,長期運行的代理最終會填滿視窗,而如此大的提示詞在每個步驟的輸入成本為 100,000 x 0.15 / 1,000,000 = $0.015。

三個習慣可保持控制。在將大型工具結果放入對話記錄前進行截斷,例如網頁的前 2,000 個字元。一旦歷史超過閾值,將舊步驟摘要為一條短訊息。並將持久性事實儲存在你自己的資料庫中,而不是依賴對話作為記憶體。

每個回應上的 X-Balance-USD 標頭會顯示剩餘額度,因此代理程式監督者可以在餘額低於底線時停止執行。額度為預付額度,起付金額為 $20,且永不過期。請參閱 定價頁面 了解儲值獎金。

規劃時需考慮的限制

基於任何模型建立的代理都需要防護措施,此模型也不例外。請準備好應對以下情況。

  • 格式錯誤的參數。 模型可能產生無效 JSON 或缺少必要欄位的工具參數。以防禦性方式解析並將錯誤作為工具結果回傳。
  • 錯誤的工具選擇。 撰寫簡短且區分度高的工具描述。如果兩個工具聽起來相似,模型會混淆它們。使用 tool_choice 在流程需要時強制進行特定呼叫。
  • 僅文字。 無影像輸入或輸出、無音訊、無嵌入、無微調。在其他地方處理這些部分並將結果以文字形式傳遞。
  • 單一模型。 端點後方只有一個開放權重模型,而非跨供應商的路由器。你無法為簡單步驟選擇較小的模型。
  • 破壞性工具。 不要給予代理程式刪除或付款的工具,除非在你的程式碼中設有確認步驟。

規劃代理也能從第二次檢查中受益。迴圈返回答案後,你可以進行一次更便宜的呼叫,要求模型使用 JSON 模式根據它看到的工具結果檢查答案,並回傳判決與不支持的聲明列表。這會增加幾百個 token,並捕捉最常見的失敗,即忽略工具回傳內容的自信答案。

最後,記錄每個步驟。儲存訊息、工具參數以及每個回應的 X-Request-Id 標頭。當執行出錯時,請求 ID 可讓你指向確切的呼叫,而記錄的對話紀錄則顯示是哪個工具結果誤導了模型。若能重播失敗的執行並一次更改一件事,代理程式最容易改善。

在決定使用前,先用試用版測試代理程式。新用戶可領取 $0.50 的額度,以上述六步驟的執行來看,約可涵蓋 101 次完整執行(0.50 / 0.00495)。請記住試用版的 2 個並行請求限制,並一次只執行一個代理程式。若要更廣泛地了解服務,請閱讀 按 token 計費概覽。提示詞不會用於訓練。

02

問答

API 支援代理程式的工具呼叫嗎?

是的。它接受工具和 tool_choice,回傳 tool_calls(串流時亦然),並接受 role 為 tool 的訊息作為結果。

最多可並行執行多少個代理請求?

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

收到 429 時代理該怎麼辦?

等待 Retry-After 的值,若無則等待幾秒,然後重試。被拒絕的請求不會收費。

代理能處理影像或音訊嗎?

否。該模型僅支援文字,因此其他媒體必須由你的工具處理,並以文字形式傳入。

只差一個表單,即可取得金鑰

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

取得 API 金鑰