Hugging Face 免費 credits 怎麼用？用 Inference Providers 開始學生 AI Agent

Hugging Face Inference Providers 適合當作學生 AI Agent 的第五種燃料。它把 Hugging Face Hub 上的模型與多個 inference provider 接在同一個路由層後面，學生可以用一個 Hugging Face User Access Token 練習文字生成、聊天、embedding、分類、影像與其他模型任務，也可以比較不同 provider 的速度、價格與格式支援。

但這裡的「免費」不是一組永遠免費的 token。Hugging Face 官方 Inference Providers pricing 頁目前列出 Free Users 每月 0.10 美元 credits，並明確標示金額可能變動；PRO 使用者與 Team／Enterprise organization 另有不同額度。Credits 是金額額度，不是固定 token 數，因為不同模型、provider、輸入輸出長度與任務會有不同價格。

本文的安全邊界也很重要：由 Hugging Face routed 的請求才會使用 Hugging Face monthly credits；如果在 Hugging Face 設定中放入自己的 custom provider key，請求會由 provider 直接計費，並不套用這筆 Hugging Face credits。因此主 Agent 不應收集多家 provider 的私人 key，也不應把「切換 provider」當成免費額度倍增器。

當日敲門模型：用 GPT OSS 120B 測試路由，再查 provider 免費狀態

Hugging Face 當日 Inference Providers 文件以 openai/gpt-oss-120b 作為聊天模型示範，並把預設 provider selection 說明為 provider="auto"／:fastest；需要成本優先時可以查 :cheapest，需要固定偏好時再用 :preferred。這些是路由選擇政策，不等於模型本身或每個 provider 都免費。

主要 Agent 在把它放進學生 allowlist 前，應先讀 /v1/models 的 provider mapping：確認 provider status 是 live、任務與工具能力符合、價格欄位可讀，並在有提供時檢查 is_free。只有由 Hugging Face routed 且當月 credits 足夠的請求才可進入免費 canary；若 mapping 變成 error、provider 不再免費或 credits 不足，就停止，不用 custom provider key 補洞。

Hugging Face Inference Providers 的免費額度長什麼樣

官方 pricing 頁目前的表格是：Free Users 每月 0.10 美元、PRO Users 每月 2.00 美元、Team 或 Enterprise Organizations 每席每月 2.00 美元；後兩者不是學生免費帳戶的同一條件。對本系列來說，最重要的是 Free User 那一列旁邊的 subject to change，以及額度用完後若要繼續使用需要購買 credits。

這筆 0.10 美元不能直接換算成「每天幾次」或「幾千 token」。同一個模型可能有不同 provider，provider 的 input、output、context、工具支援與即時價格也可能不同。學生 Agent 應在送出前查模型與 provider mapping，送出後記錄實際 provider、用量與費用摘要；不要把一次成功的短 prompt 推廣成固定配額承諾。

Credits 也可能被 Hugging Face Hub 上的其他 Inference Providers 功能使用，例如模型頁的 inference widget、Inference Playground 或 Data Studio AI。若學生只看自己的 API 呼叫，卻忘記同一帳戶在瀏覽器上測試過模型，可能會低估月度消耗。課程帳本應把互動測試與程式請求放在同一個帳戶用量範圍內。

先選 Hugging Face routed requests

官方把使用方式分成兩條路。Routed by Hugging Face 是預設適合初學者的路徑：請求經過 Hugging Face，再送到符合條件的 provider；不需要另外建立 provider 帳戶，monthly credits 可套用在符合條件的請求。Custom Provider Key 則是使用者自己在 provider 開戶、在 Hugging Face 設定 key，請求由 provider 直接計費，不使用 Hugging Face monthly credits。

學生 Agent 的初始政策應該只允許 routed requests。這樣 adapter 可以只管理一個 Hugging Face token、一本模型與 provider allowlist，以及一個統一的用量帳本。若課程日後真的需要某個 provider 的專屬功能，應由管理者建立獨立的付費政策與秘密管理邊界，不要讓學生在同一個 prompt 中輸入 provider key。

