Créer et gérer des fournisseurs de modèles externes (services de fournisseur de modèle)

Enregistrez un fournisseur de modèles externe en tant que service de fournisseur de modèles, accordez-lui l’accès, configurez les fonctionnalités de Unity Gateway et supprimez-le.

Exigences

• CREATE SERVICE dans le schéma où vous créez le service du fournisseur de modèle, ainsi que USE CATALOG et USE SCHEMA sur son catalogue et son schéma.
• Les informations d'identification du fournisseur externe que vous souhaitez enregistrer (par exemple, une clé API OpenAI ou une paire de clés d'accès AWS).
• Pour authentifier Google Gemini Enterprise avec un identifiant de service plutôt qu’avec une clé API, vous avez besoin d’un identifiant de service existant et de ACCESS sur celui-ci. Voir Authentifier Google Gemini Enterprise avec un identifiant de service.

Créer un service de fournisseur de modèle

Les services de fournisseur de modèle et les services de modèle partagent un espace de noms unique au sein d'un schéma Unity Catalog. Vous ne pouvez pas utiliser un nom pour un service de fournisseur de modèle si un service de modèle dans le schéma l'utilise déjà, et vice versa.

Vous pouvez créer un service de fournisseur de modèle dans l’interface utilisateur de Unity Gateway ou dans Catalog Explorer, ou par programmation avec l’API REST, les SDK Databricks, la CLI Databricks ou Terraform.

UI

1. Effectuez l'une des actions suivantes :

   • Dans la barre latérale du Workspace, cliquez sur AI Gateway , puis ouvrez l'onglet tab et cliquez sur Provider .
   • Dans Catalog Explorer, accédez au schéma où vous souhaitez créer le service de fournisseur de modèle, cliquez sur Créer > Service , puis sélectionnez Service de fournisseur de modèle dans la boîte de dialogue Créer un service .

2. Saisissez un nom pour le service de fournisseur de modèle, et sélectionnez le catalogue et le schéma dans lesquels le créer. Si vous start à partir de l'Explorateur de catalogue, l'Explorateur de catalogue préremplit le catalogue et le schéma.

3. Sélectionnez le type de fournisseur, et entrez les détails de connexion et les identifiants du fournisseur.

4. Cliquez sur Créer. Databricks chiffre et stocke les identifiants. L'interface utilisateur ne les affiche pas au-delà de ce point.

REST API

Envoyez un POST à /api/2.1/unity-catalog/model-provider-services, en transmettant parent et model_provider_service_id en tant que parameters de query. Définissez provider_type et exactement un bloc fournisseur correspondant ; targets autorise les modèles en amont accessibles, et les clés secrètes sont fournies en ligne sous forme de texte brut :

Bash

databricks api post \
  "/api/2.1/unity-catalog/model-provider-services?parent=schemas/main.default&model_provider_service_id=my_provider" \
  --json '{
  "comment": "Routes to a custom OpenAI-compatible provider",
  "config": {
    "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM",
    "targets": [
      { "model": "gpt-4o", "native_api_types": ["openai/v1/chat/completions"] }
    ],
    "custom": {
      "direct": {
        "base_url": "https://api.example.com/v1",
        "api_key": { "plaintext": "dummy-api-key" }
      }
    }
  }
}'

CLI

Transmettez le schéma parent et un nom de feuille, et fournissez la configuration avec --json. Définissez provider_type et exactement un bloc de fournisseur correspondant ; targets met sur liste blanche les modèles en amont accessibles, et les secrets sont fournis en ligne sous forme de texte brut. Pour installer la CLI, consultez Installer ou mettre à jour la CLI Databricks.

Bash

databricks ai-gateway create-model-provider-service schemas/main.default my_provider --json '{
  "comment": "Routes to a custom OpenAI-compatible provider",
  "config": {
    "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM",
    "targets": [
      { "model": "gpt-4o", "native_api_types": ["openai/v1/chat/completions"] }
    ],
    "custom": {
      "direct": {
        "base_url": "https://api.example.com/v1",
        "api_key": { "plaintext": "dummy-api-key" }
      }
    }
  }
}'

Terraform

Créez et gérez un service de fournisseur de modèle avec le fournisseur Databricks Terraform et la ressource databricks_ai_gateway_model_provider_service. Ne stockez pas les clés réelles dans le contrôle de source en transmettant la clé API via une variable sensitive = true (définissez-la avec -var ou une variable d’environnement TF_VAR_provider_api_key) :

