Gerencie os pontos de extremidade de serviço de modelo

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

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

Obter o status do ponto de extremidade do modelo

Na interface do usuário de serviço, você pode verificar o status de um ponto de extremidade a partir do indicador de estado do ponto de extremidade de serviço na parte superior da página de detalhes do ponto de extremidade.

Você pode usar verificar o status e os detalhes de um ponto de extremidade programaticamente usando a API REST ou o SDK de implantações MLflow

API REST

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

O exemplo a seguir cria um ponto de extremidade que serve a primeira versão do modelo registrado no registro do my-ads-model modelo do Unity Catalog. Você deve fornecer o nome completo do modelo, incluindo o catálogo pai e o esquema, catalog.schema.example-modelcomo .

No exemplo de resposta a seguir, o campo é "READY", o state.ready que significa que o ponto de extremidade está pronto para receber tráfego. O state.update_state campo é 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"
}

SDK de implantações MLflow

from mlflow.deployments import get_deploy_client

client = get_deploy_client("databricks")
endpoint = client.get_endpoint(endpoint="chat")
assert endpoint == {
    "name": "chat",
    "creator": "alice@company.com",
    "creation_timestamp": 0,
    "last_updated_timestamp": 0,
    "state": {...},
    "config": {...},
    "tags": [...],
    "id": "88fd3f75a0d24b0380ddc40484d7a31b",
}

Parar um modelo servindo ponto de extremidade

Você pode interromper temporariamente um ponto de extremidade de serviço de modelo e iniciá-lo mais tarde. Quando um ponto de extremidade é interrompido, os recursos provisionados para ele são desligados e o ponto de extremidade não é capaz de atender consultas até que seja iniciado novamente. Apenas os pontos de extremidade que servem modelos personalizados, não são otimizados para rotas e não têm atualizações em andamento podem ser interrompidos. Os pontos de extremidade interrompidos não contam para a cota de recursos. As consultas enviadas para um ponto de extremidade interrompido retornam um erro 400.

Você pode parar um ponto de extremidade na página de detalhes do ponto de extremidade na interface do usuário de serviço .

  1. Clique no ponto de extremidade que você deseja parar.
  2. Clique em Parar no canto superior direito.

Como alternativa, você pode interromper um ponto de extremidade de serviço programaticamente usando a API REST da seguinte maneira:

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

Quando estiver pronto para iniciar um ponto de extremidade de serviço de modelo interrompido, você poderá fazê-lo na página de detalhes do ponto de extremidade na interface do usuário de serviço .

  1. Clique no ponto de extremidade que deseja iniciar.
  2. Clique em Iniciar no canto superior direito.

Como alternativa, você pode iniciar um ponto de extremidade de serviço interrompido programaticamente usando a API REST da seguinte maneira:

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

Excluir um modelo de ponto de extremidade de serviço

Para desativar a veiculação para um modelo, você pode excluir o ponto de extremidade no qual ele é servido.

Você pode excluir um ponto de extremidade da página de detalhes do ponto de extremidade na interface do usuário de serviço .

  1. Clique em Servir na barra lateral.
  2. Clique no ponto de extremidade que você deseja excluir.
  3. Clique no menu kebab na parte superior e selecione Excluir.

Como alternativa, você pode excluir um ponto de extremidade de serviço programaticamente usando a API REST ou o SDK de implantações MLflow

API REST

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

SDK de implantações MLflow

from mlflow.deployments import get_deploy_client

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

Depurar seu ponto de extremidade de serviço de modelo

Para depurar quaisquer problemas com o ponto de extremidade, você pode buscar:

  • Logs de compilação de contêiner do servidor modelo
  • Logs do servidor modelo

Esses logs também podem ser acessados a partir da interface do usuário de pontos de extremidade na guia Logs .

Para os logs de compilação para um modelo servido, você pode usar a seguinte solicitação. Consulte Guia de depuração para 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
}

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

Você deve ter pelo menos a permissão CAN MANAGE 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 Servindo ACLs de ponto de extremidade.

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

databricks permissions get servingendpoints <endpoint-id>

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

databricks permissions update servingendpoints <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.

Obter um modelo que serve o esquema de ponto de extremidade

Importante

O suporte para servir esquemas de consulta de ponto de extremidade está em Visualização pública. Essa funcionalidade está disponível em regiões de serviço 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 padrão OpenAPI 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 você não é o criador ou proprietário original do ponto de extremidade.

Para obter o esquema de ponto de extremidade de serviço de modelo, o modelo servido deve ter uma assinatura de modelo registrada e o ponto de extremidade deve estar em um READY estado.

Os exemplos a seguir demonstram como obter programaticamente o esquema de ponto de extremidade de serviço de modelo usando a API REST. Para esquemas de ponto de extremidade de serviço de recursos, consulte O que é Databricks Feature Serving?.

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, infoservers e paths. Como a resposta do esquema é um objeto JSON, você pode analisá-lo usando linguagens de programação comuns e gerar código de cliente a partir da especificação usando ferramentas de terceiros. Você também pode visualizar a especificação OpenAPI usando ferramentas de terceiros como o Swagger Editor.

Os principais domínios da resposta incluem:

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

A seguir está um exemplo de resposta de 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"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}