Creare e gestire API modello (servizi modello)

Crea, condividi e gestisci le tue API di modello (servizi modello) nel Catalogo Unity.

Tip

Le API dei modelli fornite dal sistema nello system.ai schema sono pronte per essere interrogate senza alcuna configurazione. Crea la tua API di modello solo quando vuoi governare modelli aggiuntivi o esporre un endpoint personalizzato.

Requirements

  • Un'area di lavoro Azure Databricks in un'area Unity AI Gateway supportata.
  • Catalogo Unity abilitato per l'area di lavoro. Vedere Abilitare un'area di lavoro per il Catalogo Unity.
  • Per creare un servizio modello, è necessario disporre di:
    • USE CATALOG, USE SCHEMAe CREATE SERVICE nel catalogo e nello schema in cui si crea il servizio modello.
    • EXECUTE in ogni modello a cui fa riferimento il servizio modello come destinazione.
    • EXECUTE, USE CATALOG e USE SCHEMA su ciascun servizio provider del modello a cui il servizio modello fa riferimento come destinazione.
    • USE CATALOG, USE SCHEMAe CREATE TABLE nel catalogo e nello schema in cui viene creata la tabella di inferenza, se si abilita la registrazione dell'inferenza.

Creare un servizio modello

Puoi creare un servizio modello nell'interfaccia di Unity AI Gateway o in Catalog Explorer, oppure programmaticamente con l'API REST, gli SDK di Azure Databricks, la CLI di Azure Databricks o Terraform.

I servizi modello e i servizi provider di modelli condividono uno spazio dei nomi singolo all'interno di uno schema del catalogo Unity. Non è possibile usare un nome per un servizio modello se un servizio provider di modelli nello schema lo usa già e viceversa.

Interfaccia utente

  1. Eseguire una delle operazioni seguenti:
    • Nella barra laterale dell'area di lavoro fare clic su Gateway di intelligenza artificiale e quindi su Crea.
    • In Catalog Explorer, vai allo schema in cui vuoi creare il servizio modello, quindi fai clic su Crea>Servizio>Servizio modello.
  2. Immettere un nome per il servizio modello e selezionare il catalogo e lo schema in cui crearlo. Se si inizia da Esplora cataloghi, Esplora cataloghi precompila il catalogo e lo schema.
  3. Seleziona la destinazione principale da servire. Questa destinazione può essere un modello ospitato da Databricks su cui hai EXECUTE e che Unity AI Gateway può mettere a disposizione, oppure un servizio provider di modelli su cui hai EXECUTE, USE CATALOG e USE SCHEMA.
  4. Clicca su Crea.

Dopo aver creato il servizio modello, Azure Databricks apre la relativa pagina di panoramica, in cui è possibile iniziare o configurare funzionalità aggiuntive, ad esempio la registrazione dell'inferenza.

REST API

Invia un POST a /api/2.1/unity-catalog/model-services, passando parent e model_service_id come parametri di query. La configurazione di routing deve avere almeno una destinazione:

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

Passa lo schema padre e un nome della foglia, e fornisci la configurazione con --json. La configurazione di routing deve avere almeno una destinazione. Per installare la CLI, vedi Installa o aggiorna la CLI Databricks.

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

Crea e gestisci un servizio modello con il fornitore Databricks Terraform e la risorsa 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
      }]
    }
  }
}

PYTHON SDK

Crea e gestisci un servizio modello con l'SDK Databricks per 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,
                    )
                ]
            )
        ),
    ),
)

SDK di sviluppo Go

Crea e gestisci un servizio modello con l'SDK Databricks per 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

Crea e gestisci un servizio modello con l'SDK Databricks per 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

Crea e gestisci un servizio modello con l'SDK Databricks AI Gateway per 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,
          },
        ],
      },
    },
  },
});

Concedere l'accesso a un servizio modello

Di default, solo il proprietario del servizio modello può interrogarlo. Per consentire ad altri di interrogare un servizio di modello, concedi loro EXECUTE su di esso, oltre a USE CATALOG e USE SCHEMA sul relativo catalogo e schema. Se il servizio modello accede a una tabella di inferenza, concedere SELECT alla tabella per consentire loro di leggere le richieste e le risposte registrate.

Interfaccia utente

  1. Apri il servizio modello in Catalog Explorer, oppure vai su AI Gateway e seleziona il servizio.
  2. Passare alla scheda Autorizzazioni .
  3. Fare clic su "Concedi".
  4. Selezionare gli utenti, i gruppi o le entità servizio a cui concedere l'accesso.
  5. Selezionare il privilegio EXECUTE .
  6. Fare clic su "Concedi".

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

Per maggiori informazioni sulla concessione e la scoperta dell'accesso, vedi Scopri e governa l'accesso alle API modello (servizi modello).

Configurare le funzionalità in un servizio modello

È possibile configurare funzionalità come limiti di frequenza, logging dell'inferenza e barriere di protezione nel servizio del modello dall'interfaccia utente di Unity AI Gateway, nello stesso modo in cui le si configura su un endpoint di Unity AI Gateway. See:

Registrazione delle inferenze

Quando si abilita la registrazione dell'inferenza, Azure Databricks crea una nuova tabella del catalogo Unity vuota con uno schema predefinito nella posizione specificata. Tenere presente quanto segue:

  • È necessario disporre di USE CATALOG, USE SCHEMA e CREATE TABLE sul catalogo e sullo schema di destinazione.
  • L'autore del servizio modello è il proprietario della tabella di inferenza. Nessun altro utente ha accesso a meno che non lo conceda.
  • Se una tabella esiste già nella posizione specificata, la creazione del servizio modello ha esito negativo.
  • La tabella di inferenza ha un ciclo di vita indipendente dal servizio modello. Se si elimina la tabella, il servizio del modello continua a funzionare ma smette di registrare i log.

Per maggiori informazioni sulle tabelle di inferenza, vedi Richieste di log e risposte alle tabelle di inferenza.

Aggiorna un servizio modello

Devi essere proprietario o avere MANAGE.

Interfaccia utente

Modifica la configurazione del servizio del modello nella UI di Unity AI Gateway o in Catalog Explorer. Le modifiche vengono applicate direttamente.

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

Modifica comment (o qualsiasi altro campo mutabile) sulla databricks_ai_gateway_model_service risorsa e riapplica. Le modifiche vengono applicate direttamente.

PYTHON SDK

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

SDK di sviluppo 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

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

Eliminare un servizio modello

Devi essere proprietario o avere MANAGE. I servizi modello forniti dal sistema in system.ai non possono essere eliminati.

Interfaccia utente

Apri il servizio modello nell'interfaccia di Unity AI Gateway o nell'Esplora cataloghi e seleziona Elimina dal 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

Esegui terraform destroy, oppure rimuovi il blocco risorsa e riapplica.

PYTHON SDK

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

SDK di sviluppo Go

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

Java SDK

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

Passaggi successivi

  • Last updated on