Voyage AI 2 億免費 Tokens 怎麼用？用 voyage-4-large 做學生 RAG

Voyage AI 可以成為學生 AI Agent 的第十四種燃料，但它不是免費聊天模型，而是 RAG 的 embedding 和 reranking 基礎設施。Voyage 官方目前的 Pricing 頁面列出：部分新模型每個 account 的首 200M tokens 免費，部分 multilingual、finance、law 和 code 模型列首 50M；multimodal 模型則另列免費文字 tokens 與 pixels。這些額度要依模型和 endpoint 分開查核，不是所有 Voyage API 共用一個固定數字。

這種燃料很適合學生建立公開資料的小型向量索引、比較 query／document embedding、測試 rerank、練習 citation grounding，或替主要 Agent 做檢索前處理。它不會直接產生聊天回答；通常還需要 vector store、retrieval policy 和另一個已批准的生成模型。免費 token 很大，也不代表可以把私有資料、付費內容或未授權網站批次送到遠端。

當日敲門模型：voyage-4-large

以 2026 年 8 月 25 日的官方 FAQ 和模型公告來看，通用 retrieval 的敲門模型先選 voyage-4-large：Voyage 將它列為 general-purpose embedding 的最高品質選項，也是 Voyage 4 的旗艦 MoE embedding model；Pricing 目前列首 200M tokens 免費。它適合先把公開文件做 document embedding，再以同一個 shared embedding space 的 voyage-4-lite 做低成本 query embedding。若主要 Agent 的資料是程式碼與程式文件，改用同樣列首 200M 免費的 voyage-code-4；長文件需要自動切塊時，另評估 voyage-context-4。這些「最佳」描述是官方自己的模型建議或評測，不是 YOLO LAB 的獨立 benchmark 結論。

要開始敲門，學生可由 Voyage dashboard 依官方流程建立自己的帳戶、organization／project 與 API key；本文不代註冊、不代取得 key，也不要求把 key 貼到聊天視窗。註冊後先回讀當日 model row、free balance、organization／project budget 和 data-control 狀態，再決定是否只用公開或 synthetic fixture 做第一個 smoke。

Voyage 免費額度的定位

Voyage 官方把 embedding model 描述成把文字、影像或其他資料轉成向量，把 reranker 描述成根據 query 和多份文件產生 relevance scores。典型 RAG 會先用 embedding 或 BM25 找候選，再用 reranker 排序，最後把前幾個有來源的片段交給聊天模型。學生要把這三層分開測量：召回率、排序品質和最終回答品質不能用同一個分數代替。

Voyage 的免費方案因此是 retrieval fuel，不是「主要 Agent 已經有一個免費大模型」。它能讓 Agent 更容易找到證據，但不能替代資料閘門、來源權利、模型回答的人工驗證或外部工具批准。文章只討論 self-serve API 的合法低量實驗，不討論 AWS／MongoDB marketplace 的 GPU deployment 和雲端帳單。

200M 與 50M 免費 tokens

本次查核的 Voyage Pricing 頁面目前把 voyage-4-large、voyage-4、voyage-4-lite、voyage-context-4 和 voyage-code-4 等部分模型列為每 account 首 200M tokens 免費；voyage-multilingual-2、voyage-finance-2、voyage-law-2 和 voyage-code-2 則列為首 50M。另列出的 rerank-2.5、rerank-2.5-lite、rerank-2 和 rerank-2-lite 也各有首 200M tokens 免費。模型清單會更新，請求前要回讀當日 pricing row，不要只照抄舊文章。

Multimodal embedding 的免費項目還要同時看文字 tokens 和 pixels。官方目前列出 voyage-multimodal-3.5 與 voyage-multimodal-3 的首 200M text tokens 和 150B pixels 免費；圖片與影片的像素會依規則換算成使用量。學生若只想做文字 RAG，應先關閉圖片路徑，避免一個看似小的多模態批次意外吃掉像素額度。

免費 tokens 不是每月重設，也不是每個 project 可以自行複製一份。官方 Pricing 是按模型與 endpoint row 列出每 account 的免費段；organization、project 和 API key 的權限與限制則另外管理。主要 Agent 要保存 account、organization、project、endpoint、model、free balance snapshot 和查核時間，並在每個 task 使用單一明確的 budget，避免不同學生誤以為換 project 就會增加免費池。

免費後的付費線

Voyage 是 usage-based pricing。免費額度用完後，後續 embedding、multimodal 或 rerank usage 會按當日價格計費；FAQ 目前說明帳單按月處理，信用卡可能在下個月初被收取上月用量。學生 Agent 不應因為免費額度很大，就把自動重試、背景 indexer 或無限抓取留在 production 中。

