IBM watsonx.ai Lite 300,000 tokens 怎麼用？學生 AI Agent 導流

IBM watsonx.ai Runtime Lite 是一個可以讓學生用合法本人帳戶取得 API 實驗額度的雲端方案。IBM Cloud 目前的服務目錄列出 Lite plan 每月 300,000 tokens／data points、20 CUH 與 100 pages 的免費配額；foundation model inferencing 會消耗 tokens。這不是一把可以公開分享的免費 API key，而是綁定 IBM Cloud 帳戶、region、project 和 IAM 權限的個人服務實例。

本篇的放行結論是：學生可以用本人 IBM Cloud 帳戶建立 watsonx.ai Runtime Lite，使用公開或 synthetic data 做小型 POC，並讓主要 agent 只讀取當日 plan、region、project、model 和用量狀態後再呼叫。這個方案適合學習 REST API、IAM、模型白名單與成本帳本，但不批准無人值守、付費 fallback、共用管理 key 或多帳戶輪換。

本系列只整理合法公開的免費 credits 與 API 入口，不代為註冊、不索取或分享他人的 API key、不用多帳戶規避額度，也不把 IBM Cloud 的帳戶 credits 說成永久 token fuel。若要先看所有 provider 都適用的憑證和資料原則，可延伸閱讀 AI agent 使用 FAQ。

當日敲門模型：openai/gpt-oss-120b

IBM 官方目前的supported foundation models把 openai/gpt-oss-120b 列為 watsonx.ai 可提供的第三方 foundation model，context window 131,072；但頁面也提醒模型 availability 會隨 data center 改變。它是本篇第一個文字 agent 敲門候選，實際使用仍須先讀回 region、project、model ID、Lite plan、當日價格與剩餘 tokens，不能把模型表當成所有帳戶的永久 allowlist。

若所在 region 沒有 openai/gpt-oss-120b，就從當日 Resource hub 或 foundation model specs 讀回清單中選一個已批准的文字模型；不要自動切到 on-demand deployment 或付費模型。Lite 的 300,000 tokens 是帳戶／服務 plan 的月度使用額度，模型名稱、價格與資料條款仍然要逐一確認。

Lite plan 的 300,000 tokens 與版本差異

IBM 現行 watsonx.ai Runtime 服務目錄的 Lite plan 寫明每月 300,000 tokens／data points，並註明 1 Resource Unit 等於 1,000 tokens 或 data points。這個數字是目前建立新服務實例時應優先讀回的官方 plan 證據；它不表示每個模型都能把 300,000 tokens 全部拿來生成文字，也不包含其他服務的計算、儲存或網路成本。

IBM 仍有較舊的 watsonx.ai FAQ 與 plan 文件顯示 50,000 tokens／month。這是本篇最重要的版本風險：搜尋摘要、舊文件、既有帳戶和新服務目錄可能不同。學生 agent 不得把文章內的 300,000 當作永久保證；啟用前要在當日服務目錄、帳戶 plan、usage dashboard 和 API response 中完成 read-back。若 read-back 只顯示 50,000 或顯示沒有免費 inferencing，就按較小值或停止。

300,000 也不是一個能直接轉送給別人的 token 庫。免費 plan 屬於某個 IBM Cloud account 下的 service instance，可能受 region、帳戶資格、服務可用性、模型 access 和 plan 更新影響。學生要保存查核日期、服務名稱、region、plan snapshot、剩餘 usage 與最後一次成功 read-back，而不是把固定數字寫進 gateway 設定後長期相信。

免費額度的預算與 reserve

對主要 agent 來說，最安全的第一步不是把整個免費 plan 填滿，而是先切出 reserve。例如讀回當月 300,000 tokens 時，可以由帳戶持有人決定只批准其中一部分給課堂，留下足夠的人工查錯和版本遷移空間。這個 reserve 是本地治理數字，不是 IBM 的額外配額；實際 plan 變小時要立即跟著變小。

