Provider di inferenza

Per impostazione predefinita, il tuo server invia le chiamate al modello all’API Claude. Questa pagina mostra come inviarle a un provider cloud o a un gateway di modelli che gestisci tu. Per cambiare il provider:

1. Inserisci l’esempio della sezione del tuo provider in questa pagina nel file delle impostazioni del server.
2. Fornisci al server la credenziale del provider, come mostra la stessa sezione.
3. Riavvia il server, come mostrato in Dove vanno le impostazioni. Su Docker Compose, se il passaggio 2 ha modificato .env o docker-compose.yml, esegui invece docker compose up -d, perché un riavvio non li rilegge.
4. Verifica il provider.

L’impostazione inference.provider accetta questi valori:

Con qualsiasi valore tranne anthropic, il server non ha bisogno di una chiave API Claude. Ignora ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e ANTHROPIC_BASE_URL. L’unica eccezione è un gateway di modelli la cui chiave indichi al server di leggere da una di queste variabili.

Gli agenti indicano i modelli tramite i loro ID dell’API Claude, come claude-opus-5-5. Il server traduce l’ID, quindi una definizione di agente funziona senza modifiche con qualsiasi provider che offra quel modello.

Alcuni strumenti e impostazioni degli agenti dipendono dal provider. Consulta Differenze che dipendono dal tuo provider di inferenza.

Fornire al server una credenziale cloud

Il modo in cui la credenziale di un provider cloud raggiunge il server dipende dalla tua installazione:

• Docker Compose: Passa ogni variabile e file al server.
• Kubernetes: Il chart del server non passa variabili AWS, Google Cloud o Azure, quindi usa la workload identity del tuo cloud. Crea un account di servizio con l’annotazione di workload identity del tuo cloud e imposta server.serviceAccountName sul suo nome. Il values.yaml del chart indica l’annotazione. Su Azure Kubernetes Service, imposta anche 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

Il server firma le sue chiamate con qualunque credenziale trovi sull’host la catena di credenziali predefinita dell’SDK AWS. Può trattarsi di un task role o di una pod identity. Su una workstation, può essere AWS_PROFILE o AWS_ACCESS_KEY_ID.

Abilita nell’account i modelli che usi. L’identità AWS con cui il server firma necessita di queste autorizzazioni:

• bedrock:InvokeModel e bedrock:InvokeModelWithResponseStream sui modelli e sugli “inference profile” (profili di inferenza) che usi.
• bedrock:ListFoundationModels e bedrock:ListInferenceProfiles sulla risorsa *. Il server legge gli elenchi dei modelli di Amazon Bedrock, in modo che gli agenti possano usare un modello più recente della release del tuo server. Per evitarlo, imposta inference.list_models: false.

Per impostazione predefinita, il server antepone us.anthropic. a ogni ID di modello, il che indica un inference profile cross-region. Per usare un’altra famiglia di profili, rimuovi il commento da 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 è obbligatorio. È una località di Google Cloud’s Agent Platform che offre i modelli che usi, oppure global. project_id è il progetto in cui vengono effettuate e fatturate le chiamate.

Il server usa le Google Application Default Credentials: il file indicato da GOOGLE_APPLICATION_CREDENTIALS, oppure l’account di servizio associato da Compute Engine, Cloud Run o GKE. Quell’identità necessita del ruolo roles/aiplatform.user sul progetto. Il progetto deve avere abilitati l’API aiplatform.googleapis.com e i modelli Claude che usi.

Microsoft Foundry

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

resource è il nome della tua risorsa Foundry, la prima parte del suo hostname: <resource>.services.ai.azure.com.

La credenziale proviene dall’ambiente del server:

