Créer et gérer des APIs de modèle (services de modèle)

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

astuce

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

Exigences

• Un Databricks workspace dans une région prise en charge par Unity AI Gateway.
• Unity Catalog activé pour votre workspace. Consultez Activer un workspace pour Unity Catalog.
• 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 où vous créez le service de modèle.
  • EXECUTE sur chaque modèle que le service de modèle référence comme destination.
  • EXECUTE, USE CATALOG et USE SCHEMA sur chaque service de fournisseur de modèle que le service de 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 de modèle dans l’interface utilisateur de Unity AI Gateway ou dans Catalog Explorer, ou par programmation avec l’API REST, les SDK Databricks, la CLI Databricks ou Terraform.

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

UI

1. Effectuez l'une des actions suivantes :

   • Dans la barre latérale du Workspace, cliquez sur AI Gateway , puis sur Créer .
   • Dans l'Explorateur de catalogues, 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. Saisissez un nom pour le service de modèle, et sélectionnez le catalogue et le schéma dans lequel 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 la destination principale à servir. Cette destination peut être un modèle hébergé sur Databricks sur lequel vous avez EXECUTE et que Unity AI Gateway peut servir, ou 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, Databricks ouvre sa page d’aperçu, où vous pouvez commencer ou configurer des fonctionnalités supplémentaires telles que la journalisation de l’inférence.

REST API

Envoyez un POST à /api/2.1/unity-catalog/model-services, transmission de parent et model_service_id en tant que parameters de query. La configuration de routage doit comporter au moins une destination :

Bash

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

Transmettez le schéma parent et un nom de feuille, et fournissez la configuration avec --json. La configuration de routage doit comporter au moins une destination. Pour installer la CLI, consultez Installer ou mettre à jour la CLI Databricks.

Bash

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éez et gérez un service de modèle avec le fournisseur Databricks Terraform et la ressource databricks_ai_gateway_model_service :

Hcl

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

Python SDK

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

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

Go SDK

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

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

Java SDK

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

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éez et gérez un service de modèle avec le SDK Databricks AI Gateway pour JavaScript:

TypeScript

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

Par default, seul le propriétaire du service de modèle peut effectuer une query dessus. Pour permettre à d'autres personnes d'effectuer une query sur 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 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 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_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, consultez Découvrir et gouverner l’accès aux APIs de modèle (services de modèle).

Configurer les fonctionnalités d'un service de modèle

Vous configurez des fonctionnalités telles que les limites de taux, la journalisation de l'inférence et les garde-fous sur le service de modèle à partir de l'interface utilisateur de Unity AI Gateway, de la même manière que vous les configurez sur un Endpoint Unity AI Gateway. Voir :

• Appliquer des limites de débit aux services de modèle et MCP
• Logs les requêtes et les réponses dans les tables d’inférence

Journalisation des inférences

Lorsque vous activez la journalisation des inférences, Databricks crée une nouvelle table Unity Catalog vide avec un schéma prédéfini à l'emplacement que vous spécifiez. Notez ce qui suit :

• Vous devez disposer de USE CATALOG, USE SCHEMA et CREATE TABLE sur le catalogue et le schéma cibles.
• Le créateur du service de modèle est le propriétaire de la table d’inférence. Aucun autre utilisateur n’y a accès, sauf si vous l’y autorisez.
• 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 l'enregistrement.

Pour en savoir plus sur les tables d’inférence, consultez Logs les requêtes et les réponses dans des tables d’inférence.

Mettre à jour un service de modèle

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

UI

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

REST API

Bash

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

Bash

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

Terraform

Modifiez comment (ou tout autre champ mutable) sur la ressource databricks_ai_gateway_model_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_service(
    name="model-services/main.default.my_model_service",
    update_mask=FieldMask(paths=["comment"]),
    model_service=c.ModelService(comment="Updated: routes chat traffic"),
)

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

Java 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

TypeScript

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 disposer de MANAGE. Les services de fournisseur de modèles fournis par le système dans system.ai ne peuvent pas être supprimés.

UI

Ouvrez le service de modèle dans l’interface utilisateur Unity AI 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-services/main.default.my_model_service"

CLI

Bash

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

Terraform

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

Python SDK

Python

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

Go SDK

Go

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

Java SDK

Java

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

JS SDK

TypeScript

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

Étapes suivantes

• Services de modèle
• Interroger les services de modèles
• Découvrez et gouvernez l’accès aux services de modèle
• Intégration avec les agents de codage