Hcl

variable "provider_api_key" {
  type      = string
  sensitive = true
}

resource "databricks_ai_gateway_model_provider_service" "example" {
  parent                    = "schemas/main.default"
  model_provider_service_id = "my_provider"
  comment                   = "Routes to a custom OpenAI-compatible provider"

  config = {
    provider_type = "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM"

    targets = [{
      model            = "gpt-4o"
      native_api_types = ["openai/v1/chat/completions"]
    }]

    custom = {
      direct = {
        base_url = "https://api.example.com/v1"
        api_key  = { plaintext = var.provider_api_key }
      }
    }
  }
}

Python SDK

Créez et gérez un service de fournisseur de modèles avec le SDK Databricks pour Python:

Python

from databricks.sdk.service import catalog as c

model_provider_service = w.ai_gateway.create_model_provider_service(
    parent="schemas/main.default",
    model_provider_service_id="my_provider",
    model_provider_service=c.ModelProviderService(
        comment="Routes to a custom OpenAI-compatible provider",
        config=c.ModelProviderServiceConfig(
            provider_type=(
                c.ModelProviderServiceConfigExternalModelProviderType
                .EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM
            ),
            targets=[
                c.ModelProviderServiceConfigModelTargetConfig(
                    model="gpt-4o",
                    native_api_types=["openai/v1/chat/completions"],
                )
            ],
            custom=c.ModelProviderServiceConfigCustomProviderConfig(
                direct=c.ModelProviderServiceConfigCustomProviderDirectConfig(
                    base_url="https://api.example.com/v1",
                    api_key=c.ModelProviderServiceConfigProviderSecret(
                        plaintext="dummy-api-key"
                    ),
                )
            ),
        ),
    ),
)

Go SDK

Créez et gérez un service de fournisseur de modèles avec le SDK Databricks pour Go:

Go

modelProviderService, err := w.AiGateway.CreateModelProviderService(ctx,
	catalog.CreateModelProviderServiceRequest{
		Parent:                 "schemas/main.default",
		ModelProviderServiceId: "my_provider",
		ModelProviderService: catalog.ModelProviderService{
			Comment: "Routes to a custom OpenAI-compatible provider",
			Config: &catalog.ModelProviderServiceConfig{
				ProviderType: catalog.ModelProviderServiceConfigExternalModelProviderTypeExternalModelProviderTypeCustom,
				Targets: []catalog.ModelProviderServiceConfigModelTargetConfig{{
					Model:          "gpt-4o",
					NativeApiTypes: []string{"openai/v1/chat/completions"},
				}},
				Custom: &catalog.ModelProviderServiceConfigCustomProviderConfig{
					Direct: &catalog.ModelProviderServiceConfigCustomProviderDirectConfig{
						BaseUrl: "https://api.example.com/v1",
						ApiKey: &catalog.ModelProviderServiceConfigProviderSecret{
							Plaintext: "dummy-api-key",
						},
					},
				},
			},
		},
	})

Java SDK

Créez et gérez un service de fournisseur de modèles avec le SDK Databricks pour Java:

Java

ModelProviderServiceConfig config =
    new ModelProviderServiceConfig()
        .setProviderType(
            ModelProviderServiceConfigExternalModelProviderType
                .EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM)
        .setTargets(
            Collections.singletonList(
                new ModelProviderServiceConfigModelTargetConfig()
                    .setModel("gpt-4o")
                    .setNativeApiTypes(
                        Collections.singletonList("openai/v1/chat/completions"))))
        .setCustom(
            new ModelProviderServiceConfigCustomProviderConfig()
                .setDirect(
                    new ModelProviderServiceConfigCustomProviderDirectConfig()
                        .setBaseUrl("https://api.example.com/v1")
                        .setApiKey(
                            new ModelProviderServiceConfigProviderSecret()
                                .setPlaintext("dummy-api-key"))));

ModelProviderService modelProviderService =
    w.aiGateway()
        .createModelProviderService(
            new CreateModelProviderServiceRequest()
                .setParent("schemas/main.default")
                .setModelProviderServiceId("my_provider")
                .setModelProviderService(
                    new ModelProviderService()
                        .setComment("Routes to a custom OpenAI-compatible provider")
                        .setConfig(config)));

JS SDK

Créez et gérez un service de fournisseur de modèles avec le SDK Databricks AI Gateway pour JavaScript:

TypeScript

import { ModelProviderServiceConfig_ExternalModelProviderType as ProviderType } from '@databricks/sdk-aigateway/v1';

const created = await client.createModelProviderService({
  parent: 'schemas/main.default',
  modelProviderServiceId: 'my_provider',
  modelProviderService: {
    comment: 'Routes to a custom OpenAI-compatible provider',
    config: {
      providerType: ProviderType.EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM,
      targets: [{ model: 'gpt-4o', nativeApiTypes: ['openai/v1/chat/completions'] }],
      provider: {
        $case: 'custom',
        custom: {
          providerMode: {
            $case: 'direct',
            direct: {
              baseUrl: 'https://api.example.com/v1',
              authMode: {
                $case: 'apiKey',
                apiKey: {
                  value: { $case: 'plaintext', plaintext: 'dummy-api-key' },
                },
              },
            },
          },
        },
      },
    },
  },
});

Pour obtenir la liste complète des fournisseurs et leurs méthodes d’authentification, consultez Gouverner les fournisseurs de modèles externes (services de fournisseur de modèles).

Authentifier Google Gemini Enterprise avec un identifiant de service

Vous pouvez authentifier un fournisseur Google Gemini Enterprise avec un identifiant de service au lieu de stocker une clé API. Un identifiant de service contient un compte de service Google Cloud régi par Unity Catalog, de sorte qu’aucune clé API à longue durée de vie n’est copiée dans le service de fournisseur de modèles : Databricks obtient des jetons à courte durée de vie à partir de ce compte de service pour authentifier chaque requête.

Créez le service de fournisseur de modèle comme décrit dans Create a model provider service. Sélectionnez Google Gemini Enterprise comme type de fournisseur et saisissez ses détails de connexion, y compris l’ID de projet GCP et la région. Définissez ensuite Auth method sur Service credential et sélectionnez l’identifiant au lieu de saisir une clé API. Un identifiant de service remplace uniquement le secret ; l’ID de projet GCP et la région restent donc requis.

Confirmez les exigences suivantes :

• Le propriétaire du service de fournisseur de modèle dispose de ACCESS sur l’identifiant de service. Comme Databricks revérifie l’accès du propriétaire lors du traitement des requêtes, le propriétaire doit le conserver tant que le fournisseur est utilisé. Sa révocation arrête les queries pour tout le monde, même pour les appelants qui détiennent EXECUTE sur le fournisseur. Pour accorder au propriétaire l’accès à l’identifiant :

  SQL

  GRANT ACCESS ON SERVICE CREDENTIAL <service-credential-name> TO `<model-provider-service-owner>`;

• L'objectif de l'identifiant est le service , et non le stockage.

• L'identifiant est disponible dans les Workspace d'où proviennent les requêtes. Ses liaisons de workspace s'appliquent toujours, de sorte qu'une requête provenant d'un workspace auquel l'identifiant n'est pas lié échouera, même si le service de fournisseur de modèles lui-même est accessible depuis n'importe quel workspace partageant le métastore.

• Le compte de service Google Cloud de l’identifiant de service est autorisé à appeler les modèles Gemini que vous prévoyez de query. Pour créer un identifiant de service, consultez Créer des identifiants de service.

Les appelants qui interrogent le fournisseur ont besoin des mêmes droits que pour tout autre fournisseur. Ils n'ont besoin d'aucun privilège sur l'identifiant de service, ce qui permet de garder l'identifiant lui-même hors de leur portée.

Le service de fournisseur de modèle suit un identifiant par son identifiant interne, vous pouvez donc renommer un identifiant sans échec de query.

Si vous supprimez une information d'identification, les queries échouent et aucun avertissement n'indique qu'un service de fournisseur de modèles y fait référence. Confirmez qu'il n'existe aucune référence à cet identifiant avant de le supprimer.

Vous ne pouvez pas basculer un service de fournisseur de modèle existant entre une authentification par identifiants de service et par clé API. Créez plutôt un nouveau service de fournisseur de modèle.

Envoyer une clé d'API de fournisseur personnalisée dans un en-tête

Un fournisseur personnalisé envoie sa clé API sous forme de jeton porteur par default. Lorsque votre endpoint attend plutôt la clé dans un en-tête spécifique, utilisez l'authentification par en-tête de clé API et nommez l'en-tête vous-même. Databricks envoie ensuite la clé sur chaque requête sortante sous la forme <header name>: <header value>.