• Una chiave API di Foundry: Imposta ANTHROPIC_FOUNDRY_API_KEY. Nello stack Compose, passa la variabile al server. Su Kubernetes, inseriscila nel Secret cma-server-upstream. Con earlierNames: true nel file dei valori del server, il Secret ha un altro nome. Lo trovi in Kubernetes: i nomi dei tuoi oggetti.
• Microsoft Entra ID: Lascia ANTHROPIC_FOUNDRY_API_KEY non impostata. Il server ottiene allora un token per un service principal, una workload identity su Azure Kubernetes Service o una managed identity. L’identità necessita di un ruolo Azure sulla risorsa Foundry che consenta le chiamate ai suoi deployment di modelli. Per un service principal, imposta AZURE_TENANT_ID, AZURE_CLIENT_ID e AZURE_CLIENT_SECRET.

Una richiesta a Foundry indica un deployment, e il server invia l’ID del modello come nome del deployment. Se un deployment ha un altro nome, mappalo con model_id_overrides.

Mappare un ID di modello diverso

Il tuo account cloud può avere un modello con un ID diverso da quello che invia il server. In tal caso, rimuovi il commento dalle righe model_id_overrides nell’esempio di quel provider e mappa l’ID dell’API Claude sull’ID del tuo account. Entrambi gli ID devono indicare lo stesso modello, perché il server costruisce ogni richiesta per il modello indicato dall’agente.

Gateway di modelli

Per prima cosa verifica quali richieste accetta il tuo gateway:

• Le stesse richieste dell’API Claude, con una sola credenziale a lunga durata: Mantieni il provider predefinito. Imposta ANTHROPIC_BASE_URL sull’indirizzo del gateway e imposta ANTHROPIC_API_KEY o ANTHROPIC_AUTH_TOKEN sulla credenziale che il gateway si aspetta.
• Le stesse richieste dell’API Claude, ma con token a breve durata, una credenziale in un altro header o propri ID di modello: Imposta inference.provider: gateway con format: anthropic-messages.
• Il formato InvokeModel di Amazon Bedrock: Imposta inference.provider: gateway con format: bedrock-invoke.
• Il formato rawPredict di Claude Models on Google Cloud (Google managed): Imposta inference.provider: gateway con format: vertex-raw-predict.

Questo esempio imposta inference.provider: gateway con format: bedrock-invoke, per un gateway che accetta una chiave a lunga durata. Inserisci la chiave in una variabile d’ambiente e indica il nome della variabile, mai il valore:

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 è la route del modello del gateway. {model} indica dove va l’ID del modello. L’URL deve essere https:// e terminare con /invoke.
• model_map mappa ogni ID di modello che un agente può indicare sull’ID che il gateway si aspetta. Il server rifiuta un modello che non ha una voce.
• send_as indica l’header che trasporta la chiave. Senza di esso, il server invia Authorization: Bearer <key>.
• Nello stack Compose, passa la variabile al server.
• Su Kubernetes, il chart del server non può passare una variabile definita da te. Passa però ANTHROPIC_AUTH_TOKEN, che legge dal Secret cma-server-upstream, quindi usa quel nome:
  1. Imposta env: { var: ANTHROPIC_AUTH_TOKEN }.
  2. Inserisci la chiave del gateway nel Secret cma-server-upstream, con il nome ANTHROPIC_AUTH_TOKEN. Con earlierNames: true nel file dei valori del server, il Secret ha un altro nome. Lo trovi in Kubernetes: i nomi dei tuoi oggetti.

Per format: anthropic-messages, sostituisci il blocco gateway con questo:

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"

Qui, url è l’intero URL della route Messages del gateway, senza {model}.

Per format: vertex-raw-predict, sostituisci il blocco gateway con questo:

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"

Qui, url è la route rawPredict del gateway e deve terminare con /{model}:rawPredict. Un valore di model_map non può contenere i due punti. Il blocco credentials resta invariato. Il server invia la credenziale propria del tuo gateway e non ottiene alcuna credenziale Google.

Il riferimento di configurazione elenca le altre impostazioni del gateway, come streaming, e l’impostazione inference.headers.

Token a breve durata

Se il tuo gateway accetta token a breve durata, sostituisci il blocco credentials con questo:

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"