本地預算還要分成探索、驗證和正式課堂三個桶。探索桶只允許短 prompt、低 max tokens 和少量任務；驗證桶用來比較兩個已批准模型或檢查 SDK 變更；正式課堂桶才供學生完成作業。任何一個桶耗盡都應回傳明確的 STOP 狀態，而不是從另一個帳戶偷挪配額。

一個大型 context 的請求可能同時消耗很多 input tokens 和 output tokens，並且在 agent 迴圈中重複傳送 system prompt、工具描述與歷史訊息。學生可以先壓縮歷史、限制工具 schema、截斷不必要的文件和設定低輸出上限，但不能只把 UI 上的字數當成 token 成本。每次優化後都要用 response usage 和 dashboard 做交叉核對。

如果任務需要長文件、圖片、embedding、rerank 或 on-demand deployment，應另開成本評估，不把它們偷偷塞進文字 token 預算。Lite catalog 的 300,000 tokens／data points、20 CUH 和 100 pages 是不同計量欄位；一個欄位用完，不代表其他欄位可以互相兌換，也不代表周邊服務自動免費。

課堂管理者每次開課前至少做一次 plan、region、model 和 usage read-back，課後記錄消耗與停止原因。若 IBM 更新 catalog、FAQ、模型或價格，先建立新的小型基線，再決定是否繼續；不要用上一期的 300,000 或 50,000 直接覆蓋新一期的服務狀態。

免費方案與付費服務的分界

IBM Cloud credits、watsonx.ai Runtime Lite 和其他 IBM service plan 可能同時出現在同一個帳戶，但它們不是同一個燃料池。帳戶收到的 onboarding credit、Lite instance 的月度 tokens、模型 inferencing 的 Resource Units，以及 Object Storage、Cloud Functions、網路或監控資源的費用，都要分開記錄。文章裡說「免費」只指被官方明確標示的那個 plan。

當模型不在 Lite 的立即推理範圍、需要 deploy on demand、需要更大的 context、需要額外 region 或要求付費服務時，主要 agent 不應自行切換。可以保存需求、估算費用並通知帳戶持有人，但不能把付款同意藏在 fallback 程式碼裡。這個分界也讓學生知道 API 故障和付款決策是兩種完全不同的事件。

同樣地，免費 plan 不等於可以用短期 token 來迴避 IBM Cloud 的權限。IAM access token 只是在正常權限下的暫時憑證；它不能延長 quota、解除 model access、穿越 401／403 或把別人的 project 變成自己的。遇到權限問題要回到帳戶管理者和官方文件，不要把錯誤變成輪換 key 的理由。

主要 agent 也不應根據剩餘 token 自動決定一個更昂貴的模型。模型 allowlist、用途和資料分類應在請求前固定；若估算會超過 reserve，回傳人工審核。這種「先批准、後執行」的順序比使用完免費配額後才發現請求已經進入付費 tier 更容易追蹤。

學生使用時的資料與輸出檢查

學生第一次測試時，可以用自己撰寫的短句、公開新聞標題、合成的 JSON 或公開授權的小段文件。先驗證請求格式、回應結構、usage 欄位和錯誤分類，再逐步加入工具呼叫或多輪歷史。不要為了證明 API 能用，就把真實客戶資料、私人對話或未公開作業貼進 prompt。

輸出驗收要分成格式、事實和安全三層。格式檢查 JSON、欄位、長度和 stop reason；事實檢查來源、日期、計算和引用；安全檢查是否洩漏輸入、產生危險建議或把未知內容說成確定。模型能回應，不等於結果已經適合交作業、發布或交給下游 agent。

若 prompt 需要處理同學姓名、email、學號或作業內容，先把它們替換為匿名代號和合成值，並確認課程規範允許使用外部雲端服務。若資料無法去識別化，最簡單的免費方案也不是合適的地方。免費 credits 不會降低隱私義務，也不會替使用者取得學校或客戶的授權。

錯誤 log 也要當成資料輸出管理。只保存 status、provider request ID、region、model ID、時間和去識別化的錯誤分類；不要把回應 body 原封不動寫入公開 CI、聊天室或 issue。若回應可能含有秘密，立即停止傳播並按帳戶管理者的撤銷流程處理。

