REST 리소스: projects.models.versions

리소스: Version

모델의 버전을 나타냅니다.

각 버전은 예측 요청을 처리할 수 있도록 클라우드에 배포된 학습된 모델입니다. 모델에는 여러 버전이 있을 수 있습니다. projects.models.versions.list를 호출하여 특정 모델의 모든 버전에 대한 정보를 가져올 수 있습니다.

JSON 표현

{
  "name": string,
  "description": string,
  "isDefault": boolean,
  "deploymentUri": string,
  "createTime": string,
  "lastUseTime": string,
  "runtimeVersion": string,
  "machineType": string,
  "state": enum (State),
  "errorMessage": string,
  "packageUris": [
    string
  ],
  "labels": {
    string: string,
    ...
  },
  "etag": string,
  "framework": enum (Framework),
  "pythonVersion": string,
  "acceleratorConfig": {
    object (AcceleratorConfig)
  },
  "serviceAccount": string,
  "requestLoggingConfig": {
    object (RequestLoggingConfig)
  },
  "explanationConfig": {
    object (ExplanationConfig)
  },

  // Union field scaling can be only one of the following:
  "autoScaling": {
    object (AutoScaling)
  },
  "manualScaling": {
    object (ManualScaling)
  }
  // End of list of possible types for union field scaling.
  "predictionClass": string
}
필드
name

string

필수. 버전을 만들 때 지정한 이름입니다.

버전 이름은 생성되는 모델 내에서 고유해야 합니다.

description

string

선택사항. 버전을 만들 때 지정된 설명입니다.

isDefault

boolean

출력 전용. true인 경우 이 버전은 지정된 버전이 없는 예측 요청을 처리하는 데 사용됩니다.

projects.methods.versions.setDefault를 호출하여 기본 버전을 변경할 수 있습니다.

deploymentUri

string

필수. 버전을 만드는 데 사용되는 학습된 모델의 Cloud Storage 위치입니다. 자세한 내용은 모델 배포 가이드를 참조하세요.

버전을 projects.models.versions.create에 전달할 때 모델 서비스는 지정된 위치를 모델의 소스로 사용합니다. 배포된 모델 버전은 예측 서비스에서 호스팅되므로 이 위치는 이전 레코드로만 유용합니다. 총 모델 파일 수는 1,000개를 초과할 수 없습니다.

createTime

string (Timestamp format)

출력 전용. 버전이 생성된 시간입니다.

lastUseTime

string (Timestamp format)

출력 전용. 버전이 마지막으로 예측에 사용된 시간입니다.

runtimeVersion

string

필수. 이 배포에 사용할 AI Platform 런타임 버전입니다.

자세한 내용은 런타임 버전 목록런타임 버전 관리 방법을 참조하세요.

machineType

string

선택사항. 모델을 제공할 머신 유형입니다. 현재 온라인 예측 서비스에만 적용됩니다. 이 필드를 지정하지 않으면 기본값은 mls1-c1-m2입니다.

온라인 예측은 다음 머신 유형을 지원합니다.

  • mls1-c1-m2
  • mls1-c4-m2
  • n1-standard-2
  • n1-standard-4
  • n1-standard-8
  • n1-standard-16
  • n1-standard-32
  • n1-highmem-2
  • n1-highmem-4
  • n1-highmem-8
  • n1-highmem-16
  • n1-highmem-32
  • n1-highcpu-2
  • n1-highcpu-4
  • n1-highcpu-8
  • n1-highcpu-16
  • n1-highcpu-32

mls1-c1-m2는 일반적으로 사용 가능합니다. 다른 모든 머신 유형은 베타 버전으로 제공됩니다. 머신 유형의 차이점에 대해 자세히 알아보세요.

state

enum (State)

출력 전용. 버전 상태입니다.

errorMessage

string

출력 전용. 실패 또는 취소의 세부정보입니다.

packageUris[]

string