Il server ottiene quindi ogni token in due passaggi. Per prima cosa, chiama un “callback” (callback) HTTP che costruisci tu. Il callback restituisce una “assertion” (asserzione), una dichiarazione firmata che di solito è un “JSON Web Token” (token web JSON), o JWT. Poi il server scambia l’asserzione presso il tuo endpoint token OAuth con il token di accesso che invia al gateway.

• auth indica come il server si autentica presso il callback. L’esempio usa un certificato client. Per usare un bearer token che il server legge da un file, imposta auth: { type: bearer_file, token_file: /etc/callback/token }.
• exchange indica il tuo endpoint token OAuth. Il server invia a quell’endpoint solo grant_type e l’asserzione, senza client ID né secret.
• Se il tuo endpoint token richiede più di questo, ometti exchange. Fai in modo che il tuo callback ottenga direttamente il token di accesso e lo restituisca nel campo assertion, che il server invia poi al gateway.
• Su Kubernetes, inserisci i file del certificato in un Secret, indicalo in server.extensionFiles.secretName del chart e fai puntare cert_file e key_file a /run/cma-server/extension-files/.

Il server invia al callback una richiesta POST con questo body:

{
  "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 è il chiamante che ha creato la sessione. Per un chiamante single sign-on, issuer è l’issuer_url di quel chiamante e subject è il subject del chiamante. Per la chiave API del server, principal è {"issuer": "cma", "subject": "server"}. Fai in modo che il callback ignori i campi che non conosce.

Il callback risponde con lo stato 200 e questo body:

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

reuse indica quali sessioni possono usare il token. Con session, il valore predefinito, può usarlo solo la sessione indicata nella richiesta, il che si adatta a un token che identifica un singolo utente. Con deployment, le sessioni condividono il token, quindi restituisci deployment solo per un token che identifica la tua organizzazione e nessuna persona.

Se il callback o l’endpoint token fallisce, il turno termina con un evento session.error di tipo model_request_failed_error e la sessione resta utilizzabile. Il motivo si trova nel log del server, su una riga che contiene credential supplier failed.

Se la risposta dell’endpoint token non contiene expires_in e il token non ha un claim exp, il server invia il token ma non lo memorizza. Richiede quindi un altro token a ogni chiamata al modello.

Per le altre impostazioni, come renew_before e ca_file, consulta le tabelle del Riferimento di configurazione delle impostazioni del gateway di modelli e delle impostazioni dei token a breve durata.

Token di Microsoft Entra ID

Se il tuo gateway verifica i token di Microsoft Entra ID rispetto alla propria registrazione dell’app, sostituisci il blocco credentials con questo:

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

scope è l’URI dell’ID applicazione o l’ID applicazione della registrazione dell’app del gateway, seguito da /.default. Indica solo la registrazione propria del gateway. Un token per un’altra risorsa consentirebbe a chi gestisce il gateway di agire come il server su quella risorsa.

Il token viene emesso all’identità Azure propria del server, configurata come per Microsoft Entra ID in Microsoft Foundry. Se la registrazione richiede un ruolo dell’app, assegna quel ruolo all’identità prima di avviare il server. Un’assegnazione successiva ha effetto solo quando il server ottiene un altro token.

Il token indica quell’identità e nessuna persona, quindi un gateway che deve sapere quale persona sta chiamando necessita di oauth_exchange. Esegui un turno attraverso il tuo gateway, con l’identità che useranno i tuoi server, prima di fare affidamento su questo fornitore di credenziali.

Verificare il provider

Dopo aver modificato le impostazioni e riavviato il server, cerca questa riga nel log del server. Indica che il server ha trovato una credenziale per il provider:

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

La riga non dimostra che il tuo account abbia un modello abilitato. Un modello mancante si manifesta come session.error al primo turno che lo usa.

Un gateway che indichi in ANTHROPIC_BASE_URL potrebbe rifiutare il campo o l’header del fallback lato server. Se ogni turno fallisce per questo motivo, imposta inference.model_fallback: false nel file delle impostazioni.