Services de modèles personnalisés

Un service de modèle est un point de terminaison qui traduit et achemine les requêtes d’inférence vers un ou plusieurs modèles, avec une répartition du trafic et des mécanismes de secours. Il prend en charge les requêtes en temps réel, ainsi que l’inférence par lots.

Créez un service modèle personnalisé pour des cas d’usage tels que :

  • Un point d’extrémité indépendant du modèle pour une application. Offrez à un assistant du service client un service nommé production.ai.support-assistant. Changer le modèle sous-jacent sans changer le nom que l’application appelle.
  • Routage personnalisé et mécanismes de repli. Utilisez la répartition du trafic pour envoyer 10% de flux vers un nouveau modèle avant un déploiement plus large, ou configurez une destination de secours pour les requêtes échouées.
  • Un budget pour une charge de travail. Attribuez une balise à un service avec project=support-assistant et associez un budget mensuel à cette balise, avec une alerte à 1 000 $ de dépenses.
  • Contrôles d’accès pour une équipe. Accorder à l’équipe juridique et à ses responsables de services d’application l’accès à un legal-review service, et utiliser des services séparés pour les autres équipes.
  • Des limites de taux pour une charge de travail. Configurez un service de test pour 100 requêtes par minute et un service de production pour 1 000 requêtes par minute en utilisant des limites de taux de service.
  • Séparez la surveillance et les journaux. Envoyez les demandes et réponses d’un assistant support à une table d’inférence dédiée afin que son trafic puisse être inspecté séparément du trafic de l’agent de codage.

Pour interroger un modèle de fondation servi par Azure Databricks sans créer de service, utilisez un service modèle fourni par le système dans system.ai.

Un service peut router vers des modèles servis par Azure Databricks, en utilisant le pay-per-token ou le débit provisionné, ou vers des modèles externes via un fournisseur de modèles. Vous pouvez fusionner ces destinations en un seul service.

Les services de modèles personnalisés sont des objets sécurisables de Unity Catalog. Les appelants les invoquent par leur nom pleinement qualifié, catalog.schema.name, à travers les espaces de travail ou depuis l’extérieur d’Azure Databricks. Voir Gouvernance et privilèges.

Requirements

Remarque

Unity Gateway n’est pas pris en charge sur Azure Government.

  • Un espace de travail Azure Databricks dans une région supportée par Unity Gateway.
  • Catalogue Unity activé pour votre espace de travail. Consultez Activer un espace de travail pour le Catalogue Unity.
  • Pour créer un service de modèle, vous devez disposer des éléments suivants :
    • USE CATALOG, USE SCHEMA et CREATE SERVICE sur le catalogue et le schéma dans lesquels vous créez le service de modèle.
    • EXECUTE sur chaque modèle référencé par le service de modèle en tant que destination.
    • EXECUTE, USE CATALOG et USE SCHEMA pour chaque fournisseur de modèles que le service de modèles désigne comme destination.
    • USE CATALOG, USE SCHEMA et CREATE TABLE sur le catalogue et le schéma où la table d’inférence est créée, si vous activez la journalisation de l’inférence.

Créer un service de modèles personnalisé

Créez un service modèle dans l’interface utilisateur Unity Gateway ou l’Explorateur de catalogue. Pour en créer un programmatiquement, utilisez l’API REST, les SDKs Azure Databricks, la CLI d’Azure Databricks, Terraform ou les Declarative Automation Bundles (DABs).

Les services de modèles et les fournisseurs de modèles partagent un seul espace de noms au sein d’un schéma de catalogue Unity. Vous ne pouvez pas utiliser un nom pour un service modèle si un fournisseur de modèle dans le schéma l’utilise déjà, et inversement.

Interface utilisateur

  1. Effectuez l’une des actions suivantes :
    • Dans la barre latérale de l’espace de travail, cliquez sur PASSERELLE AI, puis sur Créer.
    • Dans l’Explorateur de catalogue, accédez au schéma dans lequel vous souhaitez créer le service de modèle, puis cliquez sur Créer>Service>Service de modèle.
  2. Entrez un nom pour le service de modèle, puis sélectionnez le catalogue et le schéma dans lesquels 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 la destination principale à servir. Cette destination peut être un modèle servi par Azure Databricks sur lequel vous avez EXECUTE et que Unity Gateway peut exposer, ou un fournisseur de modèles sur lequel vous avez EXECUTE, USE CATALOG et USE SCHEMA.
  4. Cliquez sur Créer.

