Skip to content

chore: lock development dependencies with uv - #1576

Open
liuchongming74 wants to merge 1 commit into
mindspore-ai:masterfrom
liuchongming74:codex/uv-lock-migration
Open

liuchongming74 wants to merge 1 commit into
mindspore-ai:masterfrom
liuchongming74:codex/uv-lock-migration

Conversation

@liuchongming74

@liuchongming74 liuchongming74 commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Paired: GitHub #1576 ↔ GitCode !1953

What type of PR is this?
/kind task


What does this PR do / why do we need it:

让 HyperParallel 的多设备 Python 依赖可复现、可审查。 项目同时维护 CPU、NVIDIA GPU 和 Ascend NPU 的 PyTorch 版本组合及 wheel 来源。uv 将这些规则集中到 pyproject.toml,并把解析出的版本和来源记录在 uv.lock。开发者检出同一提交后,可用 uv sync --locked 在相同平台和设备组合下复现依赖。锁文件过期时,同步会报错,依赖升级也能作为 PR 差异审查。

Conda 环境仍可通过 --python 提供基础解释器,项目依赖同步到独立的 uv 虚拟环境。现有 pip 安装入口、GPU/NPU 训练环境和 Jenkins 门禁继续沿用。

  • 在 pyproject.toml 中声明开发和测试依赖组,便于按用途同步。
  • 复用 requirements.txt 声明运行时依赖。将 8 个 PyTorch extras 统一移到 pyproject.toml,保留版本、平台条件和 pip 安装入口。修正 editable 安装的元数据目录处理。
  • build.sh 复用当前环境的 Python,通过现有组件脚本编译原生库,再用 uv build --wheel 打包暂存产物。
  • 中英文安装指南提供 uv 安装命令,并给出锁定依赖的同步示例。
  • 纳入 chore: assign code ownership for Python packaging files #1581,为根目录的 pyproject.toml、uv.lock 和 setup.py 指定唯一代码所有者 @liuchongming74。强制要求代码所有者审批需在 master 规则集中启用对应选项。

uv 使用示例

以下命令从仓库根目录执行。

1. 使用 uv sync 初始化开发环境

# 若尚未安装 uv,在已激活的 Conda 环境或其他工具环境中安装项目所用版本。
python -m pip install uv==0.11.16

A. 同步到独立的 uv 虚拟环境

UV_PROJECT_ENVIRONMENT 指定依赖安装的位置。以下示例将项目和依赖安装到仓库内的 .venv-uv,系统 Python 和现有训练环境保持原状。Conda 可提供基础解释器,将 --python 3.12 改为 --python "$CONDA_PREFIX/bin/python" 即可。GPU 或 NPU 开发可在新的独立环境中选择 --extra gpu 或 --extra npu。

# 将项目虚拟环境放在仓库根目录的 .venv-uv 下。
export UV_PROJECT_ENVIRONMENT=.venv-uv

# 按 uv.lock 安装可编辑项目、CPU PyTorch 和开发依赖。
uv sync --locked --python 3.12 --extra cpu --dev

# 用虚拟环境的 Python 确认导入指向当前 checkout。
.venv-uv/bin/python -c 'import hyper_parallel; print(hyper_parallel.__file__)'

# 检查锁文件,并用锁定的测试依赖运行本地数据单测。
uv lock --check --python 3.12
uv run --locked --python 3.12 --extra cpu --group test python -m pytest -q \
    tests/ut/data/indexed/ tests/ut/distributed_data/test_indexed_text.py

B. 同步到系统 Python

适用于专用容器等可写的 Python 安装。--inexact 保留项目未声明的包,但仍可能替换项目依赖的已有版本。操作系统管理的 Python 可能拒绝写入。

# 改成目标系统 Python 的绝对路径。此处以容器内的 Python 3.12 为例。
SYSTEM_PYTHON=/usr/local/bin/python3.12

# 获取该解释器的安装前缀,例如 /usr/local。
SYSTEM_PREFIX=$("$SYSTEM_PYTHON" -c 'import sysconfig; print(sysconfig.get_config_var("prefix"))')

# 仅为这条命令覆盖环境路径,按锁文件同步到目标 Python 的 site-packages。
UV_PROJECT_ENVIRONMENT="$SYSTEM_PREFIX" \
    uv sync --locked --python "$SYSTEM_PYTHON" --extra cpu --dev --inexact

也可以用 pip 兼容接口按 requirements.txt 的版本范围安装运行时依赖。

# 复用上面的目标解释器,仅安装 requirements.txt 声明的依赖。
uv pip install --system --python "$SYSTEM_PYTHON" -r requirements.txt

uv 项目环境路径 · uv 系统环境安装

2. 使用 uv 编译和构建 wheel

在 Linux 上,构建含 Indexed Dataset C++ 扩展的 wheel 需要与 Python 版本匹配的开发头文件和 C++17 工具链。build.sh 先编译原生扩展,再让 uv build --wheel 使用同一个 Python 解释器打包。

# 激活第 1 节创建的 .venv-uv,让 build.sh 从 PATH 找到该环境的 Python。
source .venv-uv/bin/activate

