Créer et gérer des API modèles (services modèles)

Créez, partagez et gérez vos propres API de modèles (services de modèles) dans le catalogue Unity.

Tip

Les API de modèles fournies par le système dans le system.ai schéma sont prêtes à être interrogées sans aucune configuration. Créez votre propre API de modèle uniquement lorsque vous souhaitez gouverner des modèles supplémentaires ou exposer un point de terminaison personnalisé.

Requirements

  • Espace de travail Azure Databricks dans une région prise en charge par Unity AI 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 sur chaque service fournisseur de modèles que le service modèle référence 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èle

Vous pouvez créer un service modèle dans l’interface Unity AI Gateway UI ou dans Catalog Explorer, ou programmatiquement avec l’API REST, les SDK Azure Databricks, la CLI Azure Databricks ou Terraform.

Les services de modèle et les services de fournisseur de modèles 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 modèle si un service fournisseur de modèles dans le schéma l’utilise déjà, et vice versa.

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. Il peut s’agir d’un modèle hébergé par Databricks sur lequel vous avez EXECUTE et que Unity AI Gateway peut servir, ou d’un service de 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.

API REST

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

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

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)));

JS SDK

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

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.

API REST

databricks api patch \
  "/api/2.1/unity-catalog/permissions/model_service/main.default.my_model_service" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["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 API modèles (services modèles).

Configurer des fonctionnalités sur un service de modèle

Vous configurez des fonctionnalités telles que les limites de débit, la journalisation des inférences et les garde-fous sur le service de modèle à partir de l’interface utilisateur de la passerelle AI Unity, de la même façon que vous les configurez sur un point de terminaison Unity AI 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

Modifier la configuration du service de modèles depuis l’interface Unity AI Gateway ou l’Explorateur de catalogue. Les modifications sont appliquées directement.

API REST

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.

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"},
})

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")));

JS SDK

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 de 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 AI 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-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.

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",
})

Kit de développement logiciel (SDK) Java

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

JS SDK

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

Étapes suivantes

  • Last updated on