lora-scripts联邦学习探索：分布式数据下的LoRA协同训练设想
2026/1/20 1:05:27
一、uv 安装步骤（三大主流系统）
以下是 uv 的安装步骤和它与 pip 的常用命令对比，方便你快速上手并迁移使用。
推荐方式（官方一键脚本，最快最稳）
- macOS/Linux
- 打开终端，执行：
curl -LsSf https://astral.sh/uv/install.sh | sh。 - 部分 Linux 可能需要加
sudo以获取权限：curl -LsSf https://astral.sh/uv/install.sh | sudo sh。
- Windows
- 打开 PowerShell（管理员模式可选），执行：
irm https://astral.sh/uv/install.ps1 | iex。 - 若用 CMD，执行：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"。
- 验证安装
- 安装后重启终端，执行
uv --version，显示版本号即成功（如uv 0.1.32）。
备选安装方式
| 方式 | 命令 | 适用场景 |
|---|---|---|
| pip 安装 | pip install uv | 快速测试，不推荐用于生产（非最新版，启动稍慢） |
| pipx 安装 | pipx install uv | 隔离工具依赖，避免污染全局环境 |
| Homebrew（macOS） | brew install uv | 习惯用 Homebrew 管理软件的用户 |
| Cargo（Rust 开发者） | cargo install uv | 已安装 Rust 环境，需自定义编译 |
uv 与 pip 常用命令对比表
| 功能 | pip 命令 | uv 兼容命令 | uv 原生命令（更推荐） | 备注 |
|---|---|---|---|---|
| 安装包 | pip install 包名 | uv pip install 包名 | uv add 包名 | uv 原生会写入 pyproject.toml 并锁定依赖 |
| 从文件安装 | pip install -r requirements.txt | uv pip install -r requirements.txt | uv add -r requirements.txt | 兼容 pip 的 requirements.txt 格式 |
| 卸载包 | pip uninstall 包名 | uv pip uninstall 包名 | uv remove 包名 | 原生命令会清理无用的间接依赖 |
| 列出已安装包 | pip list | uv pip list | - | 输出格式略有差异 |
| 导出依赖清单 | pip freeze > requirements.txt | uv pip freeze > requirements.txt | uv export -o requirements.txt | uv 导出更精准，支持锁定依赖版本 |
| 创建虚拟环境 | python -m venv 环境名 | - | uv venv | uv 创建速度更快，自动管理路径 |
| 激活虚拟环境 | source 环境名/bin/activate（Linux/macOS）环境名\Scripts\activate（Windows） | - | source .venv/bin/activate（Linux/macOS）.venv\Scripts\activate（Windows） | uv 创建的环境默认在 .venv 目录下 |
| 运行脚本 | python 脚本名.py | - | uv run 脚本名.py | 自动使用项目虚拟环境的 Python |
| 初始化项目 | - | - | uv init 项目名 | 生成 pyproject.toml 等项目文件 |
| 安装 Python 版本 | - | - | uv python install 3.11 | 无需额外工具，直接管理 Python 版本 |
关键使用建议
- 兼容优先：若你是从 pip 迁移，可先用
uv pip install等兼容命令，无缝过渡。 - 新项目推荐：直接用 uv 原生命令（如
uv init、uv add），体验更快的依赖管理和环境创建。 - 虚拟环境：uv 创建的虚拟环境默认在项目根目录的 .venv 下，无需手动指定路径，更符合现代项目规范。
二、从 pip 迁移到 uv 的 5 步实战清单
这份清单覆盖虚拟环境迁移、依赖锁定、命令替换、问题排查，确保无缝切换，适配新旧项目。
前提
已按照之前的步骤安装好 uv，执行uv --version验证安装成功。
第 1 步：导出 pip 旧项目的依赖清单
目的：把 pip 管理的项目依赖导出为requirements.txt，供 uv 识别。
- 激活原 pip 虚拟环境
- Linux/macOS：
source venv/bin/activate - Windows：
venv\Scripts\activate
- Linux/macOS：
- 导出依赖
pip freeze>requirements.txt- 退出原环境：
deactivate
第 2 步：用 uv 创建新虚拟环境（替代 venv）
uv 创建虚拟环境更快，默认路径为项目根目录的.venv，更规范。
- 进入项目根目录
- 创建 uv 虚拟环境
uv venv- 激活 uv 虚拟环境
- Linux/macOS：
source .venv/bin/activate - Windows：
.venv\Scripts\activate
激活后终端会显示(.venv)前缀。
- Linux/macOS：
第 3 步：迁移依赖并锁定版本（核心步骤）
uv 支持两种迁移方式，推荐用原生锁定方式，依赖更稳定。
| 迁移方式 | 命令 | 适用场景 |
|---|---|---|
| 兼容 pip 方式 | uv pip install -r requirements.txt | 快速迁移，完全兼容旧依赖 |
| uv 原生方式 | uv add -r requirements.txt | 新项目推荐，自动写入pyproject.toml并生成锁定文件uv.lock |
关键优势：
uv.lock是比requirements.txt更精准的锁定文件，能固定所有间接依赖的版本，避免“在我电脑能跑”的问题。
第 4 步：替换日常 pip 命令（无缝过渡）
把项目中常用的pip命令换成 uv 命令，按下表对应替换即可：
| 日常操作 | 原 pip 命令 | uv 替代命令 | 备注 |
|---|---|---|---|
| 安装单个包 | pip install requests | uv add requests | 自动更新pyproject.toml和uv.lock |
| 卸载包 | pip uninstall requests | uv remove requests | 自动清理无用的间接依赖 |
| 升级包 | pip install --upgrade requests | uv add requests@latest | 指定最新版本 |
| 查看已装包 | pip list | uv list | 输出更简洁，按字母排序 |
| 导出依赖清单 | pip freeze > req.txt | uv export -o req.txt | 可导出兼容 pip 的requirements.txt |
| 运行 Python 脚本 | python main.py | uv run main.py | 自动使用当前虚拟环境的 Python |
第 5 步：常见问题排查（避坑指南）
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
执行uv命令提示“找不到” | 安装后未重启终端，环境变量未生效 | 重启终端，或手动将 uv 路径加入环境变量 |
| 安装包时报“网络错误” | uv 默认从 PyPI 下载，网络不稳定 | 配置国内镜像源：uv config set registry.index-url https://pypi.tuna.tsinghua.edu.cn/simple |
| 部分旧包安装失败 | uv 对极老旧包的兼容性待完善 | 切换回兼容模式安装：uv pip install 旧包名 |
| 虚拟环境激活失败（Windows） | 系统执行策略限制 | 以管理员身份打开 PowerShell，执行：Set-ExecutionPolicy RemoteSigned，然后选“Y” |
三、uv 原生命令的适用场景（推荐用的情况）
当你的项目是现代 Python 项目（用pyproject.toml管理依赖，而非仅requirements.txt），优先用 uv 原生命令，核心场景包括：
1. 新建/管理项目依赖（核心场景）
# 1. 初始化项目（生成 pyproject.toml）uv init my_projectcdmy_project# 2. 添加依赖（自动写入 pyproject.toml，替代 pip install）uvaddnumpy requests# 推荐！比 pip install 快数倍# 3. 移除依赖（自动从 pyproject.toml 删除）uv remove requests# 4. 同步依赖（根据 pyproject.toml 安装/更新，替代 pip install -r requirements.txt）uvsync# 5. 生成锁文件（锁定依赖版本，确保环境一致）uv lock- 优势：自动维护
pyproject.toml（项目依赖清单）和uv.lock（版本锁文件），团队协作时只需共享这两个文件，uv sync即可一键还原环境，比requirements.txt更规范。
2. 管理 Python 版本/虚拟环境
# 创建虚拟环境（替代 venv 模块）uv venv# 管理 Python 版本（安装指定版本的 Python）uv pythoninstall3.12uv python use3.12# 切换当前项目使用的 Python 版本3. 运行/构建项目
# 运行 Python 脚本（自动使用虚拟环境）uv run main.py# 构建 Python 包（生成 wheel/源码包，替代 setuptools）uv build四、uv工具的全局镜像源
通过环境变量配置（全局生效，推荐）
这是最直接且全局生效的方式，适配所有版本的 uv，步骤和之前一致，这里再明确一遍（Windows 系统）：
1.按下Win + R，输入sysdm.cpl回车，打开「系统属性」；
2. 切换到「高级」选项卡 → 点击「环境变量」；
3. 在「用户变量」区域点击「新建」：
变量名：UV_INDEX_URL
变量值：https://pypi.tuna.tsinghua.edu.cn/simple
4. 点击「确定」保存所有设置，关闭所有命令行窗口后重新打开；
5. 验证：执行uv pip install numpy（用 uv 的 pip 兼容接口安装包），会自动从清华源下载，无需额外参数。
5 个常用 Python 镜像源（均支持 pip/uv）
| 镜像源名称 | 镜像源地址 | 特点 |
|---|---|---|
| 清华大学镜像源 | https://pypi.tuna.tsinghua.edu.cn/simple | 国内最常用、速度快、更新及时 |
| 阿里云镜像源 | https://mirrors.aliyun.com/pypi/simple/ | 阿里云服务器，稳定性高，适合阿里云服务器环境 |
| 腾讯云镜像源 | https://mirrors.cloud.tencent.com/pypi/simple/ | 腾讯云节点，南方地区访问速度优 |
| 中科大镜像源 | https://pypi.mirrors.ustc.edu.cn/simple/ | 学术机构维护，更新快，无商业限制 |
| 豆瓣镜像源 | https://pypi.douban.com/simple/ | 老牌镜像源，配置简单，适合测试/轻量使用 |
关键验证步骤
配置完成后，新建一个文件，并创建虚拟环境，激活后
uv 默认要求在虚拟环境中安装包
- 创建虚拟环境（默认会在当前目录生成 .venv 文件夹）
uv venv
- 激活虚拟环境（Windows cmd 命令）
.venv\Scripts\activate
# 3. 激活后，再安装 numpy（此时会自动使用你配置的清华源）
# 安装一个测试包，观察下载地址是否为清华源 uv pip install numpy -v在输出日志中会看到类似Downloading from https://pypi.tuna.tsinghua.edu.cn/…的信息，说明镜像源已生效。
你现在看到的这些日志是uv pip install numpy -v的详细执行过程，核心意思是：uv 已经成功识别你配置的清华镜像源，在虚拟环境中完成了 numpy 的版本筛选、下载和安装，整个过程完全符合预期，没有报错。下面是逐段拆解这些日志的关键信息，让你清楚每一步在做什么。
日志核心信息拆解
1. 环境准备阶段（前几行）
DEBUG Found `cpython-3.13.11-windows-x86_64-none` at `...\.venv\Scripts\python.exe` (active virtual environment) DEBUG Using Python 3.13.11 environment at: .venv- 含义：uv 检测到你已经激活了虚拟环境（
.venv），并确认使用该环境下的 Python 3.13.11（避免污染系统 Python）； - 这是你之前执行
uv venv+ 激活环境的结果，符合 uv 的最佳实践。
2. 依赖检查阶段
DEBUG At least one requirement is not satisfied: numpy DEBUG Adding direct dependency: numpy*- 含义：uv 检查到当前虚拟环境中没有安装 numpy，需要新增这个依赖包。
3. 镜像源生效关键证据（重点）
DEBUG No cache entry for: https://pypi.tuna.tsinghua.edu.cn/simple/numpy/ DEBUG Sending fresh GET request for: https://pypi.tuna.tsinghua.edu.cn/simple/numpy/ ... DEBUG No cache entry for: https://pypi.tuna.tsinghua.edu.cn/packages/.../numpy-2.4.1-cp313-cp313-win_amd64.whl DEBUG Sending fresh GET request for: https://pypi.tuna.tsinghua.edu.cn/packages/.../numpy-2.4.1-cp313-cp313-win_amd64.whl- 核心含义：uv 正在从你配置的清华大学镜像源（而非官方 pypi.org）请求 numpy 包，这证明你之前设置的
UV_INDEX_URL环境变量已经生效！ - 这是最关键的验证点，说明镜像源配置成功。
4. 版本筛选阶段（大量 WARN 行）
WARN Skipping file for numpy: numpy-1.0.1.dev3460.win32-py2.4.exe WARN Skipping file for numpy: numpy-1.3.0.win32-py2.5.exe ...（一堆类似 WARN 行）- 含义：uv 会遍历镜像源里所有 numpy 版本，但会跳过和你当前环境不兼容的版本（比如适配 Python 2.4/2.5/3.1 等旧版本的安装包，而你用的是 Python 3.13）；
- 这些 WARN 不是报错，只是正常的版本筛选，无需担心。
5. 版本选择与下载阶段
DEBUG Selecting: numpy==2.4.1 [compatible] (numpy-2.4.1-cp313-cp313-win_amd64.whl) Downloading numpy (11.7MiB) Downloaded numpy- 含义：uv 最终选中了和你 Python 3.13 兼容的 numpy 2.4.1 版本（64位 Windows 适配包），并从清华源下载完成（11.7MB）。
6. 安装完成阶段
Prepared 1 package in 2.35s Installed 1 package in 460ms- 含义：numpy 包的准备（解压、校验）耗时 2.35 秒，实际安装到虚拟环境仅用了 460 毫秒，整个过程成功完成。
关键结论
这些日志没有任何错误，反而证明了两件你最关心的事：
- 虚拟环境配置成功：uv 正确识别并使用了
.venv虚拟环境，没有污染系统 Python； - 清华镜像源配置生效：所有下载请求都指向
https://pypi.tuna.tsinghua.edu.cn，而非官方源，下载速度会比直接连国外源快很多。
总结
- 这些日志是 uv 安装 numpy 的详细过程，核心是从清华镜像源下载并安装了兼容的 numpy 版本；
- 日志中的
WARN是正常的版本筛选，不是报错； - 关键验证点：日志中出现清华源地址 → 镜像源配置成功；最终显示
Installed 1 package→ numpy 安装成功。
你现在可以在虚拟环境中执行python -c "import numpy; print(numpy.__version__)"，会输出2.4.1，进一步确认 numpy 已成功安装。