synapse-sdk 1.0.0a13__py3-none-any.whl → 2025.11.7__py3-none-any.whl

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/plugins/plugins.md

@@ -0,0 +1,117 @@
+---
+id: plugins
+title: 플러그인 시스템
+sidebar_position: 1
+---
+
+# 플러그인 시스템
+
+Synapse SDK는 다양한 카테고리와 실행 방법에 걸쳐 ML 플러그인을 구축하고 관리하기 위한 포괄적인 플러그인 시스템을 제공합니다. 플러그인 시스템은 다양한 환경에서 배포되고 실행될 수 있는 모듈식, 재사용 가능한 컴포넌트를 가능하게 합니다.
+
+## 개요
+
+플러그인 시스템은 **액션** 개념을 중심으로 구축됩니다 - 패키징, 배포 및 다양한 컨텍스트에서 실행될 수 있는 개별 작업들입니다. 각 플러그인은 특정 카테고리에 속하며 여러 액션을 지원할 수 있습니다.
+
+### 주요 기능
+
+- **🔌 모듈식 아키텍처**: 플러그인은 자체 종속성과 구성을 가진 자체 포함형입니다
+- **⚡ 다중 실행 방법**: Job, Task 및 REST API 엔드포인트 지원
+- **📦 분산 실행**: 확장 가능한 분산 컴퓨팅을 위해 구축됨
+- **🛠️ 템플릿 시스템**: 신속한 플러그인 개발을 위한 Cookiecutter 기반 스캐폴딩
+- **📊 진행률 추적**: 내장된 로깅, 메트릭 및 진행률 모니터링
+- **🔄 동적 로딩**: 런타임 플러그인 발견 및 등록
+
+## 플러그인 카테고리
+
+SDK는 플러그인을 특정 카테고리로 구성하며, 각각은 ML 워크플로우의 다양한 측면을 위해 설계되었습니다:
+
+### 1. 신경망 (`neural_net`)
+
+ML 모델 훈련, 추론 및 배포 작업들.
+
+**사용 가능한 액션:**
+
+- `deployment` - 모델을 프로덕션 환경에 배포
+- `gradio` - 모델용 대화형 웹 인터페이스 생성
+- `inference` - 데이터에 대한 모델 예측 실행
+- `test` - 모델 성능과 정확도 검증
+- `train` - 사용자 정의 데이터셋으로 ML 모델 훈련
+- `tune` - 하이퍼파라미터 최적화 및 모델 튜닝
+
+**사용 사례:**
+
+- 컴퓨터 비전 모델 훈련
+- 모델을 웹 서비스로 배포
+- 데이터셋에 대한 배치 추론 실행
+- 대화형 모델 데모 생성
+
+### 2. Export (`export`)
+
+Synapse 플랫폼에서 주석이 달린 데이터, 그라운드 트루스 데이터셋, 할당 및 작업을 내보내기 위한 데이터 내보내기 및 변환 작업.
+
+**사용 가능한 액션:**
+
+- `export` - 다양한 소스(할당, 그라운드 트루스, 작업)에서 사용자 정의 처리와 함께 데이터 내보내기
+
+**사용 사례:**
+
+- 훈련용 주석 데이터셋 내보내기
+- 그라운드 트루스 데이터를 사용자 정의 형식으로 변환
+- 배포용 데이터 패키지 생성
+- 할당 결과의 배치 처리
+- 외부 도구용 주석 데이터 변환
+
+**지원되는 내보내기 대상:**
+
+- `assignment` - 주석이 있는 할당 데이터 내보내기
+- `ground_truth` - 그라운드 트루스 데이터셋 버전 내보내기
+- `task` - 관련 주석이 있는 작업 데이터 내보내기
+
+Export 플러그인에 대한 자세한 정보, BaseExporter 클래스 구조, 구현 예시 및 모범 사례는 [Export 플러그인](./export-plugins) 문서를 참조하세요.
+
+## 플러그인 구성
+
+플러그인은 YAML 구성 파일을 사용하여 구성되며, 이 파일은 메타데이터, 종속성, 패키지 관리 옵션 및 액션을 정의합니다.
+
+### 패키지 관리
+
+```yaml
+# 플러그인 메타데이터 (필수)
+name: "my-ml-plugin"          # 필수: 플러그인 이름
+version: "1.0.0"              # 필수: 버전
+category: "neural_net"        # 필수: 카테고리
+description: "사용자 정의 ML 플러그인"  # 필수: 설명
+
+# 패키지 관리 (선택사항)
+package_manager: "pip"        # 선택사항: "pip" 또는 "uv" (기본값: "pip")
+
+# 패키지 매니저 옵션 (선택사항)
+# uv만 지원 pip_install_options: 지원 예정
+# uv의 경우 기본값은 ['--no-cache']입니다
+package_manager_options: ["--no-cache", "--quiet"]  # 선택사항: 설치 옵션
+
+# 액션 정의 (필수)
+actions:                      # 필수: 최소 하나의 액션 필요
+  train:
+    entrypoint: "plugin.train.TrainAction"  # 필수
+    method: "job"             # 필수: 실행 방법
+```
+
+**구성 옵션 설명:**
+
+**필수 필드:**
+- `name`: 플러그인 이름
+- `version`: 플러그인 버전
+- `category`: 플러그인 카테고리 (`neural_net`, `export` 등)
+- `description`: 플러그인 설명
+- `actions`: 플러그인 액션 정의 (최소 하나 필요)
+  - `entrypoint`: 액션의 진입점 클래스
+  - `method`: 실행 방법 (`job`, `task`, `serve` 등)
+
+**선택사항 필드:**
+- `package_manager`: 종속성에 사용할 패키지 매니저 (기본값: `"pip"`)
+  - 지원 값: `"pip"` 또는 `"uv"`
+- `package_manager_options`: 패키지 설치 명령에 대한 사용자 제공 옵션
+  - 현재 Ray 2.44.1에서는 `uv`만 지원됩니다
+  - `uv`의 경우 기본값은 `["--no-cache"]`입니다
+  - 사용자 정의 옵션이 기본값과 병합됩니다

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/quickstart.md

