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 suportada pelo Unity AI 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

Você pode criar um serviço de modelo na interface do usuário do Unity AI Gateway ou no Catalog Explorer, ou programaticamente com a API REST, os SDKs do Databricks, a CLI do Databricks ou o Terraform.

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.

UI

1. 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**.

2. 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.

3. Selecione o destino principal para servir. Este destino pode ser um modelo hospedado no Databricks no qual você tem EXECUTE e que o Unity AI Gateway pode servir, ou um serviço de provedor de modelo no qual você tem EXECUTE, USE CATALOG e USE SCHEMA.

4. 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.

REST API

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

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

Terraform

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

Python SDK

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

Go SDK

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

Java SDK

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

JS SDK

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.

UI

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

REST API

Bash

databricks api patch \
  "/api/2.1/unity-catalog/permissions/model_service/main.default.my_model_service" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["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

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

• Aplicar limites de taxa a serviços de modelo e MCP
• Fazer log de solicitações e respostas em tabelas de inferência

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.

UI

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

REST API

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

CLI

Bash

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 recurso databricks_ai_gateway_model_service e reaplique. As alterações são aplicadas no local.

Python SDK

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 SDK

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 SDK

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 SDK

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.

UI

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

REST API

Bash

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

CLI

Bash

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

Terraform

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

Python SDK

Python

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

Go SDK

Go

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

Java SDK

Java

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

JS SDK

TypeScript

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

Próximos os passos

• Serviços de modelo
• Consultar serviços de modelo
• Descobrir e governar o acesso a serviços de modelo
• Integrar com agentes de codificação