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

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

사전 요구 사항

이 가이드는 synapse-sdk v1에 대한 이해를 전제로 합니다. v2 설정은 [설치 가이드](/ko/installation.md)를 참조하세요.

## 주요 변경 사항 (Breaking Changes)[​](#주요-변경-사항-breaking-changes "주요 변경 사항 (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)[​](#비호환-변경-사항-없음-non-breaking-changes "비호환 변경 사항 없음 (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)[​](#플러그인-유틸리티-plugin-utils "플러그인 유틸리티 (Plugin Utils)에 대한 직접 링크")

### 이전 (synapse-sdk v1)[​](#이전-synapse-sdk-v1 "이전 (synapse-sdk v1)에 대한 직접 링크")

```python
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)[​](#이후-synapse-sdk-v2 "이후 (synapse-sdk v2)에 대한 직접 링크")

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

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

```

***

## 플러그인 타입 (Plugin Types)[​](#플러그인-타입-plugin-types "플러그인 타입 (Plugin Types)에 대한 직접 링크")

### 이전[​](#이전 "이전에 대한 직접 링크")

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

```

### 이후[​](#이후 "이후에 대한 직접 링크")

```python
from synapse_sdk.plugins.enums import PluginCategory, RunMethod

```

***

## Pre-Annotation 액션[​](#pre-annotation-액션 "Pre-Annotation 액션에 대한 직접 링크")

### 이전 (synapse-sdk v1)[​](#이전-synapse-sdk-v1-1 "이전 (synapse-sdk v1)에 대한 직접 링크")

```python
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)[​](#이후-synapse-sdk-v2-1 "이후 (synapse-sdk v2)에 대한 직접 링크")

```python
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)[​](#플러그인-디스커버리-plugin-discovery "플러그인 디스커버리 (Plugin Discovery)에 대한 직접 링크")

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

```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)[​](#스토리지-유틸리티-storage-utils "스토리지 유틸리티 (Storage Utils)에 대한 직접 링크")

### 이전 (synapse-sdk v1)[​](#이전-synapse-sdk-v1-2 "이전 (synapse-sdk v1)에 대한 직접 링크")

```python
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)[​](#이후-synapse-sdk-v2-2 "이후 (synapse-sdk v2)에 대한 직접 링크")

```python
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의 새로운 기능[​](#v2의-새로운-기능 "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()`               | 프로토콜 자동 선택을 통한 작업 로그 스트리밍                            |

***

## 참고 문서[​](#참고-문서 "참고 문서에 대한 직접 링크")

* [설치](/ko/installation.md) - 스토리지 extras 포함 설치 옵션
* [스토리지 프로바이더](/ko/utils/storage.md) - 상세한 스토리지 설정
* [AgentClient](/ko/api/clients/agent.md) - 동기 및 비동기 클라이언트 사용법
* [RayClient](/ko/api/clients/ray.md) - 작업 로그 스트리밍