开发容器（推荐）#
FlagGems 为每种支持的硬件后端提供了 VS Code Dev Container 配置。 开发容器能够为你提供一个开箱即用的开发环境——包括正确的基础镜像、驱动、pip 依赖， 以及以可编辑模式（editable mode）安装好的 FlagGems——无需对宿主机做任何配置。
前提条件#
- 安装了 Dev Containers 扩展的 VS Code
- Docker（需支持对应硬件的 GPU 透传）
可用后端#
| 目录 | 后端 | 硬件 |
|---|---|---|
nvidia/ | CUDA | NVIDIA GPU |
hygon/ | DTK | 海光 DCU |
更多目录结构说明及新增后端的指引，请参阅
.devcontainer/README_CN.md。
场景 A — 本地机器#
适用于 Docker、GPU 和 VS Code 均在同一台机器上的情况。
┌─────────────────────────────────────────────────────────────┐
│ 本地机器 │
│ │
│ 1. 克隆仓库 2. 在 VS Code 中打开 │
│ git clone … 文件 › 打开文件夹… │
│ │ │ │
│ └──────────────┬───────────┘ │
│ ▼ │
│ VS Code 检测到 .devcontainer/ │
│ │ │
│ ▼ │
│ 弹出提示："在容器中重新打开？" │
│ → 点击 在容器中重新打开 │
│ → 选择后端（nvidia / hygon） │
│ │ │
│ ▼ │
│ Docker 构建镜像（仅首次） │
│ │ │
│ ▼ │
│ 执行 postCreateCommand │
│ install-dev-tools.sh → pip install -e . │
│ │ │
│ ▼ │
│ ✓ VS Code 工作区在容器内打开 │
└─────────────────────────────────────────────────────────────┘操作步骤：
- 克隆仓库，在 VS Code 中打开对应文件夹。
- VS Code 检测到
.devcontainer/后会弹出在容器中重新打开的提示，点击即可 （也可在命令面板中运行 Dev Containers: Reopen in Container）。 - 在提示中选择硬件后端。
- Docker 在首次启动时构建镜像，后续启动会复用已缓存的镜像。
- 构建完成后，
install-dev-tools.sh会自动执行，以可编辑模式安装 FlagGems。 此后 VS Code 工作区即运行在容器内部。
场景 B — 通过 SSH 登录远端服务器后进入容器#
适用于 GPU 部署在远端服务器的情况。VS Code 先通过 SSH 连接到服务器，再在服务器端启动 Dev Container。
┌─────────────────────┐ ┌──────────────────────────────────────────┐
│ 本地机器 │ SSH │ 远端服务器 │
│ │◄────────►│ │
│ VS Code │ │ 1. 仓库已克隆至服务器（或现在克隆） │
│ + Remote-SSH 扩展 │ │ 2. 服务器已安装 Docker 和 GPU 驱动 │
│ + Dev Containers │ │ │
│ │ │ │ │
│ │ SSH 连接 │ │ │
│ ├────────────►│ │ │
│ │ │ │ VS Code Server 在服务器上运行 │
│ │ │ │ │ │
│ │ │ │ ▼ │
│ │ │ │ VS Code 检测到 .devcontainer/ │
│ │ │ │ │ │
│ │◄───────────┤ │ ▼ │
│ 弹出提示： │ │ 弹出提示："在容器中重新打开？" │
│ 在容器中重新打开 │ │ → 选择后端（nvidia / hygon） │
│ │ │ │ │ │
│ │ │ │ ▼ │
│ │ │ │ Docker 在服务器上构建镜像 │
│ │ │ │ │ │
│ │ │ │ ▼ │
│ │ │ │ 执行 postCreateCommand │
│ │ │ │ install-dev-tools.sh │
│ │ │ │ │ │
│ │ │ │ ▼ │
│ │◄───────────┤ │ ✓ 容器在服务器上运行 │
│ 本地渲染 VS Code UI │ │ VS Code UI 转发至本地显示 │
└─────────────────────┘ └──────────────────────────────────────────┘操作步骤：
- 在 VS Code 中安装 Remote - SSH 扩展（与 Dev Containers 扩展配合使用）。
- 连接远端服务器：打开命令面板，运行 Remote-SSH: Connect to Host…，
输入
user@hostname。 - 连接成功后，在远端服务器上打开仓库所在文件夹（文件 › 打开文件夹…）。
- VS Code 检测到远端的
.devcontainer/并弹出在容器中重新打开的提示， 点击并选择后端。 - Docker 在远端服务器上构建镜像。端口转发、文件 I/O 和终端会话均在远端执行， 仅 UI 界面渲染在本地。
- 构建完成后，
install-dev-tools.sh在远端容器内自动运行，以可编辑模式安装 FlagGems。