Criar e gerenciar APIs de modelo (serviços de modelo)

Crie, compartilhe e gerencie suas próprias APIs de modelo (serviços de modelo) no Unity Catalog.

dica

As APIs de modelo fornecidas pelo sistema no esquema system.ai estão prontas para query sem necessidade de configuração. Crie sua própria API de modelo apenas quando desejar governar modelos adicionais ou expor um endpoint personalizado.

Requisitos

Um workspace do Databricks em uma região com suporte ao Unity Gateway.
Unity Catalog habilitado para seu workspace. Consulte Ativar 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 esquema onde 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 serviço de provedor de modelo que o serviço de modelo referencia como destino.
- USE CATALOG, USE SCHEMA, e CREATE TABLE no catálogo e esquema onde a tabela de inferência é criada, se você habilitar o log de inferência.

Criar um serviço de modelo

Crie um serviço de modelo na interface de usuário do Unity Gateway ou no Explorador de Catálogos. Para criar um programaticamente, use a API REST, os Databricks SDKs, a CLI do Databricks, o Terraform ou os Declarative Automation Bundles (DABs).

Os serviços de modelo e os serviços de provedor de modelo compartilham um único namespace de nome dentro de um esquema do Unity Catalog. Não é possível usar um nome para um serviço de modelo se um serviço de provedor de modelo no esquema já o usa, e vice-versa.

Siga um destes procedimentos:
- Na barra lateral do workspace, clique em AI Gateway e, em seguida, em Criar .
- No Catalog Explorer, vá para o esquema onde você deseja criar o serviço de modelo e, em seguida, clique em **Criar** > **Serviço** > **Serviço de modelo**.
Insira um nome para o serviço de modelo e selecione o catálogo e o esquema para criá-lo. Se você começar do Catalog Explorer, o Catalog Explorer preencherá automaticamente o catálogo e o esquema.
Selecione o destino principal para atender. Este destino pode ser um modelo hospedado no Databricks no qual você tem EXECUTE e que o Unity Gateway pode atender, ou um serviço de provedor de modelo no qual você tem EXECUTE, USE CATALOG e USE SCHEMA.
Clique em Criar .

Após criar o serviço de modelo, o Databricks abrirá sua página de visão geral, onde você poderá começar ou configurar recursos adicionais, como o registro de inferência.

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

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

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 CLI, consulte Instalar ou atualizar a CLI do Databricks.

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

Crie e gerencie um serviço de modelo com o provedor Databricks Terraform e o recurso databricks_ai_gateway_model_service:

Hcl
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
      }]
    }
  }
}

Define the model serviço in a bundle and deploy it with databricks bundle deploy. The routing config must have at least one destination:

YAML
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

Crie e gerencie um serviço de modelo com o SDK do Databricks para Python:

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

Crie e gerencie um serviço de modelo com o SDK do Databricks para Go:

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

Crie e gerencie um serviço de modelo com o SDK do Databricks para Java:

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

Criar e gerenciar um serviço de modelo com o Databricks AI Gateway SDK for JavaScript:

TypeScript
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 de modelo

Por default, apenas o proprietário do serviço de modelo pode fazer query nele. Para permitir que outros façam query em um serviço de modelo, conceda a eles EXECUTE nele, além de USE CATALOG e USE SCHEMA no catálogo e no esquema correspondentes. Se o serviço de modelo fizer Logs em uma tabela de inferência, conceda SELECT na tabela para permitir que eles leiam as solicitações e respostas registradas.

Abra o serviço de modelo no Catalog Explorer ou vá para o AI Gateway e selecione o serviço.
Vá para a tab Permissões.
Clique em Conceder .
Selecione os usuários, grupos ou Service Principal aos quais deseja conceder acesso.
Selecione o privilégio EXECUTE .
Clique em Conceder .

Bash
databricks api patch \
  "/api/2.1/unity-catalog/permissions/model_service/main.default.my_model_service" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["EXECUTE"] }
    ]
  }'

Conceda EXECUTE com a CLI do Databricks. Para instalar a CLI, consulte Instalar ou atualizar a CLI do Databricks.

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

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

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

Adicione um bloco grants ao recurso de serviço de modelo no seu pacote e reimplante para conceder acesso.

YAML
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]

Conceda EXECUTE com o SDK do Databricks para Python:

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

Conceda EXECUTE com o SDK do Databricks para Go:

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

Conceda EXECUTE com o SDK do Databricks para Java:

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

Para saber mais sobre como conceder e descobrir acesso, consulte Descobrir e governar o acesso a APIs de modelo (serviços de modelo).

Configurar recursos em um serviço de modelo

Você configura recursos como limites de taxa, log de inferência e guardrails no serviço de modelo a partir da interface do usuário do Unity Gateway, da mesma forma que os configura em um endpoint do Unity Gateway. Consulte:

Log de inferência

Ao habilitar o registro de inferência, a 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 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ê o conceda.
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ê remover a tabela, o serviço de modelo continua funcionando, mas para de registrar.

Para saber mais sobre tabelas de inferência, consulte Logs solicitações e respostas em tabelas de inferência.

Atualizar um serviço de modelo

Você deve ser um proprietário ou ter MANAGE.

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

Bash
databricks api patch \
  "/api/2.1/unity-catalog/model-services/main.default.my_model_service?update_mask=comment" \
  --json '{"comment": "Updated: routes chat traffic"}'

Bash
databricks ai-gateway update-model-service model-services/main.default.my_model_service comment \
  --json '{"comment": "Updated: routes chat traffic"}'

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

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

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

TypeScript
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 de Modelo

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

Abra o serviço de modelo na interface do Unity Gateway ou no Explorador de Catálogos e selecione Excluir no menu kebab.

Bash
databricks api delete "/api/2.1/unity-catalog/model-services/main.default.my_model_service"

Bash
databricks ai-gateway delete-model-service model-services/main.default.my_model_service

Execute terraform destroy ou remova o bloco de recurso e reaplique.

Remova o recurso do bundle e execute databricks bundle deploy para excluí-lo. databricks bundle destroy also works, but it removes every recurso the bundle gerencia, not just this one.

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

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

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

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

Requisitos​

Criar um serviço de modelo​

Conceda acesso a um serviço de modelo​

Configurar recursos em um serviço de modelo​

Log de inferência​

Atualizar um serviço de modelo​

Excluir um Serviço de Modelo​

Próximos os passos​