Serviços de modelos personalizados

Um serviço de modelos é um endpoint que traduz e encaminha pedidos de inferência para um ou mais modelos, com divisão de tráfego e mecanismos de recurso. Suporta pedidos em tempo real, além de inferência em lote.

Crie um serviço de modelo personalizado para casos de uso como:

  • Um endpoint independente do modelo para uma aplicação. Dê a um assistente de apoio ao cliente um serviço chamado production.ai.support-assistant. Muda o modelo subjacente sem alterar o nome que a aplicação chama.
  • Roteamento personalizado e contingências. Use a divisão de tráfego para enviar 10% de tráfego para um novo modelo antes de uma implementação mais ampla, ou configure um destino de backup para pedidos falhados.
  • Um orçamento para uma carga de trabalho. Identifique um serviço com project=support-assistant e associe um orçamento mensal a essa etiqueta, com um alerta quando os gastos atingirem 1000 dólares.
  • Controlos de acesso para uma equipa. Conceder à equipa jurídica e aos seus responsáveis de serviços de aplicação acesso a um legal-review serviço, e utilizar serviços separados para outras equipas.
  • Limites de taxa para uma carga de trabalho. Configure um serviço de teste para 100 pedidos por minuto e um serviço de produção para 1.000 pedidos por minuto usando limites de taxa de serviço.
  • Monitorização e registos separados. Envie os pedidos e respostas de um assistente de suporte para uma tabela de inferência dedicada para que o seu tráfego possa ser inspecionado separadamente do tráfego do agente de codificação.

Para consultar um modelo de fundação servido pelo Azure Databricks sem criar um serviço, use um serviço modelo fornecido pelo sistema em system.ai.

Um serviço pode encaminhar pedidos para modelos disponibilizados pelo Azure Databricks, utilizando pay-per-token ou débito aprovisionado, ou para modelos externos através de um fornecedor de modelos. Pode misturar estes destinos num só serviço.

Os serviços de modelos personalizados são objetos protegíveis do Unity Catalog. Os chamadores invocam-nos pelo seu nome totalmente qualificado, catalog.schema.name, em espaços de trabalho ou fora do Azure Databricks. Ver Governação e privilégios.

Requirements

Note

O Unity Gateway não é suportado no Azure Government.

  • Um espaço de trabalho Azure Databricks numa região suportada pelo Unity Gateway.
  • Unity Catalog ativado para o seu espaço de trabalho. Consulte Habilitar um espaço de trabalho para o Unity Catalog.
  • Para criar um serviço modelo, deve ter:
    • USE CATALOG, USE SCHEMA e CREATE SERVICE no catálogo e no esquema onde cria o serviço de modelo.
    • EXECUTE em cada modelo que o serviço de modelos referencia como destino.
    • EXECUTE, USE CATALOG, e USE SCHEMA em cada fornecedor de modelos que o serviço de modelos tem como destino.
    • USE CATALOG, USE SCHEMA e CREATE TABLE no catálogo e no esquema onde a tabela de inferência é criada, caso ative o registo de inferência.

Criar um serviço personalizado de modelos

Crie um serviço modelo na interface do Unity Gateway ou no Explorador de Catálogos. Para criar uma programáticamente, use a API REST, os SDKs do Azure Databricks, a CLI do Azure Databricks, o Terraform ou os Pacotes de Automação Declarativa (DABs).

Os serviços de modelo e os fornecedores de modelos partilham um único espaço de nomes dentro de um esquema de Catálogo Unity. Não podes usar um nome para um serviço modelo se um fornecedor de modelos no esquema já o usar, e vice-versa.

