# 설치 및 설정

Synapse SDK를 몇 분 안에 시작하세요.

## 사전 요구 사항[​](#사전-요구-사항 "사전 요구 사항에 대한 직접 링크")

Synapse SDK를 설치하기 전에 다음이 필요합니다:

* **Python 3.12 이상** 설치
* **uv**(권장) 또는 **pip** 패키지 관리자

### uv 설치 (권장)[​](#uv-설치-권장 "uv 설치 (권장)에 대한 직접 링크")

이 프로젝트는 [uv](https://docs.astral.sh/uv/)를 권장 패키지 관리자로 사용합니다.

```bash
# macOS (Homebrew)
brew install uv

# Linux/macOS (curl)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

```

## 설치 방법[​](#설치-방법 "설치 방법에 대한 직접 링크")

### uv로 설치 (권장)[​](#uv로-설치-권장 "uv로 설치 (권장)에 대한 직접 링크")

```bash
git clone https://github.com/datamaker-kr/synapse-sdk-v2.git
cd synapse-sdk-v2

# 전체 의존성 동기화
uv sync

# 또는 편집 가능 모드로 설치
uv pip install -e .

```

CLI 명령 실행

`uv sync` 후에는 `uv run`으로 명령을 실행하거나(예: `uv run synapse --version`), 가상 환경을 먼저 활성화하세요. 자세한 내용은 [설치 확인](#%EC%84%A4%EC%B9%98-%ED%99%95%EC%9D%B8)을 참조하세요.

#### 선택적 의존성 설치 (uv)[​](#선택적-의존성-설치-uv "선택적 의존성 설치 (uv)에 대한 직접 링크")

```bash
# 전체 의존성 설치 (Ray, 클라우드 스토리지 프로바이더, MCP)
uv pip install -e ".[all]"

# 여러 extras 설치
uv pip install -e ".[dev,test,all]"

```

### pip으로 설치 (대안)[​](#pip으로-설치-대안 "pip으로 설치 (대안)에 대한 직접 링크")

pip을 직접 사용하려면:

```bash
git clone https://github.com/datamaker-kr/synapse-sdk-v2.git
cd synapse-sdk-v2

# 가상 환경 생성 및 활성화
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install -e .

```

pip을 찾을 수 없나요?

`pip`이 PATH에 없다면 Python 모듈 문법을 사용하세요:

```bash
python -m pip install -e .

```

#### 선택적 의존성 설치 (pip)[​](#선택적-의존성-설치-pip "선택적 의존성 설치 (pip)에 대한 직접 링크")

```bash
# 전체 의존성 설치 (Ray, 클라우드 스토리지 프로바이더, MCP)
pip install -e ".[all]"

```

| Extra  | 설명                                          | 의존성                                                |
| ------ | --------------------------------------------- | ----------------------------------------------------- |
| `all`  | Ray + 전체 클라우드 스토리지 프로바이더 + MCP | ray\[all], universal-pathlib, s3fs, gcsfs, sshfs, mcp |
| `test` | 테스트 유틸리티                               | pytest, pytest-asyncio, pytest-cov 등                 |
| `dev`  | 개발 도구                                     | pre-commit, ruff                                      |
| `docs` | 문서 생성                                     | pydoc-markdown                                        |

## 설치 확인[​](#설치-확인 "설치 확인에 대한 직접 링크")

설치 후 정상 동작을 확인하세요:

```bash
# uv 사용 (권장)
uv run synapse --version
uv run synapse

# 또는 가상 환경 먼저 활성화
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

synapse --version
synapse

```

## 문제 해결[​](#문제-해결 "문제 해결에 대한 직접 링크")

### 일반적인 문제[​](#일반적인-문제 "일반적인 문제에 대한 직접 링크")

1. **ImportError: No module named 'synapse\_sdk'**

   * 가상 환경이 활성화되어 있는지 확인하세요
   * Python 경로 확인: `python -c "import sys; print(sys.path)"`

2. **백엔드 연결 타임아웃**

   * API 토큰이 올바른지 확인하세요
   * 네트워크 연결 상태를 확인하세요
   * 백엔드 URL에 접근 가능한지 확인하세요

### 도움 받기[​](#도움-받기 "도움 받기에 대한 직접 링크")

문제가 발생하면:

1. [문제 해결 가이드](/ko/operations/troubleshooting.md)를 확인하세요
2. [GitHub Issues](https://github.com/datamaker-kr/synapse-sdk-v2/issues)를 검색하세요

## 다음 단계[​](#다음-단계 "다음 단계에 대한 직접 링크")

* [빠른 시작 가이드](/ko/quickstart.md) 따라하기
* [플러그인 시스템](/ko/plugins/index.md) 알아보기