# 로컬 Python 모델 런타임

> C++나 ONNX 포트가 없는 로컬 모델(3D 생성 및 리깅)을 이 컴퓨터에서 PyTorch로 실행하며, 모델마다 별도의 비공개 Python 환경을 사용해 여러분의 Python에는 전혀 손대지 않습니다. TripoSG, Hunyuan3D-2.1 Shape, SkinTokens 같은 모델은 별도 패키지입니다.

- Id: `aigd.python`
- 소스: 공식 (자사 `aigd.*`)
- 카테고리: 3D
- 게시자: AI Game Dev (`aigd`), 인증됨
- 최신 버전: 1.0.2 (2026-11-22 게시)
- 라이선스: MIT
- AI Game Dev 앱 필요: `>=0.32.0-beta.6`
- 네이티브 코드: 아니요
- 평점: 아직 평가 없음
- HTML 페이지: https://ai-game.dev/ko/packages/aigd.python

## 설치

gamedev CLI를 사용한다면 프로젝트 폴더에서:

```bash
gamedev pkg add aigd.python
```

데스크톱 앱에서 Packages 창을 열고(상태 표시줄의 패키지 아이콘) **Browse**를 선택한 뒤 `aigd.python`를 검색하고 **Add to Project**를 클릭합니다. 자세히: https://ai-game.dev/docs/wiki/app/packages

## 버전

| 버전 | 게시일 | 앱 필요 | 참고 |
|---|---|---|---|
| 1.0.2 | 2026-11-22 | `>=0.32.0-beta.6` | 최신 |
| 1.0.1 | 2026-11-21 | `>=0.32.0-beta.6` | - |

## 설명

````markdown
# 로컬 Python 모델 런타임 (`aigd.python`)