IU

  1. Proceda de uma das seguintes formas:
    • Na barra lateral do espaço de trabalho, clique em AI Gateway e depois em Criar.
    • No Catalog Explorer, vá para o esquema onde pretende criar o serviço de modelo e, em seguida, clique em Criar>Serviço>Serviço de modelo.
  2. Introduza um nome para o serviço de modelo e selecione o catálogo e o esquema para o criar. Se começares pelo Explorador de Catálogos, o Explorador de Catálogos prepreenche o catálogo e o esquema.
  3. Selecione o destino principal a servir. Este destino pode ser um modelo disponibilizado pelo Azure Databricks que tem EXECUTE ativado e que o Unity Gateway consegue disponibilizar, ou um fornecedor de modelos em que tem EXECUTE, USE CATALOG e USE SCHEMA.
  4. Clique em Criar.

Depois de criar o serviço de modelo, o Azure Databricks abre a sua página de visão geral, onde pode começar ou configurar funcionalidades adicionais, como registo de inferências.

API REST

Enviar um POST para /api/2.1/unity-catalog/model-services, passando parent e model_service_id como parâmetros de consulta. A configuração de roteamento deve ter pelo menos um destino:

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

Passe o esquema principal e o nome de uma folha, e forneça a configuração com --json. A configuração de encaminhamento deve ter pelo menos um destino. Para instalar a linha de código, consulte Instalar ou atualizar a CLI de 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

Crie e gere um serviço modelo com o fornecedor Databricks Terraform e o recurso 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
      }]
    }
  }
}

DABs (Beta)

Defina o serviço modelo num bundle e implemente-o com databricks bundle deploy. A configuração de roteamento deve ter pelo menos um destino:

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

Criar e gerir um serviço de modelo com o SDK Databricks para 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 Desenvolvimento de Software Go

Crie e gere um serviço modelo com o SDK Databricks para 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

Crie e gira um serviço de modelo com o Databricks AI Gateway SDK for Go. Campos opcionais são ponteiros, por isso o exemplo usa uma função auxiliar de uma linha, 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"),
						},
					},
				}},
			},
		},
	},
})

SDK de Java

Crie e gere um serviço modelo com o SDK Databricks para 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

Crie e gere um serviço modelo com o Databricks AI Gateway SDK para 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,
          },
        ],
      },
    },
  },
});

Conceder acesso a um serviço modelo

Por defeito, só o proprietário do serviço modelo pode consultá-lo. Para permitir que outros consultem um serviço de modelo, conceda-lhes EXECUTE sobre ele, bem como USE CATALOG e USE SCHEMA no respetivo catálogo e esquema. Se o serviço de modelo registar dados numa tabela de inferência, conceda SELECT na tabela para lhes permitir ler os pedidos e as respostas registados.

IU

  1. Abra o serviço de modelo no Explorador de Catálogos, ou vá ao AI Gateway e selecione o serviço.
  2. Vá para a guia Permissões .
  3. Clique em Conceder.
  4. Selecione os utilizadores, grupos ou identidades de serviço a quem pretende conceder acesso.
  5. Selecione o privilégio EXECUTE.
  6. Clique em Conceder.

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

CLI

Grant EXECUTE com a linha de comando do Databricks. Para instalar a linha de código, consulte Instalar ou atualizar a CLI de Databricks.

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

Terraform

Subvenção EXECUTE com o fornecedor Databricks Terraform e o databricks_grant recurso:

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

DABs (Beta)

Adiciona um grants bloco ao recurso de serviço modelo no teu bundle e reimplementa para conceder acesso.

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

Subvenção EXECUTE com o SDK Databricks para 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])],
)

Kit de Desenvolvimento de Software Go

Grant EXECUTE com o SDK Databricks para 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},
	}},
})

SDK de Java

Grant EXECUTE com o SDK Databricks para 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)))));

Consulte Descobrir e regular o acesso a serviços modelo para mais informações sobre conceder e descobrir acesso.

Configurar funcionalidades num serviço modelo

Configure limites de taxa, registo de inferência e guardrails implementados com políticas de serviço no serviço modelo a partir da interface do Unity Gateway. See:

Registo de inferência