Après avoir créé le service de modèle, Azure Databricks ouvre sa page de vue d’ensemble, où vous pouvez commencer ou configurer des fonctionnalités supplémentaires telles que la journalisation d’inférence.

REST API

Envoyez un POST à /api/2.1/unity-catalog/model-services, en passant parent et model_service_id en tant que paramètres de requête. La configuration de routage doit avoir au moins une destination :

databricks api post \
  "/api/2.1/unity-catalog/model-services?parent=schemas/main.default&model_service_id=my_model_service" \
  --json '{
  "comment": "Routes chat traffic to a foundation model",
  "config": {
    "routing": {
      "destinations": [
        {
          "name": "primary",
          "destination_type": "DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL",
          "pay_per_token_config": { "model": "models/system.ai.databricks-gpt-5" },
          "traffic_percentage": 100
        }
      ]
    }
  }
}'

CLI

Passez le schéma parent et un nom de feuille, puis renseignez la configuration avec --json. La configuration de routage doit avoir au moins une destination. Pour installer l’interface de ligne de commande, consultez Installer ou mettre à jour Databricks CLI.

databricks ai-gateway create-model-service schemas/main.default my_model_service --json '{
  "comment": "Routes chat traffic to a foundation model",
  "config": {
    "routing": {
      "destinations": [
        {
          "name": "primary",
          "destination_type": "DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL",
          "pay_per_token_config": { "model": "models/system.ai.databricks-gpt-5" },
          "traffic_percentage": 100
        }
      ]
    }
  }
}'

Terraform

Créer et gérer un service modèle avec le fournisseur Databricks Terraform et la ressource databricks_ai_gateway_model_service :

resource "databricks_ai_gateway_model_service" "example" {
  parent           = "schemas/main.default"
  model_service_id = "my_model_service"
  comment          = "Routes chat traffic to a foundation model"

  config = {
    routing = {
      destinations = [{
        name                 = "primary"
        destination_type     = "DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL"
        pay_per_token_config = { model = "models/system.ai.databricks-gpt-5" }
        traffic_percentage   = 100
      }]
    }
  }
}

DABs (Bêta)

Définissez le service modèle dans un bundle et déployez-le avec databricks bundle deploy. La configuration de routage doit avoir au moins une destination :

resources:
  model_services:
    my_model_service:
      parent: schemas/main.default
      model_service_id: my_model_service
      comment: Routes chat traffic to a foundation model
      config:
        routing:
          destinations:
            - name: primary
              destination_type: DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL
              pay_per_token_config:
                model: models/system.ai.databricks-gpt-5
              traffic_percentage: 100

Kit de développement logiciel (SDK) Python

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

from databricks.sdk.service import catalog as c

model_service = w.ai_gateway.create_model_service(
    parent="schemas/main.default",
    model_service_id="my_model_service",
    model_service=c.ModelService(
        comment="Routes chat traffic to a foundation model",
        config=c.ModelServiceConfig(
            routing=c.ModelServiceConfigRoutingConfig(
                destinations=[
                    c.ModelServiceConfigDestinationConfig(
                        name="primary",
                        destination_type=(
                            c.ModelServiceConfigDestinationConfigDestinationType
                            .DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL
                        ),
                        pay_per_token_config=c.ModelServiceConfigPayPerTokenConfig(
                            model="models/system.ai.databricks-gpt-5"
                        ),
                        traffic_percentage=100,
                    )
                ]
            )
        ),
    ),
)

Kit de développement logiciel (SDK) Go

Créer et gérer un service modèle avec le SDK Databricks pour Go :

