2、环境准备：算能AI盒子的硬件接口、操作系统、开发环境搭建、SDK安装与验证方法

算能AI盒子（如SE5、SM5、SG6系列）本质上是将算能TPU（张量处理器）与通用计算单元（ARM或x86 CPU）集成在一台边缘计算设备中。在开始服务化开发之前，必须对硬件资源、系统环境、SDK工具链有清晰的认识。本章将围绕硬件接口识别、操作系统烧录、开发环境搭建、SDK安装与验证四个维度展开，帮助开发者建立一套可复现、可诊断的基础环境准备流程。

2.1 硬件接口识别与连接规范

算能AI盒子的硬件设计遵循边缘计算设备的通用规范，但不同型号在接口数量和布局上存在差异。以SE5为例，其前面板通常包含电源指示灯、系统状态灯、两个千兆以太网口（GE0/GE1）、两个USB 3.0 Type-A口、一个Type-C调试口以及一个HDMI输出口。后面板则提供DC电源输入（12V/3A或24V/2A，具体以铭牌为准）、音频输入输出、以及一组2.54mm排针用于GPIO和串口调试。

在连接硬件时，需要遵循以下操作顺序：

1. 电源连接：使用原装适配器，先连接设备端，再插入市电插座。避免带电插拔电源线，防止瞬间浪涌损坏主板。
2. 网络连接：将GE0口连接至交换机或路由器，GE1口可配置为第二网段用于数据隔离。默认IP地址通常为192.168.1.10（以出厂标签为准）。
3. 调试连接：Type-C口同时支持ADB调试和串口输出（波特率115200），在Windows下需安装驱动，Linux下通常免驱。
4. 显示连接：HDMI口支持1080P输出，首次启动建议连接显示器观察启动日志。

2.2 操作系统与固件准备

算能AI盒子出厂时通常预装Linux系统，但为了满足服务化开发需求，建议重新烧录官方提供的Ubuntu 20.04 LTS镜像（针对ARM架构）或Buildroot精简系统。烧录过程需要一台Linux主机（或Windows+WSL）作为烧录工具。

烧录流程如下：

# 1. 下载官方烧录工具和镜像
wget https://sophon算能官方镜像站/ubuntu20.04_sd.img.gz
wget https://sophon算能官方镜像站/sd_card_tool.tar.gz

# 2. 解压并进入烧录工具目录
tar -xzf sd_card_tool.tar.gz
cd sd_card_tool

# 3. 查看设备挂载点（注意：/dev/sdX 为SD卡设备）
lsblk

# 4. 执行烧录（以 /dev/sdb 为例）
sudo ./burn_sd.sh -i ubuntu20.04_sd.img.gz -d /dev/sdb

# 5. 烧录完成后，将SD卡插入AI盒子，上电启动

烧录完成后，系统默认账号为root，密码为sophon（以官方文档为准）。首次登录后建议立即修改密码并更新软件源。

2.3 开发环境搭建与依赖安装

开发环境搭建的核心目标是让宿主机（开发PC）与AI盒子之间建立高效的代码编辑、编译、部署链路。推荐采用“宿主机交叉编译 + 盒子端运行”的模式，或者直接在盒子端进行原生编译（适用于小规模项目）。

在盒子端执行以下命令安装基础依赖：

# 更新软件源
apt update && apt upgrade -y

# 安装基础开发工具
apt install -y build-essential cmake git python3-pip \
    libopencv-dev libssl-dev libsqlite3-dev

# 安装Python虚拟环境管理
pip3 install virtualenv virtualenvwrapper

# 安装Docker（可选，用于服务化部署）
curl -fsSL https://get.docker.com | sh
systemctl enable docker && systemctl start docker

对于宿主机交叉编译场景，需要安装算能提供的交叉编译工具链：

# 在宿主机上执行
wget https://sophon算能官方/gcc-aarch64-linux-gnu.tar.gz
tar -xzf gcc-aarch64-linux-gnu.tar.gz -C /opt/
export PATH=/opt/gcc-aarch64-linux-gnu/bin:$PATH
# 验证
aarch64-linux-gnu-gcc --version

2.4 SDK安装与验证方法

算能AI盒子的SDK主要包括三个核心组件：tpu-mlir（模型编译器）、sophon-sail（运行时推理库）、sophon-pipeline（示例流水线）。安装方式分为在线安装和离线安装两种。

2.4.1 在线安装（推荐开发阶段）

# 添加算能软件源
echo "deb https://sophon算能官方/apt stable main" | tee /etc/apt/sources.list.d/sophon.list
wget -O- https://sophon算能官方/apt/key.asc | apt-key add -
apt update

