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

Enregistrer un fournisseur de modèles externe comme service de fournisseur modèle, lui accorder l’accès, configurer les fonctionnalités de la passerelle Unity, puis le supprimer.

Exigences

  • CREATE SERVICE sur le schéma dans lequel est créé le service de fournisseur de modèles, ainsi que USE CATALOG et USE SCHEMA sur son catalogue et son schéma.
  • Informations d’identification du fournisseur externe que vous souhaitez inscrire (par exemple, une clé API OpenAI ou une paire de clés d’accès AWS).
  • Pour authentifier Azure OpenAI ou Microsoft Foundry avec un identifiant de service plutôt qu’avec une clé ou un secret, vous avez besoin d’un identifiant de service existant et de ACCESS sur celui-ci. Voir Authentifier Azure OpenAI ou Microsoft Foundry avec une certification de service.

Créer un service de fournisseur modèle

Les services de fournisseur de modèles et les services de modèle partagent un espace de noms unique au sein d’un schéma de catalogue Unity. Vous ne pouvez pas utiliser de nom pour un service de fournisseur de modèles 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èles dans l’interface Unity Gateway UI ou dans Catalog Explorer, ou programmatiquement avec l’API REST, les SDK Azure Databricks, la CLI Azure Databricks, ou Terraform.

Interface utilisateur

  1. Effectuez l’une des actions suivantes :
    • Dans la barre latérale de l’espace de travail, cliquez sur AI Gateway, puis ouvrez l’onglet Fournisseurs et cliquez sur Fournisseur.
    • Dans l’Explorateur de catalogue, allez dans le schéma où vous souhaitez créer le service fournisseur de modèles, cliquez sur Créer>un service, puis sélectionnez Service de fournisseur modèle dans la boîte de dialogue Créer un service .
  2. Entrez un nom pour le service du fournisseur de modèles, puis sélectionnez le catalogue et le schéma dans utilisant lequel le créer. Si vous démarrez à partir de l’Explorateur de catalogues, l’Explorateur de catalogues prérempli le catalogue et le schéma.
  3. Sélectionnez le type de fournisseur, puis entrez les informations d’identification et les détails de connexion du fournisseur.
  4. Cliquez sur Créer. Azure Databricks chiffre et stocke les informations d’identification. L’interface utilisateur ne les affiche pas après ce point.

API REST

Envoyez un POST à /api/2.1/unity-catalog/model-provider-services, en passant parent et model_provider_service_id comme paramètres de requête. Définissez provider_type et exactement un bloc de fournisseur correspondant ; targets liste explicitement les modèles upstream accessibles, et les secrets sont fournis directement en ligne en texte clair :

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

Passez le schéma parent et un nom de feuille, puis renseignez la configuration avec --json. Définissez provider_type et un seul bloc fournisseur correspondant ; targets permet de lister les modèles amont accessibles, et les secrets sont fournis en ligne sous forme de texte clair. Pour installer l’interface de ligne de commande, consultez Installer ou mettre à jour Databricks CLI.

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éer et gérer un service de fournisseur modèle avec le fournisseur Databricks Terraform et la ressource databricks_ai_gateway_model_provider_service . N’incluez pas de vraies clés dans le contrôle de code source ; transmettez la clé API via une variable sensitive = true (définie avec -var ou avec une variable d’environnement TF_VAR_provider_api_key) :

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 }
      }
    }
  }
}

Kit de développement logiciel (SDK) Python

Créer et gérer un service de fournisseur de modèles avec le SDK Databricks pour 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"
                    ),
                )
            ),
        ),
    ),
)

Kit de développement logiciel (SDK) Go

Créer et gérer un service de fournisseur modèle avec le SDK Databricks for 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",
						},
					},
				},
			},
		},
	})

Kit de développement logiciel (SDK) Java

Créer et gérer un service de fournisseur de modèles avec le SDK Databricks pour 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éer et gérer un service de fournisseur modèle avec le SDK Databricks AI Gateway pour JavaScript :

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 la liste complète des fournisseurs et de leurs méthodes d’authentification, voir Gouverner les fournisseurs modèles externes (services de fournisseurs modèle).

Authentifier Azure OpenAI ou Microsoft Foundry avec une certification de service

Vous pouvez authentifier un fournisseur Azure OpenAI ou Microsoft Foundry à l’aide d’informations d’identification de service au lieu de stocker une clé API ou un secret client d’un principal de service Microsoft Entra ID. Un identifiant de service est associé à une identité Azure gérée par Unity Catalog, de sorte qu’aucun secret à longue durée de vie n’est copié dans le service du fournisseur de modèles : Azure Databricks obtient des jetons de courte durée à partir de cette identité pour authentifier chaque requête.

Créez le service de fournisseur modèle tel que décrit dans Créer un service de fournisseur modèle. Sélectionnez Azure OpenAI ou Microsoft Foundry comme type de fournisseur et entrez ses détails de connexion, y compris l’URL de base du point de terminaison. Ensuite, définissez Méthode d’authentification sur Identifiants de service et sélectionnez les identifiants au lieu de saisir une clé API ou un secret client. Une identifiante de service ne remplace que le secret, donc l’URL de base du point de terminaison reste requise.

