Improve uv and flash-attn installation

README.md

@@ -223,6 +223,13 @@ docker run -it \
 ```
 > This image has used `uv` to install all GPU-related dependencies of Trinity-RFT. The virtual environment will be automatically activated upon entering the container (you can also manually activate it via `source /opt/venv/bin/activate` if needed). You can use `uv pip install` to add extra packages as necessary.
 
+**Using the Installation Script (uv)**
+
+```bash
+bash scripts/install/install_trinity.sh
+source .venv/bin/activate
+```
+
 **Using Conda**
 
 ```bash
@@ -235,7 +242,7 @@ pip install -e ".[vllm,flash_attn]"
 # pip install -e ".[tinker]"
 
 # If you encounter issues when installing flash-attn, try:
-# pip install flash-attn==2.8.1 --no-build-isolation
+# pip install "flash-attn>=2.8.3" --no-build-isolation
 pip install -e ".[dev]"  # for development like linting and debugging
 ```
 
@@ -251,34 +258,38 @@ pip install -e ".[vllm,flash_attn]"
 # pip install -e ".[tinker]"
 
 # If you encounter issues when installing flash-attn, try:
-# pip install flash-attn==2.8.1 --no-build-isolation
+# pip install "flash-attn>=2.8.3" --no-build-isolation
 
 pip install -e ".[dev]"  # for development like linting and debugging
 ```
 
-**Using uv**
+**Using uv manually**
 
 ```bash
-uv sync --extra vllm --extra dev --extra flash_attn
+uv venv .venv
+
+uv pip install \
+  --python .venv/bin/python \
+  --overrides scripts/install/trinity-overrides.txt \
+  -e ".[vllm,dev]"
+
+.venv/bin/python scripts/install/install_flash_attn.py --uv
 
 # If you have no GPU, try to use Tinker instead:
-# uv sync --extra tinker --extra dev
+# uv pip install --python .venv/bin/python -e ".[tinker,dev]"
+
+source .venv/bin/activate
 ```
 