Créez le service de fournisseur de modèle comme décrit dans Create a model provider service. Sélectionnez Custom comme type de fournisseur, puis définissez Auth method sur API key header et fournissez le Header name attendu par votre endpoint (tel que X-API-Key ou Ocp-Apim-Subscription-Key) ainsi que la Header value .

Les deux méthodes sont mutuellement exclusives : un fournisseur personnalisé utilise soit un jeton de porteur, soit un en-tête nommé, mais pas les deux. L'authentification par en-tête nécessite exactement un en-tête.

Le nom de l'en-tête doit être un nom d'en-tête HTTP valide : lettres, chiffres et caractères !#$%&'*+-.^_`|~, jusqu'à 255 caractères. Tout autre caractère est rejeté, y compris les espaces, les deux-points, les barres obliques et les sauts de ligne.

Accorder l’accès à un service de fournisseur de modèles

Par default, seul le propriétaire du service de fournisseur de modèles peut l’interroger. Pour permettre à d’autres utilisateurs d’interroger un service de fournisseur de modèles, accordez-leur EXECUTE sur celui-ci, ainsi que USE CATALOG et USE SCHEMA sur son catalogue et son schéma. Si le service de fournisseur de modèles enregistre des Logs dans une table d’inférence, accordez SELECT sur la table pour leur permettre de lire les requêtes et les réponses enregistrées.

UI

1. Ouvrez le service de fournisseur de modèle dans Catalog Explorer, ou accédez à AI Gateway et sélectionnez le service.
2. Accédez à l'onglet tab .
3. Cliquez sur Accorder .
4. Sélectionnez les utilisateurs, les groupes ou les Service Principal auxquels accorder l'accès.
5. Sélectionnez le privilège EXECUTE .
6. Cliquez sur Accorder .

REST API

Bash

databricks api patch \
  "/api/2.1/unity-catalog/permissions/model_provider_service/main.default.my_provider" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["EXECUTE"] }
    ]
  }'

CLI

Accordez EXECUTE avec la CLI Databricks. Pour installer la CLI, consultez Installer ou mettre à jour la CLI Databricks.

Bash

databricks grants update model_provider_service main.default.my_provider \
  --json '{"changes": [{"principal": "data-team", "add": ["EXECUTE"]}]}'

Terraform

Accordez EXECUTE avec le fournisseur Databricks Terraform et la ressource databricks_grant :

Hcl

resource "databricks_grant" "example" {
  model_provider_service = "main.default.my_provider"
  principal              = "data-team"
  privileges             = ["EXECUTE"]
}

Python SDK

Accordez EXECUTE avec le SDK Databricks pour Python:

Python

from databricks.sdk.service import catalog as c

w.grants.update(
    securable_type="model_provider_service",
    full_name="main.default.my_provider",
    changes=[c.PermissionsChange(principal="data-team", add=[c.Privilege.EXECUTE])],
)

Go SDK

Accordez EXECUTE avec le SDK Databricks pour Go:

Go

_, err := w.Grants.Update(ctx, catalog.UpdatePermissions{
	SecurableType: "model_provider_service",
	FullName:      "main.default.my_provider",
	Changes: []catalog.PermissionsChange{{
		Principal: "data-team",
		Add:       []catalog.Privilege{catalog.PrivilegeExecute},
	}},
})

Java SDK

Accordez EXECUTE avec le SDK Databricks pour Java:

Java

w.grants().update(
    new UpdatePermissions()
        .setSecurableType("model_provider_service")
        .setFullName("main.default.my_provider")
        .setChanges(Arrays.asList(
            new PermissionsChange().setPrincipal("data-team").setAdd(Arrays.asList(Privilege.EXECUTE)))));

Pour en savoir plus sur l’octroi et la découverte d’accès, consultez Découvrir et gouverner l’accès aux fournisseurs de modèles externes (services de fournisseur de modèle).

Configurez les fonctionnalités

Comme un service de fournisseur de modèles passe par Unity Gateway, appliquez les mêmes fonctionnalités de gouvernance et d’observabilité que celles que vous utilisez pour les autres trafics Unity Gateway :