可持續的課堂交接

交接時只交付 provider 名稱、服務 plan、region、approved model、API version、剩餘 usage 的級距、資料同意狀態、最近 read-back 時間和停止規則。不要交付 API key、IAM token、cookie、付款資料或可以重新取得它們的截圖。下一位管理者先重新驗證帳戶，再接受上一期的帳本。

如果服務被刪除、plan 變更、模型下架或 FAQ 與 catalog 再次出現差異，交接狀態應改成 REVERIFY_REQUIRED，不是自動重建。這個狀態讓系列文章可以一篇一篇持續更新，也讓學生看到 provider 變動時應該重新查核，而不是追逐一串不明來源的 token。

最終要留下的是可重現的最小測試、清楚的用量紀錄和可回復的停止點。只要沒有帳戶授權、最新 plan read-back 或合法資料，就不執行 live request。這個節奏雖然比直接把 key 貼給 agent 慢，卻能讓免費額度成為學生的學習燃料，而不是不可審計的共享秘密。

IBM Cloud 帳戶與付款護欄

IBM Cloud 的免費 Lite／Free 導覽目前要求建立帳戶時提供付款卡作身份驗證，並把新帳戶設成 Pay-As-You-Go；官方同頁另寫明新帳戶可得首 30 天使用的 USD 200 credit。這不等於所有服務都永遠不收費，也不等於可以在主要 agent 裡自動動用 credits。付款卡、帳戶身份和付款計畫都由本人決定，本篇不代註冊、不代綁卡、不代升級。

watsonx.ai Runtime Lite 本身標為 Free，但 IBM Cloud 的帳戶級 Pay-As-You-Go 狀態仍要單獨確認。建立服務前先檢查 catalog 的 pricing plan、region availability、是否有必要的 Cloud Object Storage 或 project 資源；任何提示要 upgrade、增加 quota、建立付費 instance、部署 on-demand model 或接受額外 EULA，都要停下來交給帳戶持有人。

服務若 30 天沒有開發活動可能被刪除，這類 inactivity policy 和 token usage 是兩個不同狀態。學生不應為了保留免費 quota 而製造無意義請求，也不應透過刪除、重建或多帳戶方式試圖刷新配額。真正可持續的做法是低頻使用、保存帳本、到期或不符合條件時正常停止。

Region、project 與模型 read-back

watsonx.ai API endpoint 按 region 區分，例如 Dallas 是 https://us-south.ml.cloud.ibm.com，Frankfurt 是 https://eu-de.ml.cloud.ibm.com。官方 region 文件指出 foundation model inferencing 與 Prompt Lab 並非每個 data center 都可用；因此不能只複製別人的 hostname。主 agent 每次啟動要把帳戶批准的 region 和 endpoint 做精確比對。

REST API 需要 project 或 space ID、IBM Cloud IAM bearer token、model ID，以及每次請求的 version date。官方 REST API 文件要求指定 model ID；模型清單可以由 GET /ml/v1/foundation_model_specs?version=YYYY-MM-DD 讀回。這個清單才是當日可用模型的證據，不能因為網路文章提過 Granite、Llama 或 Mistral 就假設自己的 region 一定可以呼叫。

function assertWatsonxLiteState(state, now = Date.now()) {
  if (state.plan !== 'LITE') throw new Error('watsonx.ai Lite plan is not verified');
  if (!Number.isFinite(state.tokensRemaining) ||
      state.tokensRemaining <= state.reserveTokens) {
    throw new Error('watsonx.ai free token reserve is too low');
  }
  if (!state.approvedRegions.includes(state.region)) {
    throw new Error('watsonx.ai region is outside the allowlist');
  }
  if (!state.approvedModels.includes(state.modelId)) {
    throw new Error('watsonx.ai model is outside the allowlist');
  }
  if (state.paidFallbackAllowed === true) {
    throw new Error('Paid fallback is not approved');
  }
  if (state.checkedAt + state.maxReadbackAgeMs < now) {
    throw new Error('watsonx.ai dashboard read-back is stale');
  }
}

這些欄位是本地安全策略，不是 IBM Dashboard 的欄位名稱。tokensRemaining 必須由人工或受控的帳戶讀回填入，不能從 300,000 倒推；approvedModels 也必須隨 API 模型清單更新。若 plan、region、model 或 read-back 任一項不明，主要 agent 應拒絕請求。

API 相容性與最小化設計

watsonx.ai 有 text generation、text chat、embeddings、rerank 和 agent 相關 API，但「有 API」不代表每個 Lite 實例都開通所有方法。先選一個課堂目標，再只啟用必要 endpoint，可以減少權限、資料和成本範圍。例如只做文字摘要，就不需要建立向量庫、部署自訂模型或開啟額外的資料連線。

OpenAI 相容的工具或 SDK 可能讓請求看起來很熟悉，但 endpoint、header、project ID、model ID、version date 和 usage 欄位仍以 IBM 文件為準。不要因為某個 client 接受 baseURL 和 apiKey，就假設可以把 IBM IAM token、模型名稱和 OpenAI 的參數完全混用。

每一個 adapter 都應保存 provider schema 的版本，並把未使用的參數排除。工具呼叫、JSON schema、stream、multimodal content 和 system message 可能需要特定模型或 API version；第一次實驗先用單輪純文字，再逐項加入功能。這樣遇到 400 時能知道是 payload 問題，而不是把整個免費帳戶判斷成失效。

模型的 context window 也要視為 read-back 欄位。輸入太長時，API 可能截斷、回 400、消耗大量 tokens 或讓輸出品質下降。gateway 應在送出前限制 prompt、歷史、工具描述和預期 output，並在超過本地上限時直接拒絕，不讓 provider 用昂貴或不透明的方式替學生做截斷。

Region 也會影響延遲、可用模型、資料處理位置與課堂測試結果。學生換電腦或換 SDK 時，不能只搬移 model ID；必須一起搬移 approved endpoint、project、版本、資料分類和最後一次 smoke 證據。若使用不同 region，應視為新的候選環境重新驗收。

streaming 能改善互動感，但會增加中斷、部分輸出保存和重試判斷的複雜度。免費燃料的第一個版本先使用非 streaming response，等到 usage、撤銷和錯誤狀態都能正確記錄，再由人工批准 streaming。不要為了看起來更快而犧牲完整的成本與安全證據。

相同的 prompt 在不同 model、API version、region 或 tokenizer 下可能得到不同 usage 與答案。學生做比較實驗時要固定輸入、輸出上限、temperature、模型、region 和查核時間，並保存去識別化結果。否則看似節省 tokens 的改動，可能只是把較短的輸出或較弱的模型當成效率提升。

所有 provider adapter 都應提供 dry-run 模式。dry-run 只檢查 plan、secret 是否存在、model allowlist、資料分類、預算和 endpoint，不發出網路請求；live 模式才允許一次短 synthetic smoke。文章中的程式碼故意將兩者分開，讓學生先學會驗收，再學會呼叫。

IAM key、短期 bearer token 與秘密保存

IBM Cloud API 以 IAM 驗證。官方文件說 API key 可以換取 IAM access token，而 IAM token 最長有效 60 分鐘；API 請求再以 Authorization: Bearer 傳送。短期 IAM token 比把長期 API key 放進 agent runtime 更容易限制風險，但 token 仍是秘密，不能出現在前端、Git、公開 notebook、Issue、聊天、log 或模型 prompt。

IBM 也提醒 API key 不會自動過期，應採最小權限、放在環境變數或 secret store、定期撤銷與輪換。這裡的輪換是本人帳戶的正常憑證管理，不是拿來增加免費額度；同一帳戶建立更多 key 不會讓 Lite plan 變大。學生 gateway 只保存匿名帳戶代號、key 狀態和 token 到期時間，不保存 key 原文。

async function getIamToken() {
  const apiKey = process.env.IBM_CLOUD_API_KEY;
  if (!apiKey) throw new Error('IBM Cloud API key is missing');
  const response = await fetch('https://iam.cloud.ibm.com/identity/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'urn:ibm:params:oauth:grant-type:apikey',
      apikey: apiKey
    })
  });
  const data = await response.json().catch(() => ({}));
  if (!response.ok || typeof data.access_token !== 'string') {
    throw new Error(`IBM IAM token request failed: ${response.status}`);
  }
  return { token: data.access_token, expiresIn: data.expires_in ?? 3600 };
}

這是沒有真實 key 的示意，工作區沒有對 IBM Cloud 做 live smoke。生產流程不應把原始 API key 交給每位學生；若課程需要多人使用，應由帳戶持有人建立受限的 server-side gateway，再以本地學生配額分流。課程結束後刪除或撤銷不再使用的 key，並清理失效 IAM token。

最小 text chat 請求

watsonx.ai API 同時支援 text generation、text chat、REST、Python library 和 Node.js SDK。本系列的學生 agent 先選 text chat，因為請求可以把 model ID、project ID、messages、max tokens 和 temperature 放在同一個可審計 payload。version date 必須改成當天查閱並測試的日期，不要複製多年以前的固定版本。

async function callWatsonxLite(prompt, state) {
  assertWatsonxLiteState(state);
  const token = process.env.IBM_WATSONX_IAM_TOKEN;
  if (!token) throw new Error('IBM watsonx IAM token is missing');

  const url = `https://${state.region}.ml.cloud.ibm.com/ml/v1/text/chat?version=${state.apiVersion}`;
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
      Accept: 'application/json'
    },
    body: JSON.stringify({
      model_id: state.modelId,
      project_id: state.projectId,
      messages: [{ role: 'user', content: [{ type: 'text', text: prompt.slice(0, 1800) }] }],
      max_tokens: 160,
      temperature: 0.2
    })
  });

  const data = await response.json().catch(() => ({}));
  if (!response.ok) {
    throw Object.assign(new Error(`watsonx HTTP ${response.status}`), {
      status: response.status,
      data
    });
  }
  return data;
}

這段程式碼只顯示結構，不代表已經有 IBM Cloud 帳戶、project、model access 或可用 token。真正 smoke 前，先用 API 文件與當日 Developer access 讀回 host、project ID、region、version、model ID 和 plan；再使用一個很短的 synthetic prompt。不要把完整回應或原始 prompt 寫入長期 log。

token 帳本與免費額度估算

IBM 以 input 加 output 的 tokens 計算文字推理用量；一次請求的 max_tokens 是輸出上限，不是一定會消耗的數量。學生帳本至少記錄匿名 task ID、region、model ID、API version、estimated input tokens、actual output tokens、HTTP status、請求前後 read-back、retry count 和時間。不要把 300,000 寫成每個學生可支配的個人餘額。

如果 response 提供 usage，就以回應的 input、output 或 generated token 欄位作請求級證據；如果當日 API 不提供同樣欄位，就用 conservative estimate 並在 dashboard 做帳戶級核對。模型 tokenizer、system prompt、工具描述與輸出格式都可能影響用量，中文字數或請求次數不能取代 token read-back。

function recordWatsonxUsage(ledger, event) {
  const safe = {
    taskId: String(event.taskId),
    modelId: String(event.modelId),
    region: String(event.region),
    status: Number(event.status),
    inputTokens: Number.isFinite(event.inputTokens) ? event.inputTokens : null,
    outputTokens: Number.isFinite(event.outputTokens) ? event.outputTokens : null,
    estimatedTotal: Number.isFinite(event.estimatedTotal) ? event.estimatedTotal : null,
    tokensRemaining: Number.isFinite(event.tokensRemaining) ? event.tokensRemaining : null,
    retryCount: Number.isFinite(event.retryCount) ? event.retryCount : 0,
    recordedAt: new Date().toISOString()
  };
  ledger.push(safe);
  return safe;
}

本地 ledger 故意不包含 API key、IAM token、姓名、email、完整 prompt 或完整輸出。若要向 IBM 支援回報，應由帳戶持有人依官方流程提供最小必要的 request ID、時間、region 和 HTTP status。帳本是成本與學習證據，不是把秘密備份到文章或 agent 的方法。

模型、語言與 agent 適用範圍

