Gerenciar pontos de extremidade do serviço de modelo

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

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

• Crie pontos de extremidade de serviço de modelo personalizados.
• Crie 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). Preparo se refere a um ponto de extremidade poder 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 do 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']}")

Interromper um Ponto de extremidade do Serviço de Modelo

Você pode interromper temporariamente um endpoint de serviço de modelo e iniciá-lo novamente mais tarde. Quando um ponto de extremidade é interrompido:

• Os recursos provisionados para eles foram desativados.
• O endpoint não é capaz de atender consultas até que ele seja iniciado novamente.
• Somente endpoints que oferecem suporte a modelos personalizados e não têm atualizações em andamento podem ser parados.
• Os pontos de extremidade interrompidos 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 ponto de extremidade

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 do 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 ponto de extremidade do serviço de modelo

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 runtime e registro em log no nível do 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 o Guia de Depuração para Serviço de Modelos 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 CAN MANAGE em um Ponto de extremidade do Serviço de Modelo 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 do endpoint 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 de consulta no endpoint 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 uso sem servidor para um ponto de extremidade de serviço de modelo

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

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

Se tiver permissões MANAGE para um ponto de extremidade existente, você poderá editar e adicionar uma política de uso sem servidor a esse ponto de extremidade da página Detalhes do ponto de extremidade na interface do usuário.

Obter um esquema do ponto de extremidade do serviço de modelo

Um esquema de consulta de ponto de extremidade do serviço é uma descrição formal do ponto de extremidade do 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 ponto de extremidade do serviço, o modelo atendido deve ter uma assinatura de modelo registrada e o ponto de extremidade 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 pontos de extremidade do serviço de funcionalidades, consulte pontos de extremidade do serviço de funcionalidades.

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 endpoint 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 de 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"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}