버전: docs v25.02

TAD Parameter

Updated 2024.07.06

experimental_plan.yaml 설명

AI Contents를 가지고 있는 데이터에 적용하려면 데이터에 대한 정보와 사용할 Contents 기능들을 experimental_plan.yaml 파일에 기입해야 합니다.
AI Contents를 solution 폴더에 설치하면 solution 폴더 아래에 contents 마다 기본으로 작성되어있는 experimental_plan.yaml 파일을 확인할 수 있습니다.
이 YAML 파일에 데이터 정보를 입력하고 asset마다 제공하는 user arugments를 수정/추가하여 ALO를 실행하면, 원하는 세팅으로 데이터 분석 모델을 생성할 수 있습니다.

1. 파일 개요

experimental_plan.yaml은 TAD의 실험 계획을 정의하는 설정 파일로, 데이터의 경로와 다양한 파이프라인 단계에서 사용할 파라미터들을 포함합니다. 이 파일을 통해 데이터 전처리, 모델 학습 및 배포 과정을 자동화할 수 있습니다.

2. 구조 설명

experimental_plan.yaml은 다음과 같은 주요 섹션으로 구성됩니다:

외부 데이터 경로 설정 (external_path)
사용자 파라미터 설정 (user_parameters)

3. 외부 데이터 경로 설정 (external_path)

데이터를 불러오거나 결과를 저장하는 경로를 지정합니다.

load_train_data_path: 학습 데이터를 불러올 경로를 지정합니다.
load_inference_data_path: 추론 데이터를 불러올 경로를 지정합니다.
save_train_artifacts_path: 학습 결과를 저장할 경로를 지정합니다.
save_inference_artifacts_path: 추론 결과를 저장할 경로를 지정합니다.
load_model_path: 기존 모델을 불러올 경로를 지정합니다.

external_path:
  - load_train_data_path: ./solution/sample_data/train/
  - load_inference_data_path: ./solution/sample_data/test/
  - save_train_artifacts_path:
  - save_inference_artifacts_path:
  - load_model_path:

파라미터명	DEFAULT	설명 및 옵션
load_train_data_path	./sample_data/train/	학습 데이터를 불러올 경로를 지정합니다. (csv 파일 명 입력 X) 입력한 경로 하위에 있는 모든 csv를 가져와 concat 합니다.
load_inference_data_path	./sample_data/test/	추론 데이터를 불러올 경로를 지정합니다. (csv 파일 명 입력 X) 입력한 경로 하위에 있는 모든 csv를 가져와 concat 합니다.
save_train_artifacts_path	-	학습 결과를 저장할 경로를 지정합니다.
save_inference_artifacts_path	-	추론 결과를 저장할 경로를 지정합니다.
load_model_path	-	기존 모델을 불러올 경로를 지정합니다.

입력한 경로 하위 폴더 안에 있는 파일도 모두 가져와 합칩니다.

합칠 파일의 모든 컬럼 명은 동일해야 합니다.

4. 사용자 파라미터 설정 (user_parameters)

Pipeline & Asset

user_parameters는 각 파이프라인 단계에서 사용할 설정 파라미터들을 정의합니다. 각 파이프라인은 train_pipeline과 inference_pipeline으로 나뉘며, 각 파이프라인은 여러 개의 단계(Asset)로 구성됩니다. 각 Asset은 특정 데이터 처리 작업을 수행하며, 해당 작업을 제어하는 다양한 파라미터를 가집니다.

Pipeline: 데이터 처리 흐름의 상위 개념으로, 여러 단계(Asset)로 구성됩니다.
Asset: 파이프라인 내에서 개별 작업을 수행하는 단위입니다. 예를 들어, 데이터 전처리, 모델 학습 등이 있습니다.
args: 각 Asset의 동작을 설정하는 파라미터입니다.
ui_args: AI Conductor UI에서 사용자가 변경할 수 있는 파라미터를 정의합니다.

User arguments 설명

User arguments란?

User arguments는 각 asset 별 동작 설정을 위한 파라미터로 experimental_plan.yaml의 각 asset step의 args밑에 기입해 사용합니다. AI Contents의 pipeline을 구성하는 asset마다 사용자가 다양한 기능을 데이터에 적용할 수 있도록 user arguments를 제공하고 있습니다. 사용자는 아래 가이드를 참고해서 user arguments를 변경, 추가하여 데이터에 맞는 모델링을 할 수 있습니다. User arguments는 experimental_plan.yaml에 미리 작성되어있는 "필수 arguments"와 사용자가 가이드를 보고 추가하는 "Custom arguments"로 구분됩니다.

