---
title: 推論提供者
url: https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/inference-provider
description: 將自行託管的 Claude Managed Agents 伺服器的模型呼叫傳送至 Amazon Bedrock、Claude Models on Google Cloud (Google managed)、Microsoft Foundry 或您自行執行的模型閘道，而非 Claude API。
---
若要申請自行託管的 Claude Managed Agents 存取權，請聯絡您的 Anthropic 客戶團隊。
根據預設，您的伺服器會將模型呼叫傳送至 Claude API。此頁面說明如何將這些呼叫傳送至雲端提供者，或您自行執行的模型閘道。若要變更提供者：
1. 將此頁面中您提供者章節的範例放入伺服器的[設定檔](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#where-settings-go)中。
2. 依照同一章節的說明，將提供者的憑證提供給伺服器。
3. 依照[設定的存放位置](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#where-settings-go)的說明重新啟動伺服器。在 Docker Compose 上，如果步驟 2 變更了 `.env` 或 `docker-compose.yml`，請改為執行 `docker compose up -d`，因為重新啟動不會重新讀取這些檔案。
4. [檢查提供者](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/inference-provider#check-the-provider)。
`inference.provider` 設定可接受下列值：
| `inference.provider` | 模型呼叫傳送至 | 伺服器的驗證方式 |
| -------------------- | ---------------------------------------------- | -------------------------------------- |
| `anthropic`（預設） | Claude API | `ANTHROPIC_API_KEY` |
| `bedrock` | Amazon Bedrock | 您的 AWS 憑證 |
| `vertex` | Claude Models on Google Cloud (Google managed) | Google Application Default Credentials |
| `foundry` | Microsoft Foundry | Foundry API 金鑰，或 Microsoft Entra ID |
| `gateway` | 您自行執行的模型閘道 | 您的閘道所接受的金鑰或權杖 |
在 `anthropic` 以外的所有值下，伺服器都不需要 Claude API 金鑰。它會忽略 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 和 `ANTHROPIC_BASE_URL`。唯一的例外是您指示伺服器從其中一個變數讀取金鑰的[模型閘道](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/inference-provider#model-gateway)。
代理程式以 Claude API ID 指定模型，例如 `claude-opus-5-5`。伺服器會轉換此 ID，因此代理程式定義在任何提供該模型的提供者下都能直接使用，無需修改。
部分工具和代理程式設定取決於提供者。請參閱[取決於推論提供者的差異](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/differences#differences-that-depend-on-your-inference-provider)。
## 將雲端憑證提供給伺服器
雲端提供者的憑證如何送達伺服器，取決於您的安裝方式：
* **Docker Compose：** [將每個變數和檔案傳遞給伺服器](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack)。
* **Kubernetes：** 伺服器 chart 不會傳遞任何 AWS、Google Cloud 或 Azure 變數，因此請使用您雲端的工作負載身分。建立一個帶有您雲端工作負載身分註解的服務帳戶，並將 `server.serviceAccountName` 設定為其名稱。chart 的 `values.yaml` 會列出該註解。在 Azure Kubernetes Service 上，也請設定 `server.azureWorkloadIdentity: true`。
## Amazon Bedrock
```yaml
inference:
provider: bedrock
region: us-east-1
#model_id_prefix: global.anthropic.
#model_id_overrides:
# claude-opus-5-5: us.anthropic.claude-opus-5-5
```
伺服器會使用 AWS SDK 預設憑證鏈在主機上找到的任何憑證來簽署其呼叫。這可以是任務角色或 pod 身分。在工作站上，則可以是 `AWS_PROFILE` 或 `AWS_ACCESS_KEY_ID`。
請在帳戶中啟用您使用的模型。伺服器用來簽署的 AWS 身分需要下列權限：
* 對您使用的模型和推論設定檔具有 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 權限。
* 對資源 `*` 具有 `bedrock:ListFoundationModels` 和 `bedrock:ListInferenceProfiles` 權限。伺服器會讀取 Amazon Bedrock 的模型清單，讓代理程式可以使用比您伺服器版本更新的模型。若要略過此項，請設定 `inference.list_models: false`。
根據預設，伺服器會在每個模型 ID 前加上 `us.anthropic.`，以指定一個跨區域推論設定檔。若要使用其他系列的設定檔，請取消註解 `model_id_prefix`。
## Claude Models on Google Cloud (Google managed)
```yaml
inference:
provider: vertex
region: us-east5
project_id: my-project
#model_id_overrides:
# claude-haiku-4-5: claude-haiku-4-5@20251001
```
`region` 為必填。它是提供您所使用模型的 Google Cloud’s Agent Platform 位置，或 `global`。`project_id` 是發出呼叫並計費的專案。
伺服器使用 Google Application Default Credentials：即 `GOOGLE_APPLICATION_CREDENTIALS` 所指定的檔案，或 Compute Engine、Cloud Run 或 GKE 所附加的服務帳戶。該身分需要在專案上具有 `roles/aiplatform.user` 角色。專案需要啟用 `aiplatform.googleapis.com` API 以及您使用的 Claude 模型。
## Microsoft Foundry
```yaml
inference:
provider: foundry
foundry:
resource: my-resource
#model_id_overrides:
# claude-opus-5-5: team-a-opus
```
`resource` 是您的 Foundry 資源名稱，也就是其主機名稱的第一部分：`.services.ai.azure.com`。
憑證來自伺服器的環境：
* **Foundry API 金鑰：** 設定 `ANTHROPIC_FOUNDRY_API_KEY`。在 Compose 堆疊中，[將該變數傳遞給伺服器](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack)。在 Kubernetes 上，請將其放入 `cma-server-upstream` Secret。若您的伺服器 values 檔案中設定了 `earlierNames: true`，該 Secret 會使用另一個名稱。請在 [Kubernetes：您的物件名稱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/upgrade#object-names)中查找。
* **Microsoft Entra ID：** 不要設定 `ANTHROPIC_FOUNDRY_API_KEY`。伺服器接著會為服務主體、Azure Kubernetes Service 上的工作負載身分，或受控身分取得權杖。該身分需要在 Foundry 資源上具有允許呼叫其模型部署的 Azure 角色。若使用服務主體，請設定 `AZURE_TENANT_ID`、`AZURE_CLIENT_ID` 和 `AZURE_CLIENT_SECRET`。
對 Foundry 的請求會指定一個部署，而伺服器會將模型 ID 作為部署名稱傳送。如果部署使用其他名稱，請使用 [`model_id_overrides`](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/inference-provider#map-a-model-id-that-differs) 進行對應。
## 對應不同的模型 ID
您的雲端帳戶中的模型 ID 可能與伺服器傳送的 ID 不同。在此情況下，請取消註解該提供者範例中的 `model_id_overrides` 行，並將 Claude API ID 對應至您帳戶的 ID。兩個 ID 必須指定同一個模型，因為伺服器會針對代理程式所指定的模型建置每個請求。
## 模型閘道
首先確認您的閘道接受哪些請求：
* **與 Claude API 相同的請求，搭配單一長期憑證：** 保留預設提供者。將 `ANTHROPIC_BASE_URL` 設定為閘道的位址，並將 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` 設定為閘道所要求的憑證。
* **與 Claude API 相同的請求，但使用短期權杖、位於其他標頭中的憑證，或其自有的模型 ID：** 設定 `inference.provider: gateway` 並搭配 `format: anthropic-messages`。
* **Amazon Bedrock 的 InvokeModel 格式：** 設定 `inference.provider: gateway` 並搭配 `format: bedrock-invoke`。
* **Claude Models on Google Cloud (Google managed) 的 `rawPredict` 格式：** 設定 `inference.provider: gateway` 並搭配 `format: vertex-raw-predict`。
此範例設定 `inference.provider: gateway` 並搭配 `format: bedrock-invoke`，適用於接受單一長期金鑰的閘道。請將金鑰放入環境變數中，並指定變數名稱，切勿填入值本身：
```yaml
inference:
provider: gateway
gateway:
url: "https://llm-gateway.example.com/v1/model/{model}/invoke"
format: bedrock-invoke
# Quote every model_map value.
model_map:
claude-opus-5-5: "us.anthropic.claude-opus-5-5"
claude-sonnet-5: "us.anthropic.claude-sonnet-5"
credentials:
supplier: env
env: { var: LLM_GATEWAY_KEY }
send_as: { header: x-api-key }
```
* `url` 是閘道的模型路由。`{model}` 標示模型 ID 的放置位置。URL 必須為 `https://` 並以 `/invoke` 結尾。
* `model_map` 將代理程式可指定的每個模型 ID 對應至閘道所要求的 ID。伺服器會拒絕沒有對應項目的模型。
* `send_as` 指定攜帶金鑰的標頭。若未設定，伺服器會傳送 `Authorization: Bearer `。
* 在 Compose 堆疊中，[將該變數傳遞](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack)給伺服器。
* 在 Kubernetes 上，伺服器 chart 無法傳遞您自訂的變數。它確實會傳遞 `ANTHROPIC_AUTH_TOKEN`，並從 `cma-server-upstream` Secret 讀取該變數，因此請使用該名稱：
1. 設定 `env: { var: ANTHROPIC_AUTH_TOKEN }`。
2. 將閘道的金鑰以 `ANTHROPIC_AUTH_TOKEN` 名稱放入 `cma-server-upstream` Secret。若您的伺服器 values 檔案中設定了 `earlierNames: true`，該 Secret 會使用另一個名稱。請在 [Kubernetes：您的物件名稱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/upgrade#object-names)中查找。
若要使用 `format: anthropic-messages`，請將 `gateway` 區塊替換為以下區塊：
```yaml
inference:
gateway:
url: "https://llm-gateway.example.com/v1/messages"
format: anthropic-messages
# Quote every model_map value.
model_map:
claude-opus-5-5: "corp-claude-opus"
claude-sonnet-5: "corp-claude-sonnet"
```
此處的 `url` 是閘道 Messages 路由的完整 URL，不含 `{model}`。
若要使用 `format: vertex-raw-predict`，請將 `gateway` 區塊替換為以下區塊：
```yaml
inference:
gateway:
url: "https://llm-gateway.example.com/v1/projects/my-project/locations/global/publishers/anthropic/models/{model}:rawPredict"
format: vertex-raw-predict
# Quote every model_map value.
model_map:
claude-opus-5-5: "claude-opus-5-5"
claude-sonnet-5: "claude-sonnet-5"
```
此處的 `url` 是閘道的 `rawPredict` 路由，且必須以 `/{model}:rawPredict` 結尾。`model_map` 的值不得包含冒號。`credentials` 區塊維持不變。伺服器會傳送您閘道自身的憑證，且不會取得任何 Google 憑證。
[設定參考](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#model-gateway)列出了閘道的其他設定，例如 `streaming`，以及 `inference.headers` 設定。
### 短期權杖
如果您的閘道接受短期權杖，請將 `credentials` 區塊替換為以下區塊：
```yaml
inference:
credentials:
supplier: oauth_exchange
assertion:
url: "https://app.example.com/assertion"
auth: { type: mtls, cert_file: /etc/callback/client.pem, key_file: /etc/callback/client.key }
exchange:
token_url: "https://login.example.com/oauth2/token"
grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer"
```
伺服器接著會分兩個步驟取得每個權杖。首先，它會呼叫您建置的 HTTP 回呼。該回呼會傳回一個斷言（assertion），即一份經過簽署的聲明，通常是「JSON Web Token」（JSON 網路權杖），即 JWT。接著，伺服器會在您的 OAuth 權杖端點以該斷言交換存取權杖，並將其傳送給閘道。
* `auth` 是伺服器向回呼進行驗證的方式。範例使用用戶端憑證。若要使用伺服器從檔案讀取的持有人權杖，請設定 `auth: { type: bearer_file, token_file: /etc/callback/token }`。
* `exchange` 指定您的 OAuth 權杖端點。伺服器只會向該端點傳送 `grant_type` 和斷言，不含用戶端 ID 或密鑰。
* 如果您的權杖端點需要更多資訊，請省略 `exchange`。請讓您的回呼自行取得存取權杖，並在 `assertion` 欄位中傳回，伺服器接著會將其傳送給閘道。
* 在 Kubernetes 上，請將憑證檔案放入 Secret，在 chart 的 `server.extensionFiles.secretName` 中指定其名稱，並將 `cert_file` 和 `key_file` 指向 `/run/cma-server/extension-files/`。
伺服器會以下列主體向回呼傳送 `POST` 請求：
```json
{
"version": 1,
"purpose": "inference",
"session": {
"id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
"agent_id": "agent_011CYm1BLqPXpQRk5khsSXrs",
"environment_id": "env_01595EKxaaTTGwwY3kyXdtbs"
},
"principal": {
"issuer": "https://login.example.com/oauth2/default",
"subject": "00u1a2b3c4d5e6f7g8h9"
},
"request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}
```
`principal` 是建立工作階段的呼叫者。對於[單一登入](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configure#single-sign-on)呼叫者，`issuer` 是該呼叫者的 `issuer_url`，而 `subject` 是該呼叫者的主體。對於伺服器 API 金鑰，`principal` 為 `{"issuer": "cma", "subject": "server"}`。請讓回呼忽略它不認識的欄位。
回呼會以狀態 `200` 和下列主體回應：
```json
{ "assertion": "", "reuse": "session" }
```
`reuse` 表示哪些工作階段可以使用該權杖。若為預設的 `session`，則只有請求中的工作階段可以使用，適用於代表單一使用者的權杖。若為 `deployment`，則工作階段會共用該權杖，因此僅在權杖代表您的組織而非任何個人時才傳回 `deployment`。
如果回呼或權杖端點失敗，該回合會以類型為 `model_request_failed_error` 的 `session.error` 事件結束，而工作階段仍可繼續使用。原因記錄在伺服器日誌中包含 `credential supplier failed` 的那一行。
如果權杖端點的回覆沒有 `expires_in`，且權杖沒有 `exp` 聲明，伺服器會傳送該權杖但不會儲存。接著它會在每次模型呼叫時要求另一個權杖。
如需其他設定，例如 `renew_before` 和 `ca_file`，請參閱設定參考中的[模型閘道設定](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#model-gateway)和[短期權杖設定](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#short-lived-gateway-tokens)表格。
### Microsoft Entra ID 權杖
如果您的閘道會依據其自身的「app registration」（應用程式註冊）檢查 Microsoft Entra ID 權杖，請將 `credentials` 區塊替換為以下區塊：
```yaml
inference:
credentials:
supplier: azure
azure: { scope: "api://11111111-2222-3333-4444-555555555555/.default" }
```
`scope` 是閘道應用程式註冊的應用程式 ID URI 或應用程式 ID，後面接著 `/.default`。請僅指定閘道自身的註冊。若使用其他資源的權杖，將讓執行閘道的任何人得以在該資源上以伺服器的身分行事。
該權杖會核發給伺服器自身的 Azure 身分，其設定方式與 [Microsoft Foundry](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/inference-provider#microsoft-foundry) 下的 Microsoft Entra ID 相同。如果該註冊要求應用程式角色，請在啟動伺服器之前將該角色指派給此身分。之後才進行的指派，只有在伺服器取得另一個權杖時才會生效。
該權杖僅指名該身分而非任何個人，因此必須知道是哪個人在呼叫的閘道需要使用 `oauth_exchange`。在依賴此供應程式之前，請以您的伺服器將使用的身分，透過您的閘道執行一個回合。
## 檢查提供者
變更設定並重新啟動伺服器後，請在伺服器日誌中尋找這一行。它表示伺服器已找到該提供者的憑證：
```text wrap
level=INFO msg="upstream credential resolved" provider=bedrock
```
這一行並不能證明您的帳戶已啟用模型。缺少的模型會在第一個使用它的回合中以 `session.error` 形式出現。
您在 `ANTHROPIC_BASE_URL` 中指定的閘道可能會拒絕[伺服器端備援](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#server-side-fallback)欄位或標頭。如果每個回合都因此而失敗，請在[設定檔](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#where-settings-go)中設定 `inference.model_fallback: false`。