본문으로 건너뛰기
버전: docs v25.02

GCR Parameter

Updated 2024.05.17

experimental_plan.yaml 설명​

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

experimental_plan.yaml 구조​

experimental_plan.yaml에는 ALO를 구동하는데 필요한 다양한 setting값이 작성되어 있습니다. 이 setting값 중 '데이터 경로'와 'user arguments'부분을 수정하면 AI contents를 바로 사용할 수 있습니다.

데이터 경로 입력 (external_path)​

  • external_path의 parameter는 불러올 파일의 경로나 저장할 파일의 경로를 지정할 때 사용합니다. save_train_artifacts_path와 save_inference_artifacts_path는 입력하지 않으면 default 경로인 train_artifacts, inference_artifacts 폴더에 모델링 산출물이 저장됩니다.
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:
파라미터명DEFAULT설명 및 옵션
load_train_data_path./sample_data/train/학습 데이터가 위치한 폴더 경로를 입력합니다. (csv 파일 명 입력 X) 입력한 경로 하위에 있는 모든 csv를 가져와 concat 합니다.
load_inference_data_path./sample_data/test/추론 데이터가 위치한 폴더 경로를 입력합니다. (csv 파일 명 입력 X) 입력한 경로 하위에 있는 모든 csv를 가져와 concat 합니다.
*입력한 경로 하위 폴더 안에 있는 파일도 모두 가져와 합칩니다.
*합칠 파일의 모든 컬럼 명은 동일해야 합니다.

사용자 파라미터 (user_parameters)​

  • user_parameters 아래 step은 asset 명을 의미합니다. 아래 step: input은 input asset단계임을 의미합니다.
  • args는 input asset (step: input)의 user arguments를 의미합니다. user arguments는 각 asset마다 제공하는 데이터 분석 관련 설정 파라미터입니다. 이에 대한 설명은 아래에 User arguments 설명을 확인해주세요.
user_parameters:
	- train_pipeline:
		- step: input
		  args:
			- file_type
			...
		  ui_args:
			...

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 값이 YAML 파일에 세팅 되어있습니다.
  • experimental_plan.yaml의 필수 arguments중 데이터 관련 arguments는 유저가 필수로 값을 설정해주어야 합니다. (ex. x_columns, y_column)

Custom arguments​

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

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

User arguments 요약​

아래는 GCR의 user arguments 요약입니다. 'Argument 명'을 누르면 해당 arguments의 상세 설명으로 이동할 수 있습니다.

Default​

  • 'Default' 항목은 해당 user argument의 기본 값 입니다.
  • 기본 값이 없는 경우 '-' 로 표기하였습니다.
  • 기본 값이 비워 두는 것인 경우 ' '로 표기하였습니다.
  • Default에 로직이 있는 경우에는 '설명 참고'로 표기하였습니다. 'Argument 명'을 눌러 상세 설명을 확인해 주세요.

ui_args​

  • 아래 표의 'ui_args'는 AI conductor의 UI에서 argument 값을 변경할 수 있는 ui_args기능 지원 여부를 나타냅니다.
  • O: experimental_plan.yaml의 ui_args밑에 해당 argument 명을 기입하면 AI Conductor UI에서 arguments 값을 변경할 수 있습니다.
  • X: ui_args 기능을 지원하지 않습니다.
  • ui_args에 대한 자세한 설명은 다음 가이드를 확인해 주세요. Write UI Parameter

사용자 설정 필수 여부​

  • 아래 표의 '사용자 설정 필수 여부'는 AI Contents를 동작시키기 위해 사용자가 반드시 확인하고 변경해야 할 user arguments 입니다.
  • O: 일반적으로 과제, 데이터 관련 정보를 입력하는 arguments로 사용자가 모델링 전에 확인해야 합니다.
  • X: 사용자가 값을 변경하지 않으면 default 값으로 모델링이 진행됩니다.  
