Crear y gestionar proveedores modelo externos (servicios de proveedor modelo)

Registrar un proveedor de modelos externo como servicio de proveedor modelo, concederle acceso, configurar las funciones de Unity AI Gateway y elimíralo.

Requirements

  • CREATE SERVICE en el esquema donde se crea el servicio del proveedor de modelos, además de USE CATALOG y USE SCHEMA en su catálogo y esquema.
  • Las credenciales del proveedor externo que desea registrar (por ejemplo, una clave de API de OpenAI o un par de claves de acceso de AWS).
  • Para autenticarse en Azure OpenAI o Microsoft Foundry con una credencial de servicio en lugar de una clave o un secreto, necesita una credencial de servicio existente y ACCESS en ella. Consulta Autenticar Azure OpenAI o Microsoft Foundry con credencial de servicio.

Crear un servicio modelo de proveedor

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

Puedes crear un servicio de proveedor de modelos en la interfaz de Unity AI Gateway o en Catalog Explorer, o programáticamente con la API REST, los SDKs de Azure Databricks, la CLI de Azure Databricks o Terraform.

Interfaz de usuario

  1. Realice una de las acciones siguientes:
    • En la barra lateral del espacio de trabajo, haz clic en AI Gateway, luego abre la pestaña de Proveedores y haz clic en Proveedor.
    • En el Explorador de Catálogo, ve al esquema donde quieres crear el servicio proveedor de modelos, haz clic en Crear>servicio y luego selecciona Servicio de proveedor de modelo en el cuadro de diálogo Crear un servicio .
  2. Escriba un nombre para el servicio de proveedor de modelos 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. Seleccione el tipo de proveedor y escriba los detalles y las credenciales de conexión del proveedor.
  4. Haga clic en Crear. Azure Databricks cifra y almacena las credenciales. La interfaz de usuario no las muestra después de este punto.

REST API

Envía un POST a /api/2.1/unity-catalog/model-provider-services, pasando parent y model_provider_service_id como parámetros de consulta. Establece provider_type y exactamente un bloque de proveedor coincidente; targets incluye en la lista de permitidos los modelos de origen accesibles, y los secretos se proporcionan en línea como texto sin cifrar:

databricks api post \
  "/api/2.1/unity-catalog/model-provider-services?parent=schemas/main.default&model_provider_service_id=my_provider" \
  --json '{
  "comment": "Routes to a custom OpenAI-compatible provider",
  "config": {
    "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM",
    "targets": [
      { "model": "gpt-4o", "native_api_types": ["openai/v1/chat/completions"] }
    ],
    "custom": {
      "direct": {
        "base_url": "https://api.example.com/v1",
        "api_key": { "plaintext": "dummy-api-key" }
      }
    }
  }
}'

CLI

Pasa el esquema padre y un nombre de nodo hoja, y proporciona la configuración con --json. establecen provider_type y exactamente un bloque de proveedor coincidente; targets permite listar los modelos ascendentes accesibles, y los secretos se suministran en línea como texto plano. Para instalar la línea de código, consulte Instalar o actualizar la CLI de Databricks.

databricks ai-gateway create-model-provider-service schemas/main.default my_provider --json '{
  "comment": "Routes to a custom OpenAI-compatible provider",
  "config": {
    "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM",
    "targets": [
      { "model": "gpt-4o", "native_api_types": ["openai/v1/chat/completions"] }
    ],
    "custom": {
      "direct": {
        "base_url": "https://api.example.com/v1",
        "api_key": { "plaintext": "dummy-api-key" }
      }
    }
  }
}'

Terraform

Crea y gestiona un servicio de proveedor modelo con el proveedor de Databricks Terraform y el recurso databricks_ai_gateway_model_provider_service . Mantén las claves reales fuera del control de versiones pasando la clave API a través de una sensitive = true variable (configúrala con -var o una TF_VAR_provider_api_key variable de entorno):

variable "provider_api_key" {
  type      = string
  sensitive = true
}

resource "databricks_ai_gateway_model_provider_service" "example" {
  parent                    = "schemas/main.default"
  model_provider_service_id = "my_provider"
  comment                   = "Routes to a custom OpenAI-compatible provider"

  config = {
    provider_type = "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM"

    targets = [{
      model            = "gpt-4o"
      native_api_types = ["openai/v1/chat/completions"]
    }]

    custom = {
      direct = {
        base_url = "https://api.example.com/v1"
        api_key  = { plaintext = var.provider_api_key }
      }
    }
  }
}

SDK de Python

Crea y gestiona un servicio proveedor de modelos con el SDK Databricks para Python:

from databricks.sdk.service import catalog as c

