특성 기반 설명 구성

커스텀 학습 모델에서 Vertex Explainable AI를 사용하려면 설명을 요청하려는 Model 리소스를 만들거나, 모델을 배포하거나, 배치 설명 작업을 제출할 때 특정 옵션을 구성해야 합니다. 이 페이지에서는 이러한 옵션을 구성하는 방법을 설명합니다.

AutoML 테이블 형식 모델에서 Vertex Explainable AI를 사용하려는 경우에는 구성을 수행할 필요가 없습니다. Vertex AI는 Vertex Explainable AI용 모델을 자동으로 구성합니다. 이 문서를 건너뛰고 설명 받기를 읽어보세요.

설명 구성 시점 및 위치

모델을 만들거나 가져올 때 설명을 구성합니다. 이전에 설명을 구성하지 않았더라도 이미 만든 모델에 대한 설명을 구성할 수도 있습니다.

모델을 만들거나 가져올 때 설명 구성

Model을 만들거나 가져올 때 ModelexplanationSpec 필드를 사용하여 모든 설명에 대한 기본 구성을 설정할 수 있습니다.

다음 방법으로 Vertex AI에서 커스텀 학습 Model을 만들 수 있습니다.

두 경우 모두 Vertex Explainable AI를 지원하도록 Model을 구성할 수 있습니다. 이 문서의 예시에서는 Model을 가져온다고 가정합니다. TrainingPipeline을 사용하여 커스텀 학습 Model을 만들 때 Vertex Explainable AI를 구성하려면 이 문서의 TrainingPipelinemodelToUpload 필드에 설명된 구성 설정을 사용합니다.

모델 배포 또는 일괄 예측 수행 시 설명 구성

ModelEndpoint 리소스에 배포하면 다음 중 하나를 수행할 수 있습니다.

  • 모델이 이전에 설명을 위해 구성되었는지 여부에 관계없이 설명을 구성합니다. 처음에 설명을 가져올 의도가 없었지만(모델을 만들 때 explanationSpec 필드 생략) 나중에 모델에 대한 설명을 원하거나 설명 설정 일부를 재정의하는 경우에 유용합니다.
  • 설명 중지 모델이 설명을 위해 구성되었지만 엔드포인트에서 설명을 가져올 계획이 없는 경우에 유용합니다. 엔드포인트에 모델을 배포할 때 설명을 중지하려면 Cloud 콘솔의 설명 기능 옵션을 선택 해제하거나 DeployedModel.disableExplanationstrue로 설정합니다.

마찬가지로, Model에서 일괄 예측을 가져올 때 BatchPredictionJob.explanationSpec 필드를 채워 설명을 구성하거나 BatchPredictionJob.generateExplanationfalse로 설정하여 중지할 수 있습니다.

온라인 설명을 가져올 때 구성 재정의

설명 설정이 있는 Model을 만들거나 가져온 여부와 관계없이, 그리고 배포 중에 설명 설정을 구성했는지 여부와 관계없이 온라인 설명을 가져올 때 Model의 최초 설명 설정을 재정의할 수 있습니다.

Vertex AI에 explain 요청을 보내면 이전에 Model 또는 DeployedModel에 설정한 일부 설명 구성을 재정의할 수 있습니다.

explain 요청 시 다음 필드를 재정의할 수 있습니다.

설명 요청의 explanationSpecOverride 필드에서 이러한 설정을 재정의합니다.

explanationSpec 필드로 모델 가져오기

예측을 게재하는 데 사전 빌드된 컨테이너 또는 커스텀 컨테이너를 사용하는지에 따라 ExplanationSpec에 지정하는 세부정보가 약간 다릅니다. 사용 중인 컨테이너와 일치하는 탭을 선택합니다.

TensorFlow 사전 빌드된 컨테이너

Vertex Explainable AI에 다음과 같은 기여 분석 방법을 사용할 수 있습니다. 특성 기여 분석 방법 비교를 읽고 Model에 적합한 방법을 선택합니다.

샘플링된 Shapley

Model을 만들거나 가져오는 데 사용할 도구에 따라 다음 탭 중 하나를 선택합니다.

Console

