마이그레이션 가이드 (v1 → v2)

이 가이드는 synapse-sdk v1과 v2 사이의 변경 사항을 다루며, 코드 업데이트가 필요한 주요 변경 사항(Breaking Changes)과 새로운 기능을 포함합니다.

사전 요구 사항

이 가이드는 synapse-sdk v1에 대한 이해를 전제로 합니다. v2 설정은 설치 가이드를 참조하세요.

주요 변경 사항 (Breaking Changes)

v1에서 마이그레이션할 때 코드 업데이트가 필요한 변경 사항:

v1	v2	마이그레이션 방법
`get_action_class(category, action)`	`get_action_method(config, action)`	category 문자열 대신 config dict 전달
`action_class.method`	`get_action_method(config, action)`	메서드를 클래스 속성이 아닌 config에서 읽음
`@register_action` 데코레이터	제거됨	`config.yaml`에 액션 정의 또는 `PluginDiscovery.from_module()` 사용
`_REGISTERED_ACTIONS` 전역 변수	제거됨	액션 검사에 `PluginDiscovery` 사용
`get_storage('s3://...')` URL 문자열	Dict 전용 설정	`get_storage({'provider': 's3', 'configuration': {...}})` 사용
`STORAGE_PROVIDERS` dict	`get_registered_providers()`	dict 대신 프로바이더 이름 목록 반환
`convert_v1_to_v2()`	아직 미제공	임시로 로컬 `DMV1ToV2Converter` 사용
`AgentClient(long_poll_handler=...)`	제거됨	롱 폴 핸들러 더 이상 미지원
`run_debug_plugin_release(data=...)`	`run_debug_plugin_release(action, params, ...)`	data dict 대신 명시적 키워드 인자 사용
`run_plugin_release(code, data=...)`	`run_plugin_release(lookup, action, params, ...)`	명시적 키워드 인자 사용; `data=`는 하위 호환성을 위해 지원
`ClientError.status`	`ClientError.status_code`	속성명 변경
`ClientError.reason`	`ClientError.detail`	속성명 변경
`RayJobExecutor(dashboard_address=...)`	제거됨	대시보드 URL을 executor에 전달하지 않음
`from ... import FileSystemStorage`	`from ... import LocalStorage`	클래스명 변경
`from ... import GCPStorage`	`from ... import GCSStorage`	클래스명 변경
`BaseStorage` ABC 상속	`StorageProtocol` 구현	상속 대신 구조적 타이핑(덕 타이핑) 사용

비호환 변경 사항 없음 (Non-Breaking Changes)

하위 호환성이 유지되는 변경 사항 - 기존 코드가 계속 동작합니다:

기능	비고
프로바이더 별칭 `file_system`	여전히 동작, `LocalStorage`로 매핑
프로바이더 별칭 `gcp`, `gs`	여전히 동작, `GCSStorage`로 매핑
`get_plugin_actions()`	동일한 API
`read_requirements()`	동일한 API
`get_pathlib()`	동일한 API
`get_path_file_count()`	동일한 API
`get_path_total_size()`	동일한 API

플러그인 유틸리티 (Plugin Utils)

이전 (synapse-sdk v1)

from synapse_sdk.plugins.utils import get_action_class, get_plugin_actions, read_requirements

# 액션 클래스를 로드하여 실행 메서드 조회
action_method = get_action_class(config['category'], action).method

이후 (synapse-sdk v2)

from synapse_sdk.plugins.utils import get_action_method, get_plugin_actions, read_requirements

# config에서 직접 실행 메서드 조회 (클래스 로딩 불필요)
action_method = get_action_method(config, action)

플러그인 타입 (Plugin Types)

from synapse_sdk.plugins.enums import PluginCategory
from synapse_sdk.plugins.base import RunMethod

이후

from synapse_sdk.plugins.enums import PluginCategory, RunMethod

Pre-Annotation 액션

이전 (synapse-sdk v1)

from synapse_sdk.plugins.categories.pre_annotation.actions.to_task import ToTaskAction

class AnnotationToTask:
    def convert_data_from_file(...):
        ...

    def convert_data_from_inference(...):
        ...

action = ToTaskAction(run=run_instance, params=params)
result = action.start()

이후 (synapse-sdk v2)

from synapse_sdk.plugins.actions.to_task import ToTaskAction

class ToTask(ToTaskAction):
    action_name = 'to_task'

    def convert_data_from_file(...):
        ...

    def convert_data_from_inference(...):
        ...

config.yaml에서 to_task 액션 이름을 사용하고 엔트리포인트를 ToTask 서브클래스로 지정하세요.