Quando ativas o registo de inferências, o Azure Databricks cria uma nova tabela vazia do Unity Catalog com um esquema pré-definido no local que especificas. Tenha em atenção o seguinte::

  • Tem de ter USE CATALOG, USE SCHEMA e CREATE TABLE no catálogo e no esquema de destino.
  • O criador do serviço modelo é o proprietário da tabela de inferência. Nenhum outro utilizador tem acesso a menos que o concedas.
  • Se uma tabela já existir na localização especificada, a criação do serviço modelo falha.
  • A tabela de inferência tem um ciclo de vida independente do serviço modelo. Se eliminares a tabela, o serviço do modelo continua a funcionar, mas deixa de registar.

Para mais informações sobre tabelas de inferência, veja Pedidos de registo e respostas a tabelas de inferência.

Atualizar um serviço modelo

Tem de ser proprietário/a ou ter MANAGE.

IU

Editar a configuração do serviço de modelos a partir da interface do Unity Gateway ou do Explorador de Catálogos. As alterações são aplicadas no local.

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

Edita comment (ou qualquer outro campo mutável) no databricks_ai_gateway_model_service recurso e volta a aplicar. As alterações são aplicadas no local.

DABs (Beta)

Edite comment (ou qualquer outro campo mutável) no recurso bundle e execute databricks bundle deploy. As alterações são aplicadas no local.

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

Kit de Desenvolvimento de Software 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,
})

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

Eliminar um serviço modelo

Tem de ser proprietário/a ou ter MANAGE. Os serviços modelo fornecidos pelo sistema em system.ai não podem ser eliminados.

IU

Abra o serviço de modelos na interface do Unity Gateway ou no Explorador de Catálogos e selecione Eliminar no 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

Executa terraform destroy, ou remove o bloco de recurso e volta a aplicar.

DABs (Beta)

Remova o recurso do pacote e execute databricks bundle deploy para o eliminar. databricks bundle destroy Também funciona, mas remove todos os recursos que o pacote gere, não apenas este.

Python SDK

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

Kit de Desenvolvimento de Software 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"),
})

SDK de Java

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

Governação e privilégios

Como objeto seguro pelo Unity Catalog, um serviço modelo:

  • Vive num catálogo e esquema, onde herda definições de esquema, como ligações de espaço de trabalho.
  • Transporta metadados padrão do Unity Catalog, como nome, proprietário, comentário e etiquetas.
  • É regido pelos privilégios do Unity Catalog, por isso concede acesso usando as GRANTREVOKE mesmas instruções que usa para tabelas, funções e modelos.
  • Pode ser descoberto no Explorador de Catálogos, juntamente com o resto dos teus ativos do Catálogo Unity.

Aplicam-se os seguintes privilégios:

Privilégio Description
USE CATALOG, USE SCHEMA Aceda ao catálogo e ao esquema que contêm o serviço de modelo. Obrigatório para todas as operações.
CREATE SERVICE Crie serviços de modelo num esquema. Concedido no catálogo ou esquema.
EXECUTE Consulta a um serviço modelo.
MANAGE Modificar ou eliminar um serviço modelo e gerir as suas subvenções. O proprietário tem um superconjunto de MANAGE.

Os serviços modelo utilizam os privilégios do definidor. O Azure Databricks avalia uma consulta com base nos privilégios do proprietário em vez dos do chamador. Quando um utilizador consulta um serviço modelo, o Azure Databricks verifica se o proprietário tem EXECUTE acesso aos destinos referenciados, como os modelos subjacentes e quaisquer fornecedores de modelos. O interlocutor não precisa de acesso direto a esses destinos.

Limitações

As seguintes capacidades não são suportadas:

  • Criar e gerir serviços de modelo com SQL.
  • Descobrir serviços do modelo apenas com o privilégio BROWSE.
  • Pesquisa global por serviços modelo.

Recursos adicionais

  • Última atualização a