Google Cloud Console을 사용하여 모델 가져오기 가이드를 따르세요. 설명 기능 단계에 도달하면 다음을 수행합니다.

  1. 특성 기여 분석 메서드에 대해 샘플링된 모양(표 형식 모델)을 선택합니다.

  2. 경로 수를 샘플링된 Shapley 기여 분석 메서드에 사용할 특성 순열 수로 설정합니다. 이는 [1, 50] 범위의 정수여야 합니다.

    값이 높을수록 근사치 오류가 감소할 수 있지만 계산량이 더 많습니다. 어떤 값을 사용해야 할지 모르는 경우 25를 사용합니다.

  3. 모델의 각 입력 특성을 구성합니다.

    1. 입력 특성 이름을 입력합니다.

    2. 필요한 경우 하나 이상의 입력 기준을 추가할 수 있습니다. 그렇지 않으면 Vertex Explainable AI에서 모든 값이 0인 기본 입력 기준을 선택하며 이 기준은 이미지 데이터의 검은색 이미지입니다.

    3. TensorFlow 모델을 가져오는 경우 추가 입력 필드가 있습니다.

      1. 입력 텐서 이름을 입력합니다.

      2. 해당되는 경우 색인 텐서 이름 또는 밀도 형태 텐서 이름을 입력합니다.

      3. 여기에서 모달리티를 업데이트할 수 없습니다. 테이블 형식 모델의 경우 NUMERIC, 이미지 모델의 경우 IMAGE로 자동 설정됩니다.

      4. 해당하는 경우 인코딩 필드를 설정합니다. 설정하지 않을 경우 기본값은 IDENTITY입니다.

      5. 해당하는 경우 그룹 이름 필드를 설정합니다.

  4. TensorFlow 모델을 가져오는 경우 출력 필드를 지정합니다.

    1. 특성의 출력 이름을 설정합니다.
    2. 특성의 출력 텐서 이름을 설정합니다.
    3. 해당하는 경우 색인 표시 이름 매핑을 설정합니다.
    4. 해당하는 경우 표시 이름 매핑 키를 설정합니다.

  5. 설명 기능 설정 구성을 완료했으면 가져오기 버튼을 클릭합니다.

gcloud

  1. TensorFlow 2의 경우 ExplanationMetadata는 선택사항입니다.

    다음 ExplanationMetadata를 로컬 환경의 JSON 파일에 작성합니다. 파일 이름은 중요하지 않지만 이 예시에서는 파일 이름을 explanation-metadata.json으로 지정합니다.

    explanation-metadata.json

    {
      "inputs": {
        "FEATURE_NAME": {
          "inputTensorName": "INPUT_TENSOR_NAME",
        }
      },
      "outputs": {
        "OUTPUT_NAME": {
          "outputTensorName": "OUTPUT_TENSOR_NAME"
        }
      }
    }
    

    다음을 바꿉니다.

    • FEATURE_NAME: 입력 특성의 기억하기 쉬운 이름입니다.
    • INPUT_TENSOR_NAME: TensorFlow의 입력 텐서 이름입니다. 이 필드에 올바른 값을 찾으려면 Vertex Explainable AI에서 TensorFlow 사용을 참조하세요.
    • OUTPUT_NAME: 모델 출력의 기억하기 쉬운 이름입니다.
    • OUTPUT_TENSOR_NAME: TensorFlow의 출력 텐서 이름입니다. 이 필드에 올바른 값을 찾으려면 Vertex Explainable AI에서 TensorFlow 사용을 참조하세요.

    선택사항으로 입력 기준ExplanationMetadata에 추가할 수 있습니다. 그렇지 않은 경우 Vertex AI가 Model의 입력 기준을 선택합니다.

  2. 다음 명령어를 실행하여 Vertex Explainable AI를 지원하는 Model 리소스를 만듭니다. Vertex Explainable AI와 가장 관련성이 높은 플래그가 강조표시됩니다.

    gcloud ai models upload \
      --region=LOCATION \
      --display-name=MODEL_NAME \
      --container-image-uri=IMAGE_URI \
      --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
      --explanation-method=sampled-shapley \
      --explanation-path-count=PATH_COUNT \
      --explanation-metadata-file=explanation-metadata.json
    

    다음을 바꿉니다.

    다른 자리표시자에 적합한 값을 알아보려면 upload모델 가져오기를 참조하세요.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

다른 자리표시자에 적합한 값을 알아보려면 upload모델 가져오기를 참조하세요.

선택사항으로 입력 기준ExplanationMetadata에 추가할 수 있습니다. 그렇지 않은 경우 Vertex AI가 Model의 입력 기준을 선택합니다.

TensorFlow 2 모델의 경우 metadata 필드는 선택사항입니다. 생략하면 Vertex AI가 모델에서 inputsoutputs를 자동으로 추론합니다.

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