建立 read 或 fine-grained User Access Token

Hugging Face 官方 token 文件把 User Access Token 視為應用程式或 notebook 的主要認證方式。建立 token 的入口是 Hugging Face 帳戶設定中的 Access Tokens，再選 New token。若只需要讀取 Hub 內容或呼叫 inference，官方說明可使用 read token；若需要更窄的資源範圍，則使用 fine-grained token。

read token 不代表可以把完整帳戶權限交給每個學生。對主 Agent，最好為不同應用程式建立不同 token；若使用組織的 gated model 或私有 repository，再由組織管理者審查細粒度權限。token 必須可撤銷、可重新建立、不可出現在前端、Git、課程投影片、錯誤 log 或聊天記錄中。

export HF_TOKEN='YOUR_HUGGINGFACE_TOKEN'

curl --fail-with-body -sS \
  "https://router.huggingface.co/v1/chat/completions" \
  -H "Authorization: Bearer ${HF_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-120b",
    "messages": [
      {
        "role": "user",
        "content": "請把這段公開課程介紹整理成三個重點，並標出需要人工查證的地方。"
      }
    ],
    "max_tokens": 160
  }'

這段範例只把 token 放在環境變數，實際值是佔位符。模型 ID 只是示範目前文件中出現的 chat-completion 模型，不是永久保證；執行前應查 Hugging Face 的模型頁與 provider mapping，確認它目前有 live provider、支援 chat completion、符合課堂資料政策，並且沒有超出你的 credits。

先查模型與 provider mapping 再呼叫

Inference Providers 的模型目錄會變動，所以不要把模型名稱、provider 名稱與價格永久寫死在主 Agent。官方 Hub API 提供 OpenAI-compatible 的 /v1/models 路由，可以列出由 Inference Providers 提供的 chat-completion models 與 provider metadata；也可以在特定模型的 Hub API 回應中查 inferenceProviderMapping。

curl --fail-with-body -sS \
  "https://router.huggingface.co/v1/models" \
  -H "Authorization: Bearer ${HF_TOKEN}" \
  -H "Accept: application/json"

curl --fail-with-body -sS \
  "https://huggingface.co/api/models/google/gemma-3-27b-it?expand=inferenceProviderMapping" \
  -H "Authorization: Bearer ${HF_TOKEN}" \
  -H "Accept: application/json"

mapping 裡的 provider status 可能是 live 或 error；有些項目還會提供 context length、input／output pricing、supports_tools、supports_structured_output、首 token 延遲與 throughput。主 Agent 可以把這些欄位轉成短期 allowlist：只讓學生使用 status 是 live、資料政策已確認、任務能力符合、預算仍足夠的路徑。

如果模型頁只顯示一個過期或 error provider，Agent 應回報「目前沒有符合條件的路徑」，而不是把模型名稱改成另一個相似模型。模型與 provider 的替換要留下查核日期與理由，這樣學生才知道路由失敗可能是供應狀態，而不是自己的 prompt 一定寫錯。

使用 auto 路由練習 provider failover

官方 Inference Providers 文件支援 provider="auto" 或相應的自動路由設定。自動路由可以在主要 provider 不可用時嘗試另一個可用 provider，也可以根據目前的 provider 選擇政策處理模型請求。它適合學生觀察同一個模型 ID 在不同基礎設施上的差異，但不代表每次都會拿到同一個 provider、相同延遲或完全相同答案。

如果課堂需要可重現的比較，可以使用明確 provider 或設定中的 preferred 順序；若需要節省費用，官方文件也提供 :cheapest 之類的選擇政策。這些選擇仍要回到目前 provider mapping 與價格查核，不能把「cheapest」解讀成「免費」，也不能把 failover 解讀成額度增加。

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    api_key=os.environ["HF_TOKEN"],
    provider="auto",
)

answer = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[
        {
            "role": "user",
            "content": "只處理公開資料，列出三個可人工驗證的重點。",
        }
    ],
    max_tokens=160,
)

print(answer.choices[0].message.content)

