Gerenciar pontos de extremidade de serviço de modelo

Este artigo descreve como gerenciar ponto de extremidade de modelo usando a interface do usuário de Serviços ou a API REST. Confira os pontos de extremidade de serviço na referência da API REST.

Para criar pontos de extremidade de serviço de modelo, use uma das seguintes opções:

• Criar pontos de extremidade de serviço de modelo personalizados.
• Criar pontos de extremidade de serviço de modelos de base.

Obter o status do ponto de extremidade do modelo

Você pode verificar o status de um endpoint usando a Serving UI ou programaticamente usando a API REST, o Cliente de Workspace do Databricks ou o SDK de Implantações do MLflow.

Os status do ponto de extremidade podem ser Ready, Ready (Update failed), Not ready (Updating), Not ready (Update failed) ou Not ready (Stopped). Prontidão refere-se a se um ponto de extremidade pode ser consultado ou não. A atualização falhou, sinalizando que a alteração mais recente no endpoint não foi bem-sucedida. Parado significa que o ponto de extremidade foi interrompido.

interface do usuário

O indicador de estado do ponto de extremidade de serviço na parte superior da página de detalhes de um ponto de extremidade:

API REST

GET /api/2.0/serving-endpoints/{name}

Na resposta de exemplo a seguir, o campo state.ready é "READY", o que significa que o endpoint está pronto para receber tráfego. O campo state.update_state é NOT_UPDATING e pending_config não é mais retornado porque a atualização foi concluída com êxito.

{
  "name": "unity-model-endpoint",
  "creator": "customer@example.com",
  "creation_timestamp": 1666829055000,
  "last_updated_timestamp": 1666829055000,
  "state": {
    "ready": "READY",
    "update_state": "NOT_UPDATING"
  },
  "config": {
    "served_entities": [
      {
        "name": "my-ads-model",
        "entity_name": "myCatalog.mySchema.my-ads-model",
        "entity_version": "1",
        "workload_size": "Small",
        "scale_to_zero_enabled": false,
        "state": {
          "deployment": "DEPLOYMENT_READY",
          "deployment_state_message": ""
        },
        "creator": "customer@example.com",
        "creation_timestamp": 1666829055000
      }
    ],
    "traffic_config": {
      "routes": [
        {
          "served_model_name": "my-ads-model",
          "traffic_percentage": 100
        }
      ]
    },
    "config_version": 1
  },
  "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "permission_level": "CAN_MANAGE"
}

Cliente do Databricks Workspace

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
endpoint = w.serving_endpoints.get(name="my-endpoint")
print(f"Endpoint state: {endpoint.state.ready}")
print(f"Update state: {endpoint.state.config_update}")

SDK de Implantações do MLflow

from mlflow.deployments import get_deploy_client

client = get_deploy_client("databricks")
endpoint = client.get_endpoint(endpoint="my-endpoint")
print(f"Endpoint state: {endpoint['state']}")
print(f"Endpoint config: {endpoint['config']}")

Parar um modelo que serve ao ponto de extremidade

Você pode parar temporariamente um ponto de extremidade que serve ao modelo e iniciá-lo mais tarde. Quando um terminal é interrompido:

• Os recursos provisionados para eles foram desativados.
• O endpoint não é capaz de atender consultas até que ele seja iniciado novamente.
• Somente pontos de extremidade que atendem modelos personalizados e não têm atualizações em andamento podem ser interrompidos.
• Os pontos de extremidade parados não são contabilizados na cota de recursos.
• Consultas enviadas a um ponto de extremidade parado retornam um erro 400.

Parar um ponto de extremidade

interface do usuário

Clique em Parar no canto superior direito.

API REST

POST /api/2.0/serving-endpoints/{name}/config:stop

Iniciar um endpoint

Iniciar um endpoint cria uma nova versão de configuração com as mesmas propriedades que a configuração interrompida existente.

Quando você estiver pronto para iniciar um ponto de extremidade de serviço de modelo parado:

interface do usuário

Clique em Iniciar no canto superior direito.

API REST

POST /api/2.0/serving-endpoints/{name}/config:start

Excluir um ponto de extremidade de serviço de modelo

