agentscope-ai / agentscope-ai/TuFT
Installer: make CUDA wheel selection and runtime verification environment-aware
- Ngôn ngữ chính
- Python
- Star
- 69
- Fork
- 14
- Merge trung bình
- 6 giờ 31 phút
- Pull request đã merge (30 ngày)
- 13
Mô tả
## Summary
TuFT's installer already uses `uv`, but the GPU dependency resolution is not CUDA-variant-aware. Both the initial install and generated `tuft upgrade` commands install the TuFT package specification without selecting a Torch backend or a matching vLLM wheel variant.
This can produce a fully resolved Python environment that passes dependency metadata checks but cannot initialize CUDA because the selected Torch/vLLM binaries require a newer driver than the host supports. Exact public-version pins such as `torch==2.11.0` and `vllm==0.24.0` do not identify whether the installed wheels are `+cu129`, `+cu130`, or another build.
There are also a few related installer rough edges:
- `scripts/verify_runtime_versions.py` compares version strings literally, so an official local version such as `2.11.0+cu129` is rejected against a `2.11.0` project pin even though it satisfies that requirement.
- The installer does not expose or document common `uv` controls for custom certificate authorities, package indexes, cache placement, and link mode.
- `TUFT_VENV` is derived unconditionally from `TUFT_HOME`, making it difficult to place the environment on a filesystem better suited to large GPU packages.
- There is no GPU compatibility preflight before downloading the runtime, nor a CUDA smoke test after installation.
## Proposed changes
### 1. Add explicit CUDA backend selection
Add an installer option/environment variable such as:
```text
--torch-backend auto|cu129|cu130|cpu
TUFT_TORCH_BACKEND=auto|cu129|cu130|cpu
```
The automatic mode should inspect the NVIDIA driver, choose a supported published backend, and fail with a clear diagnostic if no compatible TuFT/vLLM combination is available.
Resolve Torch and vLLM as one compatibility unit. For example, selecting `cu129` should install both the official Torch `+cu129` build and the corresponding official vLLM `+cu129` wheel. It should never combine a backend-specific Torch wheel with the default vLLM wheel accidentally.
Use the same resolver/helper in both `install_tuft` and the generated `tuft upgrade` implementation.
### 2. Make runtime verification PEP 440-aware
Use `packaging.version.Version` or `packaging.specifiers.SpecifierSet` to validate the pinned public/base version while accepting official local build suffixes.
Then validate backend consistency separately, for example:
- Torch and vLLM have compatible CUDA build variants.
- `torch.version.cuda` agrees with the selected backend.
- CUDA can initialize successfully when a GPU backend was requested.
### 3. Add preflight and post-install checks
Before resolving the large GPU packages:
- Detect whether an NVIDIA driver is available.
- Print the selected Torch/vLLM/CUDA variant plan.
- Fail early when the requested backend is incompatible or unavailable.
After installation:
- Run `pip check` or the `uv` equivalent.
- Import TuFT, Tinker, Torch, and vLLM.
- Check `torch.cuda.is_available()` and device count.
- Execute a minimal CUDA tensor operation.
- Report actionable remediation if any check fails.
### 4. Expose standard network and filesystem controls
Pass through and document, without hardcoding a specific provider:
- `UV_SYSTEM_CERTS` / `--system-certs`
- `UV_DEFAULT_INDEX` and additional indexes
- `UV_CACHE_DIR`
- `UV_LINK_MODE` / `--link-mode`
- An overridable `TUFT_VENV`, e.g. `TUFT_VENV="${TUFT_VENV:-$TUFT_HOME/venv}"`
When the cache and target environment are on different filesystems, either select copy mode explicitly or print a concise explanation of the hardlink fallback.
## Suggested acceptance criteria
- A user can select `cu129` or `cu130` and get matching Torch and vLLM builds in one installer invocation.
- `auto` never installs a runtime that fails the driver's basic CUDA initialization check.
- Initial install and upgrade share the same backend-resolution code path.
- Runtime verification accepts compatible local-version suffixes but rejects mismatched CUDA variants.
- Custom CA/index/cache/link-mode settings work through documented environment variables.
- GPU incompatibility is reported before multi-gigabyte downloads whenever it can be determined during preflight.
- Unit or shell tests cover backend selection, local-version comparison, and install/upgrade command construction.
This can remain entirely installer- and validation-scoped; no model-training behavior needs to change.
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Đánh giá
Issue này chưa được đánh giá.