@@ -0,0 +1,78 @@
+---
+id: quickstart
+title: 빠른 시작 가이드
+sidebar_position: 3
+---
+
+# 빠른 시작 가이드
+
+Synapse SDK를 몇 분 안에 시작하고 실행하세요.
+
+## 대화형 CLI
+
+모든 기능에 대화형 메뉴를 통해 접근하기 위해 Synapse CLI를 실행하세요:
+
+```bash
+synapse
+```
+
+다음 옵션들이 있는 메인 메뉴가 열립니다:
+
+- 🌐 **개발 도구**: 에이전트 및 작업 관리를 위한 웹 기반 대시보드
+- 💻 **Code-Server IDE**: 플러그인 개발을 위한 웹 기반 VS Code
+- ⚙️ **설정**: 백엔드 연결 및 에이전트 설정
+- 🔌 **플러그인 관리**: 플러그인 생성, 테스트 및 게시
+
+## 빠른 명령어
+
+특정 기능에 빠르게 접근하기 위해:
+
+```bash
+# 개발 도구 즉시 시작
+synapse --dev-tools
+
+# 백엔드 및 에이전트 구성
+synapse config
+
+# 코드 편집 환경 열기
+synapse code-server
+
+# 새 플러그인 생성
+synapse plugin create
+```
+
+## 첫 번째 플러그인
+
+1. **플러그인 생성**:
+
+   ```bash
+   synapse
+   # "🔌 플러그인 관리" → "새 플러그인 생성" 선택
+   ```
+
+2. **Code-Server에서 편집**:
+
+   ```bash
+   synapse
+   # "💻 Code-Server IDE 열기" 선택
+   ```
+
+3. **로컬에서 테스트**:
+
+   ```bash
+   synapse plugin run my_action '{"param": "value"}' --run-by script
+   ```
+
+4. **백엔드에 게시**:
+
+   ```bash
+   synapse
+   # "🔌 플러그인 관리" → "플러그인 게시" 선택
+   ```
+
+## 다음 단계
+
+- 완전한 [CLI 사용 가이드](./cli-usage.md) 읽기
+- [핵심 개념](./concepts/index.md)에 대해 학습하기
+- [API 참조](./api/index.md) 탐색하기
+- [자주 묻는 질문](./faq.md) 확인하기

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/troubleshooting.md