Python client 的好處是把 provider routing 的格式差異包在官方 client 裡，但它不會替你決定資料能不能送出，也不會替你取得免費配額。真正的 adapter 仍需在呼叫前檢查 data_class、model allowlist、月度預算與是否允許自動 failover；呼叫後記錄實際模型、provider、狀態與人工驗收結果。

Hugging Face 的資料政策與外部 provider 要分開讀

Hugging Face Security & Compliance 文件目前說明，Hugging Face 不會為了訓練而保存使用者資料；透過 Hugging Face routing 時，不保存 request body 或 response。文件同時指出，為除錯而保存的 logs 最長可達 30 天，並說明不保存 user data 或 tokens。這表示不要把 token 放進 request body、prompt、檔名或自訂 header；即使平台不保存內容，也不應自行製造秘密外洩位置。

更重要的是，Inference Providers 會把請求送到外部 provider。Hugging Face 官方明確要求使用者再閱讀每個 provider 的 data security policy；外部 provider 的保存、訓練、監控與地區處理條件可能不同。主 Agent 的預設資料分類應該是公開資料或去識別化資料；如果 provider policy 沒有確認，就拒絕送出個資、客戶資料、未公開研究或秘密。

模型 license 也不能被「Hugging Face 有路由」取代。模型頁可能有自己的開源、研究、商用或 gated 條款；學生若要做公開教材、商業內容或模型評測，應先保存模型頁與 license 連結，再決定是否加入課程 allowlist。主 Agent 只負責把 policy 檢查自動化，不替學校或組織接受法律條款。

免費額度與 custom provider key 的帳務分界

這是 Hugging Face 文章最容易被誤讀的地方。使用 HF routed request 時，Hugging Face 會管理路由與帳務，monthly credits 可以抵扣符合條件的請求；使用 custom provider key 時，Hugging Face 不會向你收取該次請求費用，但 provider 會按照自己的帳戶與價格直接計費，而且 Hugging Face credits 不適用。

因此，學生若看到「在 settings 加入 provider key 可以繼續使用」，不能把它當成免費額度續杯。它只是改變付款責任與認證路徑。主 Agent 在沒有明確付款授權時，遇到 credits 不足就應停止、排程稍後或改用本機模型，不應自動切換 custom key，也不應要求學生尋找別人的 key。

429 與 provider unavailable 的有限處理

Hugging Face Hub 本身對 Hub API、模型搜尋、repository 與 resolver 有 rate limits；官方說明在超過限制時會回傳 HTTP 429，並可能提供 RateLimit 與 RateLimit-Policy headers。Inference Provider 也可能受到 provider 自己的限流、容量或 credits 狀態影響，因此不能只看一個 status code 就把所有失敗歸類成同一件事。

使用 provider="auto" 時，官方路由可能在 provider 不可用時做 failover。主 Agent 仍應保存這次實際選到的 provider，避免把 failover 誤算成免費配額增加。若回應是 429 且有明確 reset header，可以做少量退避；若是 credits 不足、付款要求、模型條款或資料 policy 不符合，則應停止，不可用無限重試掩蓋成本問題。

async function callWithBoundedRetry(call) {
  const maxRetries = 2;

  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
    const response = await call();
    if (response.ok) return response;

    const retryAfter = Number(response.headers.get('retry-after'));
    const rateLimit = response.headers.get('ratelimit');
    const retryable = response.status === 429 && (retryAfter >= 0 || Boolean(rateLimit));

    if (!retryable || attempt === maxRetries) return response;

    const waitMs = Math.min(8000, retryAfter >= 0 ? retryAfter * 1000 : 750 * 2 ** attempt);
    await new Promise((resolve) => setTimeout(resolve, waitMs));
  }
}

這段程式只示範低量、可重試的讀取型請求。若上一個請求可能已觸發外部工具、寫入資料或消耗付費 credits，重試前要先確認 idempotency 與回應狀態。若服務回傳 401、403、付款或權限錯誤，不應把它當成 429；應顯示原因並交回管理者。

把每月 0.10 美元分成可觀測的學生預算

