# PR #41377 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[CI/Build] Skip terratorch + torchgeo while PyPI has lightning quarantined
- 合并时间：2026-04-30 22:59
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/41377

---

# 执行摘要

- 一句话：临时注释 terratorch 依赖修复 pip-compile 失败
- 推荐动作：建议精读此 PR 以学习如何优雅处理外部依赖中断：使用 `pytest.importorskip` 或模块级 `find_spec` + `skipif` 跳过测试，并添加清晰注释和关联 issue 以便后续恢复。该模式可在其他类似场景复用。

# 功能与动机

PyPI 将 `lightning` 项目标记为 quarantined（无发布文件暴露），导致 `terratorch` 和 `torchgeo` 传递依赖 `lightning` 解析失败，约一半 PR 的 `pip-compile` 预提交钩子报错（详见 issue #41376）。此 PR 提供临时 workaround 恢复 CI 稳定性。

# 实现拆解

按以下 5 步实现：
1. 在 `requirements/test/cuda.in` 中注释掉 `terratorch>=1.2.2` 依赖行，添加注释指向 issue #41376 以便后续恢复。
2. 在 `requirements/test/rocm.in` 中注释掉 `terratorch>=1.2.2` 和 `torchgeo==0.7.0`（后者也传递依赖 `lightning`），同样添加恢复指引注释。
3. 重新运行 `pip-compile` 和 `pip-compile-rocm` 预提交钩子，自动更新 `cuda.txt` 和 `rocm.txt` 锁文件，移除了 `terratorch` 及其大量传递依赖。
4. 在四个测试文件中添加跳过逻辑：`tests/models/test_terratorch.py`、`tests/plugins_tests/test_terratorch_io_processor_plugins.py`、`tests/models/multimodal/pooling/test_prithvi_mae.py` 使用模块级 `pytest.importorskip("terratorch")`；`tests/entrypoints/openai/chat_completion/test_vision_embeds.py` 使用 `importlib.util.find_spec` 和 `@pytest.mark.skipif` 装饰器，仅跳过需要 `terratorch` 的 Prithvi 测试用例，不影响同文件中其他模型（如 Qwen3-VL）的测试。
5. 验证 `pip-compile`、`pip-compile-rocm`、`pip-compile-xpu` 三个预提交钩子均通过，且 `grep` 确认 `terratorch` 和 `torchgeo` 已从锁文件中移除。

关键文件：
- `requirements/test/cuda.in`（模块 CUDA 依赖；类别 config；类型 configuration）: CUDA 测试依赖入口文件，注释掉 terratorch 依赖行以绕过 PyPI quarantine，是本次变更的核心触发点。
- `requirements/test/rocm.in`（模块 ROCm 依赖；类别 config；类型 configuration）: ROCm 测试依赖入口，额外注释了 torchgeo（也传递依赖 lightning），是 ROCm 环境下的关键变更。
- `tests/models/test_terratorch.py`（模块 Terratorch 测试；类别 test；类型 test-coverage）: 测试文件，添加 importorskip 确保 terratorch 未安装时测试被优雅跳过而非报错。
- `tests/entrypoints/openai/chat_completion/test_vision_embeds.py`（模块 视觉嵌入测试；类别 test；类型 test-coverage）: 测试文件，添加 skipif 装饰器仅跳过 Prithvi 测试用例，不干扰同文件中其他模型。
- `requirements/test/cuda.txt`（模块 锁文件；类别 docs；类型 documentation）: 自动生成的锁文件，重新编译后移除了 terratorch 及其传递依赖，反映了依赖变更的最终结果。

关键符号：未识别

## 关键源码片段

### `requirements/test/cuda.in`

CUDA 测试依赖入口文件，注释掉 terratorch 依赖行以绕过 PyPI quarantine，是本次变更的核心触发点。