@@ -0,0 +1,519 @@
+---
+id: troubleshooting
+title: 문제 해결
+sidebar_position: 10
+---
+
+# 문제 해결
+
+Synapse SDK 사용 시 발생하는 일반적인 문제와 해결방법입니다.
+
+## 설치 문제
+
+## 인증 문제
+
+### ClientError: 401 Unauthorized
+
+**증상**: API 호출이 401 오류로 실패합니다.
+
+**진단 단계**:
+
+
+3. **CLI를 통한 토큰 확인**:
+   ```bash
+   # 토큰을 확인하기 위한 대화형 설정 사용
+   synapse config
+   # "Show current configuration" 선택
+   # 토큰이 검증을 위해 평문으로 표시됩니다
+   ```
+
+4. **코드에서 토큰 확인**:
+   ```python
+   from synapse_sdk.clients.backend import BackendClient
+   
+   client = BackendClient(
+       base_url="https://api.synapse.sh",
+       api_token="your-token"  # "Token " 접두사 없음
+   )
+   
+   try:
+       user = client.get_current_user()
+       print(f"Authenticated as: {user.email}")
+   except Exception as e:
+       print(f"Auth failed: {e}")
+   ```
+
+**일반적인 해결방법**:
+- 웹 인터페이스에서 토큰 재생성
+- 토큰이 만료되지 않았는지 확인
+- 올바른 백엔드 URL 확인
+
+### Agent 인증 오류
+
+**증상**: Agent 관련 작업이 실패합니다.
+
+**해결방법**:
+
+1. **Agent 설정 확인**:
+   ```bash
+   synapse config
+   # "Show current configuration" 선택
+   # 백엔드와 Agent 토큰 모두 평문으로 표시됩니다
+   ```
+
+2. **Agent 토큰 확인**:
+   ```python
+   from synapse_sdk.clients.agent import AgentClient
+   
+   client = AgentClient(
+       base_url="https://api.synapse.sh",
+       agent_token="your-agent-token"
+   )
+   ```
+
+## 연결 문제
+
+### 연결 시간 초과
+
+**증상**: 요청이 시간 초과되거나 멈춤 상태가 됩니다.
+
+**해결방법**:
+
+1. **시간 초과 값 증가**:
+   ```python
+   client = BackendClient(
+       base_url="https://api.synapse.sh",
+       api_token="your-token",
+       timeout={'connect': 30, 'read': 120}
+   )
+   ```
+
+2. **네트워크 연결 확인**:
+   ```bash
+   # 기본 연결 테스트
+   ping api.synapse.sh
+   
+   # HTTPS 접근 테스트
+   curl -I https://api.synapse.sh/health
+   ```
+
+3. **필요시 프록시 설정**:
+   ```bash
+   export HTTP_PROXY="http://proxy.company.com:8080"
+   export HTTPS_PROXY="https://proxy.company.com:8080"
+   ```
+
+### DNS 해결 문제
+
+**증상**: "Name or service not known" 오류가 발생합니다.
+
+**해결방법**:
+
+1. **DNS 설정 확인**:
+   ```bash
+   nslookup api.synapse.sh
+   ```
+
+2. **대체 DNS 시도**:
+   ```bash
+   # Google DNS 임시 사용
+   export SYNAPSE_BACKEND_HOST="$(dig @8.8.8.8 api.synapse.sh +short)"
+   ```
+
+3. **IP 주소 직접 사용** (임시):
+   ```python
+   client = BackendClient(base_url="https://192.168.1.100:8000")
+   ```
+
+## 플러그인 개발 문제
+
+### 플러그인 가져오기 오류
+
+**증상**: 플러그인 로딩 또는 가져오기가 실패합니다.
+
+**진단**:
+```bash
+# 플러그인 구문 테스트
+python -m py_compile plugin/__init__.py
+
+# 순환 가져오기 확인
+python -c "import plugin; print('OK')"
+```
+
+**해결방법**:
+
+1. **구문 오류 수정**:
+   ```bash
+   # 린팅 사용
+   pip install ruff
+   ruff check plugin/
+   ```
+
+2. **가져오기 경로 확인**:
+   ```python
+   # plugin/__init__.py에서
+   from synapse_sdk.plugins.categories.base import Action, register_action
+   # 아님: from synapse_sdk.plugins.base import Action
+   ```
+
+3. **플러그인 구조 확인**:
+   ```
+   my-plugin/
+   ├── config.yaml
+   ├── plugin/
+   │   └── __init__.py
+   ├── requirements.txt
+   └── README.md
+   ```
+
+### 플러그인 실행 실패
+
+**증상**: 플러그인이 시작되지만 실행 중 실패합니다.
+
+**디버깅 단계**:
+
+1. **CLI를 통한 디버그 모드 활성화**:
+   ```bash
+   synapse
+   # "Plugin Management" 선택
+   # "Run plugin locally" 선택
+   # 액션과 매개변수 입력
+   # 로컬 실행 시 디버그 모드가 기본적으로 활성화됩니다
+   ```
+
+2. **수동으로 디버그 모드 활성화**:
+   ```bash
+   export SYNAPSE_DEBUG=true
+   synapse plugin run --path ./my-plugin --action test
+   ```
+
+2. **로그 확인**:
+   ```python
+   def start(self):
+       try:
+           self.run.log("Starting plugin execution")
+           # 여기에 코드 작성
+           self.run.log("Plugin completed successfully")
+       except Exception as e:
+           self.run.log(f"Error: {str(e)}", level="ERROR")
+           raise
+   ```
+
+3. **매개변수 검증**:
+   ```python
+   from pydantic import ValidationError
+   
+   def start(self):
+       try:
+           # 매개변수 검증
+           params = self.params_model(**self.params)
+       except ValidationError as e:
+           self.run.log(f"Parameter validation failed: {e}")
+           raise
+   ```
+
+### 파일 처리 문제
+
+**증상**: 플러그인에서 파일 작업이 실패합니다.
+
+**일반적인 문제 & 해결방법**:
+
+1. **FileField가 다운로드되지 않음**:
+   ```python
+   # 파일 URL 형식 확인
+   class MyParams(BaseModel):
+       input_file: FileField  # URL 형식 예상
+   
+   def start(self):
+       file_path = self.params.input_file
+       if not os.path.exists(file_path):
+           raise FileNotFoundError(f"File not found: {file_path}")
+   ```
+
+2. **권한 오류**:
+   ```python
+   import tempfile
+   import shutil
+   
+   def start(self):
+       # 임시 디렉토리 사용
+       with tempfile.TemporaryDirectory() as temp_dir:
+           output_path = os.path.join(temp_dir, "result.csv")
+           # output_path에서 처리 및 저장
+   ```
+
+3. **대용량 파일 처리**:
+   ```python
+   def start(self):
+       # 대용량 파일을 청크 단위로 처리
+       chunk_size = 1024 * 1024  # 1MB 청크
+       with open(self.params.input_file, 'rb') as f:
+           while True:
+               chunk = f.read(chunk_size)
+               if not chunk:
+                   break
+               process_chunk(chunk)
+   ```
+
+## 분산 컴퓨팅 문제
+
+### 클러스터 연결
+
+**증상**: 컴퓨팅 클러스터에 연결할 수 없습니다.
+
+**해결방법**:
+
+1. **클러스터 상태 확인**:
+   ```bash
+   synapse cluster status
+   # 클러스터 정보가 표시되어야 함
+   ```
+
+2. **로컬 클러스터 시작**:
+   ```bash
+   synapse cluster start --dashboard-host=0.0.0.0
+   ```
+
+3. **원격 클러스터 연결**:
+   ```bash
+   export SYNAPSE_CLUSTER_ADDRESS="cluster://remote-cluster:10001"
+   synapse cluster status  # 원격 클러스터에 연결되어야 함
+   ```
+
+### 메모리 문제
+
+**증상**: 실행 중 메모리 부족 오류가 발생합니다.
+
+**해결방법**:
+
+1. **메모리 할당 증가**:
+   ```bash
+   synapse cluster start --memory=2000000000  # 2GB
+   ```
+
+2. **코드에서 설정**:
+   ```python
+   from synapse_sdk.compute import init
+   init(memory=2000000000)
+   ```
+
+3. **데이터를 작은 청크로 처리**:
+   ```python
+   def process_chunk(data_chunk):
+       return process(data_chunk)
+   
+   # 대용량 데이터를 청크로 분할
+   chunks = split_data(large_data)
+   results = [process_chunk(chunk) for chunk in chunks]
+   ```
+
+### 작업 실패
+
+**증상**: 작업이 시작되지 않거나 완료되지 않습니다.
+
+**해결방법**:
+
+1. **리소스 요구사항 확인**:
+   ```python
+   def my_task(resources={'cpus': 2, 'memory': '1GB'}):
+       pass
+   ```
+
+2. **런타임 환경 확인**:
+   ```yaml
+   # 플러그인 config.yaml에서
+   runtime_env:
+     pip:
+       packages: ["pandas", "numpy"]
+   ```
+
+## 개발 도구 문제
+
+### 개발 도구가 시작되지 않음
+
+**증상**: `synapse --dev-tools` 시작이 실패합니다.
+
+**해결방법**:
+
+1. **대시보드 의존성 설치**:
+   ```bash
+   pip install synapse-sdk[dashboard]
+   ```
+
+2. **포트 사용 가능성 확인**:
+   ```bash
+   # 포트 8080 사용 중인지 확인
+   lsof -i :8080
+   
+   # 다른 포트 사용
+   synapse devtools --port 8081
+   ```
+
+3. **프론트엔드 수동 빌드**:
+   ```bash
+   cd synapse_sdk/devtools/web
+   npm install
+   npm run build
+   ```
+
+### 프론트엔드 빌드 오류
+
+**증상**: 프론트엔드 에셋 빌드가 실패합니다.
+
+**해결방법**:
+
+1. **Node.js 의존성 설치**:
+   ```bash
+   # Node.js 설치 (설치되지 않은 경우)
+   curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+   sudo apt-get install -y nodejs
+   
+   # 또는 nvm 사용
+   nvm install 18
+   nvm use 18
+   ```
+
+2. **npm 캐시 정리**:
+   ```bash
+   cd synapse_sdk/devtools/web
+   rm -rf node_modules package-lock.json
+   npm cache clean --force
+   npm install
+   ```
+
+## 성능 문제
+
+### 플러그인 실행 속도 저하
+
+**증상**: 플러그인 실행 시간이 너무 오래 걸립니다.
+
+**최적화 전략**:
+
+1. **코드 프로파일링**:
+   ```python
+   import time
+   
+   def start(self):
+       start_time = time.time()
+       # 여기에 코드 작성
+       self.run.log(f"Execution took {time.time() - start_time:.2f}s")
+   ```
+
+2. **병렬 처리 사용**:
+   ```python
+   from concurrent.futures import ThreadPoolExecutor
+   
+   def parallel_task(item):
+       return process_item(item)
+   
+   def start(self):
+       # 병렬로 항목 처리
+       with ThreadPoolExecutor() as executor:
+           results = list(executor.map(parallel_task, items))
+   ```
+
+3. **데이터 로딩 최적화**:
+   ```python
+   # 모든 것을 한 번에 로딩하는 대신
+   data = pd.read_csv(large_file)
+   
+   # 청크 로딩 사용
+   for chunk in pd.read_csv(large_file, chunksize=1000):
+       process_chunk(chunk)
+   ```
+
+### 메모리 사용량 문제
+
+**증상**: 높은 메모리 사용량 또는 메모리 부족 오류가 발생합니다.
+
+**해결방법**:
+
+1. **메모리 사용량 모니터링**:
+   ```python
+   import psutil
+   
+   def start(self):
+       process = psutil.Process()
+       self.run.log(f"Memory usage: {process.memory_info().rss / 1024 / 1024:.1f} MB")
+   ```
+
+2. **리스트 대신 제너레이터 사용**:
+   ```python
+   # 대신
+   all_data = [process(item) for item in large_list]
+   
+   # 제너레이터 사용
+   def process_items():
+       for item in large_list:
+           yield process(item)
+   ```
+
+3. **변수 명시적 정리**:
+   ```python
+   def start(self):
+       large_data = load_data()
+       result = process(large_data)
+       del large_data  # 메모리 명시적 해제
+       return result
+   ```
+
+## 로깅 및 디버깅
+
+### 디버그 로깅 활성화
+
+```bash
+export SYNAPSE_DEBUG=true
+export SYNAPSE_LOG_LEVEL=DEBUG
+```
+
+### 커스텀 로깅
+
+```python
+import logging
+
+# 로깅 설정
+logging.basicConfig(
+    level=logging.DEBUG,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+logger = logging.getLogger(__name__)
+
+def start(self):
+    logger.debug("Starting plugin execution")
+    # 여기에 코드 작성
+```
+
+### 디버깅 팁
+
+1. **print 문 사용** (로그에 표시됨):
+   ```python
+   def start(self):
+       print(f"Parameters: {self.params}")
+       print(f"Working directory: {os.getcwd()}")
+   ```
+
+2. **파일 존재 확인**:
+   ```python
+   def start(self):
+       file_path = self.params.input_file
+       print(f"File exists: {os.path.exists(file_path)}")
+       print(f"File size: {os.path.getsize(file_path)} bytes")
+   ```
+
+3. **데이터 타입 검증**:
+   ```python
+   def start(self):
+       print(f"Parameter types: {type(self.params.input_data)}")
+       print(f"Parameter value: {repr(self.params.input_data)}")
+   ```
+
+## 도움 받기
+
+문제를 해결할 수 없는 경우:
+
+1. **로그 철저히 확인**
+2. **GitHub issues 검색**: https://github.com/datamaker/synapse-sdk/issues
+3. **최소한의 재현 케이스** 생성
+4. **Discord 커뮤니티 참여**: https://discord.gg/synapse-sdk
+5. 자세한 오류 정보와 함께 **지원팀 문의**