Asset명Argument typeArgument 명Default설명사용자 설정 필수 여부ui_args
Input필수file_typecsvinput data의 파일 확장자를 입력합니다.XO
Input필수encodingutf-8input data의 encoding type을 입력합니다.XO
Readiness필수x_columns' '학습 대상 x 컬럼 명을 입력합니다. 비워 두면 y_column 외 모든 컬럼들을 사용합니다.XO
Readiness필수drop_columns' 'x 컬럼에서 제외할 컬럼 명을 입력합니다.XO
Readiness필수y_column  -y 컬럼 명을 입력합니다.OO
Graph필수dimension32graph embeddings 차원 수를 입력합니다.XO
Graph필수num_epochs10graph embeddings 알고리즘의 학습 횟수를 입력합니다.XO
Graph필수num_partitions1입력 데이터를 몇 개로 나누어 embedding할 지를 입력합니다.XO
Graph필수use_gpuFalseGPU가 가용한 환경에서 graph embedding 시 GPU 사용 여부를 입력합니다.XX
GraphCustomworkers1graph embedding 시 병렬 수행할 process 수를 입력합니다.XX
GraphCustomcustom_connection_lhs' '도메인 지식에 의거해 연결할 두 x 컬럼들 중 좌측 컬럼들을 입력합니다.XX
GraphCustomcustom_connection_rhs' '도메인 지식에 의거해 연결할 두 x 컬럼들 중 우측 컬럼들을 입력합니다.XX
GraphCustomcomparatordotgraph embedding 시 두 embeddings의 유사도를 비교할 함수를 입력합니다.XX
GraphCustomloss_fnsoftmaxgraph embedding 시의 학습 목적함수를 입력합니다.XX
GraphCustomlr0.01graph embedding 시의 학습율을 입력합니다.XX
GraphCustombatch_size1000graph embedding 시의 batch size를 입력합니다.XX
Train필수taskclassification추론의 종류를 결정합니다.XO
Train필수eval_metricf1_scoreHPO 시 best 모델을 선택하기 위한 평가 metric을 결정합니다.XO
Train필수num_hpo20HPO 시 trial의 횟수를 입력합니다.XO
Inference필수global_xaiFalse추론 시 global XAI 수행 여부를 결정합니다.XO
Inference필수local_xaiFalse추론 시 local XAI 수행 여부를 결정합니다.XO

User arguments 상세 설명​

Input asset​

file_type​

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

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

encoding​

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

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

Readiness asset​

x_columns​

Dataframe에 있는 학습 대상 x 컬럼 명을 list 형태로 입력합니다. 비워 두면 y_column을 제외한 모든 컬럼들을 x 컬럼으로 사용합니다.  

  • Argument type: 필수
  • 입력 type
    • list
  • 입력 가능한 값
    • ** 비워 둠 (default)** 또는 컬럼 명 list
  • 사용법
    • x_columns: [col1, col2]
  • ui_args: O

drop_columns​

X 컬럼들 가운데 제외할 컬럼 명을 list 형태로 입력합니다. 비워 두면 제외할 컬럼이 없음을 의미합니다.

  • Argument type: 필수
  • 입력 type
    • list
  • 입력 가능한 값
    • ** 비워 둠 (default)** 또는 컬럼 명 list
  • 사용법
    • drop_columns: [col1, col2]
  • ui_args: O

y_column​

Dataframe에 있는 y 컬럼 (label 컬럼) 명 1개를 입력합니다. 사용자가 입력 데이터에 맞게 반드시 입력해야 합니다.

  • Argument type: 필수
  • 입력 type
    • string
  • 입력 가능한 값
    • 컬럼 명
  • 사용법
    • y_column: target
  • ui_args: O

Graph asset​

dimension​

입력 데이터의 각 컬럼이 몇 차원의 vector로 graph embedding될 지 결정합니다. dimension이 높을 수록 vector들 간 구분력이 높아져 모델 정확도가 높아지지만 더 많은 메모리와 더 긴 임베딩 수행 시간이 필요합니다.

  • Argument type: 필수
  • 입력 type
    • int
  • 입력 가능한 값
    • 4, 8, 16, 32 (default), 64, 128, 256, 512, 1024
  • 사용법
    • dimension: 32
  • ui_args: O

num_epochs​

Graph embedding 시 몇 번의 반복적 시도를 할 것인지 결정합니다. 일반적으로 10회 정도에서 loss값이 saturated됩니다.

  • Argument type: 필수
  • 입력 type
    • int
  • 입력 가능한 값
    • 1~100 (10 (default))
  • 사용법
    • num_epochs: 10
  • ui_args: O

num_partitions​

GCR은 전체 입력 데이터를 여러 조각으로 나누어 graph embedding을 실시함으로써 peak memory를 줄여 메모리가 제한된 환경에서도 동작이 가능합니다. 이 때, 전체 입력 데이터를 몇 개의 조각으로 나누어 embedding할 지를 결정하는 argument입니다. num_partitions 수가 클수록 더 작은 peak memory가 요구되지만 전체 입력 데이터를 embedding 완료하는 데 걸리는 시간은 길어집니다.

  • Argument type: 필수
  • 입력 type
    • int
  • 입력 가능한 값
    • 1 (default), 2, 4, 8, 16, 32, 64, 128, 256, 512
  • 사용법
    • num_partitions: 1
  • ui_args: O

