Skip to content

chore: lock development dependencies with uv - #1576

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

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:

草稿:HyperMulticore 尚未发布正式 wheel。当前 pyproject.toml 使用 http://hyper-multicore-download-url 下的占位地址,uv.lock 保留接入前的锁定结果。正式制品发布后需重新生成锁文件,届时才能运行下列锁定同步示例及门禁。

让 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 安装的元数据目录处理。
  • 基于多核拆仓后的 master。无参数的 build.sh 编译 Indexed Dataset C++ 扩展,再使用同一解释器调用 uv build --wheel 打包。
  • Linux ARM64 和 x86_64 的 npu extra 必须安装 HyperMulticore。下载源按 Python 3.10–3.12 的 ABI 和 CPU 架构匹配 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 开发可在新的独立环境中选择 --extra gpu。

# 将项目虚拟环境放在仓库根目录的 .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

正式制品发布并重新生成锁文件后,Linux Ascend 环境只需选择 npu extra。

# 把 PyTorch、TorchNpu 和 HyperMulticore 一起装入独立的 Ascend 环境。
UV_PROJECT_ENVIRONMENT=.venv-npu uv sync --locked --python 3.12 --extra npu --dev

# 启动训练前,激活 CANN 和 HyperMulticore。
source .venv-npu/bin/activate
source /usr/local/Ascend/cann/set_env.sh
source .venv-npu/bin/hyper_multicore_set_env.bash

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

# 编译 Indexed Dataset C++ 扩展并打包。构建路径见脚本输出的 Wheel: 行。
./build.sh

只需要打包 Python 源码时,可直接指定开发环境的解释器。生成的 wheel 仍带当前解释器的 ABI 和平台标签。

# 只打包 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.):

  • 当前提交 561e582d,基于拆仓后的 master(f908f4d6)。通过 git diff --check、仓库目录检查、pylint、lizard 和 Markdown lint。
  • 用临时 HTTP wheel 验证 Linux ARM64 和 x86_64 上 --extra npu 同时选择 HyperMulticore 与 TorchNpu,CPU 和 GPU 安装预演均未选择 HyperMulticore。
  • 在加入占位源前,Linux ARM64 上主干原构建和 uv 候选构建均产出同一 ABI 标签的 wheel。候选 wheel 经 pip 安装后成功调用 Indexed C++ 扩展。现有 Python 3.12 环境通过 35 项单测、41 项子测试。
  • 当前草稿的 uv lock --check --offline 在下载 HyperMulticore 占位 wheel 时按预期失败。正式 wheel 发布后需重新锁定,验证 CPU、GPU、NPU 同步并运行 Jenkins 门禁。

Self-checklist:

  • 设计:Maintainer 评审待完成。
  • 测试:待正式制品发布后重新验证锁定依赖。
  • 验证:待生成正式锁文件并运行 Jenkins 门禁。
  • 接口:现有公开运行时 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

Copy link
Copy Markdown
Contributor Author

/retest

@mindspore-ai-bot

Copy link
Copy Markdown

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

@mindspore-ai-bot

Copy link
Copy Markdown
Project Name Build_Stage Build Result Details(Full/Incremental) Detail
Coverage Line Coverage ❌ FAILURE 76%/0% Link

@mindspore-ai-bot

Copy link
Copy Markdown
Platform Type Module Excution Time Time Limit
- distributed_data 411.542s 450.0s
- activation_memory 477.142s 375.0s
- shard 251.465s 300.0s
- accuracy 139.627s 120.0s
- pipeline_parallel 795.217s 675.0s
- auto_models 125.388s 150.0s
- optimizer 367.415s 300.0s
- fully_shard 371.618s 600.0s
- tensor_parallel 304.533s 300.0s
- swap_optimizer 402.739s 300.0s
- process_group 80.402s 90.0s
- distributed_checkpoint 108.883s 120.0s
- clip_grad 114.829s 120.0s
- multicore 118.33075s 120.0s
- dtensor 105.026s 120.0s
- expert_parallel 218.32487s 200.0s
- context_parallel 210.666s 240.0s
- llama3_examples 98.669s 120.0s
- init_weights 88.068s 118.75s

@mindspore-ai-bot

Copy link
Copy Markdown
Project Name Build_Stage Build Result Details
Hyper-parallel_Github_Gate - ❌ FAILURE 1739
Smoke_Ascend910b_Torch FAILURE 1739

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