Servizi per modelli personalizzati

Un servizio modello è un endpoint che traduce e instrada le richieste di inferenza a uno o più modelli, con suddivisione del traffico e fallback. Supporta richieste in tempo reale, oltre all'inferenza batch.

Crea un servizio modello personalizzato per casi d'uso come:

  • Un endpoint indipendente dal modello per un'applicazione. Offri a un assistente assistenza clienti un servizio chiamato production.ai.support-assistant. Cambia il modello sottostante senza cambiare il nome che l'applicazione chiama.
  • Routing personalizzato e soluzioni di riserva. Usa la divisione del traffico per inviare 10% di traffico a un nuovo modello prima di un lancio più ampio, oppure configura una destinazione di backup per richieste fallite.
  • Un budget per un carico di lavoro. Contrassegna un servizio con project=support-assistant e applica un budget mensile a tale tag, con un avviso al raggiungimento di una spesa di 1.000 dollari.
  • Controlli di accesso per un team. Concedere al team legale e ai principali dei servizi applicativi l'accesso a un legal-review servizio, e utilizzare servizi separati per gli altri team.
  • Limiti di tariffa per un carico di lavoro. Configura un servizio di test per 100 richieste al minuto e un servizio di produzione per 1.000 richieste al minuto utilizzando limiti di velocità di servizio.
  • Monitoraggio e log separati. Invia le richieste e le risposte di un assistente di supporto a una tabella di inferenza dedicata in modo che il suo traffico possa essere ispezionato separatamente dal traffico dell'agente di codifica.

Per interrogare un modello di fondazione servito da Azure Databricks senza creare un servizio, utilizzare un servizio modello fornito dal sistema in system.ai.

Un servizio può instradare verso modelli serviti da Azure Databricks, utilizzando pay-per-token o throughput provisionato, oppure verso modelli esterni tramite un fornitore di modelli. Puoi combinare queste destinazioni in un unico servizio.

I servizi di modelli personalizzati sono oggetti protetti di Unity Catalog. I chiamanti li richiamano tramite il loro nome completo, catalog.schema.name, tra le aree di lavoro o dall'esterno di Azure Databricks. Vedi Governance e privilegi.

Requirements

Nota

Unity Gateway non è supportato su Azure per enti pubblici.

  • Uno spazio di lavoro Azure Databricks in una regione supportata da Unity Gateway.
  • 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 fornitore modello che 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.

Crea un servizio di modelli personalizzati

Crea un servizio modello nell'interfaccia utente Unity Gateway o nell'esplora catalogo. Per crearne uno programmaticamente, usa l'API REST, gli Azure Databricks SDK, la CLI di Azure Databricks, Terraform o i Declarative Automation Bundles (DAB).

I servizi modello e i fornitori di modelli condividono un unico namespace all'interno di uno schema del Catalogo Unity. Non puoi usare un nome per un servizio modello se un fornitore 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 servito da Azure Databricks su cui hai EXECUTE e di cui Unity Gateway può eseguire il serving, oppure un 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
      }]
    }
  }
}

DAB (Beta)

Definisci il servizio modello in un bundle e distribuiscilo con databricks bundle deploy. La configurazione di routing deve avere almeno una destinazione:

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

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

Go Modular SDK

Crea e gestisci un servizio modello con l'SDK Databricks AI Gateway per Go. I campi opzionali sono puntatori, quindi l'esempio utilizza una funzione di supporto su una sola riga, 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"),
						},
					},
				}},
			},
		},
	},
})

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

SDK modulare JS

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

CLI

Concedi EXECUTE con la CLI di Databricks. Per installare la CLI, vedi Installa o aggiorna la CLI Databricks.

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

Terraform

Grant EXECUTE con il fornitore Databricks Terraform e la databricks_grant risorsa:

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

DAB (Beta)

Aggiungi un grants blocco alla risorsa di servizio modello nel tuo bundle e ridistribuisci per concedere l'accesso.

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]

PYTHON SDK

Concedere EXECUTE con SDK Databricks per 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])],
)

SDK di sviluppo Go

Concedere EXECUTE con l'SDK di Databricks per 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},
	}},
})

Java SDK

Concedere EXECUTE con l'SDK di Databricks per 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)))));

Vedi Scopri e regola l'accesso ai servizi modello per maggiori informazioni su come concedere e scoprire l'accesso.

Configura le funzionalità su un servizio modello

Configura i limiti di velocità, la registrazione delle inferenze e i guardrail implementati con le policy di servizio sul servizio modello dall'interfaccia Unity Gateway. See:

Registrazione di inferenza

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 modello dall'interfaccia Unity Gateway o dall'Esplora catalogo. 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.

DAB (Beta)

Modifica comment (o qualsiasi altro campo mutabile) nella risorsa bundle ed esegui databricks bundle deploy. 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"},
})

Go Modular SDK

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

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

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

Elimina 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 del modello nell'interfaccia utente di Unity Gateway o in Catalog Explorer 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.

DAB (Beta)

Rimuovi la risorsa dal bundle e corri databricks bundle deploy per eliminarla. databricks bundle destroy Funziona anche, ma rimuove tutte le risorse gestite dal bundle, non solo questa.

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

Go Modular SDK

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

Java SDK

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

SDK modulare JS

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

Governo e privilegi

Come oggetto sicurabile dal Catalogo Unity, un servizio modello:

  • Si trova in un catalogo e in uno schema, in cui eredita le impostazioni dello schema, ad esempio le associazioni dell'area di lavoro.
  • Contiene metadati standard del catalogo Unity, ad esempio nome, proprietario, commento e tag.
  • È disciplinato dai privilegi del catalogo Unity, in modo da concedere l'accesso usando le stesse GRANT istruzioni e REVOKE usate per tabelle, funzioni e modelli.
  • È individuabile in Esplora cataloghi, insieme al resto degli asset del catalogo Unity.

Si applicano i privilegi seguenti:

Privilegio Description
USE CATALOG, USE SCHEMA Accedere al catalogo e allo schema che contengono il servizio modello. Obbligatorio per tutte le operazioni.
CREATE SERVICE Creare servizi modello in uno schema. Concesso nel catalogo o nello schema.
EXECUTE Interrogare un servizio del modello.
MANAGE Modificare o eliminare un servizio di modello e gestire le relative autorizzazioni. Il proprietario ha un sovrainsieme di MANAGE.

I servizi modello utilizzano i privilegi del definer. Azure Databricks valuta una query in base ai privilegi del proprietario piuttosto che a quelli del chiamante. Quando un utente esegue una query su un servizio di modelli, Azure Databricks verifica che il proprietario disponga di EXECUTE nelle destinazioni a cui viene fatto riferimento, ad esempio i modelli sottostanti ed eventuali fornitori di modelli. Il chiamante non ha bisogno di accesso diretto a quelle destinazioni.

Limitations

Le seguenti funzionalità non sono supportate:

  • Creare e gestire servizi modello con SQL.
  • Individuazione dei servizi modello con solo i BROWSE privilegi.
  • Ricerca globale di servizi modello.

Risorse aggiuntive

  • Ultimo aggiornamento: