# PR #45263 完整报告

- 仓库：`vllm-project/vllm`
- 标题：Fix relative allowed local media paths
- 合并时间：2026-06-26 11:45
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/45263

---

# 执行摘要

- 一句话：修复 MediaConnector 相对路径解析
- 推荐动作：建议合并。改动小且精确，配套测试充分，是典型的高质量小修复。

# 功能与动机

用户传递相对路径的 `allowed_local_media_path` 时，路径保持相对形式，而文件 URL 被解析为绝对路径，导致路径比对失败，合法媒体文件被拒绝。

# 实现拆解

该 PR 仅涉及一行关键改动和对应的测试补充：

1. **修正路径解析**：在 `vllm/multimodal/media/connector.py` 的 `MediaConnector.__init__` 中，将 `Path(allowed_local_media_path)` 改为 `Path(allowed_local_media_path).resolve()`，确保 `allowed_local_media_path_` 在后续路径比对前被解析为绝对路径。
2. **新增回归测试**：在 `tests/multimodal/media/test_connector.py` 中新增异步测试函数 `test_fetch_image_local_files_relative_allowed_path`，使用 `tmp_path` 和 `monkeypatch.chdir` 模拟相对路径场景，验证同步和异步 `fetch_image` 均能正确加载文件。

关键文件：
- `vllm/multimodal/media/connector.py`（模块 媒体连接器；类别 source；类型 core-logic）: 核心修复所在文件，仅一行修改，但解决了关键路径比对问题。
- `tests/multimodal/media/test_connector.py`（模块 媒体连接器；类别 test；类型 test-coverage；符号 test_fetch_image_local_files_relative_allowed_path）: 新增回归测试，覆盖相对路径场景，确保修复正确性。

关键符号：MediaConnector.__init__, test_fetch_image_local_files_relative_allowed_path

## 关键源码片段

### `vllm/multimodal/media/connector.py`

核心修复所在文件，仅一行修改，但解决了关键路径比对问题。

```python
# vllm/multimodal/media/connector.py (head)
def __init__(
    self,
    media_io_kwargs: dict[str, dict[str, Any]] | None = None,
    connection: HTTPConnection = global_http_connection,
    *,
    allowed_local_media_path: str = "",
    allowed_media_domains: list[str] | None = None,
) -> None:
    # ... 省略无关代码 ...
    if allowed_local_media_path:
        # 关键修复：使用 .resolve() 将用户指定的相对路径转为绝对路径
        # 这样才能与后面从 file:// URL 解析出的绝对路径正确比对
        allowed_local_media_path_ = Path(allowed_local_media_path).resolve()

        if not allowed_local_media_path_.exists():
            raise ValueError(
                "Invalid `--allowed-local-media-path`: The path "
                f"{allowed_local_media_path_} does not exist."
            )
        if not allowed_local_media_path_.is_dir():
            raise ValueError(
                "Invalid `--allowed-local-media-path`: The path "
                f"{allowed_local_media_path_} must be a directory."
            )
    else:
        allowed_local_media_path_ = None

    self.allowed_local_media_path = allowed_local_media_path_
    # ...

```

### `tests/multimodal/media/test_connector.py`

新增回归测试，覆盖相对路径场景，确保修复正确性。

```python
# tests/multimodal/media/test_connector.py (head)
@pytest.mark.asyncio
async def test_fetch_image_local_files_relative_allowed_path(tmp_path, monkeypatch):
    """Regression test: ensure relative allowed_local_media_path works."""
    media_dir = tmp_path / "media"
    media_dir.mkdir()
    # 创建一个 1x1 的测试图片
    image_path = media_dir / "image.png"
    Image.new("RGB", (1, 1), color=(255, 0, 0)).save(image_path)

    # 将当前工作目录切换到 tmp_path，使得相对路径 "media" 有效
    monkeypatch.chdir(tmp_path)
    # 使用相对路径初始化 MediaConnector
    local_connector = MediaConnector(allowed_local_media_path="media")

    # 验证同步和异步 fetch_image 都能正确加载图片
    image_sync = local_connector.fetch_image(image_path.as_uri())
    image_async = await local_connector.fetch_image_async(image_path.as_uri())

    assert image_sync.size == (1, 1)
    # 验证两张图片内容一致
    assert not ImageChops.difference(image_sync, image_async).getbbox()

```

# 评论区精华

审定过程简单，Reviewer 仅给出 “Thanks for fixing” 的批准意见，无深入讨论。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险极低。改动仅一行，且已有测试覆盖正向用例和边界情况。`.resolve()` 在 Python 3.6+ 中为稳定行为，不会引入回归。
- 影响：影响范围限于使用相对路径设置 `allowed_local_media_path` 的用户，此前功能异常，修复后恢复正常。不改变 API 或行为语义，不影响其他功能。
- 风险标记：暂无

# 关联脉络

- 暂无明显关联 PR