model_provider_service = w.ai_gateway.create_model_provider_service(
    parent="schemas/main.default",
    model_provider_service_id="my_provider",
    model_provider_service=c.ModelProviderService(
        comment="Routes to a custom OpenAI-compatible provider",
        config=c.ModelProviderServiceConfig(
            provider_type=(
                c.ModelProviderServiceConfigExternalModelProviderType
                .EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM
            ),
            targets=[
                c.ModelProviderServiceConfigModelTargetConfig(
                    model="gpt-4o",
                    native_api_types=["openai/v1/chat/completions"],
                )
            ],
            custom=c.ModelProviderServiceConfigCustomProviderConfig(
                direct=c.ModelProviderServiceConfigCustomProviderDirectConfig(
                    base_url="https://api.example.com/v1",
                    api_key=c.ModelProviderServiceConfigProviderSecret(
                        plaintext="dummy-api-key"
                    ),
                )
            ),
        ),
    ),
)

Kit de Desarrollo de Software Go

Crea y gestiona un servicio de proveedor modelo con el SDK Databricks para Go:

modelProviderService, err := w.AiGateway.CreateModelProviderService(ctx,
	catalog.CreateModelProviderServiceRequest{
		Parent:                 "schemas/main.default",
		ModelProviderServiceId: "my_provider",
		ModelProviderService: catalog.ModelProviderService{
			Comment: "Routes to a custom OpenAI-compatible provider",
			Config: &catalog.ModelProviderServiceConfig{
				ProviderType: catalog.ModelProviderServiceConfigExternalModelProviderTypeExternalModelProviderTypeCustom,
				Targets: []catalog.ModelProviderServiceConfigModelTargetConfig{{
					Model:          "gpt-4o",
					NativeApiTypes: []string{"openai/v1/chat/completions"},
				}},
				Custom: &catalog.ModelProviderServiceConfigCustomProviderConfig{
					Direct: &catalog.ModelProviderServiceConfigCustomProviderDirectConfig{
						BaseUrl: "https://api.example.com/v1",
						ApiKey: &catalog.ModelProviderServiceConfigProviderSecret{
							Plaintext: "dummy-api-key",
						},
					},
				},
			},
		},
	})

SDK de Java

Crea y gestiona un servicio proveedor de modelos con el SDK Databricks para Java:

ModelProviderServiceConfig config =
    new ModelProviderServiceConfig()
        .setProviderType(
            ModelProviderServiceConfigExternalModelProviderType
                .EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM)
        .setTargets(
            Collections.singletonList(
                new ModelProviderServiceConfigModelTargetConfig()
                    .setModel("gpt-4o")
                    .setNativeApiTypes(
                        Collections.singletonList("openai/v1/chat/completions"))))
        .setCustom(
            new ModelProviderServiceConfigCustomProviderConfig()
                .setDirect(
                    new ModelProviderServiceConfigCustomProviderDirectConfig()
                        .setBaseUrl("https://api.example.com/v1")
                        .setApiKey(
                            new ModelProviderServiceConfigProviderSecret()
                                .setPlaintext("dummy-api-key"))));

ModelProviderService modelProviderService =
    w.aiGateway()
        .createModelProviderService(
            new CreateModelProviderServiceRequest()
                .setParent("schemas/main.default")
                .setModelProviderServiceId("my_provider")
                .setModelProviderService(
                    new ModelProviderService()
                        .setComment("Routes to a custom OpenAI-compatible provider")
                        .setConfig(config)));

JS SDK

Crea y gestiona un servicio de proveedor modelo con el SDK de IA Gateway de Databricks para JavaScript:

import { ModelProviderServiceConfig_ExternalModelProviderType as ProviderType } from '@databricks/sdk-aigateway/v1';

const created = await client.createModelProviderService({
  parent: 'schemas/main.default',
  modelProviderServiceId: 'my_provider',
  modelProviderService: {
    comment: 'Routes to a custom OpenAI-compatible provider',
    config: {
      providerType: ProviderType.EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM,
      targets: [{ model: 'gpt-4o', nativeApiTypes: ['openai/v1/chat/completions'] }],
      provider: {
        $case: 'custom',
        custom: {
          providerMode: {
            $case: 'direct',
            direct: {
              baseUrl: 'https://api.example.com/v1',
              authMode: {
                $case: 'apiKey',
                apiKey: {
                  value: { $case: 'plaintext', plaintext: 'dummy-api-key' },
                },
              },
            },
          },
        },
      },
    },
  },
});

Para consultar la lista completa de proveedores y sus métodos de autenticación, véase Administrar proveedores de modelos externos (servicios de proveedores de modelos).

Autenticar Azure OpenAI o Microsoft Foundry con una credencial de servicio