필수 arguments

필수 arguments는 experimental_plan.yaml에 바로 보여지는 기본 arguments 입니다. 대부분의 필수 arguments는 default 값이 내장되어 있습니다. default 값이 있는 arguments의 경우에는 유저가 별도로 값을 설정하지 않아도 기본 값으로 동작합니다.
experimental_plan.yaml의 필수 arguments중 데이터 관련 arguments는 유저가 필수로 값을 설정해주어야 합니다. (ex. x_columns, y_column)

Custom arguments

Custom arguments는 experimental_plan.yaml에 적혀있지 않지만, asset에서 제공하는 기능으로 사용자가 experimental_plan.yaml에 추가하여 사용할 수 있습니다. 각 asset 별 'args'에 추가하여 사용합니다.

TAD의 pipeline은 Input - Readiness - Preprocess - Modeling(train/inference) asset 순으로 구성되어 있으며 각 asset의 기능에 맞추어 user arguments가 다르게 구성되어 있습니다. experimental_plan.yaml에 기입되어 있는 필수 user arguments를 먼저 사용해보시고, user arguments를 추가하여 데이터에 딱 맞는 TAD 모델을 만들어보세요!

4.1. Train Pipeline

학습 파이프라인에 필요한 설정을 정의합니다.

4.1.1. Input Asset

학습 데이터의 입력 경로와 관련된 설정을 정의합니다.

- step: input
  args:
    - file_type: csv
      encoding: utf-8
  ui_args: 

4.1.2. Readiness Asset

학습 데이터 컬럼에 대한 정의를 진행합니다.

- step: readiness
  args:
    - x_columns: [factor0, factor1, factor2, ..]
      y_column: ''
      groupkey_columns: ''
  ui_args: 
    - x_columns:
    - y_column:

4.1.3. Preprocess Asset

데이터 전처리 설정을 정의합니다.

- step: preprocess
  args:
    - handling_missing: fill_0
      handling_scaling_x: standard
      drop_duplicate_time: False
      handling_downsampling_interval: 0
      downsampling_method: median
      difference_interval: 0

  ui_args:
    - handling_missing
    - handling_scaling_x

4.1.3. Train Asset

모델 학습과 관련된 설정을 정의합니다.

- step: train
  args:
    - hpo_param: False
      contamination: ''
      models: 
        - knn
	- dbscan
        - ocsvm
        - lof
        - isf
      visualization: False
      
  ui_args:
    - hpo_param
    - contamination
    - models

4.2. Inference Pipeline

추론 파이프라인에 필요한 설정을 정의합니다.

4.2.1. Input Asset

추론 데이터의 입력 경로와 관련된 설정을 정의합니다.

- step: input
  args:
    - none:

4.2.2. Readiness Asset

추론 데이터의 입력 경로와 관련된 설정을 정의합니다.

- step: readiness
  args:
    - none:

4.2.3. Preprocess Asset

추론 데이터 전처리 설정을 정의합니다.

- step: preprocess
  args:
    - none:

4.2.4. Inference Asset

모델을 사용하여 추론을 수행하는 설정을 정의합니다.

- step: inference
  args:
    - none:

5. User Arguments 상세 설명

Input Asset

file_type

Input data의 파일 확장자를 입력합니다. 현재 AI Solution 개발은 csv 파일만 가능합니다.

Argument type: 필수
입력 type
- string
입력 가능한 값
- csv (default)
사용법
- file_type: csv
ui_args: X

encoding

Input data의 encoding type을 입력합니다. 현재 AI Solution 개발은 utf-8 인코딩만 가능합니다.

Argument type: 필수
입력 type
- string
입력 가능한 값
- utf-8 (default)
사용법
- encoding: utf-8
ui_args: X

Readiness Asset

x_columns

이상 탐지시 활용하려는 데이터가 담긴 컬럼들을 입력합니다. 복수의 컬럼을 지원합니다.