若要設定 Tier 1 的基本 rate limits，官方目前要求 organization 加入 payment method；即使加了付款方式，free tokens 仍可適用，但免費耗盡後可能繼續進入付費 usage。這個設計要寫成兩個獨立狀態：payment method 是 rate-limit／billing capability，不是免費額度增加，也不是永遠不收費的保證。

Prepaid credit 也不能當成免費。Voyage FAQ 說預付需要付款方式，usage 先從 prepaid credits 扣除，超過購買的 credits 仍可能在月底計費；購買的 credits 還有有效期。主要 Agent 看到 balance 不足、payment required、invoice 或 auto-recharge 開啟時，應回傳 billing_review_required，而不是自動加值。

Embedding 的 query 與 document 分流

Voyage 官方建議 retrieval 任務明確設定 input_type 為 query 或 document。兩者會套用不同的後端提示，使 query vector 和 document vector 更適合配對；省略 input_type 會讓實驗失去可比性。學生每次建立索引都要保存 model、input_type、chunk rule、tokenizer version 和 embedding dimension，換模型後不能直接把向量混進同一個索引。

Embedding API 每次可送一個字串或一批字串，但不同模型有不同的 list、context 和 total token 限制。官方 reference 目前列出某些 lite 模型可到 1M tokens、一般模型 320K、large 或 domain model 120K 的單次總量。這些是單次 request boundary，不是每日免費量；gateway 要在本地先計算 token，超過就切批或交人工。

const apiKey = process.env.VOYAGE_API_KEY;
const model = process.env.VOYAGE_EMBED_MODEL || 'voyage-4-large';

if (!apiKey || !model) {
  throw new Error('Set VOYAGE_API_KEY and VOYAGE_EMBED_MODEL on the server');
}

const response = await fetch('https://api.voyageai.com/v1/embeddings', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model,
    input_type: 'document',
    input: ['只放入已批准的公開文件片段。']
  })
});

if (!response.ok) throw new Error(`Voyage embeddings failed: ${response.status}`);
const result = await response.json();
console.log(result.data?.[0]?.embedding?.length ?? result);

範例只示範 endpoint 形狀；VOYAGE_EMBED_MODEL 可用預設的 voyage-4-large，也可由當日 pricing、model capability 和 project allowlist 覆寫。產生向量後不要把整個原文和向量一起寫到公開 log；至少保存 document id、來源 URL、抓取時間、內容 hash、model 和 input_type。若資料被撤下，應能找到對應的 vector、cache、backup 和下游索引。

Rerank 的 token 計算

Voyage Reranker 的使用量不是單純把 query 和所有文件 token 相加。官方 Pricing 頁面目前把計算寫成「query tokens × documents 數量」再加上所有 documents 的 tokens 總和；目前通用敲門可先用 rerank-2.5，Pricing 列它每 account 首 200M tokens 免費，Rate Limits 基本值為 2M TPM／2,000 RPM。候選文件越多，單次 rerank 的計算量可能快速增加；先用 embedding 取小候選集合，再 rerank 前幾十份，比把整個 corpus 一次送入更容易控制免費量。

Reranker 也有模型 context 和請求數限制。學生要設定 top_k、max documents、query 長度、每份文件最大 token 和總 task budget；遇到長文件先切段或在本地摘要，不要讓 API 自動截斷後仍把結果當成完整證據。輸出的 relevance score 只代表排序訊號，不是事實正確性或授權判斷。

const apiKey = process.env.VOYAGE_API_KEY;
const model = process.env.VOYAGE_RERANK_MODEL || 'rerank-2.5';
const query = '公開資料中的主要結論';
const documents = [
  '已批准的公開文件片段 A，保留其來源標記。',
  '已批准的公開文件片段 B，保留其發布時間。'
];

if (!apiKey || !model) {
  throw new Error('Set VOYAGE_API_KEY and VOYAGE_RERANK_MODEL on the server');
}

const response = await fetch('https://api.voyageai.com/v1/rerank', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ model, query, documents, top_k: 2 })
});

if (!response.ok) throw new Error(`Voyage rerank failed: ${response.status}`);
const result = await response.json();
console.log(result.data ?? result);

範例中的文件必須先通過來源權利和資料分類檢查。rerank 結果回到主要 Agent 時，保留 document id、score、來源 URL 和查核時間；只把通過 score threshold 及人工規則的片段送到下一個生成模型。不要因為 score 最高，就把模型輸出直接發布或觸發外部工具。

Rate limits 與 organization budget

