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

Статья
06/24/2024

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

Запросы на создание рабочих нагрузок искусственного интеллекта и LLM см. в статье "Базовые модели запросов" и внешние модели.

Требования

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

Внимание

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

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

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

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

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

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

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

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

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, выполните указанные ниже действия.

Откройте набор данных, который требуется оценить.
Перейдите в раздел преобразования данных.
Щелкните правой кнопкой мыши левую панель и выберите Создать новый запрос.
Выберите Просмотр > Расширенный редактор.

Замените текст запроса приведенным ниже фрагментом кода, подставив соответствующие значения 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

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

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

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

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 — это формат на основе тензоров, который принимает тензоры в формате строк. Используйте этот формат, если все входные тензоры имеют одинаковое нулевое измерение. По сути, каждый тензор в списке экземпляров можно объединить с другими тензорами с тем же именем в остальной части списка для создания полного тензора входных данных для модели, что было бы возможно только в том случае, если все тензоры имеют одну и ту же нулевую размерность.
```
{"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 см. в следующей записной книжке:

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

Получить записную книжку

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

Таблицы вывода для моделей мониторинга и отладки.
Модели базы запросов и внешние модели.

Поделиться через

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

Требования

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

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

REST API

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

SQL

PowerBI

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

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

Кадр данных Pandas

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

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

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

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

Обратная связь

Обратная связь

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