Configurar el acceso a recursos desde puntos de conexión de servicio de modelos

En este artículo se describe cómo configurar el acceso a recursos externos y privados desde endpoints de servicio de modelos. El servicio de modelos admite variables de entorno de texto sin formato y variables de entorno basadas en secretos mediante secretos de Databricks.

Requisitos

En el caso de las variables de entorno basadas en secretos,

• El creador del punto de conexión debe tener acceso de lectura a los secretos de Databricks a los que se hace referencia en las configuraciones.
• Debe almacenar credenciales como la clave de API u otros tokens como secreto de Databricks.

Adición de variables de entorno de texto sin formato

Use variables de entorno de texto sin formato para establecer variables que no necesiten estar ocultas. Puede establecer variables en la interfaz de usuario de servicio, la API REST o el SDK al crear o actualizar un punto de conexión.

Interfaz de usuario de servicio

En la interfaz de usuario de servicio, puede agregar una variable de entorno en Configuraciones avanzadas:

REST API

A continuación se muestra un ejemplo para crear un punto de conexión de servicio mediante la API de REST POST /api/2.0/serving-endpoints y el campo environment_vars para configurar la variable de entorno.

{
  "name": "endpoint-name",
  "config": {
    "served_entities": [
      {
        "entity_name": "model-name",
        "entity_version": "1",
        "workload_size": "Small",
        "scale_to_zero_enabled": "true",
        "environment_vars": {
          "TEXT_ENV_VAR_NAME": "plain-text-env-value"
        }
      }
    ]
  }
}

WorkspaceClient SDK

A continuación se muestra un ejemplo para crear un endpoint de servicio mediante el SDK WorkspaceClient y el campo environment_vars para configurar la variable de entorno.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ServedEntityInput, EndpointCoreConfigInput, ServingModelWorkloadType

w = WorkspaceClient()

endpoint_name = "example-add-model"
model_name = "main.default.addmodel"
w.serving_endpoints.create_and_wait(
    name=endpoint_name,
    config=EndpointCoreConfigInput(
        served_entities=[
            ServedEntityInput(
                entity_name = model_name,
                entity_version = "2",
                workload_type = ServingModelWorkloadType("CPU"),
                workload_size = "Small",
                scale_to_zero_enabled = False,
                environment_vars = {
                    "MY_ENV_VAR": "value_to_be_injected",
                    "ADS_TOKEN": "abcdefg-1234"
                }
            )
        ]
    )
)

SDK de implementaciones de MLflow

A continuación se muestra un ejemplo para crear un punto de conexión de servicio utilizando el SDK de implementaciones de Mlflow y el campo environment_vars para configurar tu variable de entorno.

from mlflow.deployments import get_deploy_client

client = get_deploy_client("databricks")
endpoint = client.create_endpoint(
    name="unity-catalog-model-endpoint",
    config={
        "served_entities": [
            {
                "name": "ads-entity"
                "entity_name": "catalog.schema.my-ads-model",
                "entity_version": "3",
                "workload_size": "Small",
                "scale_to_zero_enabled": True,
                "environment_vars": {
                    "MY_ENV_VAR": "value_to_be_injected",
                    "ADS_TOKEN": "abcdefg-1234"
                }
            }
        ]
    }
)

Búsqueda de DataFrames de características de registro en tablas de inferencia

Si tiene habilitadas tablas de inferencia en su punto de conexión, puede registrar la trama de datos de búsqueda automática de características en esa tabla de inferencia mediante el uso de ENABLE_FEATURE_TRACING. Esto requiere MLflow 2.14.0 o superior.

Establezca ENABLE_FEATURE_TRACING como una variable de entorno en la interfaz de usuario de servicio, la API REST o el SDK al crear o actualizar un punto de conexión.

Interfaz de usuario de servicio

1. En Configuraciones avanzadas, seleccione ** + Agregar variables de entorno**.
2. Escriba ENABLE_FEATURE_TRACING como nombre del entorno.
3. En el campo a la derecha, escriba true.

REST API

A continuación se muestra un ejemplo para crear un punto de conexión de servicio mediante la API de REST POST /api/2.0/serving-endpoints y el campo environment_vars para configurar la variable de entorno ENABLE_FEATURE_TRACING.