JSON 요청 본문:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "sampledShapleyAttribution": {
          "pathCount": PATH_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

적분 경사

Model을 만들거나 가져오는 데 사용할 도구에 따라 다음 탭 중 하나를 선택합니다.

Console

Google Cloud Console을 사용하여 모델 가져오기 가이드를 따르세요. 설명 기능 단계에 도달하면 다음을 수행합니다.

  1. 특성 기여 분석 메서드에서는 통합 그래디언트(표 형식 모델용) 또는 통합 그래디언트(이미지 분류 모델용) 중에서 모델에 적절한 것을 선택합니다.

  2. 이미지 분류 모델을 가져오는 경우 다음을 수행합니다.

    1. 시각화 유형색상 척도를 설정합니다.

    2. 아래 클립, 위 클립, 오버레이 유형, 적분 단계 수는 기본 설정 그대로 두어도 됩니다.

    시각화 설정에 대해 자세히 알아보세요.

  3. 특성 기여 분석 시 경로 적분의 근사치를 계산하는 데 사용할 단계 수를 설정합니다. 이는 [1, 100] 범위의 정수여야 합니다.

    값이 높을수록 근사치 오류가 감소할 수 있지만 계산량이 더 많습니다. 어떤 값을 사용해야 할지 모르는 경우 50를 사용합니다.

  4. 모델의 각 입력 특성을 구성합니다.

    1. 입력 특성 이름을 입력합니다.

    2. 필요한 경우 하나 이상의 입력 기준을 추가할 수 있습니다. 그렇지 않으면 Vertex Explainable AI에서 모든 값이 0인 기본 입력 기준을 선택하며 이 기준은 이미지 데이터의 검은색 이미지입니다.

    3. TensorFlow 모델을 가져오는 경우 추가 입력 필드가 있습니다.

      1. 입력 텐서 이름을 입력합니다.

      2. 해당되는 경우 색인 텐서 이름 또는 밀도 형태 텐서 이름을 입력합니다.

      3. 여기에서 모달리티를 업데이트할 수 없습니다. 테이블 형식 모델의 경우 NUMERIC, 이미지 모델의 경우 IMAGE로 자동 설정됩니다.

      4. 해당하는 경우 인코딩 필드를 설정합니다. 설정하지 않을 경우 기본값은 IDENTITY입니다.

      5. 해당하는 경우 그룹 이름 필드를 설정합니다.

  5. TensorFlow 모델을 가져오는 경우 출력 필드를 지정합니다.

    1. 특성의 출력 이름을 설정합니다.
    2. 특성의 출력 텐서 이름을 설정합니다.
    3. 해당하는 경우 색인 표시 이름 매핑을 설정합니다.
    4. 해당하는 경우 표시 이름 매핑 키를 설정합니다.

  6. 설명 기능 설정 구성을 완료했으면 가져오기 버튼을 클릭합니다.

gcloud

  1. TensorFlow 2의 경우 ExplanationMetadata는 선택사항입니다.

    다음 ExplanationMetadata를 로컬 환경의 JSON 파일에 작성합니다. 파일 이름은 중요하지 않지만 이 예시에서는 파일 이름을 explanation-metadata.json으로 지정합니다.

    explanation-metadata.json

    {
      "inputs": {
        "FEATURE_NAME": {
          "inputTensorName": "INPUT_TENSOR_NAME",
          "modality": "MODALITY",
          "visualization": VISUALIZATION_SETTINGS
        }
      },
      "outputs": {
        "OUTPUT_NAME": {
          "outputTensorName": "OUTPUT_TENSOR_NAME"
        }
      }
    }
    

    다음을 바꿉니다.

    • FEATURE_NAME: 입력 특성의 기억하기 쉬운 이름입니다.
    • INPUT_TENSOR_NAME: TensorFlow의 입력 텐서 이름입니다. 이 필드에 올바른 값을 찾으려면 Vertex Explainable AI에서 TensorFlow 사용을 참조하세요.
    • MODALITY: Model에서 이미지를 입력으로 허용하는 경우 image, Model에서 테이블 형식 데이터를 입력으로 허용하는 경우 numeric입니다. 기본값은 numeric입니다.
    • VIZUALIZATION_OPTIONS: 설명을 시각화하기 위한 옵션입니다. 이 필드에 정보를 입력하는 방법을 알아보려면 이미지 데이터의 시각화 설정 구성을 참조하세요.

      modality 필드를 생략하거나 modality 필드를 numeric으로 설정하고 visualization 필드를 완전히 생략합니다.

    • OUTPUT_NAME: 모델 출력의 기억하기 쉬운 이름입니다.
    • OUTPUT_TENSOR_NAME: TensorFlow의 출력 텐서 이름입니다. 이 필드에 올바른 값을 찾으려면 Vertex Explainable AI에서 TensorFlow 사용을 참조하세요.

    선택사항으로 입력 기준ExplanationMetadata에 추가할 수 있습니다. 그렇지 않은 경우 Vertex AI가 Model의 입력 기준을 선택합니다.

  2. 다음 명령어를 실행하여 Vertex Explainable AI를 지원하는 Model 리소스를 만듭니다. Vertex Explainable AI와 가장 관련성이 높은 플래그가 강조표시됩니다.

    gcloud ai models upload \
      --region=LOCATION \
      --display-name=MODEL_NAME \
      --container-image-uri=IMAGE_URI \
      --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
      --explanation-method=integrated-gradients \
      --explanation-step-count=STEP_COUNT \
      --explanation-metadata-file=explanation-metadata.json
    

    다음을 바꿉니다.

    다른 자리표시자에 적합한 값을 알아보려면 upload모델 가져오기를 참조하세요.

    필요에 따라 경사의 SmoothGrad 근사값을 구성하는 플래그를 추가할 수 있습니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • IMAGE_URI: 예측 제공을 위한 TensorFlow 사전 빌드된 컨테이너의 URI입니다.
  • STEP_COUNT: 특성 기여 분석 시 경로 적분의 근사치를 계산하는 데 사용할 단계 수입니다. [1, 100] 범위의 정수여야 합니다.

    값이 높을수록 근사치 오류가 감소할 수 있지만 계산량이 더 많습니다. 어떤 값을 사용해야 할지 모르는 경우 50를 사용합니다.

  • FEATURE_NAME: 입력 특성의 기억하기 쉬운 이름입니다.
  • INPUT_TENSOR_NAME: TensorFlow의 입력 텐서 이름입니다. 이 필드에 올바른 값을 찾으려면 Vertex Explainable AI에서 TensorFlow 사용을 참조하세요.
  • MODALITY: Model에서 이미지를 입력으로 허용하는 경우 image, Model에서 테이블 형식 데이터를 입력으로 허용하는 경우 numeric입니다. 기본값은 numeric입니다.
  • VIZUALIZATION_OPTIONS: 설명을 시각화하기 위한 옵션입니다. 이 필드에 정보를 입력하는 방법을 알아보려면 이미지 데이터의 시각화 설정 구성을 참조하세요.

    modality 필드를 생략하거나 modality 필드를 numeric으로 설정하고 visualization 필드를 완전히 생략합니다.

  • OUTPUT_NAME: 모델 출력의 기억하기 쉬운 이름입니다.
  • OUTPUT_TENSOR_NAME: TensorFlow의 출력 텐서 이름입니다. 이 필드에 올바른 값을 찾으려면 Vertex Explainable AI에서 TensorFlow 사용을 참조하세요.

다른 자리표시자에 적합한 값을 알아보려면 upload모델 가져오기를 참조하세요.

선택사항으로 입력 기준ExplanationMetadata에 추가할 수 있습니다. 그렇지 않은 경우 Vertex AI가 Model의 입력 기준을 선택합니다.

원하는 경우 ExplanationParameters경사의 SmoothGrad 근사값을 구성하는 필드를 추가할 수 있습니다.

TensorFlow 2 모델의 경우 metadata 필드는 선택사항입니다. 생략하면 Vertex AI가 모델에서 inputsoutputs를 자동으로 추론합니다.

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

JSON 요청 본문:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "integratedGradientsAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "MODALITY",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

XRAI

Model을 만들거나 가져오는 데 사용할 도구에 따라 다음 탭 중 하나를 선택합니다.

Console

Google Cloud Console을 사용하여 모델 가져오기 가이드를 따르세요. 설명 기능 단계에 도달하면 다음을 수행합니다.

  1. 특성 기여 분석 메서드의 경우 XRAI(이미지 분류 모델용)를 선택합니다.

  2. 다음 시각화 옵션을 설정합니다.

    1. 색상 척도를 설정합니다.

    2. 아래 클립, 위 클립, 오버레이 유형, 적분 단계 수는 기본 설정 그대로 두어도 됩니다.

      시각화 설정에 대해 자세히 알아보세요.

  3. 특성 기여 분석 시 경로 적분의 근사치를 계산하는 데 사용할 단계 수를 설정합니다. 이는 [1, 100] 범위의 정수여야 합니다.

    값이 높을수록 근사치 오류가 감소할 수 있지만 계산량이 더 많습니다. 어떤 값을 사용해야 할지 모르는 경우 50를 사용합니다.

  4. 모델의 각 입력 특성을 구성합니다.

    1. 입력 특성 이름을 입력합니다.

    2. 필요한 경우 하나 이상의 입력 기준을 추가할 수 있습니다. 그렇지 않으면 Vertex Explainable AI에서 모든 값이 0인 기본 입력 기준을 선택하며 이 기준은 이미지 데이터의 검은색 이미지입니다.

    3. TensorFlow 모델을 가져오는 경우 추가 입력 필드가 있습니다.

      1. 입력 텐서 이름을 입력합니다.

      2. 해당되는 경우 색인 텐서 이름 또는 밀도 형태 텐서 이름을 입력합니다.

      3. 여기에서 모달리티를 업데이트할 수 없습니다. 테이블 형식 모델의 경우 NUMERIC, 이미지 모델의 경우 IMAGE로 자동 설정됩니다.

      4. 해당하는 경우 인코딩 필드를 설정합니다. 설정하지 않을 경우 기본값은 IDENTITY입니다.

      5. 해당하는 경우 그룹 이름 필드를 설정합니다.

  5. TensorFlow 모델을 가져오는 경우 출력 필드를 지정합니다.

    1. 특성의 출력 이름을 설정합니다.
    2. 특성의 출력 텐서 이름을 설정합니다.
    3. 해당하는 경우 색인 표시 이름 매핑을 설정합니다.
    4. 해당하는 경우 표시 이름 매핑 키를 설정합니다.

  6. 설명 기능 설정 구성을 완료했으면 가져오기 버튼을 클릭합니다.

gcloud

  1. TensorFlow 2의 경우 ExplanationMetadata는 선택사항입니다.

    다음 ExplanationMetadata를 로컬 환경의 JSON 파일에 작성합니다. 파일 이름은 중요하지 않지만 이 예시에서는 파일 이름을 explanation-metadata.json으로 지정합니다.

    explanation-metadata.json

    {
      "inputs": {
        "FEATURE_NAME": {
          "inputTensorName": "INPUT_TENSOR_NAME",
          "modality": "image",
          "visualization": VISUALIZATION_SETTINGS
        }
      },
      "outputs": {
        "OUTPUT_NAME": {
          "outputTensorName": "OUTPUT_TENSOR_NAME"
        }
      }
    }
    

    다음을 바꿉니다.

    • FEATURE_NAME: 입력 특성의 기억하기 쉬운 이름입니다.
    • INPUT_TENSOR_NAME: TensorFlow의 입력 텐서 이름입니다. 이 필드에 올바른 값을 찾으려면 Vertex Explainable AI에서 TensorFlow 사용을 참조하세요.
    • VIZUALIZATION_OPTIONS: 설명을 시각화하기 위한 옵션입니다. 이 필드에 정보를 입력하는 방법을 알아보려면 이미지 데이터의 시각화 설정 구성을 참조하세요.
    • OUTPUT_NAME: 모델 출력의 기억하기 쉬운 이름입니다.
    • OUTPUT_TENSOR_NAME: TensorFlow의 출력 텐서 이름입니다. 이 필드에 올바른 값을 찾으려면 Vertex Explainable AI에서 TensorFlow 사용을 참조하세요.

    선택사항으로 입력 기준ExplanationMetadata에 추가할 수 있습니다. 그렇지 않은 경우 Vertex AI가 Model의 입력 기준을 선택합니다.

  2. 다음 명령어를 실행하여 Vertex Explainable AI를 지원하는 Model 리소스를 만듭니다. Vertex Explainable AI와 가장 관련성이 높은 플래그가 강조표시됩니다.

    gcloud ai models upload \
      --region=LOCATION \
      --display-name=MODEL_NAME \
      --container-image-uri=IMAGE_URI \
      --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
      --explanation-method=xrai \
      --explanation-step-count=STEP_COUNT \
      --explanation-metadata-file=explanation-metadata.json
    

    다음을 바꿉니다.

    다른 자리표시자에 적합한 값을 알아보려면 upload모델 가져오기를 참조하세요.

    필요에 따라 경사의 SmoothGrad 근사값을 구성하는 플래그를 추가할 수 있습니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

다른 자리표시자에 적합한 값을 알아보려면 upload모델 가져오기를 참조하세요.

선택사항으로 입력 기준ExplanationMetadata에 추가할 수 있습니다. 그렇지 않은 경우 Vertex AI가 Model의 입력 기준을 선택합니다.

원하는 경우 ExplanationParameters경사의 SmoothGrad 근사값을 구성하는 필드를 추가할 수 있습니다.

TensorFlow 2 모델의 경우 metadata 필드는 선택사항입니다. 생략하면 Vertex AI가 모델에서 inputsoutputs를 자동으로 추론합니다.

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

JSON 요청 본문:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "xraiAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "image",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

scikit-learn 및 XGBoost의 사전 빌드된 컨테이너

Model이 테이블 형식 데이터를 입력으로 사용하고 사전 빌드된 scikit-learn 또는 XGBoost의 컨테이너 예측을 사용하여 예측을 제공하는 경우 설명에 샘플링된 Shapley 기여 분석 메서드를 사용하도록 구성할 수 있습니다.

Model을 만들거나 가져오는 데 사용할 도구에 따라 다음 탭 중 하나를 선택합니다.

Console

Google Cloud Console을 사용하여 모델 가져오기 가이드를 따르세요. 설명 기능 단계에 도달하면 다음을 수행합니다.

  1. 특성 기여 분석 메서드에 대해 샘플링된 모양(표 형식 모델)을 선택합니다.

  2. 경로 수를 샘플링된 Shapley 기여 분석 메서드에 사용할 특성 순열 수로 설정합니다. 이는 [1, 50] 범위의 정수여야 합니다.

    값이 높을수록 근사치 오류가 감소할 수 있지만 계산량이 더 많습니다. 어떤 값을 사용해야 할지 모르는 경우 25를 사용합니다.

  3. 모델의 각 입력 특성을 구성합니다.

    1. 입력 특성 이름을 입력합니다.

      모델 아티팩트에 특성 이름이 없으면 Vertex AI가 지정된 입력 특성 이름을 모델에 매핑할 수 없습니다. 이 경우 input_features와 같이 사용자 친화적인 임의의 이름을 가진 입력 특성 하나만 제공해야 합니다. 설명 응답에서 기여 분석의 N차원 목록이 표시됩니다. 여기서 N은 모델의 특성 수이고 목록의 요소는 학습 데이터 세트와 동일한 순서로 표시됩니다.

    2. 필요한 경우 하나 이상의 입력 기준을 추가할 수 있습니다. 그렇지 않으면 Vertex Explainable AI에서 모든 값이 0인 기본 입력 기준을 선택하며 이 기준은 이미지 데이터의 검은색 이미지입니다.

  4. 특성의 출력 이름을 설정합니다.

  5. 설명 기능 설정 구성을 완료했으면 가져오기 버튼을 클릭합니다.

gcloud

  1. 다음 ExplanationMetadata를 로컬 환경의 JSON 파일에 작성합니다. 파일 이름은 중요하지 않지만 이 예시에서는 파일 이름을 explanation-metadata.json으로 지정합니다.

    explanation-metadata.json

    {
      "inputs": {
        "FEATURE_NAME": {
        }
      },
      "outputs": {
        "OUTPUT_NAME": {
        }
      }
    }
    

    다음을 바꿉니다.

    • FEATURE_NAME: 입력 특성의 기억하기 쉬운 이름입니다.
    • OUTPUT_NAME: 모델 출력의 기억하기 쉬운 이름입니다.

    입력 기준을 지정하는 경우 모델의 입력(일반적으로 2-D 행렬 목록)과 일치해야 합니다. 그렇지 않으면 입력 기준의 기본값은 입력 형태의 0 값 2-D 행렬입니다.

  2. 다음 명령어를 실행하여 Vertex Explainable AI를 지원하는 Model 리소스를 만듭니다. Vertex Explainable AI와 가장 관련성이 높은 플래그가 강조표시됩니다.

    gcloud ai models upload \
      --region=LOCATION \
      --display-name=MODEL_NAME \
      --container-image-uri=IMAGE_URI \
      --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
      --explanation-method=sampled-shapley \
      --explanation-path-count=PATH_COUNT \
      --explanation-metadata-file=explanation-metadata.json
    

    다음을 바꿉니다.

    다른 자리표시자에 적합한 값을 알아보려면 upload모델 가져오기를 참조하세요.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • IMAGE_URI: 예측 제공을 위한 사전 빌드된 컨테이너의 URI입니다.
  • PATH_COUNT: 샘플링된 Shapley 기여 분석 메서드에 사용할 특성 치환 개수입니다. [1, 50] 범위의 정수여야 합니다.

    값이 높을수록 근사치 오류가 감소할 수 있지만 계산량이 더 많습니다. 어떤 값을 사용해야 할지 모르는 경우 25를 사용합니다.

  • FEATURE_NAME: 입력 특성의 기억하기 쉬운 이름입니다.
  • OUTPUT_NAME: 모델 출력의 기억하기 쉬운 이름입니다.

다른 자리표시자에 적합한 값을 알아보려면 upload모델 가져오기를 참조하세요.

입력 기준을 지정하는 경우 모델의 입력(일반적으로 2-D 행렬 목록)과 일치해야 합니다. 그렇지 않으면 입력 기준의 기본값은 입력 형태의 0 값 2-D 행렬입니다.

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

JSON 요청 본문:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {
         }
       },
       "outputs": {
         "OUTPUT_NAME": {
         }
       }
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

