DragonArray 文档

在 DragonArray LoongArch 平台上安装 TensorFlow

DragonArray（龙阵列）为 LoongArch 处理器提供原生 TensorFlow wheel 安装包。面向龙芯 3A6000 的 LA664 版本现已发布，并在编译时启用了 LASX 支持。面向龙芯 3A5000 和 3B5000、仅使用 LSX 的 wheel 安装包也已发布。

请使用与您的处理器相匹配的 wheel 安装包。 /download/664 下的文件要求处理器支持 LA664 和 LASX，不能安装在 LA464（3*5000）机器上。

面向龙芯 3C5000、启用 LASX 的专用 wheel 安装包仍在准备中，预计一周内发布。在此期间，3C5000 可以使用 3A5000 的 LSX wheel 安装包，但性能会有所降低。

目前提供的两套软件包均包含 TensorFlow 2.21.0，以及它在 64 位 LoongArch Linux 上使用标准、启用 GIL 的 CPython 3.13 时所需的全部 Python 依赖项。

检查应使用哪套 wheel

请在准备安装 TensorFlow 的机器上运行：

LC_ALL=C lscpu | grep -E 'Architecture|Model name|Flags'

先确认 Architecture 为 loongarch64，再根据处理器型号选择安装包：

处理器	SIMD 支持	应使用的 wheel 安装包
龙芯 3A6000 / LA664	LASX	`tensorflow-3x6000.tar`
龙芯 3A5000 或 3B5000	仅 LSX；`Flags` 中有 `lsx`，但没有 `lasx`	`tensorflow-3a5000.tar`
龙芯 3C5000	LASX	目前使用 `tensorflow-3a5000.tar`；可以正常运行，但性能较低。专用 3C5000 版本发布后请改用该版本。

不要仅根据是否出现 lasx 来选择安装包：3A6000 和 3C5000 都会报告 LASX，但目前应选择不同的安装包。

从源码构建

如需自行编译 TensorFlow，请阅读 TensorFlow 2.21.0 LoongArch 源码构建指南。其中包括完整的补丁流程、native dependency、Bazel configuration、三种 CPU profile 各自的 compiler flag，以及 wheel 验证方法。consolidated tensorflow-2.21.0-loongarch64.patch.gz 也可单独下载，用于其他 build system。

如果发现错误或遇到安装问题，请向 DragonArray 帮助台提交错误报告。提交时请附上 CPU 型号、Linux 发行版、Python 版本和完整的错误输出。

1. 安装编译 Python 所需的工具

pyenv 会从源代码编译 Python，因此请先安装编译器和 Python 的编译依赖项。

银河麒麟 V10、Debian 或 Ubuntu：

sudo apt update
sudo apt install -y \
  build-essential curl git make \
  libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \
  libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev uuid-dev

RHEL、Fedora 或其他基于 RPM 的发行版：

sudo dnf install -y \
  git curl make gcc patch \
  zlib-devel bzip2-devel readline-devel sqlite-devel openssl-devel \
  xz-devel libffi-devel ncurses-devel tk-devel gdbm-devel libuuid-devel

如果系统提供的是 yum 而不是 dnf，请将上述命令中的 dnf 替换为 yum。

2. 安装 pyenv

截至本文撰写时，pyenv 最新的正式标签版本是 pyenv 2.8.1。官方安装脚本会跟踪当前的上游代码，包括新加入的 Python 版本：

curl --fail --location https://pyenv.run | bash

将 pyenv 添加到 Bash：

printf '%s\n' \
  'export PYENV_ROOT="$HOME/.pyenv"' \
  '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' \
  'eval "$(pyenv init - bash)"' \
  >> ~/.bashrc
exec bash

如果使用 Zsh，请将相同设置写入 ~/.zshrc，并将 pyenv init 所在行和最后一条 exec 命令中的 bash 替换为 zsh。

确认 pyenv 可以正常运行：

pyenv --version

3. 安装 Python 3.13

Python 3.13.14 是当前的 Python 3.13 维护版本。请安装启用 GIL 的普通版本，不要选择自由线程的 3.13t 变体。

git -C "$(pyenv root)" pull --ff-only
pyenv install 3.13.14
pyenv global 3.13.14
python --version

最后一条命令应输出 Python 3.13.14。这些 wheel 安装包使用 CPython 3.13.13 编译，并已在 3.13.13 和 3.13.14 上完成测试。

4. 创建并激活虚拟环境

将 TensorFlow 安装在虚拟环境中，可以避免它更改系统 Python 的软件包：