{
  "name": "endpoint-name",
  "config": {
    "served_entities": [
      {
        "entity_name": "model-name",
        "entity_version": "1",
        "workload_size": "Small",
        "scale_to_zero_enabled": "true",
        "environment_vars": {
          "ENABLE_FEATURE_TRACING": "true"
        }
      }
    ]
  }
}

WorkspaceClient SDK

A continuación se muestra un ejemplo para crear un punto de conexión de servicio mediante WorkspaceClient SDK y el campo environment_vars para configurar la variable de entorno ENABLE_FEATURE_TRACING.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ServedEntityInput, EndpointCoreConfigInput, ServingModelWorkloadType

w = WorkspaceClient()

endpoint_name = "example-add-model"
model_name = "main.default.addmodel"
w.serving_endpoints.create_and_wait(
    name=endpoint_name,
    config=EndpointCoreConfigInput(
        served_entities=[
            ServedEntityInput(
                entity_name = model_name,
                entity_version = "2",
                workload_type = ServingModelWorkloadType("CPU"),
                workload_size = "Small",
                scale_to_zero_enabled = False,
                environment_vars = {
                    "ENABLE_FEATURE_TRACING": "true"
                }
            )
        ]
    )
)

SDK de implementaciones de MLflow

A continuación se muestra un ejemplo para crear un endpoint de servicio mediante el SDK de implementaciones de Mlflow y el campo environment_vars para configurar la variable de entorno ENABLE_FEATURE_TRACING.

from mlflow.deployments import get_deploy_client

client = get_deploy_client("databricks")
endpoint = client.create_endpoint(
    name="unity-catalog-model-endpoint",
    config={
        "served_entities": [
            {
                "name": "ads-entity"
                "entity_name": "catalog.schema.my-ads-model",
                "entity_version": "3",
                "workload_size": "Small",
                "scale_to_zero_enabled": True,
                "environment_vars": {
                    "ENABLE_FEATURE_TRACING": "true"
                }
            }
        ]
    }
)

Adición de variables de entorno basadas en secretos

Puede almacenar de forma segura las credenciales mediante secretos de Databricks y hacer referencia a esos secretos en el servicio de modelos mediante variables de entorno basadas en secretos. Esto permite capturar las credenciales de los puntos de conexión de servicio del modelo en tiempo de servicio.

Por ejemplo, puede proporcionar credenciales para realizar llamadas a OpenAI y a otros puntos de conexión de modelos externos, o para acceder directamente a ubicaciones externas de almacenamiento de datos desde el servicio de inferencia de modelos.

Databricks recomienda esta característica para implementar los tipos de modelo de MLflow de OpenAI y LangChain en servicio. También es aplicable a otros modelos de SaaS que requieren credenciales con la comprensión de que el patrón de acceso se basa en el uso de variables de entorno y claves de API y tokens.

Paso 1: Creación de un ámbito de secreto

Durante la implementación del modelo, los secretos se recuperan del almacén de secretos de Databricks mediante la clave y el ámbito del secreto. Estos se asignan a los nombres de variables de entorno secretas que se pueden usar dentro del modelo.

En primer lugar, cree un ámbito de secreto. Consulte Administración de ámbitos secretos.

A continuación se muestran los comandos de la CLI:

databricks secrets create-scope my_secret_scope

Después, puede agregar el secreto a una clave y ámbito de secreto deseados, como se muestra a continuación:

databricks secrets put-secret my_secret_scope my_secret_key

La información secreta y el nombre de la variable de entorno pueden pasarse en la configuración del punto de conexión durante la creación del punto de conexión o al actualizar la configuración de un punto de conexión existente.

Paso 2: Agregar ámbitos secretos a la configuración del punto de conexión

Puede agregar el ámbito de secretos a una variable de entorno y pasar esa variable al punto de conexión al crear el punto de conexión o al actualizar su configuración. Consulte Crear endpoints personalizados para servir modelos.

Interfaz de usuario de servicio

En la interfaz de usuario de servicio, puede agregar una variable de entorno en las configuraciones avanzadas. La variable de entorno basada en secretos debe proporcionarse con la siguiente sintaxis: {{secrets/scope/key}}. De lo contrario, la variable de entorno se considera una variable de entorno de texto sin formato.