+If conflicts remain, add or adjust versions in `scripts/install/trinity-overrides.txt`.
+
 #### Via PyPI
 
 If you just want to use the package without modifying the code:
 
 ```bash
 pip install trinity-rft
-pip install flash-attn==2.8.1
-```
-
-Or with `uv`:
-
-```bash
-uv pip install trinity-rft
-uv pip install flash-attn==2.8.1
+pip install "flash-attn>=2.8.3" --no-build-isolation
 ```
 
 > For training with **Megatron-LM**, please refer to [Megatron-LM Backend](https://agentscope-ai.github.io/Trinity-RFT/en/main/tutorial/example_megatron.html).
@@ -363,9 +374,10 @@ export WANDB_API_KEY=<your_api_key>
 wandb login
 ```
 
-For command-line users, run the RFT process:
+For command-line users, activate the environment and run the RFT process:
 
 ```shell
+source .venv/bin/activate  # If using venv or uv
 trinity run --config <config_path>
 ```
 

README_zh.md

@@ -245,6 +245,13 @@ docker run -it \
 
 > 该镜像已经通过 `uv` 安装了 Trinity-RFT 以及所有 GPU 相关依赖，且会自动激活虚拟环境（也可通过 `source /opt/venv/bin/activate` 手动激活）。必要时可使用 `uv pip install` 添加额外的包。
 
+**使用安装脚本（uv）**
+
+```bash
+bash scripts/install/install_trinity.sh
+source .venv/bin/activate
+```
+
 **使用 Conda**
 
 ```bash
@@ -257,7 +264,7 @@ pip install -e ".[vllm,flash_attn]"
 # pip install -e ".[tinker]"
 
 # 如果安装 flash-attn 时遇到问题，可尝试：
-# pip install flash-attn==2.8.1 --no-build-isolation
+# pip install "flash-attn>=2.8.3" --no-build-isolation
 
 pip install -e ".[dev]"  # 用于调试和开发
 ```
@@ -274,36 +281,41 @@ pip install -e ".[vllm,flash_attn]"
 # pip install -e ".[tinker]"
 
 # 如果安装 flash-attn 时遇到问题，可尝试：
-# pip install flash-attn==2.8.1 --no-build-isolation
+# pip install "flash-attn>=2.8.3" --no-build-isolation
 
 pip install -e ".[dev]"  # 用于调试和开发
 ```
 
-**使用 uv**
+**手动使用 uv**
 
 [`uv`](https://github.com/astral-sh/uv) 是现代的 Python 包管理工具。
 
 ```bash
-uv sync --extra vllm --extra dev --extra flash_attn
+uv venv .venv
+
+uv pip install \
+  --python .venv/bin/python \
+  --overrides scripts/install/trinity-overrides.txt \
+  -e ".[vllm,dev]"
+
+.venv/bin/python scripts/install/install_flash_attn.py --uv
 
-# 如果没有GPU，可以改为使用Tinker：
-# uv sync --extra tinker --extra dev
+# 如果没有 GPU，可以改用 Tinker：
+# uv pip install --python .venv/bin/python -e ".[tinker,dev]"
+
+source .venv/bin/activate
 ```
 
+脚本会安装匹配当前环境的第三方 [flash-attn wheel](https://github.com/mjun0812/flash-attention-prebuild-wheels)。
+如果仍有依赖冲突，可在 `scripts/install/trinity-overrides.txt` 中新增或调整版本约束。
+
 #### 通过 PyPI 安装
 
 如果您只需使用 Trinity-RFT 而不打算修改代码：
 
 ```bash
 pip install trinity-rft
-pip install flash-attn==2.8.1
-```
-
-或使用 `uv`：
-
-```bash
-uv pip install trinity-rft
-uv pip install flash-attn==2.8.1
+pip install "flash-attn>=2.8.3" --no-build-isolation
 ```
 
 > 如需使用 **Megatron-LM** 进行训练，请参考 [Megatron-LM 支持](https://agentscope-ai.github.io/Trinity-RFT/zh/main/tutorial/example_megatron.html)
@@ -398,9 +410,10 @@ export WANDB_API_KEY=<your_api_key>
 wandb login
 ```
 
-对于命令行用户，运行 RFT 流程：
+对于命令行用户，先激活环境，再运行 RFT 流程：
 
 ```shell
+source .venv/bin/activate  # 使用 venv 或 uv 时
 trinity run --config <config_path>
 ```
 

docs/sphinx_doc/source/tutorial/faq.md

@@ -71,7 +71,7 @@ File ".../flash_attn/flash_attn_interface.py", line 15, in ‹module>
 ImportError: ...
 ```
 
-**A:** The `flash-attn` module is not properly installed. Try to fix it by running `pip install flash-attn==2.8.1` or `pip install flash-attn==2.8.1 -v --no-build-isolation`.
+**A:** The `flash-attn` module is not properly installed. Try to fix it by running `pip install "flash-attn>=2.8.3"` or `pip install "flash-attn>=2.8.3" -v --no-build-isolation`.
 
 ---
 

docs/sphinx_doc/source/tutorial/trinity_installation.md

@@ -49,7 +49,7 @@ pip install -e ".[vllm,flash_attn]"
 # pip install -e ".[tinker]"
 
 # If you encounter issues when installing flash-attn, try:
-# pip install flash-attn==2.8.1 --no-build-isolation
+# pip install "flash-attn>=2.8.3" --no-build-isolation
 
 pip install -e ".[dev]"  # for development like linting and debugging
 ```
@@ -66,7 +66,7 @@ pip install -e ".[vllm,flash_attn]"
 # pip install -e ".[tinker]"
 
 # If you encounter issues when installing flash-attn, try:
-# pip install flash-attn==2.8.1 --no-build-isolation
+# pip install "flash-attn>=2.8.3" --no-build-isolation
 
 pip install -e ".[dev]"  # for development like linting and debugging
 ```
@@ -146,14 +146,14 @@ If you just want to use the package without modifying the code:
 
 ```bash
 pip install trinity-rft
-pip install flash-attn==2.8.1  --no-build-isolation
+pip install "flash-attn>=2.8.3" --no-build-isolation
 ```
 
 Or with `uv`:
 
 ```bash
 uv pip install trinity-rft
-uv pip install flash-attn==2.8.1  --no-build-isolation
+uv pip install "flash-attn>=2.8.3" --no-build-isolation
 ```
 
 ---

docs/sphinx_doc/source_zh/tutorial/faq.md

@@ -70,7 +70,7 @@ File ".../flash_attn/flash_attn_interface.py", line 15, in ‹module>
 ImportError: ...
 ```
 
-**A:** `flash-attn` 模块未正确安装。请尝试运行 `pip install flash-attn==2.8.1` 或 `pip install flash-attn==2.8.1 -v --no-build-isolation` 进行修复。
+**A:** `flash-attn` 模块未正确安装。请尝试运行 `pip install "flash-attn>=2.8.3"` 或 `pip install "flash-attn>=2.8.3" -v --no-build-isolation` 进行修复。
 
 ---
 

docs/sphinx_doc/source_zh/tutorial/trinity_installation.md

@@ -49,7 +49,7 @@ pip install -e ".[vllm,flash_attn]"
 # pip install -e ".[tinker]"
 
 # 如果安装 flash-attn 时遇到问题，可尝试：
-# pip install flash-attn==2.8.1 --no-build-isolation
+# pip install "flash-attn>=2.8.3" --no-build-isolation
 
 pip install -e ".[dev]"  # 用于调试和开发
 ```
@@ -66,7 +66,7 @@ pip install -e ".[vllm,flash_attn]"
 # pip install -e ".[tinker]"
 
 # 如果安装 flash-attn 时遇到问题，可尝试：
-# pip install flash-attn==2.8.1 --no-build-isolation
+# pip install "flash-attn>=2.8.3" --no-build-isolation
 
 pip install -e ".[dev]"  # 用于调试和开发
 ```
@@ -147,14 +147,14 @@ docker run -it \
 
 ```bash
 pip install trinity-rft
-pip install flash-attn==2.8.1 --no-build-isolation
+pip install "flash-attn>=2.8.3" --no-build-isolation
 ```
 
 或使用 `uv`：
 
 ```bash
 uv pip install trinity-rft
-uv pip install flash-attn==2.8.1 --no-build-isolation
+uv pip install "flash-attn>=2.8.3" --no-build-isolation
 ```
 
 ---

pyproject.toml

@@ -57,8 +57,7 @@ trinity = "trinity.cli.launcher:main"
 
 [project.optional-dependencies]
 vllm = [
-    # for routed_experts support, please install vllm 0.22.0 or above
-    "vllm>=0.19.1,<=0.23.0",
+    "vllm>=0.22.0,<=0.23.0",
 ]
 sglang = [
     "sglang==0.5.13",