繁中 ▾
取得 API 金鑰

首頁指南

更新於

AI Agent 上下文視窗:100k token 如何使用

AI Agent 上下文視窗是提示詞、工具結果和模型回答共享的總 token 空間。在此 API 上,該空間為 100,000 個 token,長時間運行的 Agent 傾向於比預期更快地填滿它。

玻璃容器裝滿發光的區塊,同時箭頭迴圈環繞它,描繪 Agent 的上下文視窗

重點摘要

  1. 100,000 token 的視窗涵蓋提示詞加上補全,因此你保留的每個工具結果都會減少下一個回答的空間。
  2. 在 Agent 迴圈中,整個歷史記錄在每個步驟都會重新發送,因此總輸入量隨步驟數的平方增長,而非線性增長。
  3. 首先修剪舊的工具輸出,保留系統提示詞和最新的對話輪次,並使用 usage 欄位進行測量。
  4. 一個每步驟 1,500 個新 token 的 20 步迴圈,總成本約為 $0.055。

不需要信用卡。註冊後,點擊一次即可領取 $0.50 的免費試用額度(每人限領一次)。

取得 API 金鑰

簡短答案:100,000 個 token 的共享預算

當人們搜尋 AI Agent 上下文視窗時,他們通常想知道 Agent 在崩潰前能記住多少內容。這裡的數字是 100,000 個 token,它計算所有內容:系統提示詞、工具定義、每個先前的訊息、每個工具結果,以及模型即將撰寫的補全。補全可以使用剩餘的空間,且 max_tokens 是可選的。

這使得視窗成為預算,而非儲存空間。聊天機器人很少接近限制。在迴圈中呼叫工具的 Agent 可能在一個下午內達到限制,因為每個步驟都會向歷史記錄添加模型訊息和工具結果,並且整個歷史記錄會在下次呼叫時再次發送。模型在請求之間沒有記憶。看起來像記憶的是你重新發送對話記錄。

實際上在 Agent 中填滿視窗的是什麼

大部分空間不是使用者的文字。追蹤這五個來源,你就可以預測運行會在哪裡耗盡。

  • 系統提示詞。 規則、人格和輸出格式。通常為 500 到 2,000 個 token,並在每次呼叫時發送。
  • 工具定義。 每個函式名稱、描述和 JSON 結構定義都計入。十個具有長描述的工具可能在第一個使用者訊息之前耗費數千個 token。
  • 工具結果。 最常見的罪魁禍首。搜尋結果、檔案轉儲或資料庫資料列集可能達到數千個 token,並且除非你移除它,否則它會保留在歷史記錄中。
  • 助手訊息。 以文字寫出的推理以及模型產生的 tool_calls 參數。
  • 正在生成的回覆。 它也需要空間。如果提示詞是 99,000 個 token,則答案只剩下約 1,000 個空間。

API 在每個回應的 usage 區塊中報告精確數字,因此你不需要猜測。在每個步驟後記錄 prompt_tokens,你將看到曲線。

範例:工具迴圈的 20 個步驟

考慮一個具有 3,000 token 起始值(系統提示詞加上工具定義)的 Agent。每個步驟向歷史記錄添加約 1,500 個 token:模型的 tool call 和工具的結果。它還每步驟寫入約 300 個 token 的輸出。Agent 運行 20 個步驟。

步驟 k 的輸入為 3,000 + 1,500 × (k − 1)。在 20 個步驟中總和:

  • 3,000 × 20 = 60,000 個 token 用於固定起始值,每次重新發送。
  • 1,500 × (0 + 1 + ... + 19) = 1,500 × 190 = 285,000 個 token 的累積歷史記錄。
  • 總輸入:345,000 個 token。總輸出:20 × 300 = 6,000 個 token。
項目Token每 1M 價格成本
輸入345,000$0.15$0.05175
輸出6,000$0.50$0.003
總計約 $0.055

兩件事很突出。首先,步驟 20 的上下文為 3,000 + 1,500 × 19 = 31,500 個 token,遠在視窗範圍內,但你為 345,000 個輸入 token 付費,因為歷史記錄每次都被重新發送。其次,具有完全滿載視窗(100,000 個輸入 token)的單次呼叫,輸入側成本為 100,000 × $0.15 / 1M = $0.015。長上下文每次呼叫的成本很便宜;成本來自於在許多步驟中重複它們。請參閱 定價頁面 以獲取費率和儲值獎金。

視窗滿載前能容納多少步驟

你可以在編寫任何程式碼之前估算這一點。為答案保留剩餘空間,例如 20,000 個 token,這為提示詞留下了 80,000 個 token 的預算。以 3,000 token 的起始值和每步驟添加 1,500 個 token 計算,歷史記錄在 (80,000 − 3,000) / 1,500,或約 51 個步驟後達到該預算。

現在計算該長度的運行成本。在 51 個步驟中,輸入為 3,000 × 51 + 1,500 × (0 + 1 + ... + 50) = 153,000 + 1,500 × 1,275 = 153,000 + 1,912,500 = 2,065,500 個 token。每步驟 300 個 token 的輸出為 15,300 個 token。成本:2,065,500 × $0.15 / 1M = $0.30983,加上 15,300 × $0.50 / 1M = $0.00765,所以約為 $0.32。