Vérifiez les conditions suivantes :

  • Le propriétaire du service du fournisseur de modèle dispose de ACCESS sur les informations d’identification du service. Parce qu'Azure Databricks vérifie à nouveau l'accès du propriétaire lors de la prise en charge des requêtes, celui-ci doit le conserver tant que le fournisseur est en service. Sa révocation interrompt les requêtes pour tout le monde, même les appelants qui disposent de EXECUTE sur le fournisseur. Pour accorder au propriétaire l’accès à la certification :

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

  • Le but de la certification est le service, pas le stockage.

  • La certification est disponible dans les espaces de travail d’où proviennent les demandes. Ses liaisons d’espace de travail s’appliquent toujours, donc une requête d’un espace de travail auquel l’identifiant n’est pas lié échoue là-bas, même si le service fournisseur de modèles lui-même est accessible depuis n’importe quel espace de travail partageant le metastore.

  • L'identité Azure des informations d'identification du service est autorisée à appeler les déploiements Azure OpenAI ou Microsoft Foundry que vous prévoyez d'interroger. Pour créer des informations d’identification de service, consultez Créer des informations d’identification de service.

Les appelants qui interrogent le prestataire ont besoin des mêmes subventions que pour tout autre prestataire. Ils n’ont pas besoin d’aucun privilège sur la carte de service, ce qui empêche la certification elle-même de leur portée.

Le service du fournisseur de modèles suit un identifiant d’accès par son identifiant interne, ce qui vous permet de renommer un identifiant d’accès sans provoquer l’échec de la requête.

Si vous supprimez une accréditation, les requêtes échouent et il n’y a aucun avertissement indiquant qu’un service de fournisseur modèle la référence. Vérifiez qu’il n’y a aucune référence à cette qualification avant de la supprimer.

Vous ne pouvez pas basculer un service de fournisseur existant entre l’identifiant du service et l’authentification de clé API ou de secret client. Créez plutôt un nouveau service de fournisseur modèle.

Envoyez une clé API fournisseur personnalisée dans un en-tête

Un fournisseur personnalisé envoie par défaut sa clé API en tant que jeton porteur. Lorsque votre point de terminaison attend plutôt la clé dans un en-tête spécifique, utilisez l’authentification par clé API dans l’en-tête et spécifiez vous-même le nom de l’en-tête. Azure Databricks envoie ensuite la clé sur chaque requête sortante sous la forme <header name>: <header value>.

Créez le service de fournisseur modèle tel que décrit dans Créer un service de fournisseur modèle. Sélectionnez Personnalisé comme type de fournisseur, puis définissez la méthode Auth sur l’en-tête clé API et fournissez le nom d’en-tête que votre endpoint attend (comme X-API-Key ou Ocp-Apim-Subscription-Key) ainsi que la valeur de l’en-tête.

Les deux méthodes sont mutuellement exclusives : un fournisseur personnalisé utilise soit un jeton porteur, soit un en-tête nommé, et non les deux. L’authentification par en-tête utilise exactement un seul en-tête.

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

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

Par défaut, seul le propriétaire du service du fournisseur modèle peut l’interroger. Pour permettre à d’autres 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 fournisseur de modèle consigne les données dans une table d’inférence, accordez-lui SELECT sur la table pour lui permettre de lire les requêtes et les réponses consignées.

Interface utilisateur

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

API REST

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

CLI

Grant EXECUTE avec la interface de code de Databricks. Pour installer l’interface de ligne de commande, consultez Installer ou mettre à jour Databricks CLI.

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

Terraform

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

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

Kit de développement logiciel (SDK) Python

Accorder EXECUTE avec le Databricks SDK for 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])],
)

Kit de développement logiciel (SDK) Go

Accorder EXECUTE avec le SDK Databricks pour 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},
	}},
})

Kit de développement logiciel (SDK) Java

Subvention EXECUTE avec le SDK Databricks pour 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, voir Découvrir et régir l’accès aux fournisseurs modèles externes (services fournisseurs modèles).

Configurer des fonctionnalités

Parce qu’un service de fournisseur de modèles transite par Unity Gateway, appliquez les mêmes fonctionnalités de gouvernance et d’observabilité que celles que vous utilisez pour les autres flux de trafic Unity Gateway :

Mettre à jour un service de fournisseur modèle

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

Interface utilisateur

Modifiez la configuration du service fournisseur de modèles depuis l’interface Unity Gateway ou l’Explorateur de catalogue. Les modifications s’appliquent directement.

API REST

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

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

Terraform

Modifie comment (ou tout autre champ changeable) sur la databricks_ai_gateway_model_provider_service ressource et réapplique. Les modifications s’appliquent directement.

Kit de développement logiciel (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"
    ),
)

Kit de développement logiciel (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",
		},
	})

Kit de développement logiciel (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

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èles

Vous devez être propriétaire ou avoir MANAGE.

Interface utilisateur

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

API REST

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

CLI

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

Terraform

Exécute terraform destroy, ou supprime le bloc de ressources et réapplique.

Kit de développement logiciel (SDK) Python

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

Kit de développement logiciel (SDK) Go

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

Kit de développement logiciel (SDK) Java

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

JS SDK

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

Étapes suivantes

  • Last updated on