Voyage Rate Limits 頁面目前按模型列出 Basic TPM 和 Basic RPM，例如不同 embedding、multimodal 和 rerank model 的 TPM 不同，而 RPM 多數表格列為 2,000。organization 的 usage tier 會因付款方式或已付費 usage 升級，project 也可以設定不高於 organization 的子限制。文章中的數字只作查核快照，啟動前仍要回讀 dashboard 的 organization 和 project limits。

超過 rate limit 會收到 429。最安全的處理是平滑流量、降低 concurrency、使用 token-aware queue、等待 reset 和設定有限 exponential backoff。不要把 429 當成可以換一把 key 的訊號，也不要讓每個學生的 notebook 各自無限制重試。共享 organization 的額度時，主要 Agent 要保留課程預算和人工接手額度。

API key、project 與秘密管理

Voyage 官方 API Key 文件要求在 dashboard 建立 secret key，並建議使用環境變數；key 不應共享或暴露在瀏覽器與應用程式前端。學生不需要取得老師、同學或組織管理員的 key。若學校要提供受控 gateway，gateway 使用的 key 仍由管理者保管，學生只取得有限任務入口，不會看到 Authorization header。

Organization 與 project 可以分隔成不同課程、資料集或實驗。project member 的權限、API keys、usage、budget limits 和 rate limits 應按最小權限分配；課程結束後移除成員、停用 key、刪除不需要的 fixture 和索引。若 key 洩漏，先停止請求、在 dashboard 撤銷、檢查 usage，再建立替代 key，不以分享新 key 來維持工作。

資料保存與 zero-day retention

Voyage FAQ 目前說，Voyage-hosted model API endpoint 可以 opt out from storing and using data for future model training，並可做到 zero-day retention；但官方同時寫明要 opt out，必須 organization 有 payment method 且操作者是 Admin。這對免費學生帳戶很重要：不能假設自己已經 opt out，也不能把免費額度和資料訓練選項混成同一個設定。

在沒有確認 organization 資料設定前，主要 Agent 只送公開、去識別化或 synthetic data。禁止送出 API key、cookie、密碼、付款資料、健康資料、學生個資、未公開研究、公司機密或可觸發外部行動的秘密。若任務必須處理敏感資料，應停用免費 route，改用經批准的校內、自架或合約路線，並由管理者負責資料處理協議。

Batch API 與 Files API 的額外風險

Voyage Pricing 頁面目前明確寫出，Batch API 不適用 free token credits；成功處理的 batch tokens 會按適用的折扣 batch rate 計費。Files API 的檔案也有保存與刪除週期。學生不能因為 batch 比單次 API 便宜，就把它當成免費批次，或把含有私有內容的 JSONL 上傳後忘記清理。

如果課堂要練習 batch，先使用本地 synthetic JSONL 和 mock file lifecycle，再由管理者決定是否在付費 organization 做低量測試。Batch 任務要有明確 endpoint、model、completion window、input file id、成本估算、刪除時間和人工批准。免費路線的預設應是單次小批次，完成後回讀 usage 並停止。

429、401、402 與停止分流

Voyage provider adapter 不應把所有 HTTP error 都重試。401 應檢查 key 缺失或無效；402 應檢查 balance、付款與超額狀態；403 應檢查 organization、project 或權限；429 才是 rate limit 的等待分流；413、400 或 token context 錯誤要縮小輸入或修正參數。看到 billing error 時不得自動加值。

async function callVoyage(makeRequest, maxRetries = 2) {
  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
    const response = await makeRequest();
    if (response.ok) return response;

    if ([400, 401, 402, 403, 413, 422].includes(response.status)) {
      throw new Error(`Stop and review Voyage status ${response.status}`);
    }

    if (response.status !== 429 || attempt === maxRetries) return response;
    const waitMs = Math.min(10000, 800 * 2 ** attempt);
    await new Promise((resolve) => setTimeout(resolve, waitMs));
  }

  throw new Error('Voyage retry budget exhausted');
}

這段骨架只對 429 做有限退避，實際 adapter 還要讀 response headers、Retry-After、剩餘 task budget 和 organization status。若免費額度尚未耗盡但 endpoint 回傳 billing required，仍以帳戶狀態為準並交人工。不要因為一次失敗沒有扣 token，就無限重試；官方文件和課程帳本都要能說明請求是否真的被處理。

主要 Agent 的 Voyage RAG 工作流

推薦把工作流拆成九個可停點：來源 allowlist、內容權利檢查、chunk、token 預估、document embedding、向量檢索、query embedding、rerank、人工 citation review。每個停點保存 task id、model、input_type、token estimate、actual usage、來源 hash 和下一步。任何一步超過 free budget 或資料政策不明，就停止在該層，不把同一份資料偷偷轉送別家。