# 关闭 Multicore,编译 Indexed Dataset C++ 扩展并打包。构建路径见脚本输出的 Wheel: 行。
./build.sh --multicore off --strict on

只需要纯 Python wheel 时,可直接指定开发环境的解释器。

# 只打包 Python 源码,输出到 dist/core-only。
uv build --wheel --python .venv-uv/bin/python --out-dir dist/core-only

Which issue(s) this PR fixes:

无关联 Issue。


Test Plan and Test result:What scenarios were tested, and what were the verification results(Function, performance, reliability, etc.):

  • 当前源提交 73a72eef。现有 Jenkins 门禁继续沿用。下述原生编译和 pip 打包验证来自 97a93ce7,对应的构建、打包和依赖配置与当前提交一致。
  • 已核对三个 CODEOWNERS 路径都只匹配 @liuchongming74,并通过 git diff --check。
  • Jenkins #1702 对 uv.lock 中三个 PyPI 制品记录报出敏感词误报。将这三个制品的完整 SHA-256 校验值加入现有 Jenkins 白名单。本地核对这些条目仅匹配日志报告的三行。
  • uv 重新解析 146 个包并通过 uv lock --check,uv.lock 逐字节一致。
  • 指定 Linux ARM64 机器执行 build.sh --multicore off --strict on,实际编译 C++ 索引扩展并用 uv 构建 wheel。迁移前后 8 个 extras、Requires-Dist、Requires-Python 和 wheel 标签完全一致,新增 wheel 内的 .so 与暂存文件逐字节一致。
  • pip 安装新 wheel 后从安装目录导入并调用 C++ 索引扩展,通过 pip check。原源码入口 pip install -e '.[cpu]' 通过且导入指向该 checkout。
  • 97a93ce7 在指定 Linux ARM64 机器的隔离环境中通过锁定数据单测(35 项单测、41 项子测试)。当前提交的依赖配置、锁文件和用例与该验证版本一致,可按上面的命令在本地复验。
  • 在先前的锁定安装验证中,修改 requirements.txt 后,uv lock --check 正确拒绝旧锁。
  • CPU、GPU 和 NPU 锁定同步预演分别选择 Torch 2.9.1 CPU、CUDA 12.8、CPU Torch + torch-npu 2.9.1。GPU/NPU 实机训练与 Multicore 构建待相应硬件环境验证。全量 UT/ST 与硬件测试继续由现有 Jenkins 门禁负责。

Self-checklist:

  • 设计:Maintainer 评审待完成。
  • 测试:使用现有数据单测在本地验证锁定依赖。
  • 验证:已记录锁文件、安装、打包和本地单测结果。
  • 接口:现有公开运行时 API 不变。
  • 文档:已更新仓库内安装说明及通用开发命令。

@liuchongming74
liuchongming74 marked this pull request as ready for review November 14, 2026 18:48
@liuchongming74
liuchongming74 force-pushed the codex/uv-lock-migration branch 3 times, most recently from 4094760 to 5b84fae Compare November 15, 2026 06:35
@liuchongming74 liuchongming74 changed the title chore: lock development and CI dependencies with uv chore: lock development dependencies with uv Nov 15, 2026
@liuchongming74
liuchongming74 force-pushed the codex/uv-lock-migration branch from 5b84fae to f01f668 Compare November 15, 2026 06:47
@liuchongming74
liuchongming74 force-pushed the codex/uv-lock-migration branch 4 times, most recently from 5ddd94d to 6e5d40f Compare November 15, 2026 12:50
@liuchongming74

Copy link
Copy Markdown
Contributor Author

/check-pr

@liuchongming74

Copy link
Copy Markdown
Contributor Author

/retest

@mindspore-ai-bot

Copy link
Copy Markdown

🔵 The pipeline #1702 is running. Please wait a moment... (Link)

@mindspore-ai-bot

Copy link
Copy Markdown
Project Name Build_Stage Build Result Details
Hyper-parallel_Github_Gate - ❌ FAILURE 1702
Check_Codespell FAILURE 1702

@mindspore-ai-bot

Copy link
Copy Markdown

@liuchongming74, your gate pipeline failed at the code check stage. You can configure some code check tools locally following the (pre-push quick guide), to enable automatic checking when you push your code every time. Tools included are: Check_CMakelint, Check_Codespell, Check_Cpplint, Check_Lizard, Check_Pylint, Check_ClangFormat, Check_ShellCheck.

@liuchongming74

Copy link
Copy Markdown
Contributor Author

/check-pr

@liuchongming74

Copy link
Copy Markdown
Contributor Author

/retest

@mindspore-ai-bot

Copy link
Copy Markdown

🔵 The pipeline #1703 is running. Please wait a moment... (Link)

@mindspore-ai-bot

Copy link
Copy Markdown
Project Name Build_Stage Build Result Details
Hyper-parallel_Github_Gate - ❌ FAILURE 1703
Compile_Ascend_ARM FAILURE 1703
Compile_Ascend_X86 FAILURE 1703

@liuchongming74
liuchongming74 force-pushed the codex/uv-lock-migration branch from c53765b to 73a72ee Compare November 15, 2026 15:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants