🚀大模型落地开发实战指南！请关注微信公众号：「AGI启程号」 深入浅出，助你轻松入门！
📚 数据分析、深度学习、大模型与算法的综合进阶，尽在CSDN博客主页

用 uv 管包 + 用 Docker 跑 Python 项目（实战总结）

适合场景：Windows/PowerShell 开发、需要“可复现环境”、本地 + 容器双跑、要用到 HuggingFace 缓存、以及接第三方 OpenAI 兼容 API（如 DashScope/Qwen）。

在做 Python 项目（特别是模型评测、RAG、训练相关）时，经常会遇到这些痛点：

• 本地依赖和容器依赖不一致，环境一换就挂；
• Windows 开发，Linux 容器，某些包（如 pywin32）根本装不上；
• HuggingFace 下载慢，镜像重装时数据反复拉取；
• .env 配置不规范，API Key 或 URL 总是报错。

我在近期项目中踩过这些坑，最终总结出一套「Conda + uv 管包」+「Docker 部署」的实践流程。

---

0. 准备工作：虚拟环境与依赖管理

0.1 Conda 和 uv/venv 的关系

• Conda 建环境，uv 管包：

  • Conda 负责建虚拟环境，解决 Python 版本、CUDA 依赖等底层问题。
  • uv/venv 负责 Python 包安装速度与依赖解析。

• 如果你已经在用 Conda 新建了虚拟环境，就不需要再用 uv venv。只要在 Conda 环境里直接用 uv pip install 即可。

👉 最佳实践：

# 新建 Conda 环境
conda create -n pj310 python=3.10

# 激活环境
conda activate pj310

# 在 Conda 环境里用 uv 装包（替代 pip）
uv pip install -r requirements.txt

---

0.2 什么是“冻结依赖”？

• requirements.txt：开发用的主依赖清单（版本可以宽一些）。
• 冻结依赖（freeze）：把当前环境里实际安装的所有包及精确版本记录下来，用于复现或上线。

# 生成冻结依赖（PowerShell）
uv pip freeze --exclude-editable | Out-File -Encoding utf8 requirements-freeze.txt

# 从冻结文件安装（保证100%一致）
uv pip install -r requirements-freeze.txt

👉 实战建议：

• 开发时：用 requirements.txt
• 上线/归档时：生成一份 requirements-freeze.txt

---

0.3 常见报错与解决

报错提示	常见原因	解决方案
No virtual environment found	你在用 uv pip，但没在 venv/Conda 环境中	先激活环境，或加 --system
No solution found when resolving dependencies	包不兼容（Linux 容器装 pywin32）	分平台 requirements，或用条件依赖：pywin32 ; sys_platform=="win32"
硬链接（hardlink）警告	跨盘符复制	可忽略，或设置 $env:UV_LINK_MODE="copy"

---

1. Docker 入门：5 条命令够用

先理解几个概念：

• 镜像（Image）：打包好的环境 + 程序的模板
• 容器（Container）：镜像跑起来的实例
• 构建（build）：生成镜像
• 运行（run）：从镜像启动容器

常用命令（够用版）：

# 构建镜像
docker build -t pj-model-eval:py310 .

# 启动容器
docker run --rm -it --env-file .env -v "F:\code:/work" pj-model-eval:py310

# 查看运行中的容器
docker ps

# 进入容器
docker exec -it <容器ID> bash

# 停止容器并删除
docker stop <容器ID> && docker rm <容器ID>

---

2. Dockerfile 示例（逐行解释）

# 选择基础镜像：官方 Python 3.10 精简版
FROM python:3.10-slim

# 安装系统工具（git、编译工具链），并清理缓存减小体积
RUN apt-get update \
 && apt-get install -y --no-install-recommends git build-essential \
 && rm -rf /var/lib/apt/lists/*

# 设置容器内的工作目录
WORKDIR /work

# 安装 uv 并创建虚拟环境（容器内部）
RUN python -m pip install -U pip uv && uv venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# 拷贝依赖清单并安装（触发缓存命中）
COPY requirements.txt /tmp/requirements.txt
RUN uv pip install -r /tmp/requirements.txt

# 默认进入 bash
CMD ["bash"]

注意点：

• 容器里是 Linux，不要把 Windows 包（如 pywin32）写进 requirements.txt。
• 开发时建议挂载代码（-v），而不是 COPY 全部项目。

---

3. .env 文件配置规范

DASHSCOPE_API_KEY=sk-xxxxxxxx

OPENAI_API_KEY=${DASHSCOPE_API_KEY}
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

EMBEDDING_API_KEY=${DASHSCOPE_API_KEY}
EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EMBEDDING_MODEL=text-embedding-v4

注意：

• 不要加引号
• 不要写行内注释

---

4. HuggingFace 缓存挂载

避免容器内重复下载模型：

docker run --rm -it `
  --env-file .env `
  -e HF_HOME=/hf_cache `
  -v "F:\hf_cache:/hf_cache" `
  -v "F:\working\pj - model_eval:/work" `
  pj-model-eval:py310

---

5. 在容器里运行项目

# 进入容器后执行
python scripts/run_all.py

或分步运行：

python scripts/run_reasoning.py
python scripts/run_rag.py

---

6. 推荐依赖分层

1. requirements.txt（通用依赖）
2. requirements.win.txt（Windows 专属包，如 pywin32）
3. requirements-freeze.txt（冻结依赖，保证100%复现）

---

7. 经验总结（踩坑清单）

• .env 文件禁止加引号、注释
• Windows 路径有空格 → 用引号
• HuggingFace 缓存一定要挂载出来
• Windows/Linux 依赖分开写
• Dockerfile 尽量拆层，缓存命中更快

---

🔚 总结

我的实践流程：

• Conda 建环境 → uv 管包（速度快 + 兼容性好）
• Docker 复现（可移植 + 不受平台限制）
• 缓存挂载 + freeze（提速 + 可回滚）

这样无论是本地开发，还是容器化部署，都能做到稳定、可复现、少踩坑。

---

要不要我帮你在这篇博客开头，再加一个 目录（TOC），方便跳转各个小节？