Diensten voor aangepaste modellen

Een modelservice is een eindpunt dat inferentieverzoeken vertaalt en doorstuurt naar een of meer modellen, met verkeerssplitsing en fallbacks. Het ondersteunt realtime verzoeken, plus batchinferentie.

Maak een aangepaste modelservice voor gebruikssituaties zoals:

  • Een model-onafhankelijk eindpunt voor een applicatie. Geef een klantenservicemedewerker een dienst genaamd production.ai.support-assistant. Wijzig het onderliggende model zonder de naam te wijzigen die de applicatie aanroept.
  • Aangepaste routing en terugvalopties. Gebruik verkeerssplitsing om 10% verkeer naar een nieuw model te sturen vóór een bredere uitrol, of configureer een back-up bestemming voor mislukte verzoeken.
  • Een budget voor één workload. Tag een dienst met project=support-assistant en koppel een maandbudget aan die tag, met een waarschuwing bij $1.000 aan uitgaven.
  • Toegangscontroles voor een team. Geef het juridische team en de hoofdverantwoordelijken van de applicatiedienst toegang tot een legal-review dienst en gebruik aparte diensten voor andere teams.
  • Tarieflimieten voor een werkdruk. Configureer een testdienst voor 100 verzoeken per minuut en een productiedienst voor 1.000 verzoeken per minuut met servicesnelheidslimieten.
  • Aparte monitoring en logboeken. Stuur de verzoeken en antwoorden van een supportassistent naar een speciale inferentietabel zodat het verkeer afzonderlijk van het coderingsagentverkeer kan worden geïnspecteerd.

Om een Azure Databricks-bediend foundation-model te bevragen zonder een service aan te maken, gebruik je een systeem-geleverd modelservice in system.ai.

Een dienst kan worden doorgestuurd naar Azure Databricks-bediende modellen, met pay-per-token of provisioned throughput, of naar externe modellen via een modelprovider. Je kunt deze bestemmingen in één dienst mengen.

Aangepaste modelservices zijn beveiligbare objecten in Unity Catalog. Aanroepers roepen deze aan met hun volledig gekwalificeerde naam, catalog.schema.name, in verschillende werkruimten of buiten Azure Databricks. Zie Bestuur en privileges.

Requirements

Note

Unity Gateway wordt niet ondersteund op Azure Government.

  • Een Azure Databricks werkruimte in een door Unity Gateway ondersteunde regio.
  • Unity Catalog ingeschakeld voor uw werkruimte. Zie Een werkruimte inschakelen voor Unity Catalog.
  • Als u een modelservice wilt maken, moet u het volgende hebben:
    • USE CATALOG, USE SCHEMAen CREATE SERVICE in de catalogus en het schema waar u de modelservice maakt.
    • EXECUTE op elk model waarnaar de modelservice verwijst als een bestemming.
    • EXECUTE, USE CATALOG, en USE SCHEMA op elke modelprovider waarnaar de modeldienst als bestemming verwijst.
    • USE CATALOG, USE SCHEMA en CREATE TABLE op de catalogus en het schema waarin de inferentietabel wordt gemaakt, als u inferentielogboekregistratie inschakelt.

Maak een aangepaste modelservice aan

Maak een modelservice aan in de Unity Gateway UI of Catalog Explorer. Om er een programmatisch te maken, gebruik je de REST API, de Azure Databricks SDK's, de Azure Databricks CLI, Terraform of Declarative Automation Bundles (DABs).

Modelservices en modelproviders delen één naamruimte binnen een Unity Catalog-schema. Je kunt geen naam gebruiken voor een modeldienst als een modelprovider in het schema die al gebruikt, en andersom.