watsonx.ai 會提供 IBM Granite 和部分第三方 foundation models，但官方說模型可用性會按 data center 變化。每個模型有不同 context window、語言、EULA、輸出品質和價格；免費 plan 的 token 數不會消除這些差異。學生可以先從當日可讀回、內容安全審核過的低成本文字模型開始，不要讓使用者輸入自由指定任意 model ID。

本篇適合短問答、摘要、格式轉換、公開文件分類和 agent protocol 練習。它不適合把私密知識庫、未公開產品規格、個資、醫療紀錄、付款資料、密鑰或公司原始碼直接送到課堂服務。模型輸出只是輔助，不是事實真相；醫療、法律、金融、身份判斷或教育評量仍須人工審核。

資料安全、模型條款與最小資料原則

IBM watsonx.ai FAQ 說明帳戶工作和模型資料對帳戶私有，並提供資料安全與加密說明；foundation model terms 同時提醒第三方模型有各自的 provider、license、偏誤與不準確風險。學生仍要逐一查閱當日服務條款、模型卡和所在 region 的資料規則，不能用「IBM」三個字推論所有模型都具有相同的資料政策。

送出前先做資料分類：公開內容可以進入 synthetic smoke；去識別化資料要確認帳戶政策與課程授權；個資、秘密、未公開作業和公司程式碼一律留在本地。若 prompt 中意外出現 API key、cookie、access token 或身份資料，立即停止該任務、撤銷受影響憑證、不要把內容貼到錯誤報告。

429、401、403 與付費風險的停止流程

• 401：IAM token 缺失、過期或無效；停止，重新由本人 secret store 取得短期 token，不把原始 key 寫入 log。
• 403：project、region、IAM policy 或 model access 不足；停止，不改用別人的 project、不猜測權限、不輪換帳戶。
• 404：endpoint、model ID 或 project 不存在；回到官方 model／Developer access read-back，不盲試替代模型。
• 429／503：只在已批准低頻範圍做有限 backoff；未知是否已計費或狀態不明時停止，不用平行請求穿過限流。
• quota、plan 或 billing 警告：標記 STOP_FREE_PLAN_REVIEW，不自動 upgrade、不自動付款、不啟用 paid fallback。

function classifyWatsonxFailure(error) {
  const status = Number(error?.status);
  if (status === 401) return { action: 'STOP_REFRESH_IAM_TOKEN', retry: false };
  if (status === 403) return { action: 'STOP_REVIEW_PROJECT_REGION_ACCESS', retry: false };
  if (status === 404) return { action: 'STOP_REVIEW_MODEL_OR_ENDPOINT', retry: false };
  if (status === 429 || status === 503) {
    return { action: 'LIMITED_BACKOFF_OR_HUMAN_REVIEW', retry: true };
  }
  return { action: 'STOP_UNKNOWN_WATSONX_FAILURE', retry: false };
}

分類器只是本地 policy 範例，不能取代 IBM 的錯誤 body、帳戶 billing、usage dashboard 或人工判斷。尤其是 429 可能代表模型過載，並不一定是免費額度用完；credits、rate limit、IAM、model access 和付費狀態必須分開記錄。

多人課堂與主要 agent 的邊界

若多位學生要學習同一個 provider，安全做法是每人用自己的合法帳戶或由帳戶持有人明確管理的一個 server-side gateway；不把管理 key 貼在群組、不把 IAM token 交給模型、不讓學生自行修改 model、region、project 或 billing policy。gateway 只分配本地任務額度，IBM plan 的真實餘額仍由帳戶持有人核對。

主要 agent 的 provider adapter 應先驗證 plan、region、project、model、read-back age、reserve、資料分類和 paid fallback 開關，再送一次短請求。任何一項失敗就回傳人工接手狀態，而不是偷偷改 provider、改帳戶或重新註冊。學生學到的是可移植的燃料治理：能用時按量用，不能用時有清楚停機原因。

申請與驗收順序

