Gerir endpoints de serviço do modelo

Este artigo descreve como gerir endpoints de serviço de modelo usando a interface de utilizador de serviço e a API REST. Consulte Pontos de Serviço na referência da API REST.

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

• Crie endpoints de serviço de modelo personalizado.
• Criar modelo de fundação que sirva pontos de extremidade.

Obter o status do ponto de extremidade do modelo

Você pode verificar o status de um ponto de extremidade usando a interface do usuário Serving ou programaticamente usando a API REST, o Cliente de Espaço de Trabalho Databricks ou o SDK de implantações MLflow.

Os estados dos pontos finais podem ser Ready, Ready (Update failed), Not ready (Updating), Not ready (Update failed)ou Not ready (Stopped). A prontidão refere-se à possibilidade de interrogar ou não um endpoint. A falha na atualização indica que a última alteração no ponto de extremidade não teve sucesso. Interrompido significa que o endpoint foi interrompido.

IU

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

API REST

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

No exemplo de resposta seguinte, o campo state.ready é "READY", o que significa que o ponto de extremidade 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 espaço de trabalho Databricks

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 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 servidor de modelo endereço de serviço

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

• Os recursos provisionados para isso são encerrados.
• O ponto de extremidade não pode atender requisições até que seja iniciado novamente.
• Apenas os pontos de extremidade que servem modelos personalizados 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.

Parar um ponto de extremidade

IU

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 da configuração com as mesmas propriedades da configuração parada existente.

Quando estiver pronto para iniciar um endpoint de modelo em serviço parado:

IU

Clique em Iniciar no canto superior direito.

API REST

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

Eliminar um endpoint de serviço de modelo

A exclusão de 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.

IU

Clique no menu kebab na parte superior e selecione Excluir.

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 um modelo que serve o ponto de extremidade

Dois tipos de logs estão disponíveis para ajudar a depurar problemas com os pontos de extremidade.

• Logs de construção do contentor do servidor modelo: Gerados durante a inicialização do ponto final quando o contentor está a ser 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 tempo de execução. Utilize estes logs para depurar por que um endpoint falhou ao iniciar ou está bloqueado durante a implantação.
• Logs do servidor modelo: gerados durante a execução quando o endpoint está ativamente servindo previsões. Esses logs capturam as solicitações de entrada, a execução da inferência do modelo, os erros de tempo de execução e o registo ao nível da aplicação a partir 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 são acessíveis a partir da interface do usuário de Endpoints na guia Logs.

Obter logs de compilação de contêiner

Para os registos de compilação de um modelo implantado, pode-se usar a seguinte solicitação. 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 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
}

Gerir permissões num endpoint de serviço do modelo

Você deve ter pelo menos a permissão CAN MANAGE em um endpoint 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 servidora.

IU

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 utilizador jsmith@example.com a permissão CAN QUERY 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 do endpoint de serviço usando a Permissões API.

Adicionar uma política de orçamento sem servidor para um modelo de ponto de extremidade de serviço

As políticas de orçamento sem servidor permitem que sua organização aplique tags personalizadas no uso sem servidor para atribuição de faturamento granular. Se seu espaço de trabalho usa políticas de orçamento sem servidor para atribuir o uso sem servidor, você pode adicionar uma política de orçamento sem servidor ao seu modelo de pontos de extremidade de serviço. Consulte Uso de atributos com políticas de orçamento sem servidor.

Durante a criação do ponto de extremidade para disponibilização de modelos, pode selecionar a política de orçamento Serverless do ponto de extremidade 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 receberão essa política de orçamento sem servidor, mesmo que você não selecione uma política no menu Política de orçamento .

Se tiver MANAGE permissões para um endpoint existente, pode editar e adicionar uma política de orçamento serverless a esse endpoint na página Detalhes do endpoint na IU.

Obter um modelo que serve o esquema de ponto de extremidade

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 do ponto de extremidade do serviço do modelo, o modelo servido deve ter uma assinatura de modelo registada e o ponto de extremidade deve estar em um estado READY.

Os exemplos a seguir demonstram como obter de forma programática o esquema do endpoint de serviço do modelo usando a API REST. Para esquemas de ponto de extremidade de serviço de recursos, consulte Pontos de extremidade de serviço de recursos.

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 campo info.title 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 no campo oneOf.

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