Argument type: 필수
입력 type
- list
입력 가능한 값
- 컬럼 명
사용법
- x_columns : [ x_col1, x_col2 ]
ui_args: O

y_column

이상 탐지를 진행하려는 데이터 각각이 어느 라벨에 속하는지에 대한 정보가 담긴 컬럼들을 입력합니다. TAD는 기본적으로 라벨을 필요로 하지 않으므로 라벨을 이용하여 결과를 얻고 싶은 경우에만 입력합니다. Unique 값은 3개 미만이어야 합니다.

Argument type: Custom
입력 type
- string
입력 가능한 값
- 컬럼 명
사용법
- y_column : y_col
ui_args: X

groupkey_columns

이상 탐지를 진행하려는 데이터를 그룹 별로 이상탐지를 하려는 경우 각 데이터가 어느 그룹에 속하는지 정보가 담긴 컬럼을 입력합니다. 만약 그룹별로 진행을 원치 않는 경우 공란으로 둡니다. 현재 하나의 그룹키 컬럼을 지원합니다.

Argument type: 필수
입력 type
- list
입력 가능한 값
- 컬럼 명
사용법
- groupkey_columns : [ groupkey_col_example ]
ui_args: X

Preprocess asset

handling_missing

이상 탐지를 하고자 하는 데이터에 missing이 존재하는 경우 이를 어떻게 처리할 지를 결정하게 됩니다.drop 인경우 해당 row를 제거합니다.most_frequent는 최빈값, mean은 평균값, median는 중앙값, interpolation은 이전값과 다음값의 interpolation 값으로 채워 넣습니다.

Argument type: Custom
입력 type
- string
입력 가능한 값
- drop (default)
- drop
- most_frequent
- mean
- median
- interpolation
사용법
- handling_missing : drop
ui_args: X

handling_scaling

이상 탐지를 하고자 하는 데이터를 어떤 방식으로 scaling 할 지를 결정하게 됩니다. standard인 경우 train 데이터의 mean과 std를 이용하여 평균0 분산 1로 scaling 하게 됩니다. minmax 인 경우 train 데이터의 min 값, max 값을 통해 값을 0~~1 사이로 조정하게 됩니다. maxabs인 경우 train 데이터의 절대값의 최댓값을 이용하여 0~~1 사이로 값을 조정하게 됩니다. robust인 경우 train 데이터의 median과 사분위 값을 이용하여 scaling 하게 됩니다. normalizer의 경우 데이터의 특성벡터의 길이가 1이 되도록 scaling 하게 됩니다. 아무것도 입력하지 않은 경우 별도의 scaling을 진행하지 않습니다.

Argument type: Custom
입력 type
- string
입력 가능한 값
- none (default)
- stadard
- minmax
- maxabs
- robust
- normalizer
사용법
- handling_scaling : minmax
ui_args: X

drop_duplicate_time

이상 탐지를 하고자 하는 데이터의 time 컬럼에 중복이 존재하는 경우 해당 중복 row들을 어떻게 처리할 지를 결정합니다.True인 경우 time column이 중복되는 row 중 하나만 남기고 제거합니다.

Argument type: Custom
입력 type
- string
입력 가능한 값
- True (default)
- True
- False
사용법
- drop_duplicate_time : True
ui_args: X

difference_interval

이상 탐지를 하고자 하는 데이터의 차분을 진행 여부를 결정하는 항목입니다. 차분을 이용해서 이전 값들의 차이와 현재 시점에서의 차이 값이 얼마나 변했는지를 토대로 이상 탐지를 진행하려고 할 때 사용합니다. 사용 시, 값은 0보다 큰 정수로 입력해야 합니다.

Argument type: Custom
입력 type
- int
입력 가능한 값
- 0 (default)
- 0 이상의 정수
사용법
- difference_interval : 1
ui_args: X

Train asset

hpo_param

hpo_param은 이상탐지 모델들의 hyper parameter tuning을 결정하는 항목입니다.

Argument type: Custom
입력 type
- string
입력 가능한 값
- False(default)
- True
- False
사용법
- hpo_param: True
ui_args: X

contamination

contamination은 이상치 비율 범위를 설정하도록 하는 항목입니다. 이 기능은 사용자가 이상치 비율을 알지 못하는 상황에서도 hpo과정에서 최적의 비율을 찾아 모델 성능을 극대화할 수 있도록 돕거나, 사용자가 알고있는 비율을 기입해서 model을 Setting 할 수 있습니다.

