Gestire gli endpoint di servizio del modello

Questo articolo descrive come gestire gli endpoint di gestione del modello usando l'interfaccia utente di servizio e l'API REST. Consulta Servire endpoint nella guida di riferimento all'API REST.

Per creare endpoint di gestione del modello, usare una delle opzioni seguenti:

• Creare endpoint di servizio per modelli personalizzati.
• Creare un modello di base che gestisce gli endpoint.

Recupera lo stato dell'endpoint del modello

È possibile controllare lo stato di un endpoint usando l'interfaccia utente di servizio o a livello di codice usando l'API REST, il client dell'area di lavoro di Databricks o MLflow Deployments SDK.

Gli stati dell'endpoint possono essere Ready, Ready (Update failed), Not ready (Updating), Not ready (Update failed)o Not ready (Stopped). L'idoneità indica se è possibile eseguire query su un endpoint o meno. Aggiornamento non riuscito indica che la modifica più recente all'endpoint non è riuscita. "Interrotto significa che l'endpoint è stato fermato."

INTERFACCIA UTENTE

Indicatore di stato dell'endpoint di servizio nella parte superiore della pagina dei dettagli di un endpoint:

REST API (Interfaccia di Programmazione delle Applicazioni REST)

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

Nella risposta di esempio seguente il state.ready campo è "READY", il che significa che l'endpoint è pronto per ricevere il traffico. Il campo state.update_state è NOT_UPDATING e pending_config non viene più restituito perché l'aggiornamento è stato completato correttamente.

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

Client dell'area di lavoro di 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}")

MLflow Deployments SDK

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']}")

Arrestare un endpoint di gestione di un modello

È possibile arrestare temporaneamente un endpoint di gestione di un modello e avviarlo in un secondo momento. Quando un endpoint viene arrestato:

• Le risorse predisposte vengono disattivate.
• L'endpoint non è in grado di gestire le query fino a quando non viene avviato di nuovo.
• Solo gli endpoint che gestiscono modelli personalizzati e non dispongono di aggiornamenti in corso possono essere arrestati.
• Gli endpoint arrestati non vengono conteggiati rispetto alla quota di risorse.
• Le query inviate a un endpoint arrestato restituiscono un errore 400.

Fermare un endpoint

INTERFACCIA UTENTE

Fare clic su Arresta nell'angolo superiore destro.

REST API (Interfaccia di Programmazione delle Applicazioni REST)

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

Avvia un endpoint

L'avvio di un endpoint crea una nuova versione di configurazione con le stesse proprietà della configurazione arrestata esistente.

Quando si è pronti per avviare un endpoint di gestione di un modello arrestato:

INTERFACCIA UTENTE

Fare clic su Start nell'angolo superiore destro.

REST API (Interfaccia di Programmazione delle Applicazioni REST)

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

Eliminare un endpoint di gestione di un modello

L'eliminazione di un endpoint disabilita l'utilizzo ed elimina tutti i dati associati all'endpoint. Non è possibile annullare l'eliminazione.

INTERFACCIA UTENTE

Fare clic sul menu kebab nella parte superiore e selezionare Elimina.

REST API (Interfaccia di Programmazione delle Applicazioni REST)

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

MLflow Deployments SDK

from mlflow.deployments import get_deploy_client

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

Eseguire il debug di un endpoint di gestione di un modello

Sono disponibili due tipi di log per facilitare il debug dei problemi con gli endpoint:

• Log di costruzione del contenitore del server modello: generati durante l'inizializzazione dell'endpoint quando il contenitore viene creato. Questi log acquisiscono la fase di installazione, incluso il download del modello, l'installazione delle dipendenze e la configurazione dell'ambiente di runtime. Usare questi log per eseguire il debug del motivo per cui un endpoint non è riuscito ad avviarsi o è bloccato durante la distribuzione.
• Log del server del modello: generato durante il runtime quando l'endpoint serve attivamente le previsioni. Questi log acquisiscono le richieste in ingresso, l'esecuzione dell'inferenza del modello, gli errori di runtime e la registrazione a livello di applicazione dal codice del modello. Usare questi log per eseguire il debug dei problemi relativi alle stime o analizzare gli errori di query.

Entrambi i tipi di log sono accessibili anche dall'interfaccia utente endpoint nella scheda Log .

Ottenere i log di compilazione dei contenitori

Per i log di compilazione di un modello servito, puoi usare la richiesta seguente. Per altre informazioni, vedere La guida al debug per La gestione dei modelli.

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

Ottenere i log del server modello

Per i log del server modello per un modello di servizio, è possibile usare la richiesta seguente:

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