UI (Gebruikersinterface)

  1. Ga op een van de volgende manieren te werk:
    • Klik in de zijbalk van de werkruimte op AI Gateway en klik vervolgens op Maken.
    • Ga in Catalog Explorer naar het schema waarin u de modelservice wilt maken en klik vervolgensop >Servicemodel>maken.
  2. Voer een naam in voor de modelservice en selecteer de catalogus en het schema waarin u deze wilt maken. Als u begint met Catalog Explorer, vult Catalog Explorer de catalogus en het schema vooraf in.
  3. Selecteer de primaire bestemming om te bedienen. Deze bestemming kan een door Azure Databricks aangeboden model zijn waarvoor je EXECUTE hebt en dat Unity Gateway kan aanbieden, of een modelprovider waarvoor je EXECUTE, USE CATALOG en USE SCHEMA hebt.
  4. Klik op Create.

Nadat u de modelservice hebt gemaakt, opent Azure Databricks de overzichtspagina, waar u aan de slag kunt gaan of aanvullende functies kunt configureren, zoals deductielogboekregistratie.

REST API

Stuur een POST naar /api/2.1/unity-catalog/model-services, waarbij model_service_id en parent als queryparameters worden doorgegeven. De routeringsconfiguratie moet minstens één bestemming hebben:

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

Geef het bovenliggende schema en een leaf-naam door, en specificeer de configuratie met --json. De routeringsconfiguratie moet minstens één bestemming hebben. Om de CLI te installeren, zie Installeren of bijwerken de 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

Maak en beheer een modelservice met de Databricks Terraform-provider en de databricks_ai_gateway_model_service resource:

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 (Beta)

Definieer de modelservice in een bundel en deploy deze met databricks bundle deploy. De routeringsconfiguratie moet minstens één bestemming hebben:

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

Maak en beheer een modelservice met de Databricks SDK voor 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 Softwareontwikkelingskit

Maak en beheer een modelservice met de Databricks SDK voor 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

Creëer en beheer een modelservice met de Databricks AI Gateway SDK voor Go. Optionele velden zijn pointers, dus het voorbeeld gebruikt een eenregelige helper, 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

Maak en beheer een modelservice met de Databricks SDK voor 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 Modular SDK

Maak en beheer een modelservice met de Databricks AI Gateway SDK voor 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,
          },
        ],
      },
    },
  },
});

Toegang verlenen tot een modeldienst

Standaard kan alleen de eigenaar van de modelservice het opzoeken. Om anderen een modelservice te laten bevragen, verleent u hun USE CATALOG op die service, plus USE SCHEMA en EXECUTE op de catalogus en het schema ervan. Als de modelservice naar een inferentietabel logt, verleen dan SELECT op de tabel zodat de gelogde verzoeken en antwoorden kunnen worden gelezen.

UI (Gebruikersinterface)

  1. Open de modelservice in Catalog Explorer, of ga naar AI Gateway en selecteer de service.
  2. Ga naar het tabblad Machtigingen .
  3. Klik op Toestaan.
  4. Selecteer de gebruikers, groepen of service-principals om toegang te verlenen.
  5. Selecteer de execute-bevoegdheid .
  6. Klik op Toestaan.

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

Grant EXECUTE met de Databricks CLI. Om de CLI te installeren, zie Installeren of bijwerken de Databricks CLI.

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

Terraform

Geef een subsidie EXECUTE met de Databricks Terraform-provider en de databricks_grant bron:

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

DABs (Beta)

Voeg een grants blok toe aan de modelserviceresource in je bundel en deploy opnieuw om toegang te verlenen.

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

Toegang verlenen EXECUTE met de Databricks SDK voor 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])],
)

Go Softwareontwikkelingskit

Grant EXECUTE met de Databricks SDK voor 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

Grant EXECUTE met de Databricks SDK voor 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)))));

Zie Modelservices vinden en de toegang ertoe beheren voor meer informatie over het verlenen van en vinden van toegang.

Configureer functies op een modelservice

Configureer snelheidsbeperkingen, inferentielogging en guardrails die met servicebeleidsregels op de modelservice zijn geïmplementeerd, vanuit de Unity Gateway-UI. See:

Logboekregistratie voor inferentie

