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

重點摘要
- 100,000 token 的視窗涵蓋提示詞加上補全,因此你保留的每個工具結果都會減少下一個回答的空間。
- 在 Agent 迴圈中,整個歷史記錄在每個步驟都會重新發送,因此總輸入量隨步驟數的平方增長,而非線性增長。
- 首先修剪舊的工具輸出,保留系統提示詞和最新的對話輪次,並使用 usage 欄位進行測量。
- 一個每步驟 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。這就是整個設定過程。