Python 环境搭建

AI 开发首选语言：Python。本笔记涵盖 uv（推荐）、venv、pipx、conda 多种方案。

---

uv：2025 年 Python 包管理新标准

为什么选 uv？

对比项	pip	poetry	conda	uv
安装速度	慢	中	慢	10-100x 更快
依赖解析	差	好	中	最优
锁文件	无	有	无	有（uv.lock）
Python 版本管理	无	无	有	有
工具管理	无	无	无	有（uv tool）
Rust 实现	否	否	否	是

uv 由 Astral 公司开发（Ruff 同厂），GitHub Actions 迁移案例显示：依赖安装从 5 分钟缩短到 3 秒，构建成本月均节省 $200。

---

安装 uv（Linux/macOS）

# 方式1: 官方脚本（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方式2: pip 安装（临时）
pip install uv

# 验证
uv --version

全局安装（系统级）：

curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh

---

uv 基础用法

# 创建虚拟环境（替代 venv/virtualenv）
uv venv .venv
source .venv/bin/activate        # Linux/macOS
# .\.venv\Scripts\activate       # Windows

# 安装依赖（替代 pip install）
uv pip install langchain langchain-openai crewai

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 从 pyproject.toml 安装（Poetry 项目零成本迁移）
uv sync

# 运行脚本（自动使用虚拟环境）
uv run python app.py

# 锁定依赖（生成 uv.lock）
uv lock

# 更新依赖
uv lock --upgrade
uv sync

---

uv 管理多个 Python 版本

# 安装特定 Python 版本
uv python install 3.12.3

# 创建使用特定版本的虚拟环境
uv venv --python 3.12 .venv

# 列出可用版本
uv python list

---

uv tool：安装全局工具（替代 pipx）

# 安装全局工具（隔离但全局可用）
uv tool install ruff        # 代码检查
uv tool install httpie      # HTTP 客户端

# 运行全局工具
uv run ruff check .

# 卸载
uv tool uninstall ruff

---

Docker 中的 Python + uv

# 多阶段构建：编译层 + 运行层
FROM python:3.12-slim as builder
WORKDIR /app
RUN pip install uv
COPY requirements.txt .
RUN uv pip install --system --no-cache -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
COPY . .
CMD ["python", "app.py"]

提示：uv 的锁文件 uv.lock 应提交到 Git，配合 uv sync 确保团队成员环境完全一致。

---

pip 备选方案（熟悉pip者）

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装（慢，但稳定）
pip install langchain langchain-openai

# requirements.txt 管理
pip freeze > requirements.txt
pip install -r requirements.txt

---

conda 方案（需要科学计算生态时）

# 安装 Miniconda
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

# 创建环境
conda create -n ai-agent python=3.12
conda activate ai-agent

# 安装 PyTorch（conda 比 pip 更可靠）
conda install pytorch torchvision pytorch-cuda=12.1 -c pytorch -c nvidia

# 安装其他依赖
pip install langchain langgraph

---

AI 开发必备依赖清单

# requirements.txt（2025年AI Agent开发标准栈）
langchain>=0.3.0
langchain-openai>=0.2.0
langgraph>=0.2.0
crewai>=0.80.0
llama-index>=0.11.0
pydantic>=2.0
httpx>=0.27.0
tenacity>=8.0
structlog>=24.0

使用 uv pip install -r requirements.txt 安装，全部命中缓存，速度极快。

---

常见问题

问题	解决
uv 命令找不到	source $HOME/.local/bin/env 或重启终端
安装慢	设置镜像源：uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple
权限错误	不加 --system，用 .venv 本地环境
Windows 支持	支持（PowerShell / CMD / Git Bash），推荐 WSL2

---