Запрос конечных точек обслуживания для пользовательских моделей

В этой статье вы узнаете, как форматировать запросы оценки для вашей обслуживаемой модели и как отправлять эти запросы в конечную точку обслуживания модели. Это руководство относится к обслуживанию пользовательских моделей, которые Databricks определяет как традиционные модели машинного обучения или настраиваемые модели Python, упакованные в формате MLflow. Их можно зарегистрировать в каталоге Unity или в реестре моделей рабочей области. Примеры включают scikit-learn, XGBoost, PyTorch и модели преобразователя распознавания лиц. Дополнительные сведения об этой функциональности и поддерживаемых категориях моделей см. в статье "Развертывание моделей с помощью мозаичной модели ИИ".

Запросы для генеративного ИИ и рабочих нагрузок LLM см. в разделе Основные модели запросов.

Требования

  • Конечная точка обслуживания модели.
  • Для пакета SDK развертывания MLflow требуется MLflow 2.9 или более поздней версии.
  • Запрос оценки в принятом формате.
  • Чтобы отправить запрос оценки через REST API или пакет SDK развертывания MLflow, необходимо иметь маркер API Databricks.

Внимание

В качестве рекомендации по обеспечению безопасности для рабочих сценариев Databricks рекомендует использовать маркеры OAuth на компьютере для проверки подлинности во время рабочей среды.

Для тестирования и разработки Databricks рекомендует использовать личный маркер доступа, принадлежащий субъектам-службам , а не пользователям рабочей области. Сведения о создании маркеров для субъектов-служб см. в разделе "Управление маркерами" для субъекта-службы.

Запрос методов и примеров

Служба модели ИИ мозаики предоставляет следующие варианты отправки запросов оценки в обслуживаемую модель:

Метод Сведения
Обслуживающий пользовательский интерфейс Выберите конечную точку запроса на странице обслуживающей конечной точки в рабочей области Databricks. Вставьте входные данные модели формата JSON и щелкните "Отправить запрос". Если в модели есть входной пример, используйте команду Show Example для загрузки.
Функция SQL Вызов вывода модели непосредственно из SQL с помощью ai_query функции SQL. См. запрос обслуживаемой модели с помощью ai_query.
REST API Вызов и запрос модели с помощью REST API. Дополнительные сведения см. в разделе POST /обслуживающие конечные точки/{name}/invocations . Сведения о оценке запросов к конечным точкам, обслуживающим несколько моделей, см. в разделе "Запрос отдельных моделей" за конечной точкой.
Пакет SDK для развертываний MLflow Используйте функцию predict() пакета SDK для развертывания MLflow для запроса модели.

Пример оценки Pandas DataFrame

В следующем примере предполагается, что MODEL_VERSION_URI аналогичен https://<databricks-instance>/model/iris-classifier/Production/invocations, где <databricks-instance> — это имя вашего экземпляра Databricksи токен REST API Databricks с именемDATABRICKS_API_TOKEN.

См . поддерживаемые форматы оценки.

REST API

Оценка модели, принимаюющей формат разделенных входных данных кадра.

curl -X POST -u token:$DATABRICKS_API_TOKEN $MODEL_VERSION_URI \
  -H 'Content-Type: application/json' \
  -d '{"dataframe_split": [{
    "columns": ["sepal length (cm)", "sepal width (cm)", "petal length (cm)", "petal width (cm)"],
    "data": [[5.1, 3.5, 1.4, 0.2], [4.9, 3.0, 1.4, 0.2]]
    }]
  }'

Оценка модели, принимающей на вход тензоры. Входные данные Tensor должны быть отформатированы, как описано в документации по API TensorFlow.

curl -X POST -u token:$DATABRICKS_API_TOKEN $MODEL_VERSION_URI \
  -H 'Content-Type: application/json' \
  -d '{"inputs": [[5.1, 3.5, 1.4, 0.2]]}'

Пакет SDK для развертываний MLflow

Внимание

В следующем примере используется predict() API из пакета SDK для развертываний MLflow.


import mlflow.deployments

export DATABRICKS_HOST="https://<workspace_host>.databricks.com"
export DATABRICKS_TOKEN="dapi-your-databricks-token"

client = mlflow.deployments.get_deploy_client("databricks")

response = client.predict(
            endpoint="test-model-endpoint",
            inputs={"dataframe_split": {
                    "index": [0, 1],
                    "columns": ["sepal length (cm)", "sepal width (cm)", "petal length (cm)", "petal width (cm)"],
                    "data": [[5.1, 3.5, 1.4, 0.2], [4.9, 3.0, 1.4, 0.2]]
                    }
                }
          )

SQL

Внимание

В следующем примере используется встроенная функция SQL, ai_query. Эта функция является общедоступной предварительной версией , и определение может измениться. См. запрос обслуживаемой модели с помощью ai_query.

В следующем примере модель за конечной sentiment-analysis точкой запрашивается с набором text данных и указывает тип возвращаемого запроса.

SELECT text, ai_query(
    "sentiment-analysis",
    text,
    returnType => "STRUCT<label:STRING, score:DOUBLE>"
  ) AS predict
FROM
  catalog.schema.customer_reviews

PowerBI