評估時至少使用有答案、無答案、相似錯誤、過期來源和被禁止來源五類 fixture。比較 embedding-only 與 embedding-plus-rerank 的 recall、precision、citation coverage、latency 和 token cost；最後再由人工判斷生成模型是否真的只引用允許片段。這會讓學生理解 Voyage 提供的是檢索訊號，不是事實保證。

當 free tokens 低於保留線，gateway 回傳 queued_until_review 或 fallback_to_local_index。fallback 不應自動選擇更昂貴的 model、加入付款方式或啟動 Batch API。若課程需要下一輪，保存非敏感 benchmark、模型與評估指標，等待新的合法預算或使用另一個已查核的 retrieval provider。

接入前的本機驗收

沒有真實 key 也能完成大部分驗收：測試 input_type 必填規則、單次 token 上限、query／document embedding 分流、rerank 計算公式、model allowlist、project budget、免費與付費狀態、429 退避、402 人工接手、資料拒絕、Batch API 拒絕和 API key 不進 log。用固定向量和分數 fixture 驗證 RAG citation，不需要消耗遠端額度。

真正 smoke 只能由有權限的持有人，在自己的 Voyage organization、低量、公開資料和清楚的非敏感實驗範圍內完成。Smoke 後回讀 project usage、free token balance、rate limits、payment state 和索引 provenance；如果資料 opt-out 需要付款方式而帳戶沒有，就維持公開／synthetic data 閘門。完成後只交接來源、規則、fixture 和結果摘要，不交接 key。

Tokenization 與 chunking 先於遠端請求

Voyage 官方提供 tokenizer 和 count_tokens 工具，讓學生在送出 embedding 或 rerank 前預覽實際 token。中文、程式碼、表格、URL 和多語內容不應只用字元數估算；同一段文字在不同 model tokenizer 下也可能不同。pipeline 應先以即將使用的 model 計算 token，保留一部分 headroom，再決定 chunk 大小、overlap、batch size 和 max documents。

chunking 不能只追求塞滿 context。過大的 chunk 會增加 embedding、rerank 和最終生成成本，過小的 chunk 會失去標題、表格欄位和上下文。學生可用固定的標題、段落、列表和表格規則切分，為每個 chunk 保存 parent document、section、position、URL 和 hash；重跑時先以 hash 去重，不要把同一來源重複向量化。

Multimodal pixels 的預算

多模態 embedding 的成本不只看文字。Voyage 官方目前把影像像素和影片像素換算成 token-like usage，並限制每個 input 的大小、每批 input 數與總 token。學生若把 PDF 頁面渲染成高解析圖片，可能在未注意時快速消耗 150B pixels 的免費上限；應先做縮圖、頁面選擇和本地去重，再送真正需要檢索的影像。

多模態 query 和 document 也要使用一致的 input_type 與模型版本。文字 query 對影像文件、影像 query 對文字文件都要在 benchmark 裡明確標記，避免把相容的向量空間誤解成所有任務都會同樣有效。圖片、影片或 base64 內容不應寫進公開 log；只保存非敏感 asset id、尺寸、hash、model 和 usage。

Project budget 與班級隔離

Voyage organization 是 rate limits、billing、budget 和 data controls 的上層；project 可以再限制成員、API key、usage、budget 和 model rate limit。班級不應讓所有學生共用 organization Admin。可以每個課程建立獨立 project，將學生限制為 Member，只給 read usage 和自己建立的 key，讓老師保留 budget、rate-limit 和成員管理權。

project budget 不是 token 本身的安全替代品。若免費量尚未耗盡，budget 仍要限制單一 task 的 input、output、documents、pixels、重試次數和並行數；若帳戶已進入付費狀態，budget 才能提供額外的美元停線。兩種 budget 都要在請求前檢查、在 response 後回讀，並由人工核對 dashboard。

Batch 與檔案的清理責任

Voyage Batch API 支援 embedding、contextualized embeddings 和 rerank，單批可以包含很多 request，但官方目前明確說 Batch API 不扣 free token credits。批次還需要上傳 JSONL 到 Files API，學生若只看到 completion window 和折扣，就可能誤以為它是免費路線。課堂先用本地 JSONL 和 mock file id，再由付費管理者批准任何真正 batch。

一旦使用 Files API，資料生命週期就多一層：input file、batch object、output file、metadata、失敗 request 和備份都要有刪除時間。JSONL 不應包含 API key 或超出課程目的的個資；custom_id 只使用不含身份資訊的 task id。作業完成後回讀 batch status，下載需要的非敏感結果，刪除不必要檔案並記錄清理證據。

