Servicios de modelos personalizados

Un servicio de modelo es un punto final que traduce y enruta las solicitudes de inferencia a uno o más modelos, con división del tráfico y mecanismos de respaldo. Soporta peticiones en tiempo real, además de inferencia por lotes.

Crear un servicio de modelo personalizado para casos de uso como:

  • Un punto final agnóstico respecto al modelo para una aplicación. Proporciona a un asistente de atención al cliente un servicio llamado production.ai.support-assistant. Cambiar el modelo subyacente sin cambiar el nombre que usa la aplicación.
  • Enrutamiento personalizado y mecanismos de respaldo. Utiliza la división de tráfico para enviar 10% de tráfico a un nuevo modelo antes de un despliegue más amplio, o configura un destino de respaldo para solicitudes fallidas.
  • Un presupuesto para una sola carga de trabajo. Etiqueta un servicio con project=support-assistant y asocia un presupuesto mensual a esa etiqueta, con una alerta al alcanzar 1.000 $ de gasto.
  • Controles de acceso para un equipo. Conceder acceso a un servicio al equipo legal y a sus responsables legal-review de servicios de aplicación, y utilizar servicios separados para otros equipos.
  • Límites de tarifa para una carga de trabajo. Configura un servicio de prueba para 100 solicitudes por minuto y un servicio de producción para 1.000 solicitudes por minuto usando límites de tasa de servicio.
  • Monitorización y registros separados. Envía las solicitudes y respuestas de un asistente de soporte a una tabla de inferencias dedicada para que su tráfico pueda ser inspeccionado por separado del tráfico del agente de codificación.

Para consultar un modelo de fundación servido por Azure Databricks sin crear un servicio, utilice un servicio modelo proporcionado por el sistema en system.ai.

Un servicio puede enrutar a modelos servidos por Azure Databricks, usando pago por token o rendimiento provisionado, o a modelos externos a través de un proveedor de modelos. Puedes combinar estos destinos en un solo servicio.

Los servicios de modelos personalizados son objetos protegibles de Unity Catalog. Los llamantes los invocan por su nombre totalmente cualificado, catalog.schema.name, en espacios de trabajo o desde fuera de Azure Databricks. Véase Gobernanza y privilegios.

Requirements

Nota:

Unity Gateway no está compatible con Azure Government.

  • Un espacio de trabajo de Azure Databricks en una región soportada por Unity Gateway.
  • Unity Catalog habilitado para su área de trabajo. Consulte Habilitar un área de trabajo para Unity Catalog.
  • Para crear un servicio de modelos, debe disponer de:
    • USE CATALOG, USE SCHEMA y CREATE SERVICE en el catálogo y el esquema donde se crea el servicio de modelo.
    • EXECUTE en cada modelo al que el servicio de modelo hace referencia como destino.
    • EXECUTE, USE CATALOG y USE SCHEMA en cada proveedor de modelos al que el servicio del modelo hace referencia como destino.
    • USE CATALOG, USE SCHEMAy CREATE TABLE en el catálogo y el esquema donde se crea la tabla de inferencia, si habilita el registro de inferencia.

Crear un servicio de modelo personalizado

Crea un servicio modelo en la interfaz de Unity Gateway o en el Explorador de Catálogos. Para crear uno programáticamente, utiliza la API REST, los SDKs de Azure Databricks, la CLI de Azure Databricks, Terraform o los Bundles de Automatización Declarativa (DABs).

Los servicios de modelo y los proveedores de modelos comparten un único espacio de nombres dentro de un esquema de Catálogo de Unity. No puedes usar un nombre para un servicio modelo si un proveedor de modelos en el esquema ya lo usa, y viceversa.

Interfaz de usuario

  1. Realice una de las acciones siguientes:
    • En la barra lateral del área de trabajo, haga clic en Puerta de enlace de IA y, a continuación, haga clic en Crear.
    • En el Explorador de catálogos, vaya al esquema donde desea crear el servicio de modelo y, a continuación, haga clic en Crear>Servicio>Servicio de modelo.
  2. Escriba un nombre para el servicio de modelo y seleccione el catálogo y el esquema en los que se va a crear. Si empieza desde el Explorador de catálogos, el Explorador de catálogos rellena previamente el catálogo y el esquema.
  3. Selecciona el destino principal al que atender. Este destino puede ser un modelo servido por Azure Databricks en el que tengas EXECUTE y que Unity Gateway pueda servir, o un proveedor de modelos en el que tengas EXECUTE, USE CATALOG y USE SCHEMA.
  4. Haga clic en Crear.

Después de crear el servicio de modelo, Azure Databricks abre su página de información general, donde puede empezar a trabajar o configurar características adicionales, como el registro de inferencia.

API de REST

Envía a POST a /api/2.1/unity-catalog/model-services, pasando parent y model_service_id como parámetros de consulta. La configuración de enrutamiento debe tener al menos un 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

Pasa el esquema padre y un nombre de nodo hoja, y proporciona la configuración con --json. La configuración de enrutamiento debe tener al menos un destino. Para instalar la línea de código, consulte Instalar o actualizar la 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

Crea y gestiona un servicio modelo con el proveedor Databricks Terraform y el 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)

Define el servicio modelo en un paquete y despliégalo con databricks bundle deploy. La configuración de enrutamiento debe tener al menos un 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

SDK de Python

Crea y gestiona un servicio de modelo con el 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 Desarrollo de Software Go

Crea y gestiona un servicio modelo con el 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

Crea y gestiona un servicio de modelos con el SDK de AI Gateway de Databricks para Go. Los campos opcionales son punteros, por lo que el ejemplo utiliza un asistente de una línea, 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

Crea y gestiona un servicio modelo con el 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