Чтобы оценить набор данных в Power BI Desktop, выполните указанные ниже действия.

  1. Откройте набор данных, который требуется оценить.

  2. Перейдите в раздел преобразования данных.

  3. Щелкните правой кнопкой мыши на левой панели и выберите создать новый запрос.

  4. Выберите Просмотр > Расширенный редактор.

  5. Замените текст запроса приведенным ниже фрагментом кода, подставив соответствующие значения DATABRICKS_API_TOKEN и MODEL_VERSION_URI.

    (dataset as table ) as table =>
    let
      call_predict = (dataset as table ) as list =>
      let
        apiToken = DATABRICKS_API_TOKEN,
        modelUri = MODEL_VERSION_URI,
        responseList = Json.Document(Web.Contents(modelUri,
          [
            Headers = [
              #"Content-Type" = "application/json",
              #"Authorization" = Text.Format("Bearer #{0}", {apiToken})
            ],
            Content = {"dataframe_records": Json.FromValue(dataset)}
          ]
        ))
      in
        responseList,
      predictionList = List.Combine(List.Transform(Table.Split(dataset, 256), (x) => call_predict(x))),
      predictionsTable = Table.FromList(predictionList, (x) => {x}, {"Prediction"}),
      datasetWithPrediction = Table.Join(
        Table.AddIndexColumn(predictionsTable, "index"), "index",
        Table.AddIndexColumn(dataset, "index"), "index")
    in
      datasetWithPrediction
    
  6. Присвойте запросу желаемое имя модели.

  7. Откройте расширенный редактор запросов для своего набора данных и примените функцию модели.

Пример входных данных Tensor

В следующем примере оценивается модель, принимаюющая входные данные тензора. Входные данные Tensor должны быть отформатированы, как описано в документации по API TensorFlow,. В этом примере предполагается, что MODEL_VERSION_URI, например https://<databricks-instance>/model/iris-classifier/Production/invocations, где <databricks-instance> — это имяэкземпляра Databricks, а маркер REST API Databricks называется DATABRICKS_API_TOKEN.

curl -X POST -u token:$DATABRICKS_API_TOKEN $MODEL_VERSION_URI \
    -H 'Content-Type: application/json' \
    -d '{"inputs": [[5.1, 3.5, 1.4, 0.2]]}'

Поддерживаемые форматы оценки

Для пользовательских моделей служба моделей поддерживает запросы оценки в Кадре данных Pandas или Tensor входных данных.

Кадр данных Pandas

Запросы должны отправляться путем создания json-сериализованного кадра данных Pandas с одним из поддерживаемых ключей и объекта JSON, соответствующего входной формату.

  • (Рекомендуется)dataframe_split формат — это сериализованный JSON-кадр данных Pandas в split ориентации.

    {
      "dataframe_split": {
        "index": [0, 1],
        "columns": ["sepal length (cm)", "sepal width (cm)", "petal length (cm)", "petal width (cm)"],
        "data": [[5.1, 3.5, 1.4, 0.2], [4.9, 3.0, 1.4, 0.2]]
      }
    }
    
  • dataframe_records — сериализованный JSON Pandas DataFrame в records ориентации.

    Примечание.

    Этот формат не гарантирует сохранение порядка столбцов, а формат split предпочтителен для формата records.

    {
      "dataframe_records": [
      {
        "sepal length (cm)": 5.1,
        "sepal width (cm)": 3.5,
        "petal length (cm)": 1.4,
        "petal width (cm)": 0.2
      },
      {
        "sepal length (cm)": 4.9,
        "sepal width (cm)": 3,
        "petal length (cm)": 1.4,
        "petal width (cm)": 0.2
      },
      {
        "sepal length (cm)": 4.7,
        "sepal width (cm)": 3.2,
        "petal length (cm)": 1.3,
        "petal width (cm)": 0.2
      }
      ]
    }
    

Ответ конечной точки содержит выходные данные модели, сериализованные с помощью JSON, завернутые predictions в ключ.

{
  "predictions": [0,1,1,1,0]
}

Входные данные Tensor

Когда модель ожидает тензоров, таких как модель TensorFlow или Pytorch, существует два поддерживаемых варианта форматирования для отправки запросов: instances и inputs.

Если у вас несколько именованных тензоров для каждой строки, необходимо иметь один из каждого тензора для каждой строки.

  • instances — это формат на основе тензоров, который принимает тензоры в формате строк. Используйте этот формат, если все входные тензоры имеют одинаковое нулевое измерение. Концептуально каждый тензор в списке экземпляров можно объединить с другими тензорами того же имени в остальной части списка, чтобы создать полный тензор входных данных для модели, что может быть возможно только в том случае, если все тензоры имеют то же 0-е измерение.

    {"instances": [ 1, 2, 3 ]}
    

    В следующем примере показано, как указать несколько именованных тензоров.

    {
    "instances": [
      {
       "t1": "a",
       "t2": [1, 2, 3, 4, 5],
       "t3": [[1, 2], [3, 4], [5, 6]]
      },
      {
       "t1": "b",
       "t2": [6, 7, 8, 9, 10],
       "t3": [[7, 8], [9, 10], [11, 12]]
      }
    ]
    }
    
  • inputs — отправка запросов с тензорами в формате столбцов. Этот запрос отличается, так как фактически существует другое количество экземпляров тензора t2 (3) нежели в t1 и t3, поэтому невозможно представить эти входные данные в формате instances.

    {
    "inputs": {
      "t1": ["a", "b"],
      "t2": [[1, 2, 3, 4, 5], [6, 7, 8, 9, 10]],
      "t3": [[[1, 2], [3, 4], [5, 6]], [[7, 8], [9, 10], [11, 12]]]
    }
    }
    

Ответ конечной точки имеет следующий формат.

{
  "predictions": [0,1,1,1,0]
}

Пример записной книжки

Пример тестирования конечной точки службы модели с помощью модели Python см. в следующей записной книжке:

Записная книжка конечной точки службы модели тестирования

Получение записной книжки

Дополнительные ресурсы