# 本機 Python 模型執行環境

> 用 PyTorch 在這台電腦上，於每個模型專屬的私人 Python 環境中執行沒有 C++ 或 ONNX 移植版本的模型（3D 生成與骨架綁定），完全不會動到你自己的 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/zh-hant/packages/aigd.python

## 安裝

在專案資料夾中，使用 gamedev CLI：

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

在桌面應用程式中：開啟「套件」視窗（狀態列上的套件圖示），選擇 **瀏覽**，搜尋 `aigd.python`，然後點 **加入專案**。更多資訊：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 執行環境：它以 [PyTorch](https://pytorch.org) 在這台電腦上執行本機模型，適用於沒有 C++ 或 ONNX 移植版本的模型，例如圖片轉 3D、網格細修與自動骨架綁定。所有運算都在你的電腦上進行，不會用掉任何 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 安裝完全不受影響：每個模型都有自己專屬的私人環境。

## 範例請求

- 「用 TripoSG 在我的 GPU 上把 `Assets/Concepts/goblin.png` 變成 3D 形體。」
- 「用 Hunyuan3D-2.1 Shape 在本機把這張寶箱圖片做成 3D 模型。」
- 「用 Step1X-3D Geometry 把 `Assets/Concepts/crate.png` 變成 3D 形體。」

## 運作方式

這個套件只有資料（`aigd-package.json`，不含程式碼）。它會告訴 AI Game Dev 要為你的電腦下載哪一個版本的 [uv](https://github.com/astral-sh/uv)。應用程式會用 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` | Windows，沒有支援的 NVIDIA GPU | 15 MB |
  | `linux-x64-cuda` | Linux x64，NVIDIA GPU（驅動程式 570.124 或更新版本，運算能力 7.0 或更新），glibc 2.28 或更新版本 | 17 MB |
  | `linux-x64-cpu` | Linux x64，沒有支援的 NVIDIA GPU，glibc 2.28 或更新版本 | 17 MB |
  | `darwin-arm64-metal` | Apple 晶片的 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 鎖定。安裝只使用 wheel，所以你的電腦上不會編譯任何東西。若檔案與其 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 wheel 中，並依 [NVIDIA CUDA EULA](https://docs.nvidia.com/cuda/eula/) 重新散布。
- 每個模型套件都會註明自己的授權。部分 3D 模型對地區或商業使用有限制。模型面板會在任何下載開始前顯示這些限制。

必要的署名：本套件無。模型套件會註明自己的署名要求。

**限制：** 本套件無。NVIDIA CUDA EULA 允許這些程式庫與應用程式一起使用，但不得單獨重新散布。

所有檔案都從其上游發行者下載（GitHub、Python 套件索引、download.pytorch.org）。AI Game Dev 並未自行託管這些檔案。
````
