사용자 지정 모델에 대한 서비스 엔드포인트 쿼리

아티클
10/30/2024

이 문서에서는 제공된 모델에 대한 점수 매기기 요청의 형식을 지정하는 방법과 해당 요청을 엔드포인트를 제공하는 모델에 보내는 방법을 알아봅니다. 이 지침은 Databricks가 기존 ML 모델 또는 MLflow 형식으로 패키지된 사용자 지정 Python 모델로 정의하는 사용자 지정 모델을 제공하는 것과 관련이 있습니다. Unity 카탈로그 또는 작업 영역 모델 레지스트리에 등록할 수 있습니다. 예를 들어 scikit-learn, XGBoost, PyTorch 및 Hugging Face 변환기 모델이 있습니다. 이 기능 및 지원되는 모델 범주에 대한 자세한 내용은 Azure Databricks에서 제공하는 모델을 참조하세요.

생성 AI 및 LLM 워크로드에 대한 쿼리 요청은 생성 AI 모델 쿼리를 참조 하세요.

요구 사항

모델 서비스 엔드포인트
MLflow 배포 SDK의 경우 MLflow 2.9 이상이 필요합니다.
허용된 형식의 채점 요청입니다.
REST API 또는 MLflow 배포 SDK를 통해 점수 매기기 요청을 보내려면 Databricks API 토큰이 있어야 합니다.

Important

프로덕션 시나리오에 대한 보안 모범 사례로 Databricks는 프로덕션 중에 인증을 위해 컴퓨터-컴퓨터 OAuth 토큰을 사용하는 것이 좋습니다.

테스트 및 개발을 위해 Databricks는 작업 영역 사용자 대신 서비스 주체에 속하는 개인용 액세스 토큰을 사용하는 것이 좋습니다. 서비스 주체에 대한 토큰을 만들려면 서비스 주체에 대한 토큰 관리를 참조하세요.

메서드 및 예제 쿼리

Mosaic AI 모델 서비스 제공은 제공된 모델에 점수 매기기 요청을 보내기 위한 다음 옵션을 제공합니다.

메서드	세부 정보
서비스 UI	Databricks 작업 영역의 서비스 엔드포인트 페이지에서 쿼리 엔드포인트를 선택합니다. JSON 형식의 모델 입력 데이터를 삽입하고 요청 보내기를 클릭합니다. 모델에 기록된 입력 예제가 있는 경우 예제 표시를 사용하여 로드합니다.
REST API	REST API를 사용하여 모델을 호출하고 쿼리합니다. 자세한 내용은 POST /serving-endpoints/{name}/invocations를 참조하세요. 여러 모델을 제공하는 엔드포인트에 대한 요청의 점수를 매기려면 엔드포인트 뒤에서 개별 모델 쿼리를 참조하세요.
MLflow 배포 SDK	MLflow Deployments SDK의 predict() 함수를 사용하여 모델을 쿼리합니다.
SQL 함수	`ai_query` SQL 함수를 사용하여 SQL에서 직접 모델 유추를 호출합니다. ai_query()를 사용하여 제공된 모델 쿼리를 참조하세요.

Pandas DataFrame 점수 매기기 예제

다음 예제에서는 https://<databricks-instance>/model/iris-classifier/Production/invocations와 같은 MODEL_VERSION_URI(여기서 <databricks-instance>는 Databricks 인스턴스의 이름임)와 DATABRICKS_API_TOKEN이라는 Databricks REST API 토큰을 가장헙니다.

지원되는 채점 형식을 참조하세요.

REST API

DataFrame 분할 입력 형식을 수락하는 모델에 점수를 매깁니다.

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

텐서 입력을 수락하는 모델에 점수를 매깁니다. TensorFlow 서비스 API 설명서에 설명된 대로 텐서 입력 형식을 지정해야 합니다.

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

MLflow 배포 SDK

Important

다음 예제에서는 predict()MLflow 배포 SDK의 API를 사용합니다.


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

Important

다음 예제에서는 기본 제공 SQL 함수 ai_query를 사용합니다. 이 함수는 공개 미리 보기이며 정의가 변경될 수 있습니다. ai_query()를 사용하여 제공된 모델 쿼리를 참조하세요.

다음 예제에서는 text 데이터 세트를 사용하여 sentiment-analysis 엔드포인트 뒤에 있는 모델을 쿼리하고 요청의 반환 형식을 지정합니다.

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 입력을 허용하는 모델의 점수를 지정합니다. Tensor 입력은 TensorFlow Serving의 API 문서에 설명된 대로 포맷되어야 합니다. 이 예에서는 <databricks-instance>는 Databricks 인스턴스의 이름인 https://<databricks-instance>/model/iris-classifier/Production/invocations과 같은 MODEL_VERSION_URI와 DATABRICKS_API_TOKEN라는 Databricks REST API 토큰을 가정합니다.

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

지원되는 채점 형식

사용자 지정 모델의 경우 Model Serving는 Pandas DataFrame 또는 Tensor 입력에서 채점 요청을 지원합니다.

Pandas DataFrame

지원 키 중 하나 및 입력 형식에 해당하는 JSON 개체를 사용하여 JSON 직렬화 Pandas DataFrame을 생성하여 요청을 보낼 수 있습니다.

(권장 사항) dataframe_split 형식은 split 방향의 JSON 직렬화 Pandas Dataframe입니다.

{
  "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는 records 방향의 JSON 직렬화 Pandas Dataframe입니다.

참고 항목

이 형식은 열 순서 유지를 보장하지 않으며 records 형식보다 split 형식이 선호됩니다.

{
  "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을 보내는 데 지원되는 두 가지 형식 옵션이 있습니다.

행당 명명된 Tensor가 여러 개 있는 경우 모든 행에 대해 각 Tensor 중 하나가 있어야 합니다.

instances는 행 형식의 텐서를 허용하는 텐서 기반 형식입니다. 모든 입력 텐서에 동일한 0순위 차원이 포함된 경우 이 형식을 사용합니다. 개념적으로 인스턴스 목록의 각 텐서는 목록의 나머지 부분에 있는 동일한 이름의 다른 텐서와 결합하여 모델에 대해 전체 입력 텐서를 구성할 수 있으며, 이는 모든 텐서가 동일한 0순위 차원을 갖는 경우에만 가능합니다.
```
{"instances": [ 1, 2, 3 ]}
```
다음 예제에서는 명명된 여러 Tensor를 지정하는 방법을 보여줍니다.
```
{
"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]
}

Notebook 예제

Python 모델로 모델 서비스 엔드포인트를 테스트하는 방법의 예는 다음 Notebook을 참조하세요.

테스트 모델 서비스 엔드포인트 Notebook

Notebook 가져오기

추가 리소스

모델 모니터링 및 디버깅을 위한 유추 테이블.
생성 AI 모델을 쿼리합니다.
모델 제공에 대한 디버깅 가이드입니다.

다음을 통해 공유

사용자 지정 모델에 대한 서비스 엔드포인트 쿼리

요구 사항

메서드 및 예제 쿼리

Pandas DataFrame 점수 매기기 예제

REST API

MLflow 배포 SDK

SQL

PowerBI

Tensor 입력 예제

지원되는 채점 형식

Pandas DataFrame

Tensor 입력

Notebook 예제

테스트 모델 서비스 엔드포인트 Notebook

추가 리소스

피드백

추가 리소스