BYOK（自帶金鑰）

BYOK（Bring Your Own Key）讓 Workspace 或全域設定使用你自己的上游供應商金鑰，而不是平台共用金鑰。

設定方式（擇一）

1. 工作區 BYOK（Console → 工作區 → BYOK）
   可選的供應商就是平台後台已啟用、且有模型的供應商（例如 openai、anthropic、google、x-ai、bedrock、groq、deepseek），平台新增供應商後會自動出現在這裡；自動選模不開放自帶金鑰，一律使用平台金鑰。 點進供應商後可設定多把金鑰，每把包含：

   • 標題與 API Key
   • Endpoint URL（可選填；留空即帶入該供應商預設 Base URL）
   • 生效模型：預設是該供應商所有模型，也可只限定特定模型
   • 綁定 Hakila API Key：預設不指定（工作區所有 API Key 都適用），也可只給特定幾把

   請求同時符合模型與 API Key 條件時，Gateway 就改用這把金鑰（與其 Endpoint）呼叫上游。多把同時符合時，綁得越具體的越優先（同時指定 API Key 與模型 → 只指定 API Key → 只指定模型 → 皆不限），再依建立順序。 命中 BYOK 的成功請求仍寫入 Logs（含 token），但不扣服務點數：上游費用由你的供應商帳戶支付。組織儲值餘額用盡時，這些請求仍可呼叫。沒有命中的請求（例如同一把 Hakila API Key 呼叫尚未綁定的供應商）仍照平台用量扣點，餘額用盡時回 402。 金鑰明文只存 MySQL；服務啟動時整批載入 Redis，請求路徑不查資料庫。

2. 資料庫 ProviderKeys（平台維運）
   Tenant 層或全域（WorkspaceId／TenantId 皆 null）的後備金鑰。全域金鑰可在後台「供應商管理」為每個供應商設定。

3. 公司金鑰（平台部署後備）
   正式環境由 Secret Manager 在程序啟動時載入（例如 hakila-provider-openai）。本機／設定檔對應 Providers:{provider}:ApiKey。僅在資料庫沒有對應啟用金鑰時才使用。

地端或私有部署（Ollama、vLLM 等 OpenAI 相容服務）由平台管理員在後台「供應商管理」新增為供應商，設定 Base URL 與金鑰，再把模型掛到該供應商下；金鑰解析與其他供應商相同。

解析順序

對每個請求、每個上游供應商，Gateway 依序取第一個可用金鑰：

1. 工作區 BYOK（條件符合的那把；會連同其 Endpoint 一起使用）
2. Tenant 層金鑰（WorkspaceId 為空、有 TenantId）
3. 全域金鑰（WorkspaceId／TenantId 皆空）
4. 設定檔／Secret Manager 載入的 Providers:{provider}:ApiKey

一個模型由多家供應商提供時，有命中工作區 BYOK 的供應商會優先使用（請求以 provider.order 指定順序時除外），沒有金鑰的供應商會略過，詳見 多供應商與備援。

Responses API 的 stateful 端點（retrieve／cancel／delete／input_items）沒有 model，只會命中未限定模型的 OpenAI BYOK 金鑰。

模型的所有供應商都找不到金鑰時回 502（訊息會提示確認 Secret Manager、ProviderKeys 或設定檔）。不需要 Authorization 的地端服務，金鑰請填任意字串。

與 hakila/auto 的關係

hakila/auto 會依目錄候選順序，挑選第一個通過允許清單、且有可用金鑰的上游。若你只設定了 Gemini 金鑰，且該候選未被允許清單排除，auto 就會走 Google。候選模型的金鑰同樣套用上面的解析順序，因此 BYOK 也會影響 auto 最終用哪把金鑰。

安全提醒

• Provider Key 屬於敏感憑證，請只在 Admin / 受控設定中管理
• Gateway 對外只暴露 Hakila API Key；上游金鑰不會回傳給客戶端