Fournisseur d’inférence

Par défaut, votre serveur envoie les appels de modèle à l’API Claude. Cette page explique comment les envoyer à un fournisseur cloud, ou à une passerelle de modèles que vous exploitez. Pour changer de fournisseur :

1. Placez l’exemple de la section de votre fournisseur sur cette page dans le fichier de paramètres du serveur.
2. Fournissez au serveur les identifiants du fournisseur, comme l’indique la même section.
3. Redémarrez le serveur, comme l’indique Emplacement des paramètres. Sur Docker Compose, si l’étape 2 a modifié .env ou docker-compose.yml, exécutez plutôt docker compose up -d, car un redémarrage ne les relit pas.
4. Vérifiez le fournisseur.

Le paramètre inference.provider accepte ces valeurs :

Pour toutes les valeurs sauf anthropic, le serveur n’a besoin d’aucune clé API Claude. Il ignore ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN et ANTHROPIC_BASE_URL. La seule exception est une passerelle de modèles dont vous indiquez au serveur de lire la clé dans l’une de ces variables.

Les agents désignent les modèles par leurs identifiants de l’API Claude, tels que claude-opus-5-5. Le serveur traduit l’identifiant, de sorte qu’une définition d’agent fonctionne sans modification avec tout fournisseur qui sert ce modèle.

Certains outils et paramètres d’agent dépendent du fournisseur. Consultez Différences qui dépendent de votre fournisseur d’inférence.

Fournir au serveur un identifiant cloud

La manière dont les identifiants d’un fournisseur cloud parviennent au serveur dépend de votre installation :

• Docker Compose : Transmettez chaque variable et chaque fichier au serveur.
• Kubernetes : Le chart du serveur ne transmet aucune variable AWS, Google Cloud ou Azure, utilisez donc l’identité de charge de travail de votre cloud. Créez un compte de service avec l’annotation d’identité de charge de travail de votre cloud, et définissez server.serviceAccountName sur son nom. Le fichier values.yaml du chart nomme l’annotation. Sur Azure Kubernetes Service, définissez également 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

Le serveur signe ses appels avec les identifiants que la chaîne d’identifiants par défaut du SDK AWS trouve sur l’hôte. Il peut s’agir d’un rôle de tâche ou d’une identité de pod. Sur un poste de travail, il peut s’agir de AWS_PROFILE ou AWS_ACCESS_KEY_ID.

Activez dans le compte les modèles que vous utilisez. L’identité AWS avec laquelle le serveur signe a besoin de ces autorisations :

• bedrock:InvokeModel et bedrock:InvokeModelWithResponseStream sur les modèles et les profils d’inférence que vous utilisez.
• bedrock:ListFoundationModels et bedrock:ListInferenceProfiles sur la ressource *. Le serveur lit les listes de modèles d’Amazon Bedrock, afin que les agents puissent utiliser un modèle plus récent que la version de votre serveur. Pour ignorer cela, définissez inference.list_models: false.

Par défaut, le serveur place us.anthropic. devant chaque identifiant de modèle, ce qui désigne un « cross-region inference profile » (profil d’inférence interrégional). Pour utiliser une autre famille de profils, décommentez 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 est obligatoire. Il s’agit d’un emplacement de Google Cloud’s Agent Platform qui propose les modèles que vous utilisez, ou de global. project_id est le projet dans lequel les appels sont effectués et auquel ils sont facturés.

Le serveur utilise Google Application Default Credentials : le fichier que désigne GOOGLE_APPLICATION_CREDENTIALS, ou le compte de service que Compute Engine, Cloud Run ou GKE associe. Cette identité a besoin du rôle roles/aiplatform.user sur le projet. Le projet doit avoir l’API aiplatform.googleapis.com et les modèles Claude que vous utilisez activés.

Microsoft Foundry

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

resource est le nom de votre ressource Foundry, la première partie de son nom d’hôte : <resource>.services.ai.azure.com.

Les identifiants proviennent de l’environnement du serveur :

