alphamayo

Alpamayo 环境配置问题记录（ai生成）

1. 问题背景

在配置 Alpamayo 项目环境时，主要遇到了两类问题：

  1. flash-attn 安装失败
  2. Hugging Face 权限认证与模型下载过程不稳定

项目相关文件：

2. 第一个核心问题：flash-attn 安装失败

解释

2.1 现象

执行：

UV_HTTP_TIMEOUT=600 UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple" uv sync

报错类似：

Failed to build `flash-attn==2.8.3`
RuntimeError: FlashAttention is only supported on CUDA 11.7 and above.

2.2 原因分析

虽然 PyTorch 显示的是 CUDA 12.x 环境，但本机 nvcc 版本只有 11.5：

nvcc -V

输出为：

Cuda compilation tools, release 11.5

而 flash-attn 在没有匹配 wheel 时，会退回到源码构建。
源码构建时会调用本机 nvcc，因此因为 CUDA 编译工具链版本太低而失败。

2.3 什么是源码构建

当安装 Python 包时，安装器会优先寻找与你当前环境匹配的 .whl 文件。

如果找不到合适的 wheel，就会：

  1. 下载源码包
  2. 在本机编译
  3. 生成可导入的二进制模块

flash-attn 属于带 CUDA 扩展的包，因此源码构建依赖本机 CUDA 编译环境。

3. 第二个问题：为什么一开始会看到不同的 torch 版本

3.1 现象

前一次报错里看到：

torch.__version__ = 2.8.0+cu128

后一次又看到：

torch.__version__ = 2.4.0+cu121

3.2 原因

项目的依赖声明在 pyproject.toml 中固定为：

"torch==2.4.0",

但在不同阶段中，flash-attn 构建时看到的 torch 版本可能不同：

  1. 一次是构建隔离环境中的 torch
  2. 一次是项目 .venv 中同步后的 torch

因此日志里出现过两个版本，并不代表手动装过 torch。

4. 第三个问题：下载的 wheel 一开始不对

4.1 一开始误区

最开始尝试下载的是与 torch2.8 对应的 wheel。
但项目真实依赖是 torch==2.4.0，所以应该下载与 torch2.4 匹配的 wheel。

4.2 正确 wheel

最终确认应使用：

flash_attn-2.8.3+cu12torch2.4cxx11abiFALSE-cp312-cp312-linux_x86_64.whl

原因：

  • torch==2.4.0
  • Python 版本为 3.12
  • 系统是 Linux x86_64
  • cu12 对应 CUDA 12.x 系列
  • wheel 已经预编译完成，不需要本地 nvcc

5. 第四个问题：为什么 wheel 安装时提示 “not a supported wheel on this platform”

5.1 现象

执行 wheel 安装时报：

is not a supported wheel on this platform

5.2 原因

当时调用的是 base 环境的 Python 3.13，而 wheel 文件是：

cp312-cp312

这意味着它只适用于 Python 3.12。

项目实际环境是：

/home/qiqi/alpamayo-main/.venv/bin/python

因此必须用 .venv 里的 Python 安装 wheel，而不能直接用 base 里的 pip。

6. 第五个问题：为什么手动安装成功后，uv sync 还会重新编译 flash-attn

6.1 原因

因为 uv.lock 一开始锁定的是 registry 上的源码包，而不是本地 wheel。

也就是说：

  1. 手动 pip install 成功了
  2. 但 uv sync 仍然按照 lock 文件重新安装
  3. lock 文件指向源码分发包
  4. 因此 uv 又去源码构建，重新失败

6.2 正确解决方案

不能直接手改 uv.lock，因为它是自动生成文件。

正确方法是修改 pyproject.toml 中的依赖来源，让 flash-attn 直接指向本地 wheel。

7. 对 pyproject.toml 的修改方案

7.1 原来的依赖

"flash-attn>=2.8.3",

7.2 修改后的依赖

"flash-attn @ file:///home/qiqi/alpamayo-main/flash_attn-2.8.3+cu12torch2.4cxx11abiFALSE-cp312-cp312-linux_x86_64.whl",

7.3 为什么改 pyproject.toml 而不是改 uv.lock