# 安装运行时库
apt install -y sophon-sail sophon-sail-dev

# 安装模型编译器（在宿主机上安装）
pip3 install tpu-mlir -i https://pypi.org/simple

2.4.2 离线安装（生产环境）

# 在联网机器上下载deb包
apt download sophon-sail sophon-sail-dev

# 拷贝到AI盒子后执行
dpkg -i sophon-sail*.deb
apt-get install -f -y

2.4.3 验证SDK是否安装成功

验证分为三个层次：库文件检查、设备识别、实际推理测试。

# 1. 检查库文件
ls /usr/lib/libsophon* /usr/local/lib/libsail*

# 2. 检查TPU设备节点
ls /dev/bmdev* /dev/bm-sochip*

# 3. 运行官方自检程序
python3 -c "import sophon.sail as sail; print('sophon-sail version:', sail.__version__)"

# 4. 运行benchmark测试（以yolov5s为例）
cd /opt/sophon/sophon-pipeline/benchmark
./run_benchmark.sh --model yolov5s.bmodel --input test.jpg

2.5 实战案例：从零搭建人脸检测服务环境

本案例以某园区门禁项目为背景，需要在AI盒子上部署人脸检测模型，并通过HTTP API对外提供服务。项目约束：盒子部署在弱电井内，无显示器，仅能通过网络远程管理；要求模型推理延迟低于50ms；需要支持后续扩展人脸识别功能。

初始现象：新拆封的SE5盒子，预装系统为Buildroot，无法直接安装Python包。

关键决策过程：

1. 重新烧录Ubuntu 20.04镜像，耗时约15分钟，解决了包管理问题。
2. 安装sophon-sail时发现官方源速度慢，改为离线安装方式，从开发机拷贝deb包。
3. 使用虚拟环境隔离项目依赖，避免污染系统Python。
4. 编写验证脚本，使用官方提供的retinaface.bmodel进行首次推理测试。

实际操作步骤：

# 步骤1：烧录系统（在宿主机执行）
sudo ./burn_sd.sh -i ubuntu20.04.img.gz -d /dev/sdb

# 步骤2：盒子端初始化
ssh root@192.168.1.10
passwd  # 修改密码
apt update && apt install -y python3-venv nginx

# 步骤3：安装SDK
dpkg -i sophon-sail_3.7.0_arm64.deb
apt-get install -f -y

# 步骤4：创建虚拟环境并安装依赖
python3 -m venv /opt/face_env
source /opt/face_env/bin/activate
pip install flask gunicorn opencv-python-headless

# 步骤5：验证推理
python3 -c "
import sophon.sail as sail
engine = sail.Engine('/models/retinaface.bmodel', device_id=0)
print('模型加载成功，输入shape:', engine.get_input_shape('input'))
"

结果对比：使用Buildroot系统时，环境搭建耗时约2小时且部分依赖无法解决；更换Ubuntu后，整个环境准备在40分钟内完成。首次推理测试显示，单张640x480图片的人脸检测耗时32ms，满足50ms的延迟要求。

风险与代价：重新烧录系统会丢失出厂预置的示例程序和配置，需要提前备份。此外，Ubuntu系统占用的存储空间比Buildroot多约2GB，对于16GB eMMC版本的盒子需要注意剩余空间。

2.6 常见误区与总结

在环境准备阶段，开发者常遇到以下问题：

• 误区一：忽略电源规格。使用不匹配的电源适配器会导致系统频繁重启或TPU性能不稳定。务必使用原装或符合铭牌规格的电源。
• 误区二：SDK版本不匹配。sophon-sail的版本必须与固件版本对应，否则会出现API调用失败或设备无法识别。使用sophon-sail --version和cat /proc/bmsoc_version核对版本。
• 误区三：交叉编译时未设置sysroot。直接使用宿主机gcc编译的二进制在盒子上运行会报No such file or directory错误，必须使用aarch64交叉编译工具链并指定正确的sysroot。
• 误区四：忽略TPU散热。在密闭环境中长时间高负载运行，TPU温度超过85℃会触发降频保护，导致推理延迟突增。建议在部署时预留通风空间，并监控/sys/class/thermal/thermal_zone0/temp。

总结而言，环境准备的核心目标是建立一条从硬件到应用的可验证链路。硬件接口的规范连接是基础，操作系统的选择决定了开发效率，SDK的正确安装和验证则是后续服务化开发的前提。建议开发者在完成本章所有步骤后，制作一份环境检查清单，记录设备序列号、系统版本、SDK版本、网络配置等关键信息，作为后续排障的基线数据。