• Une clé API Foundry : Définissez ANTHROPIC_FOUNDRY_API_KEY. Dans la pile Compose, transmettez la variable au serveur. Sur Kubernetes, placez-la dans le Secret cma-server-upstream. Avec earlierNames: true dans votre fichier de valeurs du serveur, le Secret porte un autre nom. Vous le trouverez dans Kubernetes : les noms de vos objets.
• Microsoft Entra ID : Laissez ANTHROPIC_FOUNDRY_API_KEY non définie. Le serveur obtient alors un jeton pour un principal de service, une identité de charge de travail sur Azure Kubernetes Service, ou une identité managée. L’identité a besoin d’un rôle Azure sur la ressource Foundry qui autorise les appels à ses déploiements de modèles. Pour un principal de service, définissez AZURE_TENANT_ID, AZURE_CLIENT_ID et AZURE_CLIENT_SECRET.

Une requête vers Foundry désigne un déploiement, et le serveur envoie l’identifiant du modèle comme nom de déploiement. Si un déploiement porte un autre nom, faites-le correspondre avec model_id_overrides.

Faire correspondre un identifiant de modèle différent

Votre compte cloud peut proposer un modèle sous un identifiant différent de celui que le serveur envoie. Dans ce cas, décommentez les lignes model_id_overrides dans l’exemple de ce fournisseur, et faites correspondre l’identifiant de l’API Claude à l’identifiant de votre compte. Les deux identifiants doivent désigner le même modèle, car le serveur construit chaque requête pour le modèle que l’agent désigne.

Passerelle de modèles

Vérifiez d’abord quelles requêtes votre « model gateway » (passerelle de modèles) accepte :

• Les mêmes requêtes que l’API Claude, avec un seul identifiant à longue durée de vie : Conservez le fournisseur par défaut. Définissez ANTHROPIC_BASE_URL sur l’adresse de la passerelle, et définissez ANTHROPIC_API_KEY ou ANTHROPIC_AUTH_TOKEN sur les identifiants attendus par la passerelle.
• Les mêmes requêtes que l’API Claude, mais avec des jetons à courte durée de vie, des identifiants dans un autre en-tête, ou ses propres identifiants de modèle : Définissez inference.provider: gateway avec format: anthropic-messages.
• Le format InvokeModel d’Amazon Bedrock : Définissez inference.provider: gateway avec format: bedrock-invoke.
• Le format rawPredict de Claude Models on Google Cloud (Google managed) : Définissez inference.provider: gateway avec format: vertex-raw-predict.

Cet exemple définit inference.provider: gateway avec format: bedrock-invoke, pour une passerelle qui accepte une clé à longue durée de vie. Placez la clé dans une variable d’environnement et indiquez le nom de la variable, jamais sa valeur :

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 est la route de modèle de la passerelle. {model} indique l’emplacement de l’identifiant du modèle. L’URL doit commencer par https:// et se terminer par /invoke.
• model_map fait correspondre chaque identifiant de modèle qu’un agent peut désigner à l’identifiant attendu par la passerelle. Le serveur refuse un modèle qui n’a pas d’entrée.
• send_as désigne l’en-tête qui transporte la clé. Sans lui, le serveur envoie Authorization: Bearer <key>.
• Dans la pile Compose, transmettez la variable au serveur.
• Sur Kubernetes, le chart du serveur ne peut pas transmettre une variable de votre choix. Il transmet en revanche ANTHROPIC_AUTH_TOKEN, qu’il lit depuis le Secret cma-server-upstream, utilisez donc ce nom :
  1. Définissez env: { var: ANTHROPIC_AUTH_TOKEN }.
  2. Placez la clé de la passerelle dans le Secret cma-server-upstream, sous le nom ANTHROPIC_AUTH_TOKEN. Avec earlierNames: true dans votre fichier de valeurs du serveur, le Secret porte un autre nom. Vous le trouverez dans Kubernetes : les noms de vos objets.

Pour format: anthropic-messages, remplacez le bloc gateway par celui-ci :

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"

Ici, url est l’URL complète de la route Messages de la passerelle, sans {model}.

Pour format: vertex-raw-predict, remplacez le bloc gateway par celui-ci :

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"

Ici, url est la route rawPredict de la passerelle, et elle doit se terminer par /{model}:rawPredict. Une valeur de model_map ne peut pas contenir de deux-points. Le bloc credentials reste tel quel. Le serveur envoie les propres identifiants de votre passerelle et n’obtient aucun identifiant Google.

La référence de configuration liste les autres paramètres de la passerelle, comme streaming, ainsi que le paramètre inference.headers.

Jetons à courte durée de vie

Si votre passerelle accepte des jetons à courte durée de vie, remplacez le bloc credentials par celui-ci :

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"

