用 uv 替代 pip / poetry：AI 项目的包管理 + 源配置

pip 装一套 vLLM 全家桶要 80 秒，uv 8 秒——更重要的是它锁文件干净、跨机可复现，下面给一份 GPU 项目的实战配置。

一句话推销

uv 是 Astral 用 Rust 写的 Python 包管理器，定位是 pip + virtualenv + pip-tools + poetry 的合集，速度比 pip 快 10–100 倍。我在 5 个 AI 客户项目里用下来一致结论：老项目不必动，但新项目直接上 uv，没必要再纠结。

一、5 分钟跑起来

# 1) 装 uv（不需要 python，自己带）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2) 新建项目
uv init my-llm && cd my-llm

# 3) 加依赖（自动建 .venv，自动写 pyproject.toml）
uv add torch==2.5.1 vllm==0.7.2 transformers accelerate

# 4) 跑代码（不用 source activate，uv run 自动用项目 venv）
uv run python train.py

# 5) 别人 clone 后一键复现
uv sync          # 按 uv.lock 把环境拉齐

uv.lock 是跨平台 lock 文件（同一份 lock 同时锁 linux-x86_64 / linux-aarch64 / osx-arm64 等），CI 直接 commit 进库就行。

二、配置中国源

项目级——pyproject.toml 里：

[[tool.uv.index]]
name = "tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu124"
explicit = true            # 只对显式声明的包用

[tool.uv.sources]
torch       = { index = "pytorch" }
torchvision = { index = "pytorch" }

explicit = true 关键——pytorch 官方源只放它自己的 wheel，不能当全局源用，必须配合 [tool.uv.sources] 锁到具体包。

全局级——~/.config/uv/uv.toml：

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

临时——环境变量优先级最高：

export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
export UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple/

三、能跑通的国内源（2026 现状）

源	URL	备注
清华	`https://pypi.tuna.tsinghua.edu.cn/simple`	综合最稳，推荐默认
阿里云	`https://mirrors.aliyun.com/pypi/simple/`	速度快，企业用得多
中科大	`https://pypi.mirrors.ustc.edu.cn/simple/`	还在维护
豆瓣	`https://pypi.doubanio.com/simple/`	已经不稳定，不推荐
华为云	`https://repo.huaweicloud.com/repository/pypi/simple/`	备选

注意：HuggingFace、torch.org、xformers 这种非 PyPI 源，国内镜像基本都没有镜像，需要单独配 [[tool.uv.index]] + tool.uv.sources 走原站或自建反代。

四、和老 pip 项目共存

老仓库里只有 requirements.txt，不想动结构？

uv venv                                     # 建 .venv
uv pip install -r requirements.txt          # 老语法、新速度
uv pip compile requirements.in -o requirements.txt   # 锁文件

这是 uv 的 "pip 兼容模式"，行为和 pip 一致但快得多——不需要写 pyproject.toml。

五、CI / Docker 里用 uv

Dockerfile 节选：

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:0.5 /uv /usr/local/bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev          # 严格按 lock 装，不允许漂移

COPY . .
CMD ["uv", "run", "python", "-m", "app"]

--frozen 会保证 CI / 生产环境装出来的依赖和 lock 完全一致；--no-dev 排除 dev 依赖。

六、迁移一份真实数据

我们某个 vLLM + LangChain + Streamlit 项目，180 个直接依赖、1200 个传递依赖：

操作	pip + venv	uv
冷装（无缓存）	3m20s	18s
热装（命中缓存）	1m05s	1.1s
锁文件大小	无 / pip-tools 12KB	uv.lock 38KB（多平台）
跨机复现	看运气	`uv sync` 一致

迁移成本只有写一份 pyproject.toml + 一次 uv lock，强烈建议给团队推。