modelService, err := w.AiGateway.CreateModelService(ctx, catalog.CreateModelServiceRequest{
	Parent:         "schemas/main.default",
	ModelServiceId: "my_model_service",
	ModelService: catalog.ModelService{
		Comment: "Routes chat traffic to a foundation model",
		Config: &catalog.ModelServiceConfig{
			Routing: &catalog.ModelServiceConfigRoutingConfig{
				Destinations: []catalog.ModelServiceConfigDestinationConfig{{
					Name:            "primary",
					DestinationType: catalog.ModelServiceConfigDestinationConfigDestinationTypeDestinationTypePayPerTokenFoundationModel,
					PayPerTokenConfig: &catalog.ModelServiceConfigPayPerTokenConfig{
						Model: "models/system.ai.databricks-gpt-5",
					},
					TrafficPercentage: 100,
				}},
			},
		},
	},
})

SDK modulaire Go

Créer et gérer un service modèle avec le SDK IA Gateway Databricks pour Go. Les champs optionnels sont des pointeurs, donc l’exemple utilise un assistant en une ligne, func ptr[T any](v T) *T { return &v }.

modelService, err := c.CreateModelService(ctx, aigateway.CreateModelServiceRequest{
	Parent:         ptr("schemas/main.default"),
	ModelServiceId: ptr("my_model_service"),
	ModelService: &aigateway.ModelService{
		Comment: ptr("Routes chat traffic to a foundation model"),
		Config: &aigateway.ModelServiceConfig{
			Routing: &aigateway.ModelServiceConfig_RoutingConfig{
				Destinations: []aigateway.ModelServiceConfig_DestinationConfig{{
					Name:              ptr("primary"),
					DestinationType:   aigateway.ModelServiceConfig_DestinationConfig_DestinationType_DestinationTypePayPerTokenFoundationModel,
					TrafficPercentage: ptr(100),
					TypeConfig: &aigateway.ModelServiceConfig_DestinationConfig_TypeConfig_PayPerTokenConfig{
						PayPerTokenConfig: aigateway.ModelServiceConfig_PayPerTokenConfig{
							Model: ptr("models/system.ai.databricks-gpt-5"),
						},
					},
				}},
			},
		},
	},
})

Kit de développement logiciel (SDK) Java

Créer et gérer un service modèle avec le SDK Databricks pour Java :

ModelServiceConfig config =
    new ModelServiceConfig()
        .setRouting(
            new ModelServiceConfigRoutingConfig()
                .setDestinations(
                    Collections.singletonList(
                        new ModelServiceConfigDestinationConfig()
                            .setName("primary")
                            .setDestinationType(
                                ModelServiceConfigDestinationConfigDestinationType
                                    .DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL)
                            .setPayPerTokenConfig(
                                new ModelServiceConfigPayPerTokenConfig()
                                    .setModel("models/system.ai.databricks-gpt-5"))
                            .setTrafficPercentage(100L))));

ModelService modelService =
    w.aiGateway()
        .createModelService(
            new CreateModelServiceRequest()
                .setParent("schemas/main.default")
                .setModelServiceId("my_model_service")
                .setModelService(
                    new ModelService()
                        .setComment("Routes chat traffic to a foundation model")
                        .setConfig(config)));

SDK modulaire JS

Créer et gérer un service modèle avec le SDK Databricks AI Gateway pour JavaScript :

import { ModelServiceConfig_DestinationConfig_DestinationType as DestType } from '@databricks/sdk-aigateway/v1';

const created = await client.createModelService({
  parent: 'schemas/main.default',
  modelServiceId: 'my_model_service',
  modelService: {
    comment: 'Routes chat traffic to a foundation model',
    config: {
      routing: {
        destinations: [
          {
            name: 'primary',
            destinationType: DestType.DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL,
            typeConfig: {
              $case: 'payPerTokenConfig',
              payPerTokenConfig: { model: 'models/system.ai.databricks-gpt-5' },
            },
            trafficPercentage: 100,
          },
        ],
      },
    },
  },
});

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

