Configurar o acesso aos recursos dos pontos de extremidade do serviço de modelo

Esse artigo descreve como configurar o acesso a recursos externos e privados a partir de pontos finais de serviço de modelo. O Model Serving oferece suporte a variáveis de ambiente de texto simples e variáveis de ambiente baseadas em segredos usando Databricks segredos.

Requisitos

Para variáveis de ambiente baseadas em segredos,

  • O criador do endpoint deve ter acesso de leitura (READ) aos 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 simples

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

Interface do usuário de serviço

Na IU do Serving, você pode adicionar uma variável de ambiente em Configurações avançadas:

Criar um ponto de extremidade de serviço de modelo

API REST

Veja a seguir um exemplo de como criar um endpoint de serviço usando 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

O seguinte é um exemplo para criar um endpoint de serviço usando o WorkspaceClient SDK e o campo environment_vars para configurar a 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 Implantações do MLflow

O seguinte é um exemplo para criar um endpoint de serviço usando o SDK de Deployments do Mlflow e o campo environment_vars para configurar 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"
                }
            }
        ]
    }
)

DataFrames de pesquisa de recursos do log nas tabelas de inferência

Se você tiver tabelas de inferência habilitadas no seu ponto de extremidade, poderá registrar seu quadro de dados de pesquisa de recursos automático nessa tabela de inferência usando ENABLE_FEATURE_TRACING. Isso requer o MLflow 2.14.0 ou superior.

Defina ENABLE_FEATURE_TRACING como uma variável de ambiente na interface do usuário do Serving, API REST ou SDK ao criar ou atualizar um endpoint.

Interface do usuário de serviço

  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.

Criar um ponto de extremidade de serviço de modelo

API REST

Veja a seguir um exemplo para criar um endpoint de serviço usando a API REST POST /api/2.0/serving-endpoints e o campo environment_vars para configurar a variável 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

Veja a seguir um exemplo para criar um ponto de extremidade de serviço usando o SDK WorkspaceClient e o campo environment_vars para configurar a variável de ambiente 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 Implantações do MLflow

Veja a seguir um exemplo para criar um endpoint de serviço usando o SDK de Implantações do Mlflow e o campo de configuração environment_vars para definir 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"
                }
            }
        ]
    }
)

Adicione 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 dos endpoints de atendimento do modelo no momento do atendimento.

Por exemplo, você pode fornecer credenciais para fazer chamadas à OpenAI e a outros endpoints de modelo externos ou acessar locais de armazenamento de dados externos diretamente do serving de modelos.

O Databricks recomenda esse recurso para implantar tipos de modelo MLflow OpenAI e LangChain ao serviço. Isso também é aplicável a outros modelos de SaaS que exigem credenciais com a compreensão de que o padrão de acesso se baseia no uso de variáveis de ambiente, tokens e chaves de API.

Etapa 1: crie um escopo secreto

Durante o serviço de modelo, os segredos são recuperados a partir dos segredos do Databricks pela chave e pelo escopo 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.

Veja a seguir os comandos da CLI:


databricks secrets create-scope my_secret_scope

Em seguida, você pode adicionar seu segredo ao escopo de segredos e à chave 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 então ser passadas para a configuração do endpoint durante a criação do endpoint ou como uma atualização da configuração de um endpoint existente.

Etapa 2: Adicionar escopos de segredo à 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.

Interface do usuário de serviço

Na IU do Serving, 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 será considerada uma variável de ambiente de texto simples.

Criar um ponto de extremidade de serviço de modelo

API REST

A seguir, apresentamos um exemplo de como criar um endpoint de serviço usando a API REST. Durante a criação do endpoint de serving do modelo e as atualizações de configuração, você pode fornecer uma lista de especificações de variáveis de ambiente secretas para cada modelo servido na solicitação da API usando o campo environment_vars.

O exemplo a seguir atribui o valor do segredo criado no código fornecido à variável de ambiente 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}}"
        }
      }
    ]
  }
}

Também é possível atualizar um ponto de extremidade de serviço, como no seguinte exemplo 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

Veja a seguir um exemplo para criar um endpoint de serviço usando o SDK do WorkspaceClient. Durante a criação do endpoint de serving do modelo e as atualizações de configuração, você pode fornecer, na solicitação da API, uma lista de especificações de variáveis de ambiente secretas para cada modelo servido usando o campo environment_vars.

O exemplo a seguir atribui o valor do segredo criado no código fornecido à variável de ambiente 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 Implantações do MLflow

Veja a seguir um exemplo para criar um ponto de serviço usando o SDK de Deployments do Mlflow. Durante a criação do endpoint de serving do modelo e as atualizações de configuração, você pode fornecer, na solicitação da API, uma lista de especificações de variáveis de ambiente secretas para cada modelo servido usando o campo environment_vars.

O exemplo a seguir atribui o valor do segredo criado no código fornecido à variável de ambiente 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}}"
                }
            }
        ]
    }
)

Depois que o ponto de extremidade é criado ou atualizado, o serviço de modelo busca automaticamente a chave secreta do escopo de segredos do Databricks e preenche a variável de ambiente para o código de inferência do modelo a ser usado.

Exemplo de notebook

Consulte o notebook a seguir para obter um exemplo de como configurar uma chave de API do OpenAI, para uma cadeia de garantia de qualidade de recuperação LangChain, implantada atrás do modelo que atende pontos de extremidade com variáveis de ambiente baseadas em segredo.

Configurar o acesso aos recursos a partir do notebook de pontos de extremidade do serviço de modelo

Obter notebook

  • Last updated on