Free User 的 monthly credits 是帳戶層級的額度，不是每個學生、每個模型或每個 provider 各自都有一份。若一個帳戶由多個學生 Agent 共用，應先定義課堂預算，例如固定驗收、學生實驗、錯誤重試與老師示範各自保留一部分。具體切法要依當月定價與模型而定，不能從 0.10 美元推導出固定 token 數。

帳本至少要保存日期、student_id、task_id、model、provider、路由方式、輸入／輸出 token、狀態碼、是否 failover、是否通過資料閘門與人工驗收結果。不要保存 HF token、完整敏感 prompt 或完整 response。當 credits 接近用完時，adapter 應停止新工作、縮短公開測試或排到下個月，不應自動購買 credits。

• 學習任務：公開資料摘要、分類、結構化輸出、模型比較與 provider failover 實驗。
• 模型閘門：只允許目前 mapping 為 live、task 相容、license 已查核的模型。
• 資料閘門：公開或去識別化資料才可送出，外部 provider policy 不明就停止。
• 額度閘門：每次請求前檢查月度預算，credits 不足時不自動改用 custom key。
• 身份閘門：學生使用內部身份，HF token 只留在受控後端；token 遺失時撤銷該應用程式 token。

用模型與 provider metadata 做學生驗收

第一次驗收不要只問模型回答得像不像人。先用一組不含個資的固定測試集，檢查 JSON 是否可解析、是否遵守輸出長度、是否把未知內容標成需要查證、是否誤用工具，以及 auto 路由後的 provider 是否仍符合資料政策。再把同一測試集送到兩個允許的 provider，記錄 latency、throughput、價格、錯誤率與人工修正次數。

負面測試同樣重要：使用不存在的 model ID、沒有 live provider 的 mapping、過長輸入、即將用完 credits 的模擬狀態，以及資料分類為 private 的 prompt。每種情況都應得到明確的拒絕、停止或人工確認，而不是讓 Agent 悄悄切到另一個 provider。這才是學生學到的「燃料管理」，而不只是找到一個能回話的 endpoint。

主要 AI Agent 的安全 adapter

對主要 AI Agent，Hugging Face 最適合放在 provider adapter 層。學生送入任務後，adapter 先判斷 data_class、task、approved_model、budget_remaining 與 allow_failover，再由後端以 HF_TOKEN 呼叫官方 client 或 router。學生端只收到答案、模型與 provider 摘要，不會看到原始 token。

adapter 也要把 provider failover 設成明確政策。公開資料的摘要任務可以允許 auto；需要固定模型、固定延遲、特殊 license 或可重現評測的任務，則指定 provider 或直接拒絕 failover。若自動路由改變了實際 provider，結果頁應顯示這個事實，讓學生知道輸出差異來自路徑變化，而不是把所有品質問題歸咎於 prompt。

用任務需求選模型而不是追逐模型名稱

學生常把「能用的模型越多越好」當成免費 API 的價值，但主要 Agent 更需要可預測的任務契約。摘要任務要看輸出長度與事實保留；分類任務要看 label schema 與拒答行為；embedding 任務要看向量維度、批次大小與相似度驗收；工具呼叫任務要看 supports_tools 與失敗時是否會停止。模型名稱只是索引，不能代替這些能力檢查。

provider metadata 可以幫助學生理解同一模型在不同服務上的差異。context length 不足時，應先縮短輸入或分段，而不是不斷重試；supports_structured_output 為 false 時，adapter 應該使用文字後解析並保留失敗結果，或直接選擇另一條已核准路徑。每一種替代都要記錄原因，讓日後的品質比較不會把模型、provider 與 prompt 變更混在一起。

如果學生只需要一次公開資料摘要，auto 路由很方便；如果學生正在做模型評測，就應鎖定模型與 provider，並保存當日的 mapping。這樣做可能少了一點彈性，卻能讓課堂報告回答「哪個模型、哪個 provider、哪個價格與哪個資料政策」四個基本問題，也能避免免費 credits 在無意義的比較與重試中被消耗。

Hugging Face 免費額度的費用停止線