Le serveur obtient alors chaque jeton en deux étapes. D’abord, il appelle un callback HTTP que vous développez. Le callback renvoie une assertion, une déclaration signée qui est généralement un « JSON Web Token » (jeton web JSON), ou JWT. Ensuite, le serveur échange l’assertion auprès de votre point de terminaison de jetons OAuth contre le jeton d’accès qu’il envoie à la passerelle.

• auth indique comment le serveur s’authentifie auprès du callback. L’exemple utilise un certificat client. Pour utiliser un jeton bearer que le serveur lit dans un fichier, définissez auth: { type: bearer_file, token_file: /etc/callback/token }.
• exchange désigne votre point de terminaison de jetons OAuth. Le serveur n’envoie à ce point de terminaison que grant_type et l’assertion, sans identifiant ni secret client.
• Si votre point de terminaison de jetons a besoin de plus que cela, omettez exchange. Faites en sorte que votre callback obtienne lui-même le jeton d’accès et le renvoie dans le champ assertion, que le serveur envoie ensuite à la passerelle.
• Sur Kubernetes, placez les fichiers de certificat dans un Secret, nommez-le dans server.extensionFiles.secretName du chart, et faites pointer cert_file et key_file vers /run/cma-server/extension-files/.

Le serveur envoie au callback une requête POST avec ce corps :

{
  "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 est l’appelant qui a créé la session. Pour un appelant en authentification unique, issuer est le issuer_url de cet appelant, et subject est le sujet de l’appelant. Pour la clé API du serveur, principal vaut {"issuer": "cma", "subject": "server"}. Faites en sorte que le callback ignore les champs qu’il ne connaît pas.

Le callback répond avec le statut 200 et ce corps :

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

reuse indique quelles sessions peuvent utiliser le jeton. Avec session, la valeur par défaut, seule la session de la requête le peut, ce qui convient à un jeton qui désigne un seul utilisateur. Avec deployment, les sessions partagent le jeton, ne renvoyez donc deployment que pour un jeton qui désigne votre organisation et aucune personne.

Si le callback ou le point de terminaison de jetons échoue, le tour se termine par un événement session.error de type model_request_failed_error, et la session reste utilisable. La raison figure dans le journal du serveur, sur une ligne contenant credential supplier failed.

Si la réponse du point de terminaison de jetons ne contient pas de expires_in et que le jeton n’a pas de revendication exp, le serveur envoie le jeton mais ne le stocke pas. Il demande alors un autre jeton à chaque appel de modèle.

Pour les autres paramètres, tels que renew_before et ca_file, consultez les tableaux de la référence de configuration consacrés aux paramètres de la passerelle de modèles et aux paramètres des jetons à courte durée de vie.

Jetons Microsoft Entra ID

Si votre passerelle vérifie les jetons Microsoft Entra ID par rapport à sa propre inscription d’application, remplacez le bloc credentials par celui-ci :

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

scope est l’URI d’ID d’application ou l’ID d’application de l’inscription d’application de la passerelle, suivi de /.default. Ne désignez que l’inscription propre à la passerelle. Un jeton destiné à une autre ressource permettrait à quiconque exploite la passerelle d’agir en tant que serveur auprès de cette ressource.

Le jeton est émis pour la propre identité Azure du serveur, configurée comme pour Microsoft Entra ID sous Microsoft Foundry. Si l’inscription exige un rôle d’application, attribuez ce rôle à l’identité avant de démarrer le serveur. Une attribution ultérieure ne prend effet que lorsque le serveur obtient un autre jeton.

Le jeton désigne cette identité et aucune personne, de sorte qu’une passerelle qui doit savoir quelle personne appelle a besoin de oauth_exchange. Exécutez un tour via votre passerelle, sous l’identité que vos serveurs utiliseront, avant de vous fier à ce fournisseur d’identifiants.

Vérifier le fournisseur

Après avoir modifié les paramètres et redémarré le serveur, recherchez cette ligne dans le journal du serveur. Elle indique que le serveur a trouvé des identifiants pour le fournisseur :

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

Cette ligne ne prouve pas que votre compte a un modèle activé. Un modèle manquant se manifeste par un session.error lors du premier tour qui l’utilise.

Une passerelle que vous désignez dans ANTHROPIC_BASE_URL peut rejeter le champ ou l’en-tête de repli côté serveur. Si chaque tour échoue pour cette raison, définissez inference.model_fallback: false dans le fichier de paramètres.