커스텀 컨테이너

Model이 테이블 형식 데이터를 입력으로 허용하고 커스텀 컨테이너를 사용하여 예측을 제공하는 경우, 설명에 샘플링된 Shapley 기여 분석 방법을 사용하도록 구성할 수 있습니다.

기능 및 출력 이름 확인

다음 단계에서는 Model이 입력으로 예상하는 특성 이름을 Vertex AI에 제공해야 합니다. Model의 예측에서 출력에 사용되는 키도 지정해야 합니다.

특성 이름 결정

Model이 각 입력 인스턴스에 특정한 최상위 키가 있을 것을 예상하는 경우 이러한 키는 특성 이름입니다.

예를 들어 Model이 각 입력 인스턴스의 형식이 다음과 같을 것으로 예상한다고 가정해 보겠습니다.

{
  "length": <value>,
  "width": <value>
}

이 경우 특성 이름은 lengthwidth입니다. 이 필드의 값에 중첩된 목록이나 객체가 포함되어 있더라도 lengthwidth가 다음 단계에 필요한 유일한 키입니다. 설명을 요청하면 Vertex Explainable AI는 특성의 각 중첩된 요소에 대한 기여 분석을 제공합니다.

Model에 키가 없는 입력이 예상되는 경우 Vertex Explainable AI는 Model에 단일 특성이 있는 것으로 간주합니다. 특성 이름으로 기억하기 쉬운 문자열을 사용할 수 있습니다.