• Journalisation des inférences. Enregistrer les requêtes et les réponses dans une table Unity Catalog. Voir Logs les requêtes et les réponses dans les tables d'inférence.
• Limites de débit. Limitez les query par minute pour gérer la capacité et les coûts. Voir Appliquer des limites de débit aux services de modèle et MCP.
• Politiques de service. Gouvernez le contenu de chaque interaction, par exemple en bloquant les contenus dangereux ou en masquant les données sensibles, en associant une politique de service. Voir Politiques de service pour les éléments sécurisables IA et Créer et associer une politique de service.

Mettre à jour un service de fournisseur de modèles

Vous devez être propriétaire ou disposer de MANAGE. Le type de fournisseur est immuable.

UI

Modifiez la configuration du service de fournisseur de modèles depuis l'interface utilisateur de Unity Gateway ou l'Explorateur de catalogues. Les modifications s'appliquent sur place.

REST API

Bash

databricks api patch \
  "/api/2.1/unity-catalog/model-provider-services/main.default.my_provider?update_mask=comment" \
  --json '{"comment": "Updated: routes to a custom provider"}'

CLI

Bash

databricks ai-gateway update-model-provider-service model-provider-services/main.default.my_provider comment \
  --json '{"comment": "Updated: routes to a custom provider"}'

Terraform

Modifiez comment (ou tout autre champ mutable) sur la ressource databricks_ai_gateway_model_provider_service et réappliquez. Les modifications s’appliquent sur place.

Python SDK

Python

from databricks.sdk.service import catalog as c
from google.protobuf.field_mask_pb2 import FieldMask

updated = w.ai_gateway.update_model_provider_service(
    name="model-provider-services/main.default.my_provider",
    update_mask=FieldMask(paths=["comment"]),
    model_provider_service=c.ModelProviderService(
        comment="Updated: routes to a custom provider"
    ),
)

Go SDK

Go

updated, err := w.AiGateway.UpdateModelProviderService(ctx,
	catalog.UpdateModelProviderServiceRequest{
		Name:       "model-provider-services/main.default.my_provider",
		UpdateMask: *fieldmask.New([]string{"comment"}),
		ModelProviderService: catalog.ModelProviderService{
			Comment: "Updated: routes to a custom provider",
		},
	})

Java SDK

Java

ModelProviderService updated =
    w.aiGateway()
        .updateModelProviderService(
            new UpdateModelProviderServiceRequest()
                .setName("model-provider-services/main.default.my_provider")
                .setUpdateMask(FieldMask.newBuilder().addPaths("comment").build())
                .setModelProviderService(
                    new ModelProviderService()
                        .setComment("Updated: routes to a custom provider")));

JS SDK

TypeScript

import { modelProviderServiceFieldMask } from '@databricks/sdk-aigateway/v1';

const updated = await client.updateModelProviderService({
  modelProviderService: {
    name: 'model-provider-services/main.default.my_provider',
    comment: 'Updated: routes to a custom provider',
  },
  updateMask: modelProviderServiceFieldMask('comment'),
});

Supprimer un service de fournisseur de modèle

Vous devez être propriétaire ou disposer de MANAGE.

UI

Ouvrez le service de fournisseur de modèle dans l’interface utilisateur de Unity Gateway ou dans l’Explorateur de catalogues et sélectionnez Supprimer dans le menu kebab.

REST API

Bash

databricks api delete "/api/2.1/unity-catalog/model-provider-services/main.default.my_provider"

CLI

Bash

databricks ai-gateway delete-model-provider-service model-provider-services/main.default.my_provider

Terraform

Exécutez terraform destroy ou supprimez le bloc de ressources et réappliquez.

Python SDK

Python

w.ai_gateway.delete_model_provider_service(
    name="model-provider-services/main.default.my_provider"
)

Go SDK

Go

err := w.AiGateway.DeleteModelProviderService(ctx,
	catalog.DeleteModelProviderServiceRequest{
		Name: "model-provider-services/main.default.my_provider",
	})

Java SDK

Java

w.aiGateway()
    .deleteModelProviderService(
        new DeleteModelProviderServiceRequest()
            .setName("model-provider-services/main.default.my_provider"));

JS SDK

TypeScript

await client.deleteModelProviderService({
  name: 'model-provider-services/main.default.my_provider',
});

Étapes suivantes

• query des fournisseurs de modèles externes (services de fournisseur de modèles)
• Découvrir et gouverner l’accès aux fournisseurs de modèles externes (services de fournisseur de modèle)
• Gérer les fournisseurs de modèles externes (services de fournisseur de modèles)