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

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

  • Статья

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

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

Требования

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

Внимание

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

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

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

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

Метод Сведения
Обслуживающий пользовательский интерфейс Выберите конечную точку запроса на странице, посвященной обслуживающей конечной точке, в рабочей области 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]]
                    }
                }
          )

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 должны быть отформатированы, как описано в документации по 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 DataFrame или в виде тензорного входа.

Датафрейм Pandas

Запросы должны отправляться путем создания кадра данных Pandas, сериализованного в формате JSON, с использованием одного из поддерживаемых ключей и объекта 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 — Pandas DataFrame, сериализованный в формате JSON, в ориентации по 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 см. в следующей записной книжке:

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

Возьми тетрадь

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