예를 들어 Model이 각 입력 인스턴스의 형식이 다음과 같을 것으로 예상한다고 가정해 보겠습니다.

[
  <value>,
  <value>
]

이 경우 Vertex Explainable AI에 dimensions와 같이 원하는 단일 특성 이름을 제공합니다.

출력 이름 결정

Model이 키가 지정된 출력이 있는 각 온라인 예측 인스턴스를 반환하는 경우 이 키는 출력 이름입니다.

예를 들어 Model이 각 예측을 다음 형식으로 반환한다고 가정해 보겠습니다.

{
  "scores": <value>
}

이 경우 출력 이름은 scores입니다. scores 필드 값이 배열인 경우 설명을 가져오면 Vertex Explainable AI가 각 예측에서 가장 높은 값을 가진 요소의 특성 기여 분석을 반환합니다. 출력 필드의 추가 요소에 특성 기여 분석을 제공하도록 Vertex Explainable AI를 구성하기 위해 ExplanationParameterstopK 또는outputIndices 필드를 지정할 수 있습니다. 그러나 이 문서의 예시에서는 이러한 옵션을 보여주지 않습니다.

Model이 키가 지정되지 않은 예측을 반환하면 출력 이름에 기억하기 쉬운 문자열을 사용할 수 있습니다. 예를 들어 이는 Model이 각 예측에 대해 배열 또는 스칼라를 반환하는 경우 적용됩니다.

