⑶ 인공신경망 플러그인

Neural Net(모델) 플러그인이 Synapse에서 모델 학습, 배포, 추론, 테스트 액션을 실행하는 흐름을 구현합니다.

진행 순서

1. Neural Net(모델) 플러그인의 역할을 확인합니다.
2. 액션별 동작 요구사항을 확인합니다.
3. 추론 전용 플러그인 파일 구조를 확인합니다.
4. 추론 로직을 구현합니다.
5. 학습 로직을 구현합니다.
6. 모델 플러그인 구현 규칙을 확인합니다.

1. 모델 플러그인 역할 확인하기

Neural Net(모델) 플러그인은 학습, 배포, 추론, 테스트 액션을 제공합니다.

플러그인 목적에 따라 일부 액션만 구현할 수도 있습니다. 예를 들어 추론 전용 플러그인은 배포와 추론 액션만 구현하고, 학습을 지원하는 플러그인은 학습 액션을 추가로 구현합니다.

2. 동작 요구사항 확인하기

모델 플러그인은 목적에 따라 train, deployment, inference, test 액션을 구현합니다.

학습 중에는 에폭별 손실(loss)과 정확도(accuracy)를 차트로 보고할 수 있습니다. HPO를 지원하는 경우 검색 범위와 시도 횟수를 기준으로 여러 trial을 자동 실행합니다.

배포 직후 첫 추론 요청은 모델 로딩 때문에 오래 걸릴 수 있습니다. 자원이 부족하면 배포가 거부될 수 있습니다.

3. 추론전용 플러그인 구조 확인

추론 전용 플러그인은 기본적으로 세 파일로 구성됩니다.

plugin/
├── test.py         # 환경 점검
├── deployment.py   # 모델을 추론 API로 올리는 액션
└── inference.py    # 실제 추론 로직 (+ train.py — 학습 지원 시)

4. 추론 로직 구현하기

추론 구현에서는 모델 로딩과 요청 처리를 구현합니다. 추론은 Serve 방식으로 실행됩니다.

from fastapi import FastAPI
from synapse_sdk.plugins import BaseServeDeployment

app = FastAPI()

class MyServeDeployment(BaseServeDeployment):
    action_name = 'inference'
    app = app

    async def _get_model(self, model_info):
        # model_info['path'] = 플랫폼이 내려준 모델 파일의 로컬 경로
        return load_my_model(model_info['path'])

    @app.post('/')
    async def infer(self, data: MyInput):
        model = await self.get_model()      # 로딩·캐시는 SDK 담당
        return predict_and_format(model, data)

구현 포인트

deployment 액션은 골격 코드가 이미 완성형이므로, 올릴 Serve 클래스가 올바르게 지정되어 있는지 확인하면 됩니다.

5. 학습 로직 구현하기

학습 액션은 execute(data_path, checkpoint)를 구현합니다.

data_path에는 학습 데이터셋이 준비되어 있습니다. target_format을 지정하면 데이터셋 형식이 자동 변환됩니다.

학습 루프에서 지표를 보고하면 사용자 화면에 차트로 표시됩니다.

class TrainAction(BaseTrainAction[TrainParams]):
    action_name = 'train'
    target_format = 'imagefolder'   # 'yolo' / 'coco' / 'imagefolder' 중 선택 → 자동 변환

    def execute(self, data_path, checkpoint):
        for epoch in range(params.epochs):
            ...
            self.report_metrics({'loss': loss}, epoch=epoch, category='train')
            self.report_metrics({'accuracy': acc}, epoch=epoch, category='validation')
            self.set_progress(epoch, params.epochs, category='train')
        return TrainResult(weights_path=str(output_dir))   # 이 디렉토리가 모델로 등록됨

학습 중 보고할 수 있는 값

6. 모델 플러그인 구현규칙 확인

모델 플러그인을 구현할 때는 모델 로딩 경로, 학습 결과 디렉토리, GPU 라이브러리 버전을 명확히 관리해야 합니다.

모델 가중치는 플랫폼이 전달한 경로에서만 로드하기

모델 가중치는 model_info['path']에서 로드해야 합니다.

코드에서 인터넷의 사전학습 가중치를 내려받게 하면 외부망이 막힌 환경에서 실패할 수 있습니다. 예를 들어 pretrained=True 또는 Hugging Face 자동 다운로드에 의존하지 마세요.

필요한 가중치는 모델 아티팩트에 포함시켜야 합니다.

학습 결과 디렉토리에는 필요한 것만 담기

학습 결과 디렉토리에는 가중치, 클래스 목록, 메타데이터처럼 실행에 필요한 파일만 포함합니다.

로그나 중간 체크포인트까지 함께 담으면 업로드가 실패할 수 있습니다.

GPU 라이브러리는 정확한 버전으로 명시하기

GPU가 필요한 라이브러리(torch 등)는 requirements.txt에 정확한 버전으로 명시합니다.

실행 환경과 맞지 않는 버전을 사용하면 배포 또는 추론 단계에서 실패할 수 있습니다.