기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# Neptune ML에서 사용자 지정 모델 개발
<a name="machine-learning-custom-model-development"></a>

사용자 지정 모델 개발을 시작하는 좋은 방법은 [Neptune ML 도구 키트 예제](https://github.com/awslabs/neptuneml-toolkit/tree/main/examples/custom-models/introduction)에 따라 훈련 모듈을 구성하고 작성하는 것입니다. 또한 Neptune ML 도구 키트는 [modelzoo](https://github.com/awslabs/neptuneml-toolkit/tree/main/src/neptuneml_toolkit/modelzoo)에 모듈화된 그래프 ML 모델 구성 요소를 구현합니다. 이 구성 요소를 중첩하여 사용자 지정 모델을 생성하는 데 사용할 수 있습니다.

나아가 이 도구 키트는 모델 훈련 및 모델 변환 중에 필요한 아티팩트를 생성하는 데 도움이 되는 유틸리티 함수를 제공합니다. 사용자 지정 구현에서 이 Python 패키지를 가져올 수 있습니다. 도구 키트에서 제공되는 모든 함수 또는 모듈은 Neptune ML 훈련 환경에서도 사용할 수 있습니다.

Python 모듈에 추가 외부 종속성이 있는 경우 모듈 디렉터리에 `requirements.txt` 파일을 생성하여 이러한 추가 종속성을 포함할 수 있습니다. 그러면 훈련 스크립트가 실행되기 전에 `requirements.txt` 파일에 나열된 패키지가 설치됩니다.

사용자 지정 모델을 구현하는 Python 모듈에는 최소한 다음이 포함되어야 합니다.
+ 훈련 스크립트 진입점
+ 변환 스크립트 진입점
+ `model-hpo-configuration.json` 파일

## Neptune ML에서 사용자 지정 모델 훈련 스크립트 개발
<a name="machine-learning-custom-model-training-script"></a>

사용자 지정 모델 훈련 스크립트는 Neptune ML 도구 키트의 [https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py) 예제와 같은 실행 가능한 Python 스크립트여야 합니다. 하이퍼파라미터 이름과 값을 명령줄 인수로 받아들여야 합니다. 모델 훈련 중에는 `model-hpo-configuration.json` 파일에서 하이퍼파라미터 이름을 가져옵니다. 하이퍼파라미터 값은 하이퍼파라미터를 조정할 수 있는 경우 유효한 하이퍼파라미터 범위 내에 속하고, 조정할 수 없는 경우에는 기본 하이퍼파라미터 값을 사용합니다.

훈련 스크립트는 다음과 같은 구문을 사용하여 SageMaker AI 훈련 인스턴스에서 실행됩니다.

```
python3 (script entry point) --(1st parameter) (1st value) --(2nd parameter) (2nd value) (...)
```

모든 작업에 대해 Neptune ML AutoTrainer는 사용자가 지정하는 하이퍼파라미터 외에도 여러 가지 필수 파라미터를 훈련 스크립트로 전송합니다. 스크립트가 제대로 작동하려면 이러한 추가 파라미터를 처리할 수 있어야 합니다.

다음과 같은 추가 필수 파라미터는 작업에 따라 약간 다릅니다.

**노드 분류 또는 노드 회귀용**
+ **`task`**   –   Neptune ML에서 내부적으로 사용하는 작업 유형입니다. 이 값은 노드 분류의 경우 `node_class`이고, 노드 회귀의 경우 `node_regression`입니다.
+ **`model`**   –   Neptune ML에서 내부적으로 사용하는 모델 이름으로, 이 경우에는 `custom`입니다.
+ **`name`**   –   Neptune ML에서 내부적으로 사용하는 작업 이름으로, 이 경우에 노드 분류는 `node_class-custom`, 노드 회귀는 `node_regression-custom`입니다.
+ **`target_ntype`**   –   분류 또는 회귀용 노드 유형의 이름입니다.
+ **`property`**   –   분류 또는 회귀용 노드 속성의 이름입니다.

**연결 예측용**
+ **`task`**   –   Neptune ML에서 내부적으로 사용하는 작업 유형입니다. 연결 예측의 경우 이는 `link_predict`입니다.
+ **`model`**   –   Neptune ML에서 내부적으로 사용하는 모델 이름으로, 이 경우에는 `custom`입니다.
+ **`name`**   –   Neptune ML에서 내부적으로 사용하는 작업 이름으로, 이 경우에는 `link_predict-custom`입니다.

**엣지 분류 또는 엣지 회귀용**
+ **`task`**   –   Neptune ML에서 내부적으로 사용하는 작업 유형입니다. 이 값은 엣지 분류의 경우 `edge_class`이고, 엣지 회귀의 경우 `edge_regression`입니다.
+ **`model`**   –   Neptune ML에서 내부적으로 사용하는 모델 이름으로, 이 경우에는 `custom`입니다.
+ **`name`**   –   Neptune ML에서 내부적으로 사용하는 작업 이름으로, 이 경우에 엣지 분류는 `edge_class-custom`, 엣지 회귀는 `edge_regression-custom`입니다.
+ **`target_etype`**   –   분류 또는 회귀용 엣지 유형의 이름입니다.
+ **`property`**   –   분류 또는 회귀용 엣지 속성의 이름입니다.

스크립트는 모델 파라미터와 훈련 종료 시 필요한 기타 아티팩트를 저장해야 합니다.

Neptune ML 도구 키트 유틸리티 함수를 사용하여 처리된 그래프 데이터의 위치, 모델 파라미터를 저장해야 하는 위치, 훈련 인스턴스에서 사용할 수 있는 GPU 디바이스를 결정할 수 있습니다. 이러한 유틸리티 함수를 사용하는 방법에 대한 예제는 [train.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py) 샘플 훈련 스크립트를 참조하세요.

## Neptune ML에서 사용자 지정 모델 변환 스크립트 개발
<a name="machine-learning-custom-model-transform-script"></a>

모델을 재훈련하지 않고도 변화하는 그래프에서 모델 추론을 위해 Neptune ML [증분 워크플로우](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental)를 활용하려면 변환 스크립트가 필요합니다. 모델 배포에 필요한 모든 아티팩트가 훈련 스크립트에서 생성되더라도 모델을 다시 훈련하지 않고 업데이트된 모델을 생성하려면 여전히 변환 스크립트를 제공해야 합니다.

**참고**  
[실시간 유도 추론](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference)은 현재 사용자 지정 모델에 지원되지 않습니다.

사용자 지정 모델 변환 스크립트는 Neptune ML 도구 키트의 [transform.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/transform.py) 예제 스크립트와 같은 실행 가능한 Python 스크립트여야 합니다. 이 스크립트는 명령줄 인수 없이 모델 훈련 중에 간접적으로 호출되므로, 스크립트에서 허용하는 모든 명령줄 인수에는 기본값이 있어야 합니다.

스크립트는 다음과 같은 구문을 사용하여 SageMaker AI 훈련 인스턴스에서 실행됩니다.

```
python3 (your transform script entry point)
```

변환 스크립트에는 다음과 같은 다양한 정보가 필요합니다.
+ 처리된 그래프 데이터의 위치.
+ 모델 파라미터가 저장되는 위치 및 새 모델 아티팩트가 저장되어야 하는 위치.
+ 인스턴스에서 사용할 수 있는 디바이스.
+ 최상의 모델을 생성한 하이퍼파라미터.

이러한 입력은 스크립트가 호출할 수 있는 Neptune ML 유틸리티 함수를 사용하여 얻습니다. 이를 수행하는 방법에 대한 예제는 도구 키트의 샘플 [transform.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/transform.py) 스크립트를 참조하세요.

스크립트는 각 작업의 모델 배포에 필요한 노드 임베딩, 노드 ID 매핑 및 기타 아티팩트를 저장해야 합니다. 다양한 Neptune ML 작업에 필요한 모델 아티팩트에 대한 자세한 내용은 [모델 아티팩트 설명서](machine-learning-model-artifacts.md)를 참조하세요.

## Neptune ML의 사용자 지정 `model-hpo-configuration.json` 파일
<a name="machine-learning-custom-model-hpo-configuration-file"></a>

`model-hpo-configuration.json` 파일은 사용자 지정 모델의 하이퍼파라미터를 정의합니다. 이 파일은 Neptune ML 내장 모델에 사용되는 `model-hpo-configuration.json` 파일과 동일한 [형식](machine-learning-customizing-hyperparams.md)이며, Neptune ML에서 자동 생성하여 처리된 데이터 위치에 업로드하는 버전보다 우선합니다.

모델에 새 하이퍼파라미터를 추가할 때는 하이퍼파라미터가 훈련 스크립트에 전달되도록 이 파일에 하이퍼파라미터 항목도 추가해야 합니다.

하이퍼파라미터를 조정 가능하게 하려면 하이퍼파라미터의 범위를 제공하고 `tier-1`, `tier-2` 또는 `tier-3` 파라미터로 설정해야 합니다. 구성된 총 훈련 작업 수가 해당 Tier의 하이퍼파라미터를 조정할 수 있는 경우 하이퍼파라미터가 조정됩니다. 조정할 수 없는 파라미터의 경우 기본값을 제공하고 하이퍼파라미터를 파일의 `fixed-param` 섹션에 추가해야 합니다. 이를 수행하는 방법에 대한 예제는 도구 키트의 샘플 [샘플 `model-hpo-configuration.json` 파일](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/model-hpo-configuration.json)을 참조하세요.

또한 SageMaker AI 하이퍼파라미터 최적화 작업에서 훈련된 후보 모델을 평가하는 데 사용할 지표 정의를 제공해야 합니다. 이렇게 하려면 다음과 같이 `model-hpo-configuration.json` 파일에 `eval_metric` JSON 객체를 추가합니다.

```
"eval_metric": {
  "tuning_objective": {
      "MetricName": "(metric_name)",
      "Type": "Maximize"
  },
  "metric_definitions": [
    {
      "Name": "(metric_name)",
      "Regex": "(metric regular expression)"
    }
  ]
},
```

`eval_metric` 객체의 `metric_definitions` 배열에는 SageMaker AI가 훈련 인스턴스에서 추출하려는 각 지표에 대한 지표 정의 객체가 나열됩니다. 각 지표 정의 객체에는 지표 이름(예: '정확도', 'f1' 등)을 제공할 수 있는 `Name` 키가 있습니다. `Regex` 키를 사용하면 특정 지표가 훈련 로그에 출력되는 방식과 일치하는 정규 표현식 문자열을 제공할 수 있습니다. 지표를 정의하는 방법에 대한 자세한 내용은 [SageMaker AI 하이퍼파라미터 조정 페이지](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-define-metrics.html)를 참조하세요.

그런 다음 `eval_metric`의 `tuning_objective` 객체를 통해 하이퍼파라미터 최적화를 위한 목표 지표로서 역할을 할 평가 지표로 사용되어야 하는 `metric_definitions`의 지표를 지정할 수 있습니다. `MetricName`의 값은 `metric_definitions`의 정의 중 하나에 있는 `Name`의 값과 일치해야 합니다. `Type`의 값은 지표가 높을수록 좋다고 해석해야 하는지(예: '정확도'), 낮을수록 좋다고 해석해야 하는지(예: '평균 제곱 오차')에 따라 '최대화' 또는 '최소화'가 되어야 합니다.

SageMaker AI 하이퍼파라미터 조정 작업에서는 최상의 모델을 선택할 수 없기 때문에 `model-hpo-configuration.json` 파일의 이 섹션에 오류가 있으면 Neptune ML 모델 훈련 API 작업이 실패할 수 있습니다.

## Neptune ML에서 사용자 지정 모델 구현의 로컬 테스트
<a name="machine-learning-custom-model-testing"></a>

Neptune ML 도구 키트 Conda 환경을 통해 로컬에서 코드를 실행하여 모델을 테스트하고 검증할 수 있습니다. Neptune 노트북 인스턴스에서 개발하는 경우 이 Conda 환경은 Neptune 노트북 인스턴스에 사전 설치됩니다. 다른 인스턴스에서 개발하는 경우 Neptune ML 도구 키트의 [로컬 설정 지침](https://github.com/awslabs/neptuneml-toolkit#local-installation)을 따라야 합니다.

Conda 환경은 [모델 훈련 API](machine-learning-api-modeltraining.md)를 호출할 때 모델이 실행될 환경을 정확하게 재현합니다. 모든 예제 훈련 스크립트와 변환 스크립트를 사용하면 명령줄 `--local` 플래그를 전달함으로써 로컬 환경에서 스크립트를 실행하여 쉽게 디버깅할 수 있습니다. 이 방법을 사용하면 모델 구현을 대화형 방식으로 반복적으로 테스트할 수 있어 자체 모델을 개발할 때 유용합니다. Neptune ML 프로덕션 훈련 환경에서 모델을 훈련하는 동안에는 이 파라미터가 생략됩니다.