Puedes autenticar a un proveedor de Azure, OpenAI o Microsoft Foundry con una credencial de servicio en lugar de almacenar una clave API o un secreto cliente principal de servicio Microsoft Entra ID. Una credencial de servicio tiene una identidad de Azure que Unity Catalog gobierna, por lo que no se copia ningún secreto duradero en el servicio modelo de proveedor: Azure Databricks obtiene tokens de corta duración de esa identidad para autenticar cada solicitud.

Crea el servicio de proveedor modelo tal como se describe en Crea un servicio de proveedor modelo. Selecciona Azure OpenAI o Microsoft Foundry como tipo de proveedor e introduce sus datos de conexión, incluyendo la URL base del endpoint. Luego configura el método de autenticación en credencial de servicio y selecciona la credencial en lugar de introducir una clave de API o un secreto cliente. Una credencial de servicio reemplaza solo al secreto, por lo que la URL base del endpoint sigue siendo necesaria.

Confirme los siguientes requisitos:

  • El propietario del servicio de proveedor de modelos tiene ACCESS sobre la credencial del servicio. Como Azure Databricks vuelve a comprobar el acceso del propietario al atender las solicitudes, este debe conservarlo mientras el proveedor esté en uso. Revocarla detiene las consultas para todos, incluso para los usuarios que tienen EXECUTE sobre el proveedor. Para conceder al propietario acceso a la credencial:

    GRANT ACCESS ON SERVICE CREDENTIAL <service-credential-name> TO `<model-provider-service-owner>`;

  • El propósito de la credencial es el servicio, no el almacenamiento.

  • La credencial está disponible en los espacios de trabajo de donde provienen las solicitudes. Sus vinculaciones al espacio de trabajo siguen siendo válidas, por lo que una solicitud procedente de un espacio de trabajo al que no esté vinculada la credencial fallará allí, aunque se pueda acceder al propio servicio de proveedor de modelos desde cualquier espacio de trabajo que comparta el metastore.

  • La identidad de Azure de la credencial del servicio está autorizada para invocar las implementaciones de Azure OpenAI o de Microsoft Foundry que tengas previsto consultar. Para crear una credencial de servicio, consulte Creación de credenciales de servicio.

Los que llaman al proveedor necesitan las mismas ayudas que cualquier otro proveedor. No necesitan ningún privilegio sobre la credencial de servicio, que es lo que mantiene la credencial fuera de su alcance.

El servicio del proveedor del modelo hace seguimiento de una credencial mediante su identificador interno, por lo que puedes cambiar el nombre de una credencial sin que la consulta falle.

Si eliminas una credencial, las consultas fallan y no hay aviso de que un servicio modelo de proveedor la mencione. Confirma que no hay referencias a esta credencial antes de eliminarla.

No puedes cambiar un servicio de proveedor modelo existente entre credenciales de servicio y clave API o autenticación secreta de cliente. Crea un nuevo modelo de servicio de proveedor en su lugar.

Envía una clave API personalizada de proveedor en una cabecera

Un proveedor personalizado envía su clave API como token portador por defecto. Si tu punto de conexión espera la clave en un encabezado específico, utiliza la autenticación mediante encabezado de clave de API y asigna tú mismo el nombre al encabezado. Azure Databricks envía entonces la clave en cada solicitud saliente como <header name>: <header value>.

Crea el servicio de proveedor modelo tal como se describe en Crea un servicio de proveedor modelo. Selecciona Personalizado como tipo de proveedor, luego establece el método Auth en encabezado de clave API y proporciona el nombre de encabezado que espera tu endpoint (como X-API-Key o Ocp-Apim-Subscription-Key) junto con el valor de cabecera.

Los dos métodos son mutuamente excluyentes: un proveedor personalizado utiliza un token de portador o un encabezado con nombre, no ambos. La autenticación mediante encabezado usa exactamente un encabezado.

El nombre del encabezado debe ser un nombre de cabecera HTTP válido: letras, dígitos y los caracteres !#$%&'*+-.^_`|~, hasta 255 caracteres. Se rechaza cualquier otro carácter, incluidos espacios, dos puntos, barras y saltos de línea.

Concede acceso a un servicio de proveedor modelo

Por defecto, solo el propietario del servicio del proveedor del modelo puede consultarlo. Para que otros puedan consultar un servicio de proveedor de modelos, concédeles EXECUTE sobre este, además de USE CATALOG y USE SCHEMA sobre su catálogo y su esquema. Si el servicio de proveedor de modelos registra información en una tabla de inferencia, concede el privilegio SELECT sobre la tabla para permitirle leer las solicitudes y respuestas registradas.

Interfaz de usuario

  1. Abre el servicio de proveedor modelo en 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.

REST API

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

Terraform

Subvención EXECUTE con el proveedor de Databricks Terraform y el databricks_grant recurso:

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

