Serviços de modelos personalizados

Um serviço modelo é um endpoint que traduz e encaminha requisições de inferência para um ou mais modelos, com divisão de tráfego e fallbacks. Ele suporta requisições em tempo real, além de inferência em lote.

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

  • Um endpoint independente do modelo para uma aplicação. Ofereça a um assistente de suporte ao cliente um serviço chamado production.ai.support-assistant. Mude o modelo subjacente sem mudar o nome que a aplicação chama.
  • Roteamento personalizado e alternativas. 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 solicitações falhadas.
  • Um orçamento para uma carga de trabalho. Marque um serviço com project=support-assistant e defina um orçamento mensal para essa etiqueta, com um alerta de $1.000 de gasto.
  • Controles de acesso para uma equipe. Conceda à equipe jurídica e às suas entidades de serviço de aplicação acesso a um serviço legal-review e use serviços separados para outras equipes.
  • Limites de taxa para uma carga de trabalho. Configure um serviço de teste para 100 solicitações por minuto e um serviço de produção para 1.000 solicitações por minuto usando limites de taxa de serviço.
  • Monitoramento e registros separados. Envie as solicitações e respostas de um assistente de suporte para uma tabela de inferência dedicada para que 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 direcionar solicitações para modelos disponibilizados pelo Azure Databricks, usando pagamento por token ou taxa de transferência provisionada, ou para modelos externos por meio de um provedor de modelo. Você pode misturar esses destinos em um único serviço.

Os serviços de modelo personalizados são objetos protegidos do Unity Catalog. Os chamadores os invocam pelo seu nome totalmente qualificado, catalog.schema.name, em workspaces ou de fora do Azure Databricks. Veja Governança e privilégios.

Requirements

Observação

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

  • Um espaço de trabalho Azure Databricks em uma região suportada pelo Unity Gateway.
  • Unity Catalog habilitado para seu workspace. Consulte Habilitar um workspace para o Unity Catalog.
  • Para criar um serviço de modelo, você deve ter:
    • USE CATALOG, USE SCHEMA e CREATE SERVICE no catálogo e no esquema em que você cria o serviço de modelo.
    • EXECUTE em cada modelo que o serviço de modelo referencia como destino.
    • EXECUTE, USE CATALOG, e USE SCHEMA em cada provedor de modelo que o serviço de modelo usa como destino.
    • USE CATALOG, USE SCHEMA e CREATE TABLE no catálogo e no esquema em que a tabela de inferência é criada, se você habilitar o log de inferência.

Criar um serviço de modelo personalizado

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

Serviços de modelo e provedores de modelo compartilham um único namespace dentro de um esquema de catálogo Unity. Você não pode usar um nome para um serviço modelo se um provedor de modelo no esquema já o utiliza, e vice-versa.

interface do usuário

  1. Siga um destes procedimentos:
    • Na barra lateral do workspace, clique em Gateway de IA e, em seguida, clique em Criar.
    • No Explorador de Catálogo, vá para o esquema em que você deseja criar o serviço de modelo e clique em Criar>Serviço>Serviço de modelo.
  2. Insira um nome para o serviço de modelo e selecione o catálogo e o esquema em que deseja criá-lo. Se você começar no Catalog Explorer, o Catalog Explorer preenche automaticamente o catálogo e o esquema.
  3. Selecione o destino principal a ser atendido. Esse destino pode ser um modelo servido pelo Azure Databricks para o qual você tem EXECUTE e que o Unity Gateway pode disponibilizar, ou um provedor de modelos para o qual você tem EXECUTE, USE CATALOG e USE SCHEMA.
  4. Clique em Criar.

Depois de criar o serviço de modelo, o Azure Databricks abre a página de visão geral, onde você pode começar a usar o serviço ou configurar recursos adicionais, como log de inferência.

API REST

Envie 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 pai e um nome de folha, e forneça a configuração com --json. A configuração de roteamento deve ter pelo menos um destino. Para instalar a linha de código, veja Instalar ou atualizar a CLI do 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 gerencie um serviço modelo com o provedor 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 em um bundle e implante-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

Crie e gerencie um serviço 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,
                    )
                ]
            )
        ),
    ),
)

SDK do Go

Crie e gerencie 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 gerencie um serviço de modelo com o SDK do Databricks AI Gateway para o Go. Campos opcionais são ponteiros, então o exemplo usa um 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"),
						},
					},
				}},
			},
		},
	},
})

Java SDK

Crie e gerencie 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 gerencie 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,
          },
        ],
      },
    },
  },
});

Conceda acesso a um serviço modelo

Por padrão, apenas o proprietário do serviço modelo pode consultá-lo. Para permitir que outros consultem um serviço de modelo, conceda a eles EXECUTE nele, além de USE CATALOG e USE SCHEMA no catálogo e no esquema. Se o serviço de modelo registrar em uma tabela de inferência, conceda SELECT na tabela para permitir que leiam as solicitações e respostas registradas.

interface do usuário

  1. Abra o serviço de modelo no Explorador de Catálogo, ou vá até o AI Gateway e selecione o serviço.
  2. Acesse a guia Permissões.
  3. Selecione Conceder.
  4. Selecione os usuários, grupos ou entidades de serviço aos quais dar acesso.
  5. Selecione o privilégio EXECUTE .
  6. Selecione 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

Conceda EXECUTE com a CLI do Databricks. Para instalar a linha de código, veja Instalar ou atualizar a CLI do Databricks.

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

Terraform

Conceda EXECUTE com o provedor Databricks Terraform e o recurso databricks_grant:

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

DABs (Beta)

Adicione um bloco grants ao recurso de serviço de modelo no seu pacote e implante novamente 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

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

SDK do Go

Conceda EXECUTE com o SDK do 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},
	}},
})

Java SDK

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

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

Configurar recursos em um serviço modelo

Configure limites de taxa, registro de inferência e proteções implementadas com políticas de serviço no serviço modelo da interface do Unity Gateway. See:

Registro de inferência

Quando você habilita o registro de inferência em log, o Azure Databricks cria uma nova tabela vazia do Unity Catalog com um esquema predefinido no local que você especificar. Observe o seguinte:

  • Você deve ter USE CATALOG, USE SCHEMA e CREATE TABLE no catálogo e no esquema de destino.
  • O criador do serviço de modelo é o proprietário da tabela de inferência. Nenhum outro usuário tem acesso, a menos que você conceda a ele.
  • Se uma tabela já existir no local especificado, a criação do serviço de modelo falhará.
  • A tabela de inferência tem um ciclo de vida independente do serviço de modelo. Se você descartar a tabela, o serviço de modelo continuará funcionando, mas deixará de registrar logs.

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

Atualize um serviço modelo

Você deve ser proprietário ou ter MANAGE.

interface do usuário

Edite a configuração do serviço modelo a partir da interface do Unity Gateway ou do Explorador de Catálogo. 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

Edite comment (ou qualquer outro campo mutável) no databricks_ai_gateway_model_service recurso e reaplique. 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"),
)

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

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

Excluir um serviço modelo

Você deve ser proprietário ou ter MANAGE. Os serviços de modelo fornecidos pelo sistema em system.ai não podem ser excluídos.

interface do usuário

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

Execute terraform destroy, ou remova o bloco de recurso e aplique novamente.

DABs (Beta)

Remova o recurso do pacote e corra databricks bundle deploy para deletá-lo. databricks bundle destroy Também funciona, mas remove todos os recursos que o pacote gerencia, não só este.

Python SDK

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

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

JS Modular SDK

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

Governança e privilégios

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

  • Fica em um catálogo e em um esquema, onde herda configurações do esquema, como associações de espaço de trabalho.
  • Carrega metadados padrão do Catálogo do Unity, como nome, proprietário, comentário e marcas.
  • É controlado pelos privilégios do Unity Catalog, portanto, você concede acesso usando os mesmos GRANT e REVOKE comandos que usa para tabelas, funções e modelos.
  • É detectável no Catalog Explorer, juntamente com o restante dos ativos do Catálogo do Unity.

Os seguintes privilégios se aplicam:

Privilégio Descrição
USE CATALOG, USE SCHEMA Acesse o catálogo e o esquema que contêm o serviço de modelo. Necessário para todas as operações.
CREATE SERVICE Crie serviços de modelo em um esquema. Concedido no catálogo ou esquema.
EXECUTE Fazer uma consulta a um serviço de modelos.
MANAGE Modifique ou exclua um serviço de modelo e gerencie suas concessões. O proprietário tem um superconjunto de MANAGE.

Os serviços de modelo utilizam os privilégios do definidor. O Azure Databricks avalia uma consulta com base nos privilégios do proprietário, e não no do chamador. Quando um usuário consulta um serviço de modelo, o Azure Databricks verifica que o proprietário tenha EXECUTE sobre os destinos referenciados, como os modelos subjacentes e quaisquer provedores de modelos. O interlocutor não precisa de acesso direto a esses destinos.

Limitations

As seguintes capacidades não são suportadas:

  • Criar e gerenciar serviços de modelo com SQL.
  • Descobrindo serviços de modelo apenas com o privilégio BROWSE.
  • Busca global por serviços modelo.

Recursos adicionais

  • Última atualização em