선택사항. 커스텀 예측 루틴 또는 커스텀 코드가 있는 scikit-learn 파이프라인에 대한 패키지의 Cloud Storage 경로(gs://…)입니다.

커스텀 예측 루틴의 경우 이러한 패키지 중 하나에 예측자 클래스가 포함되어 있어야 합니다(predictionClass 참조). 또한 선택한 런타임 버전에 포함되지 않은 예측자 또는 scikit-learn 파이프라인에서 사용하는 모든 종속 항목을 포함합니다.

이 필드를 지정하면 runtimeVersion도 1.4 이상으로 설정해야 합니다.

labels

map (key: string, value: string)

선택사항. 모델 버전을 구성하기 위해 추가할 수 있는 하나 이상의 라벨입니다. 각 라벨은 키-값 쌍이며, 키와 값은 모두 사용자가 제공하는 임의의 문자열입니다. 자세한 내용은 라벨 사용 문서를 참조하세요.

"key": value 쌍 목록을 포함하는 객체입니다. 예를 들면 { "name": "wrench", "mass": "1.3kg", "count": "3" }입니다.

etag

string (bytes format)

etag는 동시에 발생한 모델 업데이트가 서로를 덮어쓰지 않도록 방지하는 낙관적 동시 실행 제어에 사용됩니다. 모델 업데이트를 수행할 때 읽기-수정-쓰기 주기에서 시스템이 etag를 활용하여 경합 상태를 방지하는 것이 좋습니다. etagversions.get에 대한 응답으로 반환되며, versions.patch 요청에 해당 etag를 넣어 변경사항이 의도한 대로 모델에 적용되도록 해야 합니다.

base64 인코딩 문자열입니다.

framework

enum (Framework)

선택사항. AI Platform이 이 모델 버전을 학습시키는 데 사용하는 머신러닝 프레임워크입니다. 유효한 값은 TENSORFLOW, SCIKIT_LEARN, XGBOOST입니다. 프레임워크를 지정하지 않으면 AI Platform이 deploymentUri의 파일을 분석하여 프레임워크를 결정합니다. SCIKIT_LEARN 또는 XGBOOST를 선택할 경우 모델의 런타임 버전을 1.4 이상으로 설정해야 합니다.

커스텀 예측 루틴을 배포하는 경우 프레임워크를 지정하지 않습니다.

machineType 필드에서 Compute Engine(N1) 머신 유형을 지정하는 경우 프레임워크에 TENSORFLOW를 지정해야 합니다.

pythonVersion

string

필수. 예측에 사용되는 Python 버전입니다.

다음 Python 버전을 사용할 수 있습니다.

  • Python '3.7'은 runtimeVersion이 '1.15' 이상으로 설정된 경우 사용할 수 있습니다.
  • Python '3.5'는 runtimeVersion이 '1.4'에서 '1.14'로 설정된 경우 사용할 수 있습니다.
  • Python '2.7'은 runtimeVersion이 '1.15' 이하로 설정된 경우 사용할 수 있습니다.

각 런타임 버전에서 사용할 수 있는 Python 버전에 대해 자세히 알아보세요.

acceleratorConfig

object (AcceleratorConfig)

선택사항. 온라인 예측(베타)에 GPU를 사용하기 위한 가속기 구성입니다. machineType 필드에 Compute Engine(N1) 머신 유형을 지정한 경우에만 이 필드를 지정합니다. 온라인 예측에 GPU 사용에 대해 자세히 알아보세요.

serviceAccount

string

선택사항. 리소스 액세스 제어를 위한 서비스 계정을 지정합니다.

requestLoggingConfig

object (RequestLoggingConfig)

선택사항. projects.models.versions.patch 요청에서 이 필드 지정합니다. projects.models.versions.create 요청에서 지정해도 아무런 영향이 없습니다.

이 버전의 예측에 대한 요청-응답 쌍 로깅을 구성합니다.

explanationConfig

object (ExplanationConfig)

선택사항. 모델 버전의 설명 기능을 구성합니다. 일부 설명 기능은 모델 페이로드의 일부로 추가 메타데이터를 로드해야 합니다.

통합 필드 scaling. 선택사항. 확장 옵션을 설정합니다. 지정되지 않은 경우 기본값은 min_nodes가 0인 auto_scaling입니다(AutoScaling.min_nodes는 문서 참조). scaling은 다음 중 하나여야 합니다.
autoScaling

object (AutoScaling)

트래픽 증가 및 감소에 따라 모델을 제공하는 데 사용되는 노드 수를 자동으로 확장합니다. 모델의 확장 기능에 따라 트래픽을 늘려야 합니다. 그렇지 않으면 지연 시간 및 429 응답 코드가 증가하기 시작합니다.

버전에서 GPU를 사용하는 경우 자동 확장을 사용할 수 없습니다. 대신 manualScaling을 지정해야 합니다.

manualScaling

object (ManualScaling)

모델 제공에 사용할 노드 수를 수동으로 선택합니다. 일반적으로 적절한 minNodes와 함께 autoScaling을 사용해야 하지만, 예측 가능한 결제를 원하는 경우에 이 옵션은 사용할 수 있습니다. 트래픽이 선택된 노드 수에 따라 모델을 제공하는 시스템의 용량을 초과하면 지연 시간과 오류율이 증가합니다.

predictionClass

string

선택사항. 이 참조 필드에 설명된 예측자 인터페이스를 구현하는 클래스의 정규화된 이름(module_name.class_name)입니다. 이 클래스가 포함된 모듈은 packageUris 필드에 제공된 패키지에 포함되어야 합니다.

커스텀 예측 루틴(베타)을 배포하는 경우에만 이 필드를 지정합니다. 이 필드를 지정하는 경우 runtimeVersion을 1.4 이상으로 설정해야 하며 machineType레거시(MLS1) 머신 유형으로 설정해야 합니다.

다음 코드 샘플은 예측자 인터페이스를 제공합니다.


class Predictor(object):
"""Interface for constructing custom predictors."""

def predict(self, instances, **kwargs):
    """Performs custom prediction.

    Instances are the decoded values from the request. They have already
    been deserialized from JSON.

    Args:
        instances: A list of prediction input instances.
        **kwargs: A dictionary of keyword args provided as additional
            fields on the predict request body.

    Returns:
        A list of outputs containing the prediction results. This list must
        be JSON serializable.
    """
    raise NotImplementedError()

@classmethod
def from_path(cls, model_dir):
    """Creates an instance of Predictor using the given path.

    Loading of the predictor should be done in this method.

    Args:
        model_dir: The local directory that contains the exported model
            file along with any additional files uploaded when creating the
            version resource.

    Returns:
        An instance implementing this Predictor class.
    """
    raise NotImplementedError()

예측자 인터페이스 및 커스텀 예측 루틴에 대해 자세히 알아보세요.

자동 확장

모델을 자동으로 확장하는 옵션입니다.

JSON 표현

{
  "minNodes": integer
}
필드
minNodes

integer

선택사항. 이 모델에 할당할 최소 노드 수입니다. 이러한 노드는 모델이 배포된 시점부터 항상 실행됩니다. 따라서 이 모델을 운영하는 데 드는 비용은 rate * minNodes * 마지막 결제 주기 후 경과한 시간입니다. 여기서 rate는 예측이 수행되지 않더라도 가격 책정 가이드에 설명된 대로 노드 시간당 비용입니다. 수행된 각 예측에는 추가 비용이 발생합니다.

수동 확장과 달리 실행 중인 노드에 로드가 너무 크면 서비스가 증가된 로드를 처리하도록 노드를 자동으로 추가하고 트래픽 감소 시 다시 확장되어 항상 minNodes 이상을 유지합니다. 추가 노드가 사용된 시간에 대한 요금이 청구됩니다.

minNodes를 지정하지 않고 자동 확장이 레거시(MLS1) 머신 유형에서 사용되는 경우 minNodes의 기본값은 0입니다. 이 경우 모델에 대한 트래픽이 중지되면(대기 시간 후) 모델에 대한 트래픽이 재개될 때까지 노드가 종료되고 요금이 청구되지 않습니다.

minNodes가 지정되지 않고 자동 확장이 Compute Engine(N1) 머신 유형에서 사용되면 minNodes의 기본값은 1입니다. Compute Engine 머신 유형에서 사용하려면 minNodes는 1 이상이어야 합니다.

버전에서 GPU를 사용하는 경우 자동 확장을 사용할 수 없습니다. 대신 수동 확장을 사용해야 합니다.

모델 버전을 만들 때 minNodes를 설정하고 기존 버전의 minNodes를 업데이트할 수도 있습니다.


update_body.json:
{
  'autoScaling': {
    'minNodes': 5
  }
}

HTTP 요청:


PATCH
https://ml.googleapis.com/v1/{name=projects/*/models/*/versions/*}?updateMask=autoScaling.minNodes
-d @./update_body.json

수동 확장

모델을 수동으로 확장하는 옵션입니다.

JSON 표현

{
  "nodes": integer
}
필드
nodes

integer

이 모델에 할당할 노드 수입니다. 이러한 노드는 모델이 배포된 시점부터 항상 실행되므로 이 모델을 운영하는 데 드는 비용은 nodes * 마지막 결제 주기 후 경과한 시간 + 수행된 각 예측의 비용입니다.

상태

버전 상태를 설명합니다.

열거형
UNKNOWN 버전 상태가 지정되지 않았습니다.
READY 버전을 예측할 준비가 되었습니다.
CREATING 버전을 만드는 중입니다. 버전이 CREATING 상태인 경우 새로운 versions.patch 및 version.delete 요청이 실패합니다.
FAILED 버전을 만들지 못했습니다. 취소되었을 수 있습니다. errorMessage에는 실패의 세부정보가 포함되어야 합니다.
DELETING 버전을 삭제하는 중입니다. 버전이 DELETING 상태인 경우 새로운 versions.patch 및 version.delete 요청이 실패합니다.
UPDATING 버전을 업데이트하는 중입니다. 버전이 UPDATING 상태인 경우 새로운 versions.patch 및 version.delete 요청이 실패합니다.

프레임워크

예측에 사용 가능한 프레임워크입니다.

열거형
FRAMEWORK_UNSPECIFIED 지정되지 않은 프레임워크. 파일 서픽스를 기반으로 값을 할당합니다.
TENSORFLOW Tensorflow 프레임워크.
SCIKIT_LEARN Scikit-learn 프레임워크.
XGBOOST XGBoost 프레임워크.

RequestLoggingConfig

요청-응답 쌍을 BigQuery 테이블에 로깅하기 위한 구성입니다. 모델 버전에 대한 온라인 예측 요청과 이러한 요청에 대한 응답은 원시 문자열로 변환되어 지정된 BigQuery 테이블에 저장됩니다. 로깅은 BigQuery 할당량 및 한도에 따라 제한됩니다. 프로젝트가 BigQuery 할당량 또는 한도를 초과하는 경우 AI Platform Prediction은 요청-응답 쌍을 로깅하지 않지만 계속 예측을 제공합니다.

지속적 평가를 사용하는 경우 이 구성을 수동으로 지정할 필요가 없습니다. 지속적 평가를 설정하면 요청-응답 쌍을 자동으로 로깅할 수 있습니다.

JSON 표현

{
  "samplingPercentage": number,
  "bigqueryTableName": string
}
필드
samplingPercentage

number

로깅할 요청 비율로, 0~1 사이의 비율로 표시됩니다. 예를 들어 요청의 10%를 로깅하려면 0.1을 입력합니다. 샘플링 기간은 모델 버전의 수명입니다. 기본값은 0입니다.

bigqueryTableName

string

필수. 정규화된 BigQuery 테이블 이름: 'projectId.dataset_name.table_name'

지정된 테이블이 이미 존재해야 하며 프로젝트의 'Cloud ML 서비스 에이전트'에 테이블에 쓸 수 있는 권한이 있어야 합니다. 테이블에 다음 스키마가 있어야 합니다.

필드 이름유형 모드
model문자열필수 항목
model_version문자열필수 항목
time타임스탬프필수 항목
raw_data문자열필수 항목
raw_prediction문자열null 허용
groundtruth문자열null 허용

ExplanationConfig

모델 예측을 설명하는 메시지 저장 구성 옵션입니다. TensorFlow 모델에는 두 가지 특성 기여 분석 메서드(통합 경사 및 샘플링된 Shapley)가 지원됩니다. 특성 기여 분석에 대해 자세히 알아보기.

JSON 표현

{

  // Union field attribution_method can be only one of the following:
  "integratedGradientsAttribution": {
    object (IntegratedGradientsAttribution)
  },
  "sampledShapleyAttribution": {
    object (SampledShapleyAttribution)
  },
  "xraiAttribution": {
    object (XraiAttribution)
  }
  // End of list of possible types for union field attribution_method.
}
필드
통합 필드 attribution_method. 모델의 예측을 설명하는 데 사용할 기여 분석 메서드입니다. attribution_method은 다음 중 하나여야 합니다.
integratedGradientsAttribution

object (IntegratedGradientsAttribution)

모델의 완전 미분 가능 구조를 활용해 Aumann-Shapley 값을 계산하여 얻은 속성 크레딧입니다. 자세한 내용은 다음 자료를 참조하세요. http://proceedings.mlr.press/v70/sundararajan17a.html

sampledShapleyAttribution

object (SampledShapleyAttribution)

예측되는 라벨에 영향을 미치는 특성의 Shapley 값의 근사치를 계산하는 기여 분석 메서드입니다. 샘플링 전략은 특성의 모든 하위 집합을 고려하는 대신 값의 근사치를 계산하는 데 사용됩니다.

xraiAttribution

object (XraiAttribution)

모델의 완전 미분 가능 구조를 활용해 XRAI를 계산하여 얻은 속성 크레딧입니다. 자세한 내용은 다음 자료를 참조하세요. https://arxiv.org/abs/1906.02825 현재 기본 이미지 입력이 있는 모델에만 구현됩니다.

IntegratedGradientsAttribution

모델의 완전 미분 가능 구조를 활용해 Aumann-Shapley 값을 계산하여 얻은 속성 크레딧입니다. 자세한 내용은 다음 자료를 참조하세요. http://proceedings.mlr.press/v70/sundararajan17a.html

JSON 표현

{
  "numIntegralSteps": integer
}
필드
numIntegralSteps

integer

경로 적분의 근사치를 계산하기 위한 단계 수입니다. 시작하기에 적절한 값은 50이며 원하는 오류 범위 내에서 오차 속성 합계가 충족될 때까지 점진적으로 증가합니다.

SampledShapleyAttribution

예측되는 라벨에 영향을 미치는 특성의 Shapley 값의 근사치를 계산하는 기여 분석 메서드입니다. 샘플링 전략은 특성의 모든 하위 집합을 고려하는 대신 값의 근사치를 계산하는 데 사용됩니다.

JSON 표현

{
  "numPaths": integer
}
필드
numPaths

integer

Shapley 값의 근사치를 계산할 때 고려할 특성 치환의 수입니다.

XraiAttribution

모델의 완전 미분 가능 구조를 활용해 XRAI를 계산하여 얻은 속성 크레딧입니다. 자세한 내용은 다음 자료를 참조하세요. https://arxiv.org/abs/1906.02825 현재 기본 이미지 입력이 있는 모델에만 구현됩니다.

JSON 표현

{
  "numIntegralSteps": integer
}
필드
numIntegralSteps

integer

경로 적분의 근사치를 계산하기 위한 단계 수입니다. 시작하기에 적절한 값은 50이며 원하는 오류 범위 내에서 오차 속성 합계가 충족될 때까지 점진적으로 증가합니다.

메서드

create

학습된 TensorFlow 모델에서 새 버전의 모델을 만듭니다.

delete

모델 버전을 삭제합니다.

get

모델 버전에 대한 정보를 가져옵니다.

list

모델의 모든 버전에 대한 기본 정보를 가져옵니다.

patch

지정된 버전 리소스를 업데이트합니다.

setDefault

버전을 모델의 기본값으로 지정합니다.