推論提供者

根據預設，您的伺服器會將模型呼叫傳送至 Claude API。此頁面說明如何將這些呼叫傳送至雲端提供者，或您自行執行的模型閘道。若要變更提供者：

1. 將此頁面中您提供者章節的範例放入伺服器的設定檔中。
2. 依照同一章節的說明，將提供者的憑證提供給伺服器。
3. 依照設定的存放位置的說明重新啟動伺服器。在 Docker Compose 上，如果步驟 2 變更了 .env 或 docker-compose.yml，請改為執行 docker compose up -d，因為重新啟動不會重新讀取這些檔案。
4. 檢查提供者。

inference.provider 設定可接受下列值：

在 anthropic 以外的所有值下，伺服器都不需要 Claude API 金鑰。它會忽略 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL。唯一的例外是您指示伺服器從其中一個變數讀取金鑰的模型閘道。

代理程式以 Claude API ID 指定模型，例如 claude-opus-5-5。伺服器會轉換此 ID，因此代理程式定義在任何提供該模型的提供者下都能直接使用，無需修改。

部分工具和代理程式設定取決於提供者。請參閱取決於推論提供者的差異。

將雲端憑證提供給伺服器

雲端提供者的憑證如何送達伺服器，取決於您的安裝方式：

• Docker Compose： 將每個變數和檔案傳遞給伺服器。
• Kubernetes： 伺服器 chart 不會傳遞任何 AWS、Google Cloud 或 Azure 變數，因此請使用您雲端的工作負載身分。建立一個帶有您雲端工作負載身分註解的服務帳戶，並將 server.serviceAccountName 設定為其名稱。chart 的 values.yaml 會列出該註解。在 Azure Kubernetes Service 上，也請設定 server.azureWorkloadIdentity: true。

Amazon Bedrock

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)

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

inference:
  provider: foundry
  foundry:
    resource: my-resource
  #model_id_overrides:
  #  claude-opus-5-5: team-a-opus

resource 是您的 Foundry 資源名稱，也就是其主機名稱的第一部分：<resource>.services.ai.azure.com。

憑證來自伺服器的環境：

• Foundry API 金鑰： 設定 ANTHROPIC_FOUNDRY_API_KEY。在 Compose 堆疊中，將該變數傳遞給伺服器。在 Kubernetes 上，請將其放入 cma-server-upstream Secret。若您的伺服器 values 檔案中設定了 earlierNames: true，該 Secret 會使用另一個名稱。請在 Kubernetes：您的物件名稱中查找。
• 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 進行對應。

對應不同的模型 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，適用於接受單一長期金鑰的閘道。請將金鑰放入環境變數中，並指定變數名稱，切勿填入值本身：

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 <key>。
• 在 Compose 堆疊中，將該變數傳遞給伺服器。
• 在 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：您的物件名稱中查找。

若要使用 format: anthropic-messages，請將 gateway 區塊替換為以下區塊：

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 區塊替換為以下區塊：

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 憑證。

設定參考列出了閘道的其他設定，例如 streaming，以及 inference.headers 設定。

短期權杖

如果您的閘道接受短期權杖，請將 credentials 區塊替換為以下區塊：

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 請求：

{
  "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 是建立工作階段的呼叫者。對於單一登入呼叫者，issuer 是該呼叫者的 issuer_url，而 subject 是該呼叫者的主體。對於伺服器 API 金鑰，principal 為 {"issuer": "cma", "subject": "server"}。請讓回呼忽略它不認識的欄位。

回呼會以狀態 200 和下列主體回應：

{ "assertion": "<signed JWT>", "reuse": "session" }

reuse 表示哪些工作階段可以使用該權杖。若為預設的 session，則只有請求中的工作階段可以使用，適用於代表單一使用者的權杖。若為 deployment，則工作階段會共用該權杖，因此僅在權杖代表您的組織而非任何個人時才傳回 deployment。

如果回呼或權杖端點失敗，該回合會以類型為 model_request_failed_error 的 session.error 事件結束，而工作階段仍可繼續使用。原因記錄在伺服器日誌中包含 credential supplier failed 的那一行。

如果權杖端點的回覆沒有 expires_in，且權杖沒有 exp 聲明，伺服器會傳送該權杖但不會儲存。接著它會在每次模型呼叫時要求另一個權杖。

如需其他設定，例如 renew_before 和 ca_file，請參閱設定參考中的模型閘道設定和短期權杖設定表格。

Microsoft Entra ID 權杖

如果您的閘道會依據其自身的「app registration」（應用程式註冊）檢查 Microsoft Entra ID 權杖，請將 credentials 區塊替換為以下區塊：

inference:
  credentials:
    supplier: azure
    azure: { scope: "api://11111111-2222-3333-4444-555555555555/.default" }

scope 是閘道應用程式註冊的應用程式 ID URI 或應用程式 ID，後面接著 /.default。請僅指定閘道自身的註冊。若使用其他資源的權杖，將讓執行閘道的任何人得以在該資源上以伺服器的身分行事。

該權杖會核發給伺服器自身的 Azure 身分，其設定方式與 Microsoft Foundry 下的 Microsoft Entra ID 相同。如果該註冊要求應用程式角色，請在啟動伺服器之前將該角色指派給此身分。之後才進行的指派，只有在伺服器取得另一個權杖時才會生效。

該權杖僅指名該身分而非任何個人，因此必須知道是哪個人在呼叫的閘道需要使用 oauth_exchange。在依賴此供應程式之前，請以您的伺服器將使用的身分，透過您的閘道執行一個回合。

檢查提供者

變更設定並重新啟動伺服器後，請在伺服器日誌中尋找這一行。它表示伺服器已找到該提供者的憑證：

level=INFO msg="upstream credential resolved" provider=bedrock

這一行並不能證明您的帳戶已啟用模型。缺少的模型會在第一個使用它的回合中以 session.error 形式出現。

您在 ANTHROPIC_BASE_URL 中指定的閘道可能會拒絕伺服器端備援欄位或標頭。如果每個回合都因此而失敗，請在設定檔中設定 inference.model_fallback: false。