use_gpu​

만일 GPU 사용이 가능한 환경이라면 use_gpu를 True로 설정함으로써 graph embedding에 GPU를 사용할 수 있습니다.

  • Argument type: 필수
  • 입력 type
    • boolean
  • 입력 가능한 값
    • True, False (default)
  • 사용법
    • use_gpu: False
  • ui_args: X

workers​

Graph embedding 작업을 병렬 수행할 process의 수를 지정합니다.

  • Argument type: Custom
  • 입력 type
    • int
  • 입력 가능한 값
    • 0~inf, 1 (default)
  • 사용법
    • workers: 1
  • ui_args: X

custom_connection_lhs​

GCR 등 graph-powered machine learning 모델은 graph representation learning (즉, graph embedding)을 통해 데이터에 숨겨진 유용한 정보를 추출함으로써 모델 정확도를 높일 수 있습니다. 이 때, 유용한 정보를 얼마나 잘 추출해 낼 수 있는지는 데이터 특성에 적합한 graph 형태 즉, topology에 의해 큰 영향을 받게 됩니다. Topology는 각 데이터 포인트들 간의 관계 즉, table 형태의 입력 데이터에서 각 컬럼 간의 관계를 규정하는 형태로 작성됩니다. GCR은 각 샘플들의 인덱스를 중심 노드로 삼고 여기에 각 컬럼 노드들이 엣지를 통해 관련되어 있는 형태인 방사형 그래프 topology를 default로 제공합니다. 하지만, 만일 사용자가 입력 데이터에 대한 도메인 지식을 갖추고 있어서 컬럼들 간의 관계를 추가적으로 정의함으로써 더 효과적인 정보 추출이 가능한 경우를 위해, custom_connection argument를 제공합니다. 만일 컬럼 X1과 X2 그리고 X3와 X4를 추가로 연결하는 것이 더 효과적이라 판단된다면 custom_connection_lhs와 custom_connection_rhs argument를 각각 [X1, X2], [X3, X4]와 같이 지정함으로써 topology를 update할 수 있습니다. 단, 이 때 X2와 X4 등 우측 노드에 해당하는 컬럼들의 unique 값의 수는 num_partitions보다 같거나 커야 하며, 그렇지 않으면 graph embedding 시 에러가 발생함에 주의해야 합니다. 따라서, 이 방법은 num_partitions가 1인 경우에 적용하는 것이 안전합니다.

  • Argument type: Custom
  • 입력 type
    • list
  • 입력 가능한 값
    • [] (default) 또는 [X1, X2, ...]
    • 여기서, X1, X2는 추가적으로 연결하고자 하는 컬럼쌍들 중 좌측 컬럼 명들
  • 사용법
    • custom_connection_lhs: [X1, X2, ...]
  • ui_args: X

custom_connection_rhs​

  • Argument type: Custom
  • 입력 type
    • list
  • 입력 가능한 값
    • [] (default) 또는 [X3, X4, ...]
    • 여기서, X3, X4는 추가적으로 연결하고자 하는 컬럼쌍들 중 우측 컬럼 명들
  • 사용법
    • custom_connection_rhs: [X3, X4, ...]
  • ui_args: X

comparator​

GCR의 graph embedding은 topology가 유사한 노드들은 vector space 상에서 더 가깝게 유사하지 않은 노드들은 더 멀게 조정하는 작업을 epoch 수 만큼 반복하는 과정입니다. 이 때, topology의 유사성을 따지는 함수가 comparator입니다. Comparator로는 dot, cos, l2, squared_l2가 지원되며, default는 dot입니다. 어느 comparator를 선택할지는 풀고자 하는 문제의 성격에 따라 결정됩니다.

  • Argument type: Custom
  • 입력 type
    • string
  • 입력 가능한 값
    • dot (default), cos, l2, squared_l2
  • 사용법
    • comparator: dot
  • ui_args: X

loss_fn​

