Compartilhar via

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 ponto final deve ter acesso 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

Confira a seguir um exemplo de criação de um ponto de extremidade de serviço usando a API REST POST /api/2.0/serving-endpoints e o campo environment_vars para configurar sua 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 passar credenciais para chamar OpenAI e outros pontos de extremidade de modelo externos ou acessar locais de armazenamento de dados externos diretamente do serviço de modelo.

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 a uma chave e um escopo de segredo desejados, conforme mostrado abaixo:


databricks secrets put-secret my_secret_scope my_secret_key

As informações de segredo e o nome da variável de ambiente podem ser passados para a configuração do ponto de extremidade durante a criação do ponto de extremidade ou como uma atualização para a configuração de um ponto de extremidade existente.

Etapa 2: adicionar escopos secretos à configuração do ponto de extremidade

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 pontos de extremidade do serviço de modelo personalizado.

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

Veja a seguir um exemplo de criação de um ponto de extremidade de serviço usando a API REST. Durante as atualizações de configuração e criação do ponto de extremidade do serviço de modelo, você pode fornecer uma lista de especificações de variáveis de ambiente de segredo para cada modelo de serviço 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 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 as atualizações de configuração e criação do ponto de extremidade do serviço de modelo, você pode fornecer uma lista de especificações de variáveis de ambiente de segredo para cada modelo de serviço 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 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 as atualizações de configuração e criação do ponto de extremidade do serviço de modelo, você pode fornecer uma lista de especificações de variáveis de ambiente de segredo para cada modelo de serviço 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 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