| # 安装指南（Transformers 推理） | |
| 本指南介绍如何搭建 Python 环境，以使用 `transformers` 后端在本地运行 SenseNova-U1。 | |
| > **软件版本：** Python 3.11、torch 2.8、CUDA 12.8（cu128）。如果本机驱动需要其他 CUDA 版本，请相应修改 `pyproject.toml` 中的 index URL。 | |
| 我们推荐使用 [**uv**](https://docs.astral.sh/uv/) 管理 Python 环境。 | |
| > uv 安装指南：<https://docs.astral.sh/uv/getting-started/installation/> | |
| ## 1. 克隆仓库 | |
| ```bash | |
| git clone https://github.com/OpenSenseNova/SenseNova-U1.git | |
| cd SenseNova-U1 | |
| ``` | |
| ## 2. 使用 uv 安装依赖 | |
| ```bash | |
| uv sync | |
| source .venv/bin/activate | |
| ``` | |
| `sensenova_u1` 会以可编辑模式安装，因此在 import 时，标准的 [NEO-Unify 模型](../src/sensenova_u1/models/neo_unify/) 会自动注册到 `transformers.Auto*` 接口。 | |
| > **较旧的 NVIDIA 驱动：** 默认 index 对应 CUDA 12.8。若驱动不支持 cu128，请先将 | |
| > `pyproject.toml` 中的 `[tool.uv.sources]` / `[[tool.uv.index]]` 改为例如 | |
| > `https://download.pytorch.org/whl/cu126`（并同步调整 torch / torchvision 的固定版本）， | |
| > 再执行 `uv sync`。 | |
| ## 可选：flash-attn | |
| `flash-attn` 以可选依赖（extra）的形式提供：未安装时模型会自动回退到 torch SDPA；一旦可以 import flash-attn，运行时就会自动启用（`--attn_backend auto`）。 | |
| ```bash | |
| # (a) 通过 PyPI 从源码编译 | |
| uv sync --extra flash | |
| # (b) 安装与当前 torch + Python 匹配的预编译 CUDA wheel | |
| uv pip install /path/to/flash_attn-2.8.3+cu12torch28cxx11abitrue-cp311-cp311-*.whl | |
| ``` | |