Model 만들기

Model을 만들거나 가져오는 데 사용할 도구에 따라 다음 탭 중 하나를 선택합니다.

Console

Google Cloud Console을 사용하여 모델 가져오기 가이드를 따르세요. 설명 기능 단계에 도달하면 다음을 수행합니다.

  1. 특성 기여 분석 메서드에 대해 샘플링된 모양(표 형식 모델)을 선택합니다.

  2. 경로 수를 샘플링된 Shapley 기여 분석 메서드에 사용할 특성 순열 수로 설정합니다. 이는 [1, 50] 범위의 정수여야 합니다.

    값이 높을수록 근사치 오류가 감소할 수 있지만 계산량이 더 많습니다. 어떤 값을 사용해야 할지 모르는 경우 25를 사용합니다.

  3. 모델의 각 입력 특성을 구성합니다.

    1. 입력 특성 이름을 입력합니다.

      모델 아티팩트에 특성 이름이 없으면 Vertex AI가 지정된 입력 특성 이름을 모델에 매핑할 수 없습니다. 이 경우 input_features와 같이 사용자 친화적인 임의의 이름을 가진 입력 특성 하나만 제공해야 합니다. 설명 응답에서 기여 분석의 N차원 목록이 표시됩니다. 여기서 N은 모델의 특성 수이고 목록의 요소는 학습 데이터 세트와 동일한 순서로 표시됩니다.

    2. 필요한 경우 하나 이상의 입력 기준을 추가할 수 있습니다. 그렇지 않으면 Vertex Explainable AI에서 모든 값이 0인 기본 입력 기준을 선택하며 이 기준은 이미지 데이터의 검은색 이미지입니다.

  4. 특성의 출력 이름을 설정합니다.

  5. 설명 기능 설정 구성을 완료했으면 가져오기 버튼을 클릭합니다.