{
  "config_version": 1  // optional
}

Gestire le autorizzazioni per un endpoint di gestione del modello

Per modificare le autorizzazioni, è necessario disporre almeno dell'autorizzazione CAN MANAGE per un endpoint di servizio. Per altre informazioni sui livelli di autorizzazione, vedere Gestione degli ACL degli endpoint.

Ottenere l'elenco delle autorizzazioni sull'endpoint di servizio.

INTERFACCIA UTENTE

Fare clic sul pulsante Autorizzazioni in alto a destra dell'interfaccia utente.

Interfaccia a riga di comando di Databricks

databricks permissions get serving-endpoints <endpoint-id>

Concedere all'utente jsmith@example.com l'autorizzazione CAN QUERY per l'endpoint di gestione.

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

È anche possibile modificare le autorizzazioni dell'endpoint di gestione usando l'API Autorizzazioni.

Aggiungere un criterio di budget serverless per un endpoint di gestione del modello

Importante

Questa funzionalità è in fase di Anteprima Pubblica e non è disponibile per gli endpoint che servono modelli esterni.

Le politiche di budget serverless consentono alla vostra organizzazione di applicare tag personalizzati all'utilizzo serverless per un'attribuzione dettagliata della fatturazione. Se l'area di lavoro usa criteri di budget serverless per attribuire l'utilizzo serverless, è possibile aggiungere criteri di budget serverless agli endpoint di gestione del modello. Consulta Utilizzo degli attributi con le politiche di budget serverless.

Durante la creazione dell'endpoint di gestione del modello, è possibile selezionare i criteri di budget serverless dell'endpoint dal menu Criteri budget nell'interfaccia utente di gestione. Se ti vengono assegnati dei criteri di budget serverless, tutti gli endpoint che crei utilizzeranno i criteri assegnati, anche se non selezioni un criterio dal menu Criteri di budget.

Se si dispone di autorizzazioni MANAGE per un endpoint esistente, è possibile modificare e aggiungere criteri di budget serverless a tale endpoint dalla pagina dei dettagli dell'endpoint nell'interfaccia utente.

Nota

Se ti è stata assegnata una policy di budget serverless, gli endpoint esistenti non vengono contrassegnati automaticamente con la tua policy. È necessario aggiornare manualmente gli endpoint esistenti se si desidera associarli a una policy di budget serverless.

Ottenere uno schema dell'endpoint di servizio di un modello

Importante

Il supporto per la gestione degli schemi di query degli endpoint è disponibile in anteprima pubblica. Questa funzionalità è disponibile nelle aree di gestione dei modelli.

Uno schema di query dell'endpoint di servizio è una descrizione formale dell'endpoint di servizio usando la specifica OpenAPI standard in formato JSON. Contiene informazioni sull'endpoint, inclusi il percorso dell'endpoint, i dettagli per l'esecuzione di query sull'endpoint, ad esempio il formato del corpo della richiesta e della risposta e il tipo di dati per ogni campo. Queste informazioni possono essere utili per scenari di riproducibilità o quando sono necessarie informazioni sull'endpoint, ma non si è l'autore o il proprietario dell'endpoint originale.

Per ottenere lo schema dell'endpoint di gestione del modello, il modello servito deve avere una firma del modello registrata e l'endpoint deve trovarsi in uno stato READY.

Gli esempi seguenti illustrano come ottenere a livello di codice lo schema dell'endpoint di gestione del modello usando l'API REST. Per informazioni sugli schemi degli endpoint di erogazione delle funzionalità, vedere Endpoint di erogazione delle funzionalità.

Lo schema restituito dall'API è nel formato di un oggetto JSON che segue la specifica 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"

Dettagli della risposta dello Schema

La risposta è una specifica OpenAPI in formato JSON, in genere inclusi campi come openapi, infoservers e paths. Poiché la risposta dello schema è un oggetto JSON, è possibile analizzarla usando linguaggi di programmazione comuni e generare codice client dalla specifica usando strumenti di terze parti. È anche possibile visualizzare la specifica OpenAPI usando strumenti di terze parti come L'editor Swagger.

I campi principali della risposta includono:

• Il info.title campo mostra il nome dell'endpoint di gestione.
• Il servers campo contiene sempre un oggetto, in genere il url campo che è l'URL di base dell'endpoint.
• L'oggetto paths nella risposta contiene tutti i percorsi supportati per un endpoint. Le chiavi nell'oggetto sono l'URL del percorso. Ognuno path può supportare più formati di input. Questi input sono elencati nel oneOf campo .

Di seguito è riportata una risposta dello schema di endpoint di esempio:

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