mkdir -p ~/dragon-tensorflow
cd ~/dragon-tensorflow

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

以后打开新终端时，请返回该目录并重新激活虚拟环境：

cd ~/dragon-tensorflow
source .venv/bin/activate

5. 下载并安装与处理器匹配的 wheel 安装包

下载完整的 wheel 软件包，将它解压到本地目录，然后在不访问公共 Python 软件包索引（PyPI）的情况下安装所有 wheel 文件：

龙芯 3A6000（LA664 + LASX）：

cd ~/dragon-tensorflow
curl --fail --location --output tensorflow.tar \
  https://dragon-array.org/download/664/tensorflow-3x6000.tar

龙芯 3A5000 或 3B5000 请使用仅 LSX 的安装包。3C5000 在专用 LASX 版本发布前也可以使用此安装包，但性能会有所降低：

cd ~/dragon-tensorflow
curl --fail --location --output tensorflow.tar \
  https://dragon-array.org/download/3A5000/tensorflow-3a5000.tar

下载任一安装包后，解压并安装：

mkdir -p wheels
tar -xf tensorflow.tar -C wheels

cd wheels/tf-wheelhouse-standard
sha256sum -c SHA256SUMS
cd ../..

python -m pip install --no-index \
  --find-links="$PWD/wheels/tf-wheelhouse-standard" \
  "$PWD"/wheels/tf-wheelhouse-standard/*.whl
python -m pip check

pip check 应以下列内容结束：

No broken requirements found.

验证安装结果：

python -c 'import tensorflow as tf, numpy as np; print("TensorFlow", tf.__version__); print("NumPy", np.__version__)'

6. 可选：使用 DragonArray 实验版 NumPy

请先安装标准 TensorFlow 软件包，然后仅替换 NumPy；TensorFlow 的所有共享依赖项都会保留。

实验版 wheel 与 CPU 型号绑定。请选择同时匹配处理器和 Python 版本的 wheel。不要在这里使用 --find-links：两种处理器版本使用相同的 linux_loongarch64 platform tag，因此 pip 无法安全地区分二者。

龙芯 3C5000（LA464）

龙芯 3A6000（LA664）

上面的 TensorFlow 软件包使用 Python 3.13。在龙芯 3C5000（LA464）上安装：

python -m pip install --no-index --no-deps --force-reinstall \
  'https://dragon-array.org/wheels/numpy-2.5.0.dev0+dragon.unofficial.1-1la464-cp313-cp313-linux_loongarch64.whl'

在龙芯 3A6000（LA664）上安装：

python -m pip install --no-index --no-deps --force-reinstall \
  'https://dragon-array.org/wheels/numpy-2.5.0.dev0+dragon.unofficial.1-1la664-cp313-cp313-linux_loongarch64.whl'

然后验证环境：

python -m pip check
python -c 'import numpy as np; print(np.__version__)'

不要在 3C5000 上安装 LA664 wheel。

如需恢复标准版 NumPy，请重新安装已解压软件包中的标准 wheel：

python -m pip install --no-index --no-deps --force-reinstall \
  "$PWD"/wheels/tf-wheelhouse-standard/numpy-2.5.1-cp313-cp313-linux_loongarch64.whl

7. 尝试一个有趣的示例：识别手写数字

下面这个精简示例会下载 MNIST 手写数字数据集、训练一个小型卷积神经网络，然后报告测试准确率。它只使用 MNIST 的一部分数据，因此可以在配备 8 GB 内存的 LA664 系统上轻松运行。在龙芯 3A6000 上进行实测时，进程的常驻内存峰值约为 1.2 GB。

将以下内容保存为 mnist.py：

import tensorflow as tf
(x, y), (xt, yt) = tf.keras.datasets.mnist.load_data()
x, y, xt, yt = x[:20000, ..., None] / 255.0, y[:20000], xt[:5000, ..., None] / 255.0, yt[:5000]
m = tf.keras.Sequential([tf.keras.Input((28, 28, 1)), tf.keras.layers.Conv2D(16, 3, activation="relu"), tf.keras.layers.MaxPooling2D(), tf.keras.layers.Flatten(), tf.keras.layers.Dense(10, activation="softmax")])
m.compile(optimizer="adam", loss="sparse_categorical_crossentropy", metrics=["accuracy"])
m.fit(x, y, epochs=3, batch_size=256, validation_split=0.1)
print("测试准确率：", m.evaluate(xt, yt, verbose=0)[1])

在已激活的虚拟环境中运行：

python mnist.py

数据集只会在首次运行时下载，并缓存在 ~/.keras/datasets 下。