與約 $0.055 的 20 步運行相比。運行時間長 2.55 倍,但成本約高 5.8 倍,因為每個步驟都攜帶更長的歷史記錄。這是修剪的實際原因:它限制了每步驟的成本,同時保護視窗。

讓 Agent 保持在視窗內

首先刪除舊的工具輸出

原始工具結果是舊歷史記錄中最大且最無用的部分。一旦模型對檔案列表採取行動,它很少需要再次查看該列表。將舊結果替換為一行存根,例如「結果已移除,4,200 個 token」,或完全刪除該對。

摘要中間部分,保留兩端

保留系統提示詞和最後幾個對話輪次不變。對於中間的所有內容,要求模型對所做的決策和發現的事實進行簡短摘要,然後將該摘要存儲為單一條訊息。在達到限制之前運行摘要呼叫,而不是之後。

將事實移出對話記錄

如果 Agent 學到了一些必須保留數小時的內容,請透過工具將其寫入檔案或小資料庫,並在需要時讀取它。這比在每個請求中攜帶它更便宜,並且可以承受重啟。

保持工具結構定義簡短

修剪描述,只保留模型選擇工具所需的內容。僅傳遞與任務當前階段相關的工具。

程式碼:具有 token 預算的工具迴圈

當粗略大小超過 80,000 個 token 的預算時,此迴圈會修剪最舊的訊息,為答案留出空間。該估計將字元數除以四,這是英文文本的常見近似值;實際計數將返回到 usage。修剪會刪除孤立的 tool 訊息,因此不會出現沒有對應呼叫的結果。

import json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.aivideogenapi.com/v1", api_key=os.environ["API_KEY"])
BUDGET = 80_000

tools = [{"type": "function", "function": {
    "name": "get_scene_length",
    "description": "Return the length of a scene in seconds",
    "parameters": {"type": "object",
                   "properties": {"scene": {"type": "integer"}},
                   "required": ["scene"]}}}]

def rough_tokens(messages):
    return sum(len(json.dumps(m)) for m in messages) // 4

def trim(messages):
    system, rest = messages[0], messages[1:]
    while rough_tokens([system] + rest) > BUDGET and len(rest) > 4:
        rest.pop(0)
        while rest and rest[0]["role"] == "tool":
            rest.pop(0)
    return [system] + rest

def run_tool(name, args):
    return json.dumps({"seconds": 4 * args["scene"]})  # stub

messages = [
    {"role": "system", "content": "You plan video scenes. Use tools for lengths."},
    {"role": "user", "content": "Total the length of scenes 1 to 5."},
]

for step in range(20):
    resp = client.chat.completions.create(
        model="uncensored", messages=trim(messages), tools=tools)
    msg = resp.choices[0].message
    messages.append(msg.model_dump(exclude_none=True))
    print(step, resp.usage.prompt_tokens)
    if not msg.tool_calls:
        print(msg.content)
        break
    for call in msg.tool_calls:
        result = run_tool(call.function.name, json.loads(call.function.arguments))
        messages.append({"role": "tool", "tool_call_id": call.id, "content": result})

工具呼叫遵循 OpenAI 格式:tools、tool_choice,以及作為 role: "tool" 返回的結果。文件 列出了可透傳的參數。

除了視窗之外重要的限制

視窗是一項限制。Agent 也會觸發請求限制。完整金鑰允許 8 個並行請求和每分鐘 300 個請求;試用金鑰允許 2 個和 60 個。帶有並行子 Agent 的緊密迴圈會很快超過並行上限。API 會以 HTTP 429 回應,並附上錯誤碼 concurrency 或 rate_limited,在暫時過載時則會附上 Retry-After: 5 標頭。等待該時間後再重試。

如果你進行串流輸出,請記住串流請求會在其串流結束前佔用其並發槽位。從未關閉串流的停滯客戶端會佔用一個槽位。

最大請求主體為 8 MB,遠超過 100,000 個 token 的文字量,因此視窗是你較早會觸及的限制。若要查看基於此 API 建置的純文字管線範例,請參閱 影片腳本指南。當你準備好要執行時,請 建立 API 金鑰;新用戶可以一鍵領取 $0.50 的免費試用額度,有效期 7 天且無需付款。

問答

上下文視窗有多大?

100,000 個 token,包含提示詞與補全的總計。補全可以使用提示詞剩餘的任何空間。

模型會記住之前的請求嗎?

不會。每個請求都是獨立的,因此你的程式碼必須重新傳送希望模型看見的訊息。

超過限制時會發生什麼事?

請求無法容納,請在傳送前精簡或摘要歷史記錄。失敗的請求不會收費。

我該如何計算 token?

從每個回應的 usage 區塊讀取 prompt_tokens 和 completion_tokens,或在傳送前對英文進行粗略估算,每四個字元約等於一個 token。

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

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

取得 API 金鑰