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.
- Crie um modelo de IA generativo atendendo pontos de extremidade.
Obter o status do ponto de extremidade do modelo
Na interface do usuário de Serviços, você pode marcar o status de um ponto de extremidade 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 o recurso "verificar o status e os detalhes de um ponto de extremidade" programaticamente usando a API REST ou o SDK de Implantações do MLflow
API REST
GET /api/2.0/serving-endpoints/{name}
O exemplo a seguir cria um ponto de extremidade que atende à my-ads-model
primeira versão do modelo registrada no registro de modelos do Catálogo do Unity. Você deve fornecer o nome completo do modelo, incluindo o catálogo pai e o esquema, catalog.schema.example-model
como .
Na resposta de exemplo a seguir, 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"
}
SDK de Implantações do 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 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 ponto de extremidade é parado, os recursos provisionados para ele são desligados, e o ponto de extremidade não pode servir a consultas até ser iniciado novamente. Somente pontos de extremidade que servem a modelos personalizados, não são otimizados para rota e não têm atualizações em andamento podem ser parados. 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.
Você pode parar um ponto de extremidade na página de detalhes do ponto de extremidade na interface do usuário de Serviço.
- Clique no ponto de extremidade que você deseja parar.
- Clique em Parar no canto superior direito.
Como alternativa, você pode parar 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 que serve ao modelo parado, você poderá fazer isso na página de detalhes do ponto de extremidade na interface do usuário de Serviço.
- Clique no ponto de extremidade que você deseja iniciar.
- Clique em Iniciar no canto superior direito.
Como alternativa, você pode iniciar programaticamente um ponto de extremidade parado usando a API REST da seguinte maneira:
POST /api/2.0/serving-endpoints/{name}/config:start
Excluir um ponto de extremidade de serviço de modelo
Para desabilitar o fornecimento de um modelo, você pode excluir o ponto de extremidade em que 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ços.
- Clique em Servindo na barra lateral.
- Clique no ponto de extremidade que você deseja excluir.
- Clique no menu kebab na parte superior e selecione Excluir.
Alternativamente, você pode excluir um ponto de extremidade de serviço programaticamente usando a API REST ou o SDK de Implantações do MLflow
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 o ponto de extremidade de serviço do modelo
Para depurar quaisquer problemas com o ponto de extremidade, você pode buscar:
- Logs de build de contêiner do servidor modelo
- Logs do servidor de modelo
Esses logs também podem ser acessados na interface do usuário pontos de extremidade na guia Logs.
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
}
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 no ponto de extremidade de serviço do 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.
databricks permissions get servingendpoints <endpoint-id>
Conceda ao usuário jsmith@example.com
a permissão PODE CONSULTAR 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.
Obtenha um esquema de ponto de extremidade de atendimento de modelo
Importante
O suporte para servir esquemas de consulta de ponto de extremidade está em versão prévia pública. Essa funcionalidade está disponível em regiões do Model Serving.
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 esquemas de ponto de extremidade de serviço de recurso, veja O que é o serviço de recurso do Databricks?.
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 campourl
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. Cadapath
pode suportar vários formatos de entradas. Essas entradas estão listadas no campooneOf
.
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"
}
}
}
}
}
}
}
}
}
}
}
}