因为：

  1. pyproject.toml 是依赖声明源头
  2. uv.lock 是根据它自动生成的结果
  3. 直接改 uv.lock 下次会被覆盖

另外，已保留原始备份文件：

  • pyproject.toml.backup-20260327-1

8. 关键环境修复命令

8.1 安装正确的 wheel

cd /home/qiqi/alpamayo-main
.venv/bin/python -m ensurepip --upgrade
.venv/bin/python -m pip uninstall -y flash-attn flash_attn
.venv/bin/python -m pip install --force-reinstall ./flash_attn-2.8.3+cu12torch2.4cxx11abiFALSE-cp312-cp312-linux_x86_64.whl

8.2 重新锁定并同步依赖

cd /home/qiqi/alpamayo-main
UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple" uv lock --refresh-package flash-attn
UV_HTTP_TIMEOUT=600 UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple" uv sync

8.3 验证环境

cd /home/qiqi/alpamayo-main
.venv/bin/python -c "import torch, flash_attn; print('torch', torch.__version__, torch.version.cuda); print('flash_attn', flash_attn.__version__)"

9. Hugging Face 权限与登录问题

9.1 权限申请

需要申请两个资源的访问权限：

  1. 数据集权限
    https://huggingface.co/datasets/nvidia/PhysicalAI-Autonomous-Vehicles

  2. 模型权限
    https://huggingface.co/nvidia/Alpamayo-R1-10B

网页中能看到文件列表，说明网页权限已开通。

10. Hugging Face 登录问题

10.1 一开始遇到的问题

hf auth whoami 或 huggingface-cli login 看起来像“卡住”。

10.2 原因

本质是网络问题，而不是 token 一定无效：

  1. 直连 huggingface.co 被 reset / timeout
  2. 本地代理端口并没有真正启动
  3. 所以认证请求始终不能完成远程验证

10.3 采用的方式

使用环境变量 HF_TOKEN 临时提供 token，不强依赖 CLI 登录状态。

示例：

export HF_TOKEN='你的token'

然后程序运行时会自动读取这个 token。

11. hf_transfer 报错问题

11.1 现象

运行推理时出现：

ValueError: Fast download using 'hf_transfer' is enabled ... but 'hf_transfer' package is not available

11.2 原因

之前设置了：

export HF_HUB_ENABLE_HF_TRANSFER=1

但环境中没有安装 hf_transfer 包。

11.3 最简单解决方式

直接关闭该环境变量：

unset HF_HUB_ENABLE_HF_TRANSFER

然后重新运行推理。

12. 当前最终运行命令

cd /home/qiqi/alpamayo-main
unset HF_HUB_ENABLE_HF_TRANSFER
.venv/bin/python src/alpamayo_r1/test_inference.py

如果需要 token：

export HF_TOKEN='你的token'
.venv/bin/python src/alpamayo_r1/test_inference.py

13. 当前状态

目前环境已经基本配置成功，主要表现为：

  1. torch 可正常导入
  2. flash-attn 可正常导入
  3. 数据集小文件已成功下载
  4. 模型配置文件、tokenizer 文件已下载
  5. 5 个模型分片已经开始正常下载

当前终端显示的大文件下载日志属于正常运行阶段，不是环境错误。

14. 经验总结

这次问题的关键经验有四点：

  1. 对于带 CUDA 扩展的 Python 包，优先寻找匹配 wheel，避免源码构建
  2. 安装 wheel 时必须确认 Python 版本与 wheel 标签一致
  3. uv.lock 不应手改，应通过修改 pyproject.toml 来影响 lock 结果
  4. Hugging Face 登录“卡住”很多时候不是 token 错，而是网络或代理链路问题

15. 后续建议

  1. 等待模型分片下载完成
  2. 若下载中断，可重新执行推理命令，通常会复用已下载缓存
  3. 后续若长期使用，建议解决本机 Hugging Face 访问链路问题，避免每次依赖 HF_TOKEN 环境变量

如果你想，我也可以直接把这份内容保存成项目里的一个记录文件，比如 `setup_notes.md`。如果你想，我也可以直接把这份内容保存成项目里的一个记录文件，比如 `setup_notes.md`。
posted @ 2026-04-01 16:36  MineralWaterAndCola  阅读(92)  评论(0)    收藏  举报