Configurar o acesso aos recursos a partir de endpoints de disponibilização de modelos

Este artigo descreve como configurar o acesso a recursos externos e privados a partir dos pontos finais de disponibilização de modelos. O Model Serving suporta variáveis de ambiente de texto simples e variáveis de ambiente baseadas em secrets utilizando os secrets do Databricks.

Requisitos

Para variáveis de ambiente baseadas em segredos,

• O criador do endpoint tem de ter permissão READ para os segredos do Databricks referenciados nas configurações.
• Você deve armazenar credenciais como sua chave de API ou outros tokens como um segredo do Databricks.

Adicionar variáveis de ambiente de texto sem formatação

Use variáveis de ambiente de texto sem formatação para definir variáveis que não precisam ser ocultadas. Você pode definir variáveis na Interface de Utilizador de Serviço, na API REST ou no SDK ao criar ou atualizar um endpoint.

Servindo a interface do usuário

Na interface do usuário de serviço, você pode adicionar uma variável de ambiente em Configurações avançadas:

API REST

Segue-se um exemplo de como criar um endpoint de serviço utilizando a API REST POST /api/2.0/serving-endpoints e o campo environment_vars para configurar a variável de ambiente.

{
  "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 seguir está um exemplo para criar um endpoint de serviço usando o SDK WorkspaceClient e o campo environment_vars para configurar a sua variável de ambiente.

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 desenvolvimentos MLflow

A seguir está um exemplo para criar um ponto de extremidade de serviço usando o SDK de implantações Mlflow e o campo environment_vars para configurar a sua variável de ambiente.

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

Registar a pesquisa de funcionalidades nos DataFrames em tabelas de inferência

Se tiver tabelas de inferência ativadas no seu endpoint, pode registar o seu quadro de dados de pesquisa automática de funcionalidades nessa tabela de inferência usando ENABLE_FEATURE_TRACING. Isto requer MLflow 2.14.0 ou superior.

Defina ENABLE_FEATURE_TRACING como uma variável de ambiente na interface de utilizador do serviço, API REST ou SDK ao criar ou atualizar um ponto de extremidade.

Servindo a interface do usuário

1. Em Configurações avançadas, selecione ** + Adicionar variáveis de ambiente**.
2. Digite ENABLE_FEATURE_TRACING como o nome do ambiente.
3. No campo à direita, digite true.

API REST

Aqui está um exemplo de como criar um endpoint de serviço usando a POST /api/2.0/serving-endpoints API REST e o campo environment_vars para configurar as variáveis de ambiente 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 seguir está um exemplo para criar um ponto de extremidade de serviço usando o SDK WorkspaceClient e o environment_vars campo para configurar a variável de ENABLE_FEATURE_TRACING ambiente.

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 desenvolvimentos MLflow

A seguir está um exemplo para criar um ponto de acesso de serviço usando o Mlflow Deployments SDK e o environment_vars campo para configurar a variável de ambiente 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"
                }
            }
        ]
    }
)

Adicionar variáveis de ambiente baseadas em segredos

Você pode armazenar credenciais com segurança usando segredos do Databricks e fazer referência a esses segredos no serviço de modelo usando variáveis de ambiente baseadas em segredos. Isso permite que as credenciais sejam obtidas nos endpoints de serviço do modelo no momento de execução.

Por exemplo, pode-se passar credenciais para interagir com o OpenAI e outros endpoints de modelos externos ou aceder diretamente a locais de armazenamento de dados externos a partir do provisionamento de modelos.

A Databricks recomenda esta funcionalidade para implementar em serving as variantes de modelo MLflow de OpenAI e LangChain. Também é aplicável a outros modelos SaaS que exigem credenciais com o entendimento de que o padrão de acesso é baseado no uso de variáveis de ambiente e chaves e tokens de API.

Etapa 1: Criar um escopo secreto

Durante a disponibilização do modelo, os segredos são obtidos a partir do Databricks Secrets através do âmbito e da chave do segredo. Eles são atribuídos aos nomes de variáveis de ambiente secreto que podem ser usados dentro do modelo.

Primeiro, crie um escopo secreto. Consulte Gerenciar escopos secretos.

A seguir estão os comandos da CLI:

databricks secrets create-scope my_secret_scope

Em seguida, você pode adicionar seu segredo a um escopo e chave secretos desejados, conforme mostrado abaixo:

databricks secrets put-secret my_secret_scope my_secret_key

As informações secretas e o nome da variável de ambiente podem ser transmitidos para a configuração do endpoint durante a sua criação ou como uma atualização para a configuração de um endpoint já existente.

Etapa 2: Adicionar âmbitos secretos à configuração do endpoint

Você pode adicionar o escopo secreto a uma variável de ambiente e passar essa variável para seu ponto de extremidade durante a criação do ponto de extremidade ou atualizações de configuração. Consulte Criar endpoints personalizados para disponibilização de modelos.

Servindo a interface do usuário

Na interface do usuário de serviço, você pode adicionar uma variável de ambiente em Configurações avançadas. A variável de ambiente baseada em segredos deve ser fornecida usando a seguinte sintaxe: {{secrets/scope/key}}. Caso contrário, a variável de ambiente é considerada uma variável de ambiente de texto simples.

API REST

A seguir está um exemplo para criar um ponto de extremidade de serviço usando a API REST. Durante a criação e atualização de configuração do endpoint de serviço do modelo, pode fornecer uma lista de especificações de variáveis de ambiente secretas para cada modelo servido dentro da solicitação de API, usando o campo environment_vars.

O exemplo a seguir atribui o valor do segredo criado no código fornecido à variável OPENAI_API_KEYde ambiente .

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

Você também pode atualizar um endpoint de serviço, como a seguir no exemplo de API REST do 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 seguir está um exemplo para criar um ponto de extremidade de serviço usando o SDK do WorkspaceClient. Durante a criação e atualização de configuração do endpoint de serviço do modelo, pode fornecer uma lista de especificações de variáveis de ambiente secretas para cada modelo servido dentro da solicitação de API, usando o campo environment_vars.

O exemplo a seguir atribui o valor do segredo criado no código fornecido à variável OPENAI_API_KEYde ambiente .

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 desenvolvimentos MLflow

A seguir está um exemplo para criar um endpoint de serviço usando o SDK de implementações Mlflow. Durante a criação e atualização de configuração do endpoint de serviço do modelo, pode fornecer uma lista de especificações de variáveis de ambiente secretas para cada modelo servido dentro da solicitação de API, usando o campo environment_vars.

O exemplo a seguir atribui o valor do segredo criado no código fornecido à variável OPENAI_API_KEYde ambiente .

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

Depois de o endpoint ser criado ou atualizado, o serviço de disponibilização de modelos obtém automaticamente a chave secreta do âmbito de segredos do Databricks e define a variável de ambiente para ser utilizada pelo código de inferência do modelo.

Exemplo de caderno

Consulte o bloco de anotações a seguir para obter um exemplo de como configurar uma chave de API OpenAI para uma cadeia de QA de recuperação LangChain implantada por trás do modelo que serve pontos de extremidade com variáveis de ambiente baseadas em segredo.

Configurar o acesso a recursos a partir do bloco de notas de pontos finais de serviço de modelo

Obter bloco de notas