AI Game Dev의 로컬 Python 런타임입니다. C++나 ONNX 포트가 없는 모델(이미지→3D, 메시 정밀화, 자동 리깅 등)을 이 컴퓨터에서 [PyTorch](https://pytorch.org)로 실행합니다. 모든 작업이 여러분의 컴퓨터에서 실행되며 AI Game Dev 사용량을 전혀 소모하지 않습니다. 컨셉 아트를 3D 형상으로 바꾸거나 자신의 GPU에서 캐릭터를 리깅하려는 게임 개발자에게 적합합니다. 모델 자체는 별도 패키지입니다.

## 할 수 있는 일

- 로컬 이미지→3D 모델로 컨셉 이미지 한 장을 3D 형상으로 바꿀 수 있습니다. 예를 들어 [TripoSG 1.5B](https://ai-game.dev/packages/aigd.model3d-triposg), [Hunyuan3D-2.1 Shape](https://ai-game.dev/packages/aigd.model3d-hunyuan3d-2-1-shape), [Step1X-3D Geometry](https://ai-game.dev/packages/aigd.model3d-step1x-3d-geometry) 등입니다.
- Asset Studio에서 [SkinTokens](https://ai-game.dev/packages/aigd.model3d-skintokens)로 캐릭터나 크리처 메시를 리깅할 수 있습니다(스켈레톤과 스킨 웨이트).
- 직접 설치한 Python은 그대로 유지됩니다. 모델마다 자체적인 비공개 환경이 주어집니다.

## 요청 예시

- "내 GPU에서 TripoSG로 `Assets/Concepts/goblin.png`을 3D 형상으로 만들어 줘."
- "이 보물 상자 이미지로 Hunyuan3D-2.1 Shape를 사용해 로컬에서 3D 모델을 만들어 줘."
- "Step1X-3D Geometry로 `Assets/Concepts/crate.png`을 3D 형상으로 만들어 줘."

## 작동 방식

이 패키지는 데이터만 포함합니다(`aigd-package.json`, 코드 없음). 어떤 [uv](https://github.com/astral-sh/uv) 릴리스를 여러분의 컴퓨터에 내려받아야 하는지 AI Game Dev에 알려 줍니다. 앱은 uv를 사용해 모델마다 비공개 Python 환경을 구축합니다. **여러분의 Python은 절대 건드리지 않습니다.** 전역으로 설치되는 것도, `PATH`에 기록되는 것도, Windows 레지스트리에 쓰이는 것도 없습니다. 모든 것은 앱의 모델 저장소인 `python/`에 있습니다.

## 모델은 별도 패키지입니다

이 패키지에는 모델이 들어 있지 않습니다. 패키지 브라우저에서 모델 패키지를 설치한 다음 모델 패널에서 해당 파일을 내려받으세요. 확인 없이는 아무것도 내려받지 않으며, 크기를 먼저 볼 수 있습니다.

모델을 처음 로드할 때 앱이 해당 모델의 Python 환경을 구축합니다. Python 3.12와 PyTorch, 그리고 그 모델의 다른 라이브러리를 내려받으며, CUDA 빌드의 경우 2~4 GB입니다. 몇 분 정도 걸릴 수 있습니다. 이후 로드에서는 이 환경을 재사용합니다. 다운로드가 중단되면 다음 로드 시 다시 시작하며 이미 내려받은 파일은 모두 재사용합니다.

## 내려받는 항목

- **uv** — 업스트림 릴리스 [`0.13.7`](https://github.com/astral-sh/uv/releases/tag/0.13.7), sha256으로 고정. 앱이 컴퓨터에 맞는 변형을 하나 선택합니다:

  | 변형 | 컴퓨터 | 다운로드 |
  |---|---|---|
  | `win-x64-cuda` | Windows, NVIDIA GPU (드라이버 572.61 이상, 컴퓨트 기능 7.0 이상) | 15 MB |
  | `win-x64-cpu` | 지원되는 NVIDIA GPU가 없는 Windows | 15 MB |
  | `linux-x64-cuda` | Linux x64, NVIDIA GPU (드라이버 570.124 이상, 컴퓨트 기능 7.0 이상), glibc 2.28 이상 | 17 MB |
  | `linux-x64-cpu` | 지원되는 NVIDIA GPU가 없는 Linux x64, glibc 2.28 이상 | 17 MB |
  | `darwin-arm64-metal` | Apple silicon Mac, macOS 14 이상 (PyTorch는 MPS를 통해 GPU를 사용합니다) | 14 MB |

  **Linux는 프리뷰입니다.** 아직 실제 Linux GPU에서 테스트되지 않았습니다.
- **Python** 3.12.16(모델의 라이브러리가 필요로 하는 경우 3.11.18 또는 3.13.18): [python-build-standalone](https://github.com/astral-sh/python-build-standalone)의 CPython 빌드입니다. uv가 이를 내려받고, 고정된 uv 릴리스에 내장된 체크섬과 대조해 검증합니다.
- **각 모델의 Python 라이브러리**: PyTorch 2.11(NVIDIA에서는 CUDA 12.8)과 모델 자체 라이브러리를 [PyPI](https://pypi.org)와 [download.pytorch.org](https://download.pytorch.org)에서 받습니다. 앱은 모델마다 정확한 목록을 제공하며 버전과 sha256으로 고정합니다. 설치는 휠만 사용하므로 컴퓨터에서 컴파일되는 것은 없습니다. sha256이 일치하지 않는 파일이 있으면 설치가 중단됩니다.

모델은 오프라인으로 실행됩니다. 가중치는 모델 패널에서 내려받은 파일에서만 가져옵니다.

## 요구 사항

- 각 모델 패키지는 자체적인 GPU 및 비디오 메모리 요구 사항을 명시합니다.
- 앱은 드라이버나 시스템 라이브러리를 설치하지 않습니다. PyTorch가 GPU를 인식하지 못하면 모델이 로드되지 않으며, 앱이 NVIDIA 드라이버를 업데이트하라고 알려 줍니다.
- AI Game Dev 0.32.0-beta.6 이상.

## 라이선스

- 이 패키지 — MIT.
- uv — MIT OR Apache-2.0, © Astral Software Inc. ([MIT](https://github.com/astral-sh/uv/blob/0.13.7/LICENSE-MIT), [Apache-2.0](https://github.com/astral-sh/uv/blob/0.13.7/LICENSE-APACHE)).
- CPython — [PSF License 2.0](https://docs.python.org/3/license.html), © Python Software Foundation. python-build-standalone 배포판에는 함께 번들된 라이브러리(OpenSSL, SQLite, zlib 등)의 라이선스도 포함되어 있습니다. 빌드 스크립트는 MPL-2.0입니다([라이선스](https://github.com/astral-sh/python-build-standalone/blob/main/LICENSE)).
- PyTorch — BSD-3-Clause, © Meta Platforms 및 기여자 ([라이선스](https://github.com/pytorch/pytorch/blob/main/LICENSE)).
- NVIDIA CUDA 라이브러리(cuBLAS, cuDNN 등)는 CUDA 변형에만 포함됩니다. 이들은 CUDA PyTorch 휠에 들어 있으며 [NVIDIA CUDA EULA](https://docs.nvidia.com/cuda/eula/)에 따라 재배포됩니다.
- 각 모델 패키지는 자체 라이선스를 명시합니다. 일부 3D 모델에는 지역이나 상업적 사용에 대한 제한이 있습니다. 모델 패널은 무언가를 내려받기 전에 제한 사항을 보여 줍니다.

필수 저작자 표시: 이 패키지에는 없습니다. 모델 패키지가 자체적으로 명시합니다.

**제한:** 이 패키지에서 비롯된 제한은 없습니다. NVIDIA CUDA EULA는 이 라이브러리들을 애플리케이션과 함께 사용하는 것은 허용하지만, 별도로 재배포하는 것은 허용하지 않습니다.

모든 파일은 업스트림 배포자(GitHub, Python 패키지 인덱스, download.pytorch.org)로부터 내려받습니다. AI Game Dev는 이 파일들을 호스팅하지 않습니다.
````