설계 참고: v1은 to_task에 전략/파사드 오케스트레이션을 사용했습니다. v2는 검증, 태스크 반복, 추론을 위한 헬퍼 메서드가 있는 단일 액션 클래스에 워크플로우를 유지하여 디버깅과 커스터마이징을 더 간단하게 합니다. 다단계 오케스트레이션이 필요하면 스텝 프레임워크(synapse_sdk.plugins.steps)를 사용하세요.

플러그인 디스커버리 (Plugin Discovery)

새 기능 - config 파일이나 Python 모듈에서 액션을 탐색합니다:

from synapse_sdk.plugins.discovery import PluginDiscovery

# config.yaml에서
discovery = PluginDiscovery.from_path('/path/to/plugin')
discovery.list_actions()  # ['train', 'inference', 'export']

# Python 모듈에서 (자동으로 @action 데코레이터와 BaseAction 서브클래스 탐색)
import plugin
discovery = PluginDiscovery.from_module(plugin)

스토리지 유틸리티 (Storage Utils)

이전 (synapse-sdk v1)

from synapse_sdk.utils.storage import get_storage, get_pathlib

# URL 문자열 또는 dict 설정
storage = get_storage('s3://bucket?access_key=KEY&secret_key=SECRET')
# 또는 dict 설정
storage = get_storage({'provider': 'file_system', 'configuration': {'location': '/data'}})

이후 (synapse-sdk v2)

from synapse_sdk.utils.storage import get_storage, get_pathlib

# Dict 전용 설정 (URL 문자열 파싱 제거됨)
storage = get_storage({'provider': 'local', 'configuration': {'location': '/data'}})

# S3 예시
storage = get_storage({
    'provider': 's3',
    'configuration': {
        'bucket_name': 'my-bucket',
        'access_key': 'AKIAIOSFODNN7EXAMPLE',
        'secret_key': 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
        'region_name': 'us-east-1',
    }
})

프로바이더 이름 변경

file_system → local (별칭 file_system은 여전히 동작)
FileSystemStorage → LocalStorage
GCPStorage → GCSStorage

v2의 새로운 기능

기능	설명
`PluginDiscovery`	config 파일이나 Python 모듈에서 액션 탐색
`PluginDiscovery.from_module()`	`@action` 데코레이터와 `BaseAction` 서브클래스 자동 탐색
`StorageProtocol`	커스텀 스토리지 구현을 위한 프로토콜 기반 인터페이스
`HTTPStorage` 프로바이더	HTTP 파일 서버용 새 프로바이더
플러그인 업로드 유틸리티	`archive_and_upload()`, `build_and_upload()`, `download_and_upload()`
파일 유틸리티	`calculate_checksum()`, `create_archive()`, `create_archive_from_git()`
`AsyncAgentClient`	WebSocket/HTTP 스트리밍을 지원하는 비동기 클라이언트
`tail_job_logs()`	프로토콜 자동 선택을 통한 작업 로그 스트리밍

참고 문서

설치 - 스토리지 extras 포함 설치 옵션
스토리지 프로바이더 - 상세한 스토리지 설정
AgentClient - 동기 및 비동기 클라이언트 사용법
RayClient - 작업 로그 스트리밍

주요 변경 사항 (Breaking Changes)​

비호환 변경 사항 없음 (Non-Breaking Changes)​

플러그인 유틸리티 (Plugin Utils)​

이전 (synapse-sdk v1)​

이후 (synapse-sdk v2)​

플러그인 타입 (Plugin Types)​

이전​

이후​

Pre-Annotation 액션​

이전 (synapse-sdk v1)​

이후 (synapse-sdk v2)​

플러그인 디스커버리 (Plugin Discovery)​

스토리지 유틸리티 (Storage Utils)​

이전 (synapse-sdk v1)​

이후 (synapse-sdk v2)​

프로바이더 이름 변경​

v2의 새로운 기능​

참고 문서​

주요 변경 사항 (Breaking Changes)

비호환 변경 사항 없음 (Non-Breaking Changes)

플러그인 유틸리티 (Plugin Utils)

이전 (synapse-sdk v1)

이후 (synapse-sdk v2)

플러그인 타입 (Plugin Types)

이전

이후

Pre-Annotation 액션

이전 (synapse-sdk v1)

이후 (synapse-sdk v2)

플러그인 디스커버리 (Plugin Discovery)

스토리지 유틸리티 (Storage Utils)

이전 (synapse-sdk v1)

이후 (synapse-sdk v2)

프로바이더 이름 변경

v2의 새로운 기능

참고 문서