1. 由本人閱讀 IBM Cloud 帳戶、watsonx.ai Runtime Lite、region、模型條款與資料政策，確認付款方式和帳務風險可接受。
2. 在當日 catalog 建立符合條件的 Lite service instance 和 project，不建立 on-demand deployment，不升級付費方案。
3. 讀回 plan、token／data point quota、CUH、pages、region、project ID、可用模型、endpoint 和 version date；舊 FAQ 與現行 catalog 不一致時採較小值或停止。
4. 用最小權限建立 API key，交換短期 IAM token；key 只進 server-side secret store，不能進文章、前端或 log。
5. 以 synthetic prompt 做一次短 smoke，記錄 response status、usage、request ID 和前後 read-back；若遇 billing、權限或未知狀態，立即停止。
6. 課程結束撤銷不再使用的 key，保存去識別化帳本和查核日期，不分享可重建憑證的內容。

本篇截至 2026-08-24 完成官方文件查核與本機草稿驗收，沒有進行 IBM Cloud 註冊、付款驗證、建立 service、建立 key、取得 IAM token 或 live API smoke。這個限制是刻意的：工作區沒有得到一個可用的 IBM Cloud 帳戶授權，也不應為了文章替任何人產生或保存憑證。

本篇的學生 agent 決策

IBM watsonx.ai Runtime Lite 可以列入「有帳務護欄的學生 POC」清單，不能列入「永久免費、可共享、可自動補充」清單。300,000 tokens 是目前官方 catalog 的服務 plan 數字，必須和帳戶當日 read-back 一起使用；舊文件顯示 50,000 的差異則要固定寫進驗收規則。只要付款、region、model access、資料政策或 quota 狀態不明，就停止而不是繼續捕獲下一把 token。

對主要 agent 而言，最有價值的不是一個大數字，而是能在每次呼叫前知道自己為何可以用、用了多少、何時必須停，以及誰有權恢復。這比把免費帳戶的 key 散落在學生之間更能支撐長期學習。

課堂實驗的最小驗收

課堂第一個練習可以只要求學生讀取官方 plan，寫出自己的配額判斷，不立即呼叫模型。學生要說明 300,000、50,000、20 CUH 和 100 pages 分別代表什麼，哪些數字可能屬於舊文件，哪些數字必須從帳戶重新讀回。

第二個練習是建立模型白名單。學生從當日 API model list 選一個可用模型，記錄 model ID、region、context window、資料條款和估計成本，再讓 agent 拒絕不在白名單的 model。這能把「模型能不能用」從猜測變成可檢查的證據。

第三個練習是用 synthetic prompt 做一次短請求。輸入只包含公開的虛構資料，輸出上限保持很低，回應只保存 status、usage 和匿名 request ID。學生要能指出請求用了哪個帳戶、哪個 region、哪個 project，以及如何確認沒有觸發付費 fallback。

第四個練習是故意讓 IAM token 過期，觀察 401 的停止處理。學生不能把原始 key 貼進錯誤訊息，也不能建立大量新 key 盲試；正確答案是重新取得受控的短期 token，確認最小權限，再重跑一次窄範圍 smoke。

第五個練習是模擬額度不足。當本地 reserve 低於門檻時，adapter 應在網路請求前停止並回報原因；它不能等 provider 回錯誤後才猜測，也不能自動從另一個帳戶繼續。這個練習讓學生理解預算閘門比事後補救更可靠。

第六個練習是比較短 prompt 與長歷史的 usage 差異。固定 model、region、temperature 和 output 上限，只改變輸入長度，再把 response usage 和 dashboard 總量分開記錄。學生會看到相同請求次數不代表相同 token 消耗。

第七個練習是資料分類。把一段文字標成公開、合成、去識別化或禁止送出，讓 gateway 在請求前做判斷。若文字含有學號、email、秘密、cookie 或未公開作業，測試應該直接失敗，而不是依賴模型自己忽略敏感內容。

第八個練習是 provider 版本漂移。學生把舊 FAQ 的 50,000 與現行 catalog 的 300,000 並排，說明為何不能選較大的數字當作保證。任何文件差異都要記錄來源、查核日期和採用的保守值，等待帳戶持有人重新確認。