Wanneer u deductielogboekregistratie inschakelt, maakt Azure Databricks een nieuwe, lege Unity Catalog-tabel met een vooraf gedefinieerd schema op de locatie die u opgeeft. Houd rekening met het volgende:

  • U moet USE CATALOG, USE SCHEMA en CREATE TABLE hebben op de doelcatalogus en het schema.
  • De maker van de modelservice is de eigenaar van de inferentietabel. Geen andere gebruikers hebben toegang, tenzij u deze verleent.
  • Als er al een tabel bestaat op de opgegeven locatie, mislukt het maken van de modelservice.
  • De inferentietabel heeft een levenscyclus die onafhankelijk is van de modelservice. Als u de tabel verwijdert, blijft de modelservice werken, maar stopt deze met loggen.

Voor meer informatie over inferentietabellen, zie Logverzoeken en antwoorden op inferentietabellen.

Werk een modelservice bij

Je moet eigenaar zijn of over MANAGE beschikken.

UI (Gebruikersinterface)

Bewerk de configuratie van de modelservice vanuit de Unity Gateway UI of Catalog Explorer. Wijzigingen worden direct toegepast.

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

Bewerk comment (of een ander veranderbaar veld) op de databricks_ai_gateway_model_service bron en breng opnieuw aan. Wijzigingen worden direct toegepast.

DABs (Beta)

Bewerk comment (of een ander veranderbaar veld) in de bundelresource en voer databricks bundle deploy. Wijzigingen worden direct toegepast.

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

Go Softwareontwikkelingskit

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

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

Verwijder een modelservice

Je moet eigenaar zijn of over MANAGE beschikken. Door het systeem aangeboden modelservices in system.ai kunnen niet worden verwijderd.

UI (Gebruikersinterface)

Open de modelservice in de Unity Gateway UI of Catalog Explorer en selecteer Verwijderen in het kebabmenu.

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

Voer terraform destroyuit, of verwijder het resource block en breng het opnieuw toe.

DABs (Beta)

Verwijder de bron uit de bundel en voer databricks bundle deploy uit om hem te verwijderen. databricks bundle destroy werkt ook, maar het verwijdert alle bronnen die de bundel beheert, niet alleen deze.

Python SDK

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

Go Softwareontwikkelingskit

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

JS Modular SDK

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

Bestuur en privileges

Als beveiligbaar object in Unity Catalog heeft een modelservice de volgende eigenschappen:

  • Woont in een catalogus en schema, waar schema-instellingen, zoals werkruimtebindingen, worden overgenomen.
  • Bevat standaard metagegevens van Unity Catalog, zoals naam, eigenaar, opmerking en tags.
  • Wordt beheerd door Unity Catalog-bevoegdheden, zodat u toegang verleent met behulp van dezelfde GRANT en REVOKE instructies die u gebruikt voor tabellen, functies en modellen.
  • Kan worden gedetecteerd in Catalog Explorer, naast de rest van uw Unity Catalog-assets.

De volgende bevoegdheden zijn van toepassing:

Voorrecht Beschrijving
USE CATALOG, USE SCHEMA Open de catalogus en het schema die de modelservice bevatten. Vereist voor alle bewerkingen.
CREATE SERVICE Modelservices maken in een schema. Verleend op de catalogus of het schema.
EXECUTE Een query uitvoeren op een modelservice.
MANAGE Een modelservice wijzigen of verwijderen en de bijbehorende subsidies beheren. De eigenaar heeft een superset van MANAGE.

Modelservices gebruiken de privileges van definer. Azure Databricks beoordeelt een query op basis van de rechten van de eigenaar in plaats van die van de aanroeper. Wanneer een gebruiker een query uitvoert op een modelservice, controleert Azure Databricks of de eigenaar op de bestemmingen waarnaar wordt verwezen EXECUTE heeft, zoals de onderliggende modellen en eventuele modelaanbieders. De beller heeft geen directe toegang tot die bestemmingen nodig.

Limitations

De volgende mogelijkheden worden niet ondersteund:

  • Het creëren en beheren van modelservices met SQL.
  • Modelservices detecteren met alleen de BROWSE bevoegdheid.
  • Wereldwijde zoektocht naar modeldiensten.

Aanvullende bronnen

  • Laatst bijgewerkt om