Crea y gestiona un servicio modelo con el SDK de IA Gateway de Databricks 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,
          },
        ],
      },
    },
  },
});

Concede acceso a un servicio modelo

Por defecto, solo el propietario del servicio modelo puede consultarlo. Para permitir que otros consulten un servicio de modelo, concédeles EXECUTE sobre él, además de USE CATALOG y USE SCHEMA sobre su catálogo y esquema. Si el servicio de modelo registra información en una tabla de inferencia, concédele el privilegio SELECT sobre dicha tabla para que pueda leer las solicitudes y respuestas registradas.

Interfaz de usuario

  1. Abre el servicio de modelos en el Explorador de Catálogos, o ve a AI Gateway y selecciona el servicio.
  2. Vaya a la pestaña Permisos.
  3. Haga clic en Permitir.
  4. Seleccione los usuarios, grupos o entidades de servicio a los que conceder acceso.
  5. Seleccione el privilegio EXECUTE .
  6. Haga clic en Permitir.

API de 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 con la CLI de Databricks. Para instalar la línea de código, consulte Instalar o actualizar la CLI de Databricks.

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

Terraform

Conceda EXECUTE con el proveedor de Databricks Terraform y el databricks_grant recurso:

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

DABs (Beta)

Añade un grants bloque al recurso de servicio modelo en tu paquete y vuelve a desplegar para conceder acceso.

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]

SDK de Python

Conceda EXECUTE con el SDK de 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 Desarrollo de Software Go

Conceda EXECUTE con el SDK de 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

Conceda EXECUTE con el SDK de 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)))));

Consulta Descubrir y regular el acceso a servicios modelo para más información sobre concesión y descubrimiento de acceso.

Configurar características en un servicio modelo

Configura límites de velocidad, registro de inferencias y guardaguardas implementados con políticas de servicio en el servicio modelo desde la interfaz de Unity Gateway. See:

Registro de inferencia

Al habilitar el registro de inferencia, Azure Databricks crea una tabla de catálogo de Unity nueva y vacía con un esquema predefinido en la ubicación que especifique. Tenga en cuenta lo siguiente:

  • Debes tener los privilegios USE CATALOG, USE SCHEMA y CREATE TABLE sobre el catálogo y el esquema de destino.
  • El creador del servicio de modelo es el propietario de la tabla de inferencia. Ningún otro usuario tiene acceso a menos que lo conceda.
  • Si ya existe una tabla en la ubicación especificada, se produce un error al crear el servicio de modelo.
  • La tabla de inferencia tiene un ciclo de vida independiente del servicio de modelo. Si eliminas la tabla, el servicio de modelo seguirá funcionando, pero dejará de registrar información.

Para más información sobre tablas de inferencia, véase Solicitudes de registro y respuestas a tablas de inferencia.

Actualizar un servicio modelo

Debes ser propietario o tener MANAGE.

Interfaz de usuario

Edita la configuración del servicio modelo desde la interfaz de Unity Gateway o el Explorador de catálogos. Los cambios se aplican directamente.

API de 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 (o cualquier otro campo mutable) en el databricks_ai_gateway_model_service recurso y vuelve a aplicar. Los cambios se aplican directamente.

DABs (Beta)

Edita comment (o cualquier otro campo mutable) en el recurso bundle y ejecuta databricks bundle deploy. Los cambios se aplican directamente.

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

Kit de Desarrollo 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 un servicio modelo

Debes ser propietario o tener MANAGE. Los servicios de modelo proporcionados por el sistema en system.ai no se pueden eliminar.

Interfaz de usuario

Abra el servicio de modelo en la interfaz de usuario de Unity Gateway o en Catalog Explorer y seleccione Eliminar del menú kebab.

API de 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

Ejecuta terraform destroy, o elimina el bloque de recursos y vuelve a aplicar.

DABs (Beta)

Elimina el recurso del paquete y corre databricks bundle deploy para eliminarlo. databricks bundle destroy También funciona, pero elimina todos los recursos que gestiona el paquete, no solo este.

SDK de Python

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

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

Gobierno y privilegios

Como objeto seguro en Unity Catalog, un servicio modelo:

  • Reside en un catálogo y un esquema, donde hereda la configuración del esquema, como los enlaces del área de trabajo.
  • Incluye metadatos estándar del catálogo de Unity, como el nombre, el propietario, el comentario y las etiquetas.
  • Se rige por privilegios de Catálogo de Unity, por lo que se concede acceso mediante las mismas GRANT instrucciones y REVOKE que se usan para tablas, funciones y modelos.
  • Se puede detectar en el Explorador de catálogos, junto con el resto de los recursos del catálogo de Unity.

Se aplican los privilegios siguientes:

Privilegio Descripción
USE CATALOG, USE SCHEMA Acceda al catálogo y el esquema que contienen el servicio de modelo. Necesario para todas las operaciones.
CREATE SERVICE Crear servicios de modelo en un esquema. Concedido en el catálogo o el esquema.
EXECUTE Consultar un servicio de modelos.
MANAGE Modifique o elimine un servicio de modelo y administre sus concesiones. El propietario tiene un superconjunto de MANAGE.

Los servicios modelo utilizan los privilegios del definidor. Azure Databricks evalúa una consulta en función de los privilegios del propietario en lugar de los del llamante. Cuando un usuario consulta un servicio de modelo, Azure Databricks comprueba que el propietario tenga EXECUTE sobre los destinos referenciados, como los modelos subyacentes y cualquier proveedor de modelos. El que llama no necesita acceso directo a esos destinos.

Limitations

No se soportan las siguientes capacidades:

  • Crear y gestionar servicios de modelo con SQL.
  • Descubrir servicios de modelo solo con el privilegio BROWSE.
  • Búsqueda global de servicios modelo.

Recursos adicionales

  • Se actualizó por última vez el