官方 pricing 頁說明，額度用完後可以購買額外 credits 來繼續使用。對沒有付款授權的學生 Agent，這不是自動恢復的選項，而是停止線。系統應顯示目前 credits 狀態、預估消耗、上一次使用的 provider，以及需要管理者決定的下一步；不要把付款畫面、custom provider key 或另一個帳戶偷偷接進來。

若學校或組織有合法的 Team／Enterprise 帳戶，組織管理者可以另行決定是否讓成員使用組織 credits，並依官方方式指定 billing organization。那是組織授權與帳務治理，不是學生自行取得更多免費 token。文章與主 Agent 都應把個人 Free User、PRO、Team 與 Enterprise 的條件分開顯示。

課堂介面也應在送出前顯示一個簡短預覽：這次使用哪個 Hugging Face 帳務路徑、目前模型可能由哪些 provider 處理、是否允許自動 failover、資料會經過哪些外部服務，以及 credits 不足時會如何停止。學生看見這些決策後，才是在學習如何控制 AI Agent，而不是把一個黑盒 API 當成無限燃料。

資料來源與模型變更要可回溯

Inference Providers 是快速變動的路由目錄，因此每次課堂使用都應記錄查核日期、官方 pricing URL、模型頁、provider mapping、模型 license、資料 policy、實際 provider 與帳務模式。這份紀錄不需要儲存 secret，卻能讓老師在官方價格、模型、provider 或資料條款更新時，快速知道哪些課程需要重新驗收。

當紀錄發現 token 曾出現在 log 或學生裝置上，先撤銷該 token，再檢查帳戶 credits、最近請求與 provider 使用狀態；不要把舊 token 留著觀察，也不要把撤銷後的秘密貼到報告裡。這個流程讓安全事件可控，也能避免學生把憑證輪換誤解成取得更多免費額度。

不要把社群貼出的免費 key、公共 gist、別人截圖或過期 notebook 當成來源。Hugging Face token 必須由使用者自己在官方設定建立，provider policy 必須從官方文件確認，模型能力要以目前 mapping 回讀。這種查核流程才適合持續捕獲合法免費方案，也能讓下一篇文章在條件改變時被安全替換。

給學生的安全清單

• 只從 Hugging Face 官方設定建立自己的 read 或 fine-grained token。
• 把 HF_TOKEN 放在後端環境變數或秘密管理工具，不放進前端、Git、prompt 或截圖。
• 初始只使用 Hugging Face routed requests；custom provider key 不等於免費 credits。
• 每次呼叫前查模型與 provider mapping，確認 live、task、license、資料政策與預算。
• 把 Free User 每月 0.10 美元視為可能變動的帳戶額度，不換算成固定 token 或每人額度。
• 429 只做有 header 或明確可重試條件的有限退避；付款、權限、條款與資料錯誤立即停止。
• 不分享 token、不輪換帳戶、不用 provider failover 規避限制，也不自動購買 credits。

結語：把 Hugging Face credits 變成可追蹤的學習燃料

Hugging Face Inference Providers 的優點，是讓學生在一個相對統一的介面中接觸多種模型與 provider；它的限制也正好能教學生真正的 Agent 工程：monthly credits 不是 token、模型價格不是固定、auto failover 不是額度倍增、Hugging Face 的資料政策不會取代外部 provider policy、token 權限也不等於可以分享。

如果要接到主要 AI Agent，先在沒有真實 token 的本地環境測試模型 allowlist、provider mapping、資料閘門、credits 停止線與 429 分流，再由有權限的管理者做一次低量、可撤銷、只處理公開資料的 smoke。本文目前只完成官方文件查核與本地草稿驗收，沒有代替任何人建立 token，也沒有對 Hugging Face 發出真實 API 請求。更多 Agent 基本邊界可延伸閱讀 YOLO LAB AI Agent 常見問題。

官方來源： Inference Providers Pricing and Billing、Inference Providers Overview、Security and Compliance、Hub API、User Access Tokens、Your First Inference Provider Call、Hub Rate Limits。