SDK de Python

Concede EXECUTE con el SDK de Databricks para Python:

from databricks.sdk.service import catalog as c

w.grants.update(
    securable_type="model_provider_service",
    full_name="main.default.my_provider",
    changes=[c.PermissionsChange(principal="data-team", add=[c.Privilege.EXECUTE])],
)

Kit de Desarrollo de Software Go

Conceder EXECUTE con el SDK de Databricks para Go:

_, err := w.Grants.Update(ctx, catalog.UpdatePermissions{
	SecurableType: "model_provider_service",
	FullName:      "main.default.my_provider",
	Changes: []catalog.PermissionsChange{{
		Principal: "data-team",
		Add:       []catalog.Privilege{catalog.PrivilegeExecute},
	}},
})

SDK de Java

Conceder EXECUTE con el SDK de Databricks para Java:

w.grants().update(
    new UpdatePermissions()
        .setSecurableType("model_provider_service")
        .setFullName("main.default.my_provider")
        .setChanges(Arrays.asList(
            new PermissionsChange().setPrincipal("data-team").setAdd(Arrays.asList(Privilege.EXECUTE)))));

Para más información sobre concesión y descubrimiento de acceso, consulte Descubrir y gobernar el acceso a proveedores modelo externos (servicios de proveedores modelo).

Configuración de características

Dado que un servicio de proveedor de modelos se enruta a través de Unity AI Gateway, aplique las mismas características de gobernanza y observabilidad que usa para otro tráfico de Unity AI Gateway:

Actualizar un servicio modelo de proveedor

Debes ser propietario o tener MANAGE. El tipo de proveedor es inmutable.

Interfaz de usuario

Edita la configuración del servicio del proveedor de modelos desde la interfaz de Unity AI Gateway o el Explorador de Catálogos. Los cambios se aplican directamente.

REST API

databricks api patch \
  "/api/2.1/unity-catalog/model-provider-services/main.default.my_provider?update_mask=comment" \
  --json '{"comment": "Updated: routes to a custom provider"}'

CLI

databricks ai-gateway update-model-provider-service model-provider-services/main.default.my_provider comment \
  --json '{"comment": "Updated: routes to a custom provider"}'

Terraform

Edita comment (o cualquier otro campo mutable) en el databricks_ai_gateway_model_provider_service recurso y vuelve a aplicar. 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_provider_service(
    name="model-provider-services/main.default.my_provider",
    update_mask=FieldMask(paths=["comment"]),
    model_provider_service=c.ModelProviderService(
        comment="Updated: routes to a custom provider"
    ),
)

Kit de Desarrollo de Software Go

updated, err := w.AiGateway.UpdateModelProviderService(ctx,
	catalog.UpdateModelProviderServiceRequest{
		Name:       "model-provider-services/main.default.my_provider",
		UpdateMask: *fieldmask.New([]string{"comment"}),
		ModelProviderService: catalog.ModelProviderService{
			Comment: "Updated: routes to a custom provider",
		},
	})

SDK de Java

ModelProviderService updated =
    w.aiGateway()
        .updateModelProviderService(
            new UpdateModelProviderServiceRequest()
                .setName("model-provider-services/main.default.my_provider")
                .setUpdateMask(FieldMask.newBuilder().addPaths("comment").build())
                .setModelProviderService(
                    new ModelProviderService()
                        .setComment("Updated: routes to a custom provider")));

JS SDK

import { modelProviderServiceFieldMask } from '@databricks/sdk-aigateway/v1';

const updated = await client.updateModelProviderService({
  modelProviderService: {
    name: 'model-provider-services/main.default.my_provider',
    comment: 'Updated: routes to a custom provider',
  },
  updateMask: modelProviderServiceFieldMask('comment'),
});

Eliminación de un servicio de proveedor de modelos

Debes ser propietario o tener MANAGE.

Interfaz de usuario

Abre el servicio del proveedor de modelos en la interfaz de Unity AI Gateway o en el Explorador de catálogos y selecciona Eliminar en el menú kebab.

REST API

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

CLI

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

Terraform

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

SDK de Python

w.ai_gateway.delete_model_provider_service(
    name="model-provider-services/main.default.my_provider"
)

Kit de Desarrollo de Software Go

err := w.AiGateway.DeleteModelProviderService(ctx,
	catalog.DeleteModelProviderServiceRequest{
		Name: "model-provider-services/main.default.my_provider",
	})

SDK de Java

w.aiGateway()
    .deleteModelProviderService(
        new DeleteModelProviderServiceRequest()
            .setName("model-provider-services/main.default.my_provider"));

JS SDK

await client.deleteModelProviderService({
  name: 'model-provider-services/main.default.my_provider',
});

Pasos siguientes

  • Last updated on