Argument type: Custom
입력 type
- float or list
입력 가능한 값
- ''(default)
- [사용자 판단에 따른 적절한 양의 정수 값, 사용자 판단에 따른 적절한 양의 정수 값]
- 사용자 판단에 따른 적절한 양의 정수 값
사용법
- contamination: [0.001, 0.1]
- contamination: 0.0001
ui_args: X

models

내장된 5종의 모델 중 사용할 모델을 선택하는 항목입니다. 선택 된 모델이 2개 이상일 경우 출력은 Ensemble 결과로 제공됩니다.

Argument type: Custom
입력 type
- string select
입력 가능한 값
- knn,ocsvm,lof,isf (default)
- knn, ocsvm, lof, isf, dbsacn
사용법
- models:
  - knn
  - ocsvm
  - lof
  - isf
  - dbscan
ui_args: X

visualization

visualization은 이상탐지 모델들의 탐지 결과 시각화여부를 결정하는 항목입니다.

Argument type: Custom
입력 type
- string
입력 가능한 값
- False(default)
- True
- False
사용법
- hpo_param: True
ui_args: X

Inference Asset

none: 추론에 대한 별도의 설정을 지정하지 않습니다.

User Arguments 요약

여기 User Arguments 상세 설명에 언급된 항목만 포함한 마크다운 테이블입니다:

Asset명	Argument type	Argument 명	Default	설명	사용자 설정 필수 여부	ui_args
Input	필수	file_type	csv	input data의 파일 확장자를 입력합니다.	X	O
Input	필수	encoding	utf-8	input data의 encoding type을 입력합니다.	X	O
Readiness	필수	x_columns	-	학습 대상 x 컬럼 명을 입력합니다.	O	O
Readiness	필수	y_column	-	y 컬럼 명을 입력합니다.	O	O
Readiness	Custom	groupkey_columns	-	입력한 컬럼의 value 값을 기준으로 dataframe을 grouping합니다.	X	O
Readiness	Custom	drop_columns	-	제외할 컬럼을 지정합니다.	X	X
Readiness	Custom	time_column	-	시간 컬럼을 지정합니다.	X	X
Readiness	Custom	concat_dataframes	True	데이터프레임을 병합할지 여부를 지정합니다.	X	X
Preprocess	Custom	handling_missing	설명 참고	컬럼에 적용할 결측치 처리 방식을 지정합니다.	X	X
Preprocess	Custom	handling_scaling_x	standard	특성 스케일링 방법을 지정합니다.	X	X
Preprocess	Custom	drop_duplicate_time	False	중복 시간을 제거할지 여부를 지정합니다.	X	X
Preprocess	Custom	difference_interval	0	차분 진행 여부를 지정합니다.	X	X
Train	필수	hpo_param	False	하이퍼파라미터 최적화를 수행할지 여부를 지정합니다.	X	O
Train	필수	models	knn, ocsvm, lof, isf, dbscan 중 선택	사용할 모델을 지정합니다. ("all"을 입력하면 모든 모델 선택)	X	O
Train	필수	visualization	False	시각화를 수행할지 여부를 지정합니다.	X	O

TAD Version: 1.0.0

experimental_plan.yaml 설명​

1. 파일 개요​

2. 구조 설명​

3. 외부 데이터 경로 설정 (external_path)​

4. 사용자 파라미터 설정 (user_parameters)​

Pipeline & Asset​

User arguments 설명​

User arguments란?​

필수 arguments​

Custom arguments​

4.1. Train Pipeline​

4.1.1. Input Asset​

4.1.2. Readiness Asset​

4.1.3. Preprocess Asset​

4.1.3. Train Asset​

4.2. Inference Pipeline​

4.2.1. Input Asset​

4.2.2. Readiness Asset​

4.2.3. Preprocess Asset​

4.2.4. Inference Asset​

5. User Arguments 상세 설명​

Input Asset​

file_type​

encoding​

Readiness Asset​

x_columns​

y_column​

groupkey_columns​

Preprocess asset​

handling_missing​

handling_scaling​

drop_duplicate_time​

difference_interval​

Train asset​

hpo_param​

contamination​

models​

visualization​

Inference Asset​

User Arguments 요약​