Par défaut, seul le propriétaire du service modèle peut l’interroger. Pour permettre à d’autres d’interroger un service de modèle, accordez-leur EXECUTE sur celui-ci, ainsi que USE CATALOG et USE SCHEMA sur son catalogue et son schéma. Si le service 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 modèle dans l’Explorateur de catalogue, ou allez dans AI Gateway et sélectionnez le service.
  2. Accédez à l’onglet Autorisations.
  3. Cliquez sur Accorder.
  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 Accorder.

REST API

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

CLI

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

databricks grants update model_service main.default.my_model_service \
  --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_service = "main.default.my_model_service"
  principal     = "data-team"
  privileges    = ["EXECUTE"]
}

DABs (Bêta)

Ajoutez un grants bloc à la ressource de service modèle dans votre bundle et redéployez pour accorder l’accès.

resources:
  model_services:
    my_model_service:
      parent: schemas/main.default
      model_service_id: my_model_service
      comment: Routes chat traffic to a foundation model
      config:
        routing:
          destinations:
            - name: primary
              destination_type: DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL
              pay_per_token_config:
                model: models/system.ai.databricks-gpt-5
              traffic_percentage: 100
      grants:
        - principal: data-team
          privileges: [EXECUTE]

Kit de développement logiciel (SDK) Python

Accorder EXECUTE avec le SDK Databricks pour Python :

from databricks.sdk.service import catalog as c

w.grants.update(
    securable_type="model_service",
    full_name="main.default.my_model_service",
    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_service",
	FullName:      "main.default.my_model_service",
	Changes: []catalog.PermissionsChange{{
		Principal: "data-team",
		Add:       []catalog.Privilege{catalog.PrivilegeExecute},
	}},
})

Kit de développement logiciel (SDK) Java

Accorder EXECUTE avec le SDK Databricks pour Java :

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

Voir Découvrir et régir l’accès aux services modèles pour en savoir plus sur l’octroi et la découverte d’accès.

Configurer les fonctionnalités sur un service modèle

Configurez les limites de débit, la journalisation d’inférence et les garde-fous implémentés avec des politiques de service sur le service modèle depuis l’interface Unity Gateway. See:

Journalisation des inférences

Lorsque vous activez la journalisation de l’inférence, Azure Databricks crée une table de catalogue Unity vide avec un schéma prédéfini à l’emplacement que vous spécifiez. Notez les points suivants :

  • Vous devez avoir USE CATALOG, USE SCHEMAet CREATE TABLE sur le catalogue cible et le schéma.
  • Le créateur du service de modèles est le propriétaire de la table d’inférence. Aucun autre utilisateur n’a accès, sauf si vous l’accordez.
  • Si une table existe déjà à l’emplacement spécifié, la création du service de modèle échoue.
  • La table d’inférence a un cycle de vie indépendant du service de modèle. Si vous supprimez la table, le service de modèle continue de fonctionner mais arrête la journalisation.

Pour en savoir plus sur les tables d’inférence, voir Requêtes de journal et réponses aux tables d’inférence.

Mettre à jour un service modèle

Vous devez être propriétaire ou avoir MANAGE.

Interface utilisateur

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

REST API

databricks api patch \
  "/api/2.1/unity-catalog/model-services/main.default.my_model_service?update_mask=comment" \
  --json '{"comment": "Updated: routes chat traffic"}'

CLI

databricks ai-gateway update-model-service model-services/main.default.my_model_service comment \
  --json '{"comment": "Updated: routes chat traffic"}'

Terraform

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

DABs (Bêta)

Edit comment (ou tout autre champ mutable) dans la ressource bundle et exécute databricks bundle deploy. 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_service(
    name="model-services/main.default.my_model_service",
    update_mask=FieldMask(paths=["comment"]),
    model_service=c.ModelService(comment="Updated: routes chat traffic"),
)

Kit de développement logiciel (SDK) Go

updated, err := w.AiGateway.UpdateModelService(ctx, catalog.UpdateModelServiceRequest{
	Name:         "model-services/main.default.my_model_service",
	UpdateMask:   *fieldmask.New([]string{"comment"}),
	ModelService: catalog.ModelService{Comment: "Updated: routes chat traffic"},
})

SDK modulaire Go