第九個練習是區分 API 故障和帳務決策。401、403、404、429、503、quota 警告和 upgrade 提示要進入不同狀態；只有有限的 429／503 backoff 可以自動化，其餘都要人工接手。這避免 agent 把所有錯誤都變成重試或付費。

第十個練習是撤銷與交接。課程管理者撤銷測試 key，清理短期 token，留下沒有秘密的帳本，下一位管理者再完成自己的 plan 和 model read-back。只要新管理者沒有重新確認，就維持停止狀態，不以截圖或舊報告代替現況。

這十個小練習比要求學生一次做出完整 agent 更容易驗收，也更能培養可持續的使用習慣。免費 API 的價值不只在能否產生文字，還在學生能否安全地估算、限制、記錄、停止和交接。

因此，本篇把 IBM watsonx.ai Runtime Lite 放在候選燃料層，而不是核心燃料層。只有當官方 plan、帳戶資格、地區、模型、資料政策和用量都通過新一輪查核，才允許主要 agent 做小量 synthetic 任務；任何一項失效，都回到候選狀態。

驗收報告還要標示觀察窗口，而不只標一個完成時間。plan、usage、模型和付款狀態會在之後變動；今天成功的 smoke 只能證明今天的窄範圍請求，不代表下一週仍可使用。若要長期供課堂使用，應設定定期重查，而不是把一次成功當成永久授權。

學生交作業時，可以提交 adapter 的狀態摘要、去識別化 ledger、使用的官方文件日期和停止測試結果，不提交任何 key 或 token。老師要看的是學生能否說清楚請求邊界、配額來源、資料類型、錯誤處理和人工接手點，而不是誰在共享群組找到一把可用的秘密。

如果同一個班級共用一個合法 gateway，gateway 仍要把每個任務分配到本地匿名代號，限制每人的輸入長度、輸出上限、併發和每日預算。管理者看到總 usage 時，能回溯到任務而不是猜測哪位學生耗盡額度；學生也不能看到或重建其他人的憑證。

免費方案的錯誤處理必須可重播但不可重送敏感內容。重播只保存請求的結構、模型、狀態和合成輸入；如果原始請求可能帶有個資或秘密，就不能直接重送。必要時先撤銷憑證，再在清理後的 synthetic case 上重現問題。

Agent 也應知道「沒有回答」是一個合法結果。當 plan 過期、reserve 不足、region 不符、model 未批准、IAM 過期或資料不准外送時，回傳停止碼比產生一段看似合理但未經授權的內容更好。這是把免費燃料當成受治理資源，而不是把它當作一定要消耗完的獎品。

版本差異也要納入文章維護。當 IBM 更新 plan、API version、model ID 或條款時，先在本機建立新查核段落，保留舊證據和失效原因，再決定是否更新草稿。不要直接用搜尋摘要覆蓋全文，因為摘要可能同時混有舊 FAQ 和新 catalog 的數字。

若未來要把這個 provider 接入主要 agent，應另立小型 canary：固定一個 approved model、固定一個 synthetic prompt、固定一次請求、固定讀回欄位，再由獨立 verifier 檢查帳本、錯誤和停止策略。canary 成功後也只批准窄範圍，不自動擴成全班或全站流量。

這種逐篇介紹、逐篇驗收、逐篇更新的節奏，可以讓學生看見每個 provider 的差異，也能讓主要 agent 保持可替換。當 IBM 的免費 plan 不再適合時，adapter 可以安全停下，下一篇再評估新的官方候選，而不是靠私人 key 硬撐。

IBM 官方查核入口

• watsonx.ai Runtime 服務目錄與 Lite plan
• IBM Cloud Lite／Free 帳戶導覽
• watsonx.ai REST API 前置條件
• watsonx.ai API reference
• IBM Watson IAM 認證與 API key 安全
• 取得可用 foundation models
• watsonx region availability
• watsonx.ai FAQ、免費試用與資料說明
• foundation model terms of use
• supported foundation models

下一篇會從官方文件重新挑選候選，不會因為 IBM 的 300,000 數字就自動把它升格成主要 agent 的永久燃料。