# PR #40461 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[ROCm] [Wheel] [Bugfix] [Critical] Remove any packages installed from github from rocm.txt e.g `fastsafetensors` as it is incompatible with `uv pip`
- 合并时间：2026-04-22 08:18
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/40461

---

# 执行摘要

- 一句话：移除 ROCm 依赖文件中的 git+ URL 包，修复 uv pip 安装失败问题。
- 推荐动作：该 PR 值得快速浏览，重点关注其如何解决工具链兼容性问题，以及 Dockerfile 中新增的防护逻辑。设计决策上，选择完全移除 git 依赖而非寻找替代方案，反映了对 uv pip 生态的适配优先级。

# 功能与动机

PR body 和关联 Issue #39378 指出，用户在使用 `uv pip install vllm` 安装 ROCm 版本时，因 `fastsafetensors` 包使用 git+ URL 依赖而失败，错误信息为“URL dependencies must be expressed as direct requirements or constraints”。uv pip 不兼容 git+ URL，而 pip install 可以处理，这导致了安装工具链的兼容性问题。

# 实现拆解

1. **移除 git+ URL 依赖**：在 `requirements/rocm.txt` 和 `requirements/test/rocm.txt` 中删除 `fastsafetensors @ git+https://...` 行，仅保留 `amd-quark>=0.8.99`，以消除 uv pip 的解析障碍。
2. **添加 Dockerfile 检查**：在 `docker/Dockerfile.rocm` 中新增一个 RUN 步骤，使用 grep 检查 `common.txt` 和 `rocm.txt` 中是否包含 git+ URL，如果发现则构建失败并提示错误，防止未来再次引入不兼容依赖。
3. **提交历史演进**：提交历史显示作者先尝试将 fastsafetensors 移至仅测试依赖，后完全移除，并最终添加了防护检查，反映了从局部修复到系统性预防的演进过程。

关键文件：
- `docker/Dockerfile.rocm`（模块 部署脚本；类别 infra；类型 infrastructure）: 新增了构建时检查，防止未来在依赖文件中引入 git+ URL，是预防性基础设施变更。
- `requirements/rocm.txt`（模块 依赖配置；类别 config；类型 configuration）: 移除了导致 uv pip 安装失败的 git+ URL 依赖 fastsafetensors，是修复问题的核心变更。
- `requirements/test/rocm.txt`（模块 测试依赖；类别 config；类型 configuration）: 同步更新测试依赖文件，移除 fastsafetensors 的 git 引用，确保测试环境一致性。

关键符号：未识别

## 关键源码片段

### `docker/Dockerfile.rocm`

新增了构建时检查，防止未来在依赖文件中引入 git+ URL，是预防性基础设施变更。

```dockerfile
# Fail if git-based package dependencies are found in requirements files
# (uv doesn't handle git+ URLs well, and packages should be distributed on PyPI)
# Extra notes: pip install is able to handle git+ URLs, but uv doesn't.
RUN echo "Checking for git-based packages in requirements files..." \
 && echo "Checking common.txt for git-based packages:" \
 && if grep -q 'git+' ${COMMON_WORKDIR}/vllm/requirements/common.txt; then \
    echo "ERROR: Git-based packages found in common.txt:"; \
    grep 'git+' ${COMMON_WORKDIR}/vllm/requirements/common.txt; \
    echo "Please publish these packages to PyPI instead of using git dependencies."; \
    exit 1; \
 else \
    echo " ✓ No git-based packages found in common.txt"; \
 fi \
 && echo "Checking rocm.txt for git-based packages:" \
 && if grep -q 'git+' ${COMMON_WORKDIR}/vllm/requirements/rocm.txt; then \
    echo "ERROR: Git-based packages found in rocm.txt:"; \
    grep 'git+' ${COMMON_WORKDIR}/vllm/requirements/rocm.txt; \
    echo "Please publish these packages to PyPI instead of using git dependencies."; \
    exit 1; \
 else \
    echo " ✓ No git-based packages found in rocm.txt"; \
 fi \
 && echo "All requirements files are clean - no git-based packages found"

```

# 评论区精华

review 中主要讨论点：
- **gemini-code-assist[bot] 指出 Dockerfile 检查逻辑不完善**：当前 grep 检查可能因注释行产生误报，且未覆盖 `requirements/test/` 目录下的文件，建议使用更健壮的方法（如 `grep -rq --include="*.txt" -E '^[^#]*git\+'`）。
- **gemini-code-assist[bot] 发现测试依赖残留**：指出 `requirements/test/rocm.txt` 中仍通过 `rocm.in` 间接包含 git 依赖，需要更新源文件并重新生成。
- **gshtras 要求协调修复**：建议与 @AndreasKaratzas 协调以确保正确修复，但未进一步讨论具体方案。
结论：PR 已合并，但 review 中提出的改进建议（如优化检查逻辑、清理测试依赖源）未被采纳或标记为未解决。

- Dockerfile 检查逻辑的健壮性 (design): 未在 PR 中采纳改进建议，检查逻辑保持原样，可能留下误报风险。
- 测试依赖中残留的 git URL (correctness): PR 仅移除了直接引用，但未解决底层源文件问题，依赖可能仍存在。

# 风险与影响

- 风险：技术风险较低：
 - **回归风险**：移除 `fastsafetensors` 可能影响 ROCm 环境下 safetensors 模型的加载性能，但该包原本就是可选的加速依赖，且 Issue 中未报告功能问题，主要风险是潜在的性能下降。
 - **兼容性风险**：变更仅影响使用 uv pip 安装的用户，使用传统 pip 的用户不受影响；Dockerfile 检查可能因误报导致构建失败，但这是预防性措施，不影响运行时。
 - **安全风险**：无新增安全风险。
 - 影响：对用户的影响：直接解决了使用 uv pip 安装 ROCm 版本时的失败问题，提升了安装体验和工具链兼容性。对系统的影响：移除了一个可选的性能优化包，可能轻微影响模型加载速度，但确保了核心功能可用性。对团队的影响：加强了依赖管理规范，通过 Dockerfile 检查防止未来引入不兼容依赖，但未完全采纳 review 建议可能留下技术债务。
 - 风险标记：依赖变更 , 检查逻辑不完善

# 关联脉络

- 暂无明显关联 PR