mask, err := types.NewFieldMask[aigateway.ModelService]("comment")
updated, err := c.UpdateModelService(ctx, aigateway.UpdateModelServiceRequest{
	ModelService: &aigateway.ModelService{
		Name:    ptr("model-services/main.default.my_model_service"),
		Comment: ptr("Updated: routes chat traffic"),
	},
	UpdateMask: mask,
})

Kit de développement logiciel (SDK) Java

ModelService updated =
    w.aiGateway()
        .updateModelService(
            new UpdateModelServiceRequest()
                .setName("model-services/main.default.my_model_service")
                .setUpdateMask(FieldMask.newBuilder().addPaths("comment").build())
                .setModelService(
                    new ModelService().setComment("Updated: routes chat traffic")));

SDK modulaire JS

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

const updated = await client.updateModelService({
  modelService: {
    name: 'model-services/main.default.my_model_service',
    comment: 'Updated: routes chat traffic',
  },
  updateMask: modelServiceFieldMask('comment'),
});

Supprimer un service modèle

Vous devez être propriétaire ou avoir MANAGE. Les services de modèles fournis par le système dans system.ai ne peuvent pas être supprimés.

Interface utilisateur

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

REST API

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

CLI

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

Terraform

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

DABs (Bêta)

Retirez la ressource du bundle et exécutez databricks bundle deploy pour la supprimer. databricks bundle destroy fonctionne également, mais supprime toutes les ressources gérées par le bundle, et pas seulement cette ressource-ci.

Kit de développement logiciel (SDK) Python

w.ai_gateway.delete_model_service(name="model-services/main.default.my_model_service")

Kit de développement logiciel (SDK) Go

err := w.AiGateway.DeleteModelService(ctx, catalog.DeleteModelServiceRequest{
	Name: "model-services/main.default.my_model_service",
})

SDK modulaire Go

err := c.DeleteModelService(ctx, aigateway.DeleteModelServiceRequest{
	Name: ptr("model-services/main.default.my_model_service"),
})

Kit de développement logiciel (SDK) Java

w.aiGateway()
    .deleteModelService(
        new DeleteModelServiceRequest().setName("model-services/main.default.my_model_service"));

SDK modulaire JS

await client.deleteModelService({ name: 'model-services/main.default.my_model_service' });

Gouvernance et privilèges

En tant qu’objet sécurisé par Unity Catalog, un service modèle :

  • Réside dans un catalogue et un schéma, dont il hérite des paramètres, tels que les liaisons d’espace de travail.
  • Contient les métadonnées standard du catalogue Unity, telles que le nom, le propriétaire, le commentaire et les balises.
  • Est régi par les privilèges du catalogue Unity. Vous accordez donc l’accès à l’aide des mêmes GRANT instructions que REVOKE celles que vous utilisez pour les tables, les fonctions et les modèles.
  • Est détectable dans l’Explorateur de catalogues, en même temps que le reste de vos ressources de catalogue Unity.

Les privilèges suivants s’appliquent :

Privilège Description
USE CATALOG, USE SCHEMA Accédez au catalogue et au schéma qui contiennent le service de modèle. Obligatoire pour toutes les opérations.
CREATE SERVICE Créez des services de modélisation dans un schéma. Accordé au niveau du catalogue ou du schéma.
EXECUTE Interrogez un service de modèle.
MANAGE Modifiez ou supprimez un service de modèle et gérez ses subventions. Le propriétaire dispose d’un sur-ensemble de MANAGE.

Les services de modèle utilisent les privilèges du définisseur. Azure Databricks évalue une requête selon les privilèges du propriétaire plutôt que ceux de l'appelant. Lorsqu’un utilisateur interroge un service de modèles, Azure Databricks vérifie que le propriétaire a EXECUTE accès aux destinations référencées, telles que les modèles sous-jacents et tout fournisseur de modèles. L’appelant n’a pas besoin d’un accès direct à ces destinations.

Limitations

Les capacités suivantes ne sont pas prises en charge :

  • Créer et gérer des services de modèles avec SQL.
  • Découverte des services de modèle avec uniquement le privilège BROWSE.
  • Recherche mondiale de services de modèles.

Ressources supplémentaires

  • Dernière mise à jour :