Excluir um ponto de extremidade desabilita o uso e exclui todos os dados associados ao ponto de extremidade. Não é possível desfazer a exclusão.

interface do usuário

Clique no menu kebab na parte superior e selecione Excluir.

API REST

DELETE /api/2.0/serving-endpoints/{name}

SDK de Implantações do MLflow

from mlflow.deployments import get_deploy_client

client = get_deploy_client("databricks")
client.delete_endpoint(endpoint="chat")

Depurar um endpoint de serviço de modelo de aprendizado de máquina

Dois tipos de logs estão disponíveis para ajudar a solucionar problemas com endpoints:

• Logs de compilação do contêiner do servidor de modelo: Gerados durante a inicialização do endpoint quando o contêiner está sendo criado. Esses logs capturam a fase de instalação, incluindo o download do modelo, a instalação de dependências e a configuração do ambiente de runtime. Use esses logs para solucionar problemas de por que um endpoint falhou ao iniciar ou ficou travado durante a implantação.
• Logs do servidor de modelo: gerados durante a execução quando o endpoint está atendendo ativamente previsões. Esses logs capturam solicitações de entrada, execução de inferência de modelo, erros de tempo de execução e log de nível de aplicativo do código do modelo. Use esses logs para depurar problemas com previsões ou investigar falhas de consulta.

Ambos os tipos de log também podem ser acessados na interface gráfica dos Endpoints, na guia Logs.

Obter logs de construção de contêiner

Para os logs de compilação de um modelo servido, você pode usar a solicitação a seguir. Consulte Guia de depuração para o serviço de modelo para obter mais informações.

GET /api/2.0/serving-endpoints/{name}/served-models/{served-model-name}/build-logs
{
  "config_version": 1  // optional
}

Obter logs do servidor de modelo

Para os logs do servidor modelo para um modelo de serviço, você pode usar a seguinte solicitação:

GET /api/2.0/serving-endpoints/{name}/served-models/{served-model-name}/logs

{
  "config_version": 1  // optional
}

Gerenciar permissões em um endpoint de serviço de modelo

Você deve ter pelo menos a permissão PODE GERENCIAR em um ponto de extremidade de serviço para modificar permissões. Para obter mais informações sobre os níveis de permissão, consulte ACLs de ponto de extremidade de serviço.

Obtenha a lista de permissões no ponto de extremidade de serviço.

interface do usuário

Clique no botão Permissões no canto superior direito da interface do usuário.

CLI do Databricks

databricks permissions get serving-endpoints <endpoint-id>

Conceda ao usuário jsmith@example.com a permissão PODE CONSULTAR no ponto de extremidade de serviço.

databricks permissions update serving-endpoints <endpoint-id> --json '{
  "access_control_list": [
    {
      "user_name": "jsmith@example.com",
      "permission_level": "CAN_QUERY"
    }
  ]
}'

Você também pode modificar as permissões de ponto de extremidade de serviço usando a API de Permissões.

Adicionar uma política de orçamento sem servidor para um Ponto de extremidade do Serviço de Modelo

As políticas de orçamento sem servidor permitem que a sua organização aplique marcas personalizadas no uso sem servidor para atribuição de cobrança granular. Se o workspace usar políticas de orçamento sem servidor para atribuir o uso sem servidor, você poderá adicionar uma política de orçamento sem servidor aos seus pontos de extremidade do Serviço de Modelo. Consulte o uso de atributos com políticas de orçamento sem servidor.

Durante a criação do endpoint de serviço de modelo, você pode selecionar a política de orçamento sem servidor do endpoint no menu Política de orçamento na interface de serviço. Se você tiver uma política de orçamento sem servidor atribuída a você, todos os pontos de extremidade criados serão atribuídos a essa política de orçamento sem servidor, mesmo que você não selecione uma política no menu de política de Orçamento .

Se tiver permissões de MANAGE sobre um ponto de extremidade existente, você poderá editar e adicionar uma política de orçamento sem servidor a esse ponto de extremidade na página de detalhes do ponto de extremidade na interface do usuário.

Obtenha um esquema de ponto de extremidade de atendimento de modelo