GCR의 graph embedding은 내부적으로 negative sampling 기법을 사용합니다. 즉, 주어진 입력 데이터는 positive sample로 삼아 comparator를 통한 유사도가 높아지도록 학습하는 반면, 일부러 존재할 가능성이 낮은 가상의 데이터 (negative sample)들을 생성해 내어 이들은 유사도가 낮아지도록 학습합니다. 이 때, graph 전체에 걸쳐 positive sample들에 대한 유사도와 negative sample들에 대한 유사도의 차이를 판단하는 함수가 loss_fn입니다. 적용 가능한 loss_fn에는 ranking, logistic, softmax가 있으며, 어느 loss_fn이 적합할 지는 풀고자 하는 문제의 성격에 따라 결정됩니다.

  • Argument type: Custom
  • 입력 type
    • string
  • 입력 가능한 값
    • ranking, logistic, softmax (default)
  • 사용법
    • loss_fn: softmax
  • ui_args: X

lr​

GCR의 graph embedding 시 적용되는 학습율입니다. GCR은 pytorch에 기반한 deep learning을 통해 graph embedding을 실시하므로, 일반적인 deep learning 시 적용하는 학습율을 생각하면 되겠습니다.

  • Argument type: Custom
  • 입력 type
    • float
  • 입력 가능한 값
    • 0보다 크고 1보다 작은 실수. 0.01 (default)
  • 사용법
    • lr: 0.01
  • ui_args: X

batch_size​

GCR의 graph embedding 시 적용되는 샘플들의 batch size 입니다. GCR은 pytorch에 기반한 deep learning을 통해 graph embedding을 실시하므로, 일반적인 deep learning 시 적용하는 batch size를 생각하면 되겠습니다.

  • Argument type: Custom
  • 입력 type
    • int
  • 입력 가능한 값
    • 0보다 큰 정수. 1000 (default)
  • 사용법
    • batch_size: 1000
  • ui_args: X

Train asset​

task​

GCR의 목적이 classification인지 regression인지 지정합니다.

  • Argument type: 필수
  • 입력 type
    • string
  • 입력 가능한 값
    • classification (default), regression
  • 사용법
    • loss_fn: softmax
  • ui_args: O

eval_metric​

HPO 시 best 모델을 선정하기 위한 평가 metric을 선택합니다. task argument가 classification일 경우 f1_score, accuracy, precision, recall 중 선택 가능하고, regression인 경우에는 rmse만 선택 가능합니다.

  • Argument type: 필수
  • 입력 type
    • string
  • 입력 가능한 값
    • task가 classification인 경우: f1_score (default), accuracy, precision, recall
    • task가 regression인 경우: rmse
  • 사용법
    • eval_metric: f1_score
  • ui_args: O

num_hpo​

HPO 시 몇 번의 trial을 수행할 지 지정합니다.

  • Argument type: 필수
  • 입력 type
    • int
  • 입력 가능한 값
    • 1 이상의 정수. 20 (default)
  • 사용법
    • num_hpo: 20
  • ui_args: O

Inference asset​

global_xai​

Train set에 대한 global XAI 결과 report file을 생성할 지 지정합니다. 생성한다면 ALO의 main.py가 존재하는 working directory 아래의 train_artifacts/models/train/global_feature_importance.csv file이 생성됩니다.

  • Argument type: 필수
  • 입력 type
    • boolean
  • 입력 가능한 값
    • True, False (default)
  • 사용법
    • global_xai: False
  • ui_args: O

local_xai​

Inference set에 대한 local XAI를 수행할 지 지정합니다. 수행한다면, inference set의 모든 샘플에 대해 LIME을 통한 XAI 결과가 생성되어 입력 데이터에 새로운 컬럼으로 추가됩니다. 이 때, 추가되는 컬럼들의 형태는 아래와 같습니다. 이 기능은 현재 task가 classification인 경우에만 제공됩니다.

아래 예는, X1~X9의 컬럼들을 가지는 추론 데이터에 대해 binary classification을 수행하는 경우입니다.

각 샘플의 인덱스classificationResultlabel의 category 별 score들top 5 reasons (컬럼 명과 현재 샘플의 해당 컬럼 값)
000.77, 0.23X1=0.1, X3=0.7, X4='A', X5='S', X9=0.02
100.65, 0.35X3=0.6, X2=0.2, X1=0.7, X4='B', X8=0.01
210.83, 0.17X4='B', X5='P', X9=0.07, X7='S', X1=0.3
  • Argument type: 필수
  • 입력 type
    • boolean
  • 입력 가능한 값
    • True, False (default)
  • 사용법
    • local_xai: False
  • ui_args: O