⑵ 익스포트 플러그인

Export(익스포트) 플러그인이 Synapse의 라벨링 결과를 외부 포맷으로 변환하고 스토리지에 저장하는 흐름을 구현합니다.

진행 순서

1. 익스포트 플러그인의 역할을 확인합니다.
2. 익스포트 산출 스펙을 확인합니다.
3. 기본 익스포트 플러그인 구조를 구현합니다.
4. 항목별 오류 처리 규칙을 적용합니다.
5. 산출물 저장 위치와 원본 파일 URL 처리 방식을 확인합니다.

1. 익스포트 플러그인 역할 확인

Export(익스포트) 플러그인은 대상 데이터와 필터 조건을 받아 결과 파일을 생성합니다.

데이터 조회, 항목 순회, 원본 복사, 진행률 보고는 SDK가 처리합니다. 개발자는 라벨 데이터를 원하는 형식으로 변환하고, 필요한 파일을 저장하는 로직에 집중하면 됩니다.

2. 산출 스펙 확인하기

익스포트는 대상과 필터를 입력으로 받아 결과를 스토리지에 저장합니다.

표준 출력 구조는 다음과 같습니다.

<출력 경로>/
├── labels/                # 변환된 라벨 파일 (형식은 플러그인이 결정)
├── origin_files/          # 원본 파일 (원본 포함 옵션을 켠 경우)
└── error_file_list.json   # 실패 항목 목록 (실패가 있을 때)

완료 후 내보낸 건수(exported_count)가 표시됩니다. 일부 항목이 실패해도 작업 전체는 계속 진행됩니다.

3. 기본 익스포트 플러그인 구현

익스포트 플러그인은 Exporter와 Action 두 클래스로 구성됩니다.

개발자가 주로 구현하는 메서드는 다음과 같습니다.

from synapse_sdk.plugins.actions.export import BaseExporter, DefaultExportAction

class MyExporter(BaseExporter):
    def convert_data(self, data):
        # 핵심: 항목 1건(dict)을 우리 포맷으로 변환해 반환
        return {'id': data['id'], 'objects': convert(data['data'])}

    def save_as_json(self, result, base_path, error_file_list):
        # 산출 파일 쓰기 — 확장자·내용 자유 (.json / .txt / .xml …)
        ...

class MyExportAction(DefaultExportAction):
    action_name = 'export'

    def execute(self):
        raise NotImplementedError   # 형식적 선언 — 실행은 SDK 골격이 담당

    @property
    def entrypoint(self):
        return MyExporter

4. 항목별 오류 처리 규칙 적용

변환·저장 로직은 try/except로 감싸고, 실패 항목은 오류 목록에 기록한 뒤 다음 항목으로 진행합니다.

사용자는 “999건 중 3건 실패”처럼 부분 실패 결과를 기대합니다. 일부 항목 때문에 전체 익스포트가 실패하지 않도록 구현해야 합니다.

5. 산출물 저장 위치 확인

익스포트 산출물은 표준 위치에 저장합니다.

6. 원본 파일 URL 처리 방식 구분

원본 파일 URL을 직접 다운로드한다면 두 형태를 모두 처리해야 합니다.

기본 제공되는 원본 저장 기능을 그대로 사용하면 이 처리를 직접 구현하지 않아도 됩니다.