Retrieval 品質與成本一起評估

學生報告不應只寫「向量搜尋成功」。每個 benchmark 要同時記錄 top-k recall、rerank NDCG 或人工相關性、citation coverage、輸入 tokens、rerank 計算量、latency、429 數量、單 task 免費量消耗和來源新鮮度。若 rerank 提升一點相關性卻讓每個 task 成本增加很多，就要把這個 trade-off 交給人工，而不是默認開啟。

可以用三種路線比較：本地 lexical search、Voyage embedding、embedding 加 rerank。每條路線使用相同的公開 fixture、相同的 query 和相同的人工 rubric，再觀察哪些錯誤是 retrieval 沒找到，哪些是生成模型讀錯。這樣學生會知道免費額度應該花在能改善證據品質的步驟，而不是盲目增加模型大小。

資料 opt-out 的人工門檻

Voyage FAQ 的資料設定特別需要人工核對：要選擇 zero-day retention 的 opt-out，官方目前要求 payment method 和 organization Admin；這不是學生在自己的 notebook 裡加一個 request header 就能完成的設定。課堂 manifest 應記錄 data-control status、設定查核人、查核時間和適用 organization；狀態不明時一律只送公開或 synthetic data。

即使資料已 opt out，也要把 provider data control 和來源內容權利分開。Voyage 控制的是它的 hosted model API data policy，不會替學生取得第三方網站、書籍、客戶文件或圖片的授權。來源 allowlist、robots、license、保存期間、向量刪除和回答引用仍由主要 Agent 的資料治理負責。

換 provider 時的索引移轉

Voyage embedding 換成另一家 provider 時，不能直接沿用原向量。不同模型的 dimension、tokenizer、input prompt 和語義空間都可能不同；所有 document vector、query vector、相似度 threshold 和 rerank score 都要重新建立。保留原始 chunk、provenance、hash 和 benchmark，才能在不重新抓取未授權來源的前提下做公平比較。

移轉清單要包括 model deprecation、free balance、付款狀態、project key、vector store schema、cache、索引版本、top-k、threshold、人工評估、刪除狀態和 fallback provider。若 Voyage 免費量用完，優先切換到已批准的本地 lexical index 或本地 embedding fixture；不要把原文直接送到未查核的「免費」服務。

這種索引移轉證據也能防止課程被單一 provider 綁住：來源和 chunk 保留在自己的受控環境，向量只是可重建的衍生物，評估集則用來確認新的模型沒有悄悄降低 citation 品質。換 provider 前後都要重新檢查資料政策和授權，不能只把 endpoint URL 換掉就宣稱完成。

因此，Voyage 的大額免費量應被用來學習檢索工程，而不是鼓勵無邊界的資料搬運。

學生真正帶走的能力，是把 token、向量、來源、權利、預算和人工驗收連成一條可以重播的安全管線。

這比單純追求更大的免費數字，更能支撐主要 Agent 的長期學習。

每一筆免費用量都應留下可查核的來源、模型和人工決策。

這樣，免費額度才會轉化成可重播、可交接、可停止的學習成果。

安全停止也是一種完成。

證據完整，燃料才值得持續使用。

可追溯。

可交接。

官方來源與查核方式

本篇的免費額度與模型單價以 Voyage Pricing 為核心；RPM／TPM、Tier 1 付款方式與 429 參照 Rate Limits；通用模型選擇與 voyage-4-large 建議參照 FAQ 與 Voyage 4 公告；程式碼 agent 的 voyage-code-4 參照 Voyage Code 4 公告；長文件 context embedding 參照 Voyage Context 4 公告；key 與秘密管理參照 API Key and Python Client；billing、免費 token 與資料 opt-out 參照 FAQ；organization／project 權限參照 Organizations and Projects；embedding endpoint 與 input_type 參照 Text embedding models；RAG 起步流程參照 Quickstart Tutorial。來源更新時，要重新查核 free tokens、model rows、batch 是否適用、付款和 opt-out 條件。

本篇目前只完成官方文件查核與本地 HTML 草稿驗收，沒有代替任何人建立 Voyage key，也沒有向 Voyage 發出真實 API 請求。若要延伸閱讀主要 Agent 的通用邊界，可參考 YOLO LAB AI Agent 常見問題。Voyage 的免費 embedding／rerank tokens 很適合建立有來源的 RAG 實驗，但可持續性來自精確的模型、用量、帳單、資料與停止管理，不來自把 key 交給全班。