REST API

A continuación se muestra un ejemplo para crear un punto de conexión de servicio mediante la API REST. Durante la creación de endpoints de servicio del modelo y las actualizaciones de su configuración, puede proporcionar en la solicitud a la API, mediante el campo environment_vars, una lista de especificaciones de variables de entorno secretas para cada modelo implementado.

En el ejemplo siguiente se asigna el valor del secreto creado en el código proporcionado a la variable de entorno OPENAI_API_KEY.

{
  "name": "endpoint-name",
  "config": {
    "served_entities": [
      {
        "entity_name": "model-name",
        "entity_version": "1",
        "workload_size": "Small",
        "scale_to_zero_enabled": "true",
        "environment_vars": {
          "OPENAI_API_KEY": "{{secrets/my_secret_scope/my_secret_key}}"
        }
      }
    ]
  }
}

También puede actualizar un endpoint de servicio, como en el siguiente ejemplo de API REST PUT /api/2.0/serving-endpoints/{name}/config :

{
  "served_entities": [
    {
      "entity_name": "model-name",
      "entity_version": "2",
      "workload_size": "Small",
      "scale_to_zero_enabled": "true",
      "environment_vars": {
        "OPENAI_API_KEY": "{{secrets/my_secret_scope/my_secret_key}}"
      }
    }
  ]
}

WorkspaceClient SDK

A continuación se muestra un ejemplo para crear un endpoint de servicio mediante el SDK WorkspaceClient. Durante la creación del endpoint de servicio del modelo y las actualizaciones de su configuración, puede proporcionar en la solicitud a la API, mediante el campo environment_vars, una lista de especificaciones de variables de entorno secretas para cada modelo servido.

En el ejemplo siguiente se asigna el valor del secreto creado en el código proporcionado a la variable de entorno OPENAI_API_KEY.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ServedEntityInput, EndpointCoreConfigInput, ServingModelWorkloadType

w = WorkspaceClient()

endpoint_name = "example-add-model"
model_name = "main.default.addmodel"
w.serving_endpoints.create_and_wait(
    name=endpoint_name,
    config=EndpointCoreConfigInput(
        served_entities=[
            ServedEntityInput(
                entity_name = model_name,
                entity_version = "2",
                workload_type = ServingModelWorkloadType("CPU"),
                workload_size = "Small",
                scale_to_zero_enabled = False,
                environment_vars = {
                    "OPENAI_API_KEY": "{{secrets/my_secret_scope/my_secret_key}}"
                }
            )
        ]
    )
)

SDK de implementaciones de MLflow

A continuación se muestra un ejemplo para crear un punto de servicio mediante el SDK de Mlflow Deployments. Durante la creación de endpoints de servicio de modelos y las actualizaciones de configuración, puede proporcionar en la solicitud a la API, mediante el campo environment_vars, una lista de especificaciones de variables de entorno secretas para cada modelo servido.

En el ejemplo siguiente se asigna el valor del secreto creado en el código proporcionado a la variable de entorno OPENAI_API_KEY.

from mlflow.deployments import get_deploy_client

client = get_deploy_client("databricks")
endpoint = client.create_endpoint(
    name="unity-catalog-model-endpoint",
    config={
        "served_entities": [
            {
                "name": "ads-entity"
                "entity_name": "catalog.schema.my-ads-model",
                "entity_version": "3",
                "workload_size": "Small",
                "scale_to_zero_enabled": True,
                "environment_vars": {
                    "OPENAI_API_KEY": "{{secrets/my_secret_scope/my_secret_key}}"
                }
            }
        ]
    }
)

Una vez que se crea o se actualiza el punto de conexión, el servicio de modelos obtiene automáticamente la clave secreta del ámbito de secretos de Databricks y establece la variable de entorno para que la utilice el código de inferencia de su modelo.

Ejemplo de cuaderno

Consulte el cuaderno siguiente para obtener un ejemplo de cómo configurar una clave de API de OpenAI para una cadena de control de calidad de recuperación de LangChain implementada detrás de los puntos de conexión de servicio del modelo con variables de entorno basadas en secretos.

Cuaderno de configuración del acceso a recursos desde puntos de conexión de servicio de modelos

Descargar el cuaderno