pip 24.0+ 默认启用并正确支持带 --index-url 的 pytorch cuda 轮子（wheel）缓存，升级 pip 即可解决重复下载问题，无需额外配置。
pip 24.0+ 默认启用并正确支持带 --index-url 的 pytorch cuda 轮子（wheel）缓存，升级 pip 即可解决重复下载问题，无需额外配置。
在多虚拟环境开发中频繁安装 torch + CUDA 支持（如 --index-url https://download.pytorch.org/whl/cu121）时，你可能遇到：每次新建 venv 都重新下载约 2.5 GB 的 wheel 文件，即使 pip 官方文档明确说明其默认启用缓存（pip caching docs），但 torch 却始终未出现在 pip cache info 或 pip cache list 中。
根本原因在于 pip 版本兼容性：
在 pip ≤ 23.x 中，当使用 --index-url（尤其是非 PyPI 默认源的显式索引地址）时，部分版本存在缓存逻辑缺陷——pip 未能将远程 wheel 的哈希与缓存键正确关联，导致下载后不写入缓存，或后续安装时无法命中缓存。该问题已在 pip 24.0 及更高版本中修复（参见 pip#12396 等相关 issue）。
✅ 解决方案：升级 pip 至 24.0+
python -m pip install --upgrade pip
升级完成后，验证版本：
pip --version # 应输出类似：pip 24.0.1 from ...
随后执行标准安装命令（无需修改）：
调用百度文档解析API，支持18+格式，提取文本、表格、版面分析、OCR识别及RAG文档分块。适用于文档解析、文本/表格提取、结构分析、扫描件处理。触发词：文档解析、PDF解析、Word解析、表格提取、OCR、文档分析、提取文本、文档结构、扫描识别。
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
✅ 第一次安装会正常下载并自动缓存至本地（路径可通过 pip cache dir 查看，通常为 ~/.cache/pip）；
✅ 后续在其他 venv 中执行相同命令，pip 将直接从缓存复制 wheel，跳过网络下载，耗时从分钟级降至秒级。
? 验证缓存是否生效：
# 查看缓存目录及大小 pip cache info # 列出已缓存的包（应包含 torch-*.whl） pip cache list | grep torch # 清理（可选，调试时使用） # pip cache purge
⚠️ 注意事项：
- 不要设置 PIP_DOWNLOAD_CACHE（已弃用）或 PIP_FIND_LINKS（干扰依赖解析），现代 pip 无需这些变量；
- --index-url 本身不会禁用缓存，问题仅存在于旧版 pip 的实现缺陷；
- 若使用 --no-cache-dir 或 CI 环境中显式禁用了缓存，请确保移除该标志；
- 多 CUDA 版本（如 cu118/cu121/cu124）对应不同 wheel，各自独立缓存，互不冲突。
升级 pip 是最轻量、最可靠且符合官方推荐的解法。从此，无论创建多少个 Python 3.10 venv，PyTorch CUDA 版本都只需下载一次，大幅提升本地开发与 CI 构建效率。