Um esquema de consulta de ponto de extremidade de serviço é uma descrição formal do ponto de extremidade de serviço usando a especificação OpenAPI padrão no formato JSON. Ele contém informações sobre o ponto de extremidade, incluindo o caminho do ponto de extremidade, detalhes para consultar o ponto de extremidade, como o formato do corpo da solicitação e da resposta, e o tipo de dados para cada campo. Essas informações podem ser úteis para cenários de reprodutibilidade ou quando você precisa de informações sobre o ponto de extremidade, mas não é o criador ou o proprietário original do ponto de extremidade.

Para obter o esquema do terminal de atendimento do modelo, o modelo atendido deve ter uma assinatura de modelo registrada e o terminal deve estar em um estado READY.

Os exemplos a seguir demonstram como obter programaticamente o esquema de endpoint de atendimento ao modelo usando a API REST. Para obter esquemas de ponto de extremidade de serviço de recurso, consulte pontos de extremidade de Serviço de Recurso.

O esquema retornado pela API está no formato de um objeto JSON que segue a especificação OpenAPI.

ACCESS_TOKEN="<endpoint-token>"
ENDPOINT_NAME="<endpoint name>"

curl "https://example.databricks.com/api/2.0/serving-endpoints/$ENDPOINT_NAME/openapi" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json"

Detalhes da resposta do esquema

A resposta é uma especificação OpenAPI no formato JSON, normalmente incluindo campos como openapi, info, servers e paths. Como a resposta do esquema é um objeto JSON, você pode analisá-la usando linguagens de programação comuns e gerar código do cliente a partir da especificação usando ferramentas de terceiros. Você também pode visualizar a especificação OpenAPI usando ferramentas de terceiros como Swagger Editor.

Os principais campos da resposta incluem:

• O campo info.title mostra o nome do ponto de extremidade de serviço.
• O campo servers sempre contém um objeto, normalmente o campo url que é o URL base do ponto de extremidade.
• O objeto paths na resposta contém todos os caminhos suportados para um ponto de extremidade. As chaves no objeto são o URL do caminho. Cada path pode suportar vários formatos de entradas. Essas entradas estão listadas no campo oneOf.

Veja a seguir um exemplo de resposta do esquema do ponto de extremidade:

{
  "openapi": "3.1.0",
  "info": {
    "title": "example-endpoint",
    "version": "2"
  },
  "servers": [{ "url": "https://example.databricks.com/serving-endpoints/example-endpoint" }],
  "paths": {
    "/served-models/vanilla_simple_model-2/invocations": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "dataframe_split": {
                        "type": "object",
                        "properties": {
                          "columns": {
                            "description": "required fields: int_col",
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": ["int_col", "float_col", "string_col"]
                            }
                          },
                          "data": {
                            "type": "array",
                            "items": {
                              "type": "array",
                              "prefixItems": [
                                {
                                  "type": "integer",
                                  "format": "int64"
                                },
                                {
                                  "type": "number",
                                  "format": "double"
                                },
                                {
                                  "type": "string"
                                }
                              ]
                            }
                          }
                        }
                      },
                      "params": {
                        "type": "object",
                        "properties": {
                          "sentiment": {
                            "type": "number",
                            "format": "double",
                            "default": "0.5"
                          }
                        }
                      }
                    },
                    "examples": [
                      {
                        "columns": ["int_col", "float_col", "string_col"],
                        "data": [
                          [3, 10.4, "abc"],
                          [2, 20.4, "xyz"]
                        ]
                      }
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "dataframe_records": {
                        "type": "array",
                        "items": {
                          "required": ["int_col", "float_col", "string_col"],
                          "type": "object",
                          "properties": {
                            "int_col": {
                              "type": "integer",
                              "format": "int64"
                            },
                            "float_col": {
                              "type": "number",
                              "format": "double"
                            },
                            "string_col": {
                              "type": "string"
                            },
                            "becx_col": {
                              "type": "object",
                              "format": "unknown"
                            }
                          }
                        }
                      },
                      "params": {
                        "type": "object",
                        "properties": {
                          "sentiment": {
                            "type": "number",
                            "format": "double",
                            "default": "0.5"
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "predictions": {
                      "type": "array",
                      "items": {
                        "type": "number",
                        "format": "double"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}