gcloud

  1. 다음 ExplanationMetadata를 로컬 환경의 JSON 파일에 작성합니다. 파일 이름은 중요하지 않지만 이 예시에서는 파일 이름을 explanation-metadata.json으로 지정합니다.

    explanation-metadata.json

    {
      "inputs": {
        "FEATURE_NAME": {}
      },
      "outputs": {
        "OUTPUT_NAME": {}
      }
    }
    

    다음을 바꿉니다.

    • FEATURE_NAME: 이 문서의 '특성 이름 결정' 섹션에 설명된 특성 이름입니다.
    • OUTPUT_NAME: 이 문서의 '출력 이름 결정' 섹션에 설명된 출력 이름입니다.

    선택사항으로 입력 기준ExplanationMetadata에 추가할 수 있습니다. 그렇지 않은 경우 Vertex AI가 Model의 입력 기준을 선택합니다.

    입력 기준을 지정하는 경우 모델의 입력(일반적으로 2-D 행렬 목록)과 일치해야 합니다. 그렇지 않으면 입력 기준의 기본값은 입력 형태의 0 값 2-D 행렬입니다.

  2. 다음 명령어를 실행하여 Vertex Explainable AI를 지원하는 Model 리소스를 만듭니다. Vertex Explainable AI와 가장 관련성이 높은 플래그가 강조표시됩니다.

    gcloud ai models upload \
      --region=LOCATION \
      --display-name=MODEL_NAME \
      --container-image-uri=IMAGE_URI \
      --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
      --explanation-method=sampled-shapley \
      --explanation-path-count=PATH_COUNT \
      --explanation-metadata-file=explanation-metadata.json
    

    다음을 바꿉니다.

    • PATH_COUNT: 샘플링된 Shapley 기여 분석 메서드에 사용할 특성 치환 개수입니다. [1, 50] 범위의 정수여야 합니다.

      값이 높을수록 근사치 오류가 감소할 수 있지만 계산량이 더 많습니다. 어떤 값을 사용해야 할지 모르는 경우 25를 사용합니다.

    다른 자리표시자에 적합한 값을 알아보려면 upload모델 가져오기를 참조하세요.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • PATH_COUNT: 샘플링된 Shapley 기여 분석 메서드에 사용할 특성 치환 개수입니다. [1, 50] 범위의 정수여야 합니다.

    값이 높을수록 근사치 오류가 감소할 수 있지만 계산량이 더 많습니다. 어떤 값을 사용해야 할지 모르는 경우 25를 사용합니다.

  • FEATURE_NAME: 이 문서의 '특성 이름 결정' 섹션에 설명된 특성 이름입니다.
  • OUTPUT_NAME: 이 문서의 '출력 이름 결정' 섹션에 설명된 출력 이름입니다.

다른 자리표시자에 적합한 값을 알아보려면 upload모델 가져오기를 참조하세요.

선택사항으로 입력 기준ExplanationMetadata에 추가할 수 있습니다. 그렇지 않은 경우 Vertex AI가 Model의 입력 기준을 선택합니다.

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

JSON 요청 본문:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {}
       },
       "outputs": {
         "OUTPUT_NAME": {}
       }
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

다음 단계