> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# UV 프로젝트 환경

도메인별 프로젝트를 `uv`로 분리하고, `uv sync`만으로 재현 가능한 형태로 구성합니다.

## 문서 기준

* 기준일: `2026-02-23`
* Python: `3.12` 고정
* 운영체제: macOS, Ubuntu 24.04+, Windows 11
* 재현 방식: `pyproject.toml` 고정 버전 + `uv.lock` 커밋

## 공통 원칙

* 프로젝트마다 `pyproject.toml`과 `uv.lock`을 분리합니다.
* 버전은 `==`로 고정해 팀 환경 차이를 줄입니다.
* OS별로 설치가 갈리는 패키지는 환경 마커를 사용합니다.
* 하위 문서의 `pyproject.toml`을 그대로 사용한 뒤 `uv sync`를 실행합니다.

## 공통 실행 순서

<Steps>
  <Step title="프로젝트 초기화">
    ```bash theme={null}
    uv init <project-name>
    cd <project-name>
    ```
  </Step>

  <Step title="문서의 pyproject.toml 반영">
    하위 문서의 `pyproject.toml` 예시를 현재 프로젝트의 `pyproject.toml`에 반영합니다.
  </Step>

  <Step title="락 파일 생성 및 동기화">
    ```bash theme={null}
    uv lock
    uv sync
    ```
  </Step>

  <Step title="커널 등록(선택)">
    ```bash theme={null}
    uv run python -m ipykernel install --user --name <project-name> --display-name "UV <project-name>"
    ```
  </Step>
</Steps>

## 프로젝트별 용도 비교

| 프로젝트           | 용도                        | 핵심 패키지                            | GPU 필수 | OS 제한                     |
| -------------- | ------------------------- | --------------------------------- | ------ | ------------------------- |
| `dl-env`       | 딥러닝 기본 학습/평가/해석           | torch, sklearn, shap, mlflow      | 권장     | 없음                        |
| `rag-dev`      | RAG 파이프라인 개발              | langchain, chromadb, ragas        | 선택     | faiss: Windows 제외         |
| `agent-dev`    | AI Agent 개발               | langgraph, fastapi, openai        | 불필요    | 없음                        |
| `llm-finetune` | LLM 파인튜닝 (SFT/LoRA/QLoRA) | transformers, peft, trl, unsloth  | 필수     | unsloth: Linux x86\_64 전용 |
| `cv-research`  | 컴퓨터 비전 연구                 | ultralytics, timm, albumentations | 권장     | 없음                        |
| `automl`       | AutoML 실험 자동화             | autogluon, flaml, optuna          | 선택     | autogluon: Windows 제외     |
| `vllm-serving` | LLM 서빙 (OpenAI 호환 API)    | vllm, ray, transformers           | 필수     | vllm: Linux x86\_64 전용    |

## 프로젝트 환경 목록

<CardGroup cols={2}>
  <Card title="dl-env" href="/setup/uv-env/dl-env">
    Deep Learning 기본 환경 (torch 2.10.0)
  </Card>

  <Card title="rag-dev" href="/setup/uv-env/rag-dev">
    RAG 개발 환경 (langchain 1.2.10, ragas 0.4.3)
  </Card>

  <Card title="agent-dev" href="/setup/uv-env/agent-dev">
    AI Agent 개발 환경 (langgraph 1.0.9)
  </Card>

  <Card title="llm-finetune" href="/setup/uv-env/llm-finetune">
    LLM 파인튜닝 (Unsloth 호환: transformers 4.57.6, trl 0.24.0)
  </Card>

  <Card title="cv-research" href="/setup/uv-env/cv-research">
    컴퓨터 비전 연구 (ultralytics 8.4.14)
  </Card>

  <Card title="automl" href="/setup/uv-env/automl">
    AutoML 실험 (autogluon 1.5.0, ray 2.52.1)
  </Card>

  <Card title="vllm-serving" href="/setup/uv-env/vllm-serving">
    vLLM 서빙 (Linux x86\_64 기준 vllm 0.15.1)
  </Card>
</CardGroup>

## uv 기본 명령어 참고

| 명령어                 | 설명                    | 비고                     |
| ------------------- | --------------------- | ---------------------- |
| `uv init <name>`    | 새 프로젝트 초기화            | `pyproject.toml` 자동 생성 |
| `uv lock`           | 의존성 해석 및 `uv.lock` 생성 | 버전 고정 스냅샷              |
| `uv lock --refresh` | 락 파일 갱신               | 충돌 시 사용                |
| `uv sync`           | 락 파일 기준 환경 동기화        | 가상환경 자동 생성             |
| `uv run <cmd>`      | 프로젝트 환경에서 명령 실행       | `activate` 없이 실행       |
| `uv add <pkg>`      | 의존성 추가                | `pyproject.toml` 자동 반영 |
| `uv remove <pkg>`   | 의존성 제거                | `pyproject.toml` 자동 반영 |
| `uv python list`    | 설치된 Python 버전 확인      | 버전 관리                  |

## 새 프로젝트 추가 가이드

기존 목록에 없는 새 도메인 환경을 추가하려면 다음 절차를 따르세요.

<Steps>
  <Step title="프로젝트 생성 및 의존성 정의">
    ```bash theme={null}
    uv init <new-project>
    cd <new-project>
    ```

    `pyproject.toml`에 `requires-python = "==3.12.*"`, `[tool.uv] package = false` 를 설정하고, 필요한 패키지를 `==` 고정 버전으로 추가합니다.
  </Step>

  <Step title="OS별 호환성 확인">
    특정 OS에서 설치 불가능한 패키지는 환경 마커를 사용합니다.

    ```toml theme={null}
    # 예시: Linux x86_64 전용 패키지
    "some-pkg==1.0.0; platform_system == 'Linux' and platform_machine == 'x86_64'"
    ```
  </Step>

  <Step title="락 파일 생성 및 검증">
    ```bash theme={null}
    uv lock
    uv sync
    uv run python -c "import <핵심패키지>; print('OK')"
    ```
  </Step>

  <Step title="문서 작성">
    `docs/setup/uv-env/<new-project>.mdx` 파일을 작성하고, 이 인덱스 페이지의 CardGroup에 항목을 추가합니다.
  </Step>
</Steps>

## 트러블슈팅

| 증상               | 원인                      | 해결                              |
| ---------------- | ----------------------- | ------------------------------- |
| `uv sync` 실패     | 락 파일이 오래되었거나 손상됨        | `uv lock --refresh` 후 `uv sync` |
| Python 버전 오류     | 시스템에 3.12 미설치           | `uv python install 3.12`        |
| OS별 패키지 누락       | 환경 마커 설정 누락             | 하위 문서의 `pyproject.toml` 마커 확인   |
| 가상환경 경로 충돌       | 기존 `.venv` 디렉터리 잔존      | `.venv` 삭제 후 `uv sync` 재실행      |
| 커널이 Jupyter에 미표시 | `ipykernel install` 미실행 | 커널 등록 명령 재실행                    |

## 설치 점검 목록

* 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
* 설치 후 버전 확인 명령어(`--version`)를 실행해 정상 설치를 검증했습니다.
* PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
* 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: dl-env" icon="arrow-right" href="/setup/uv-env/dl-env">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>