```ini
# Prithvi tests
# terratorch 暂时禁用，因为 PyPI 上的 `lightning` 包处于 quarantine 状态
# （每个已发布的 terratorch 版本都传递依赖 lightning，导致解析器报错
# “no versions of lightning”）。当 PyPI 解除 quarantine 后重新启用。
# 跟踪 issue：#41376。
# terratorch>=1.2.2
imagehash # Required for Prithvi tests
segmentation-models-pytorch>0.4.0 # Required for Prithvi tests

```

### `tests/models/test_terratorch.py`

测试文件，添加 importorskip 确保 terratorch 未安装时测试被优雅跳过而非报错。

```python
import pytest
import torch

from tests.conftest import VllmRunner
from tests.utils import create_new_process_for_each_test

# 如果 terratorch 未安装，跳过模块中所有测试
pytest.importorskip(
    "terratorch",
    reason="terratorch 不可用，因为 PyPI 上的 `lightning` 被隔离（见 #41376）",
)

@create_new_process_for_each_test()  # Hangs otherwise
@pytest.mark.parametrize(
    "model",
    [
        "ibm-nasa-geospatial/Prithvi-EO-2.0-300M-TL-Sen1Floods11",
        "ibm-nasa-geospatial/Prithvi-EO-2.0-300M-BurnScars",
    ],
)
def test_inference(
    vllm_runner: type[VllmRunner],
    model: str,
) -> None:
    # ... 测试体保持不变 ...

```

### `tests/entrypoints/openai/chat_completion/test_vision_embeds.py`

测试文件，添加 skipif 装饰器仅跳过 Prithvi 测试用例，不干扰同文件中其他模型。

```python
import importlib.util
import numpy as np
import pybase64 as base64
import pytest
import requests
import torch

from tests.utils import RemoteOpenAIServer
from vllm.utils.serial_utils import tensor2base64

# Prithvi 需要 terratorch，它在 PyPI 上的 `lightning` 被隔离期间不可用。
# 仅跳过 Prithvi 用例，同文件中的 Qwen3-VL 用例不受影响。
_TERRATORCH_AVAILABLE = importlib.util.find_spec("terratorch") is not None

@pytest.mark.skipif(
    not _TERRATORCH_AVAILABLE,
    reason="terratorch 不可用，因为 PyPI 上的 `lightning` 被隔离（见 #41376）",
)
@pytest.mark.parametrize(
    "model_name", ["ibm-nasa-geospatial/Prithvi-EO-2.0-300M-TL-Sen1Floods11"]
)
def test_single_content(model_name: str):
    # ... 测试体保持不变 ...

```

# 评论区精华

PR 获得简化批准：DarkLight1337 批准，Gemini Code Assist 机器人确认了必要性但未提供额外反馈。没有实质性讨论，整体被视作直接的外因 workaround。

- 暂无高价值评论线程

# 风险与影响

- 风险：临时注释依赖可能被遗忘，导致 Prithvi 模型测试覆盖率长期缺失；但 PR 中添加了指向 issue #41376 的注释，便于追踪恢复。测试跳过逻辑使用标准 `pytest.importorskip` 和 `skipif`，确保测试集不会因缺失依赖而报错。此外，`torchgeo` 在 ROCm 环境下被注释，可能影响相关测试，但 `torchgeo` 当前仅用于测试。总体风险低，但需团队在 PyPI 解除隔离后及时恢复。
- 影响：直接影响 CI 构建：修复了约半数 PR 因 `pip-compile` 失败导致的预提交失败，恢复 CI 稳定性。对用户无影响（`terratorch` 为可选运行时依赖，且从锁文件中移除后不会影响生产镜像构建）。团队需关注 issue #41376 的进展以移除临时 workaround。
- 风险标记：临时 Workaround 可能被遗忘 , Prithvi 测试覆盖暂时丢失

# 关联脉络

- PR #41376 [CI/Build] pre-commit pip-compile fails for ~half of recent PRs: PyPI quarantined the `lightning` project: 此 PR 修复的 issue，描述了依赖解析失败的根本原因和受影响 PR 列表。