第一部分：部署前奏——硬件与系统的“裸机”准备

在触碰任何代码之前，我们需要让香橙派处于“裸奔”但强壮的状态。非Docker部署意味着所有的依赖库都会直接安装在系统中，因此一个干净的系统起点至关重要。

1.1 烧录Ubuntu镜像：针对不同芯片的抉择

香橙派旗下有多款型号，分别基于Rockchip（瑞芯微）和昇腾芯片，其烧录方式略有不同，但核心逻辑一致。

针对Rockchip芯片（如Orange Pi 5 Plus）：

1. 下载镜像：前往Orange Pi官方下载页面，下载对应的Ubuntu镜像（通常是OrangePi5Plus_xxxx_Ubuntu_jammy_desktop.img.xz）。

2. 烧录工具：使用balenaEtcher或Rufus（Windows）或dd命令（Linux/Mac）。

   bash

   # 在Linux/Mac下使用dd命令（请谨慎确认of=/dev/sdX是你的SD卡）
   sudo dd if=OrangePi5Plus_xxxx_Ubuntu_jammy_desktop.img of=/dev/sdX bs=4M status=progress && sync

针对昇腾芯片（如Orange Pi AIpro / AI Studio）：

1. 下载镜像：昇腾芯片的镜像通常预装了CANN（华为异构计算架构）的部分内核驱动。从官方网盘下载带有昇腾字样的Ubuntu镜像。

2. 烧录：同样使用balenaEtcher。烧录完成后插入开发板，上电开机。

1.2 首引导配置：固化IP与换源

系统启动后，默认登录密码根据版本不同可能是orangepi、Mind@123或root，请查阅说明书。

1. 连接网络（静态IP推荐）：
   为了后续SSH调试不中断，建议在开发板上设置静态IP。

   bash

   # 编辑Netplan配置（Ubuntu 22.04+）
   sudo vim /etc/netplan/01-network-manager-all.yaml

   添加如下配置（以有线网卡为例）：

   yaml

   network:
     version: 2
     renderer: NetworkManager
     ethernets:
         eth0:
             dhcp4: no
             addresses: [192.168.1.100/24]  # 替换为你想要的固定IP
             gateway4: 192.168.1.1
             nameservers:
                     addresses: [114.114.114.114, 8.8.8.8]

   bash

   sudo netplan apply

2. 换源（ARM架构的特殊性）：
   香橙派的CPU通常是ARM架构（aarch64），必须使用支持ARM架构的软件源。将/etc/apt/sources.list替换为清华或中科大的ARM源。

   bash

   sudo sed -i 's@ports.ubuntu.com@mirrors.tuna.tsinghua.edu.cn@g' /etc/apt/sources.list
   sudo apt update && sudo apt upgrade -y

1.3 核心依赖安装：开发三板斧

无论跑什么算法，编译工具和基础库是必须的。

bash

sudo apt install -y build-essential cmake git wget curl \
    libopencv-dev python3-pip python3-venv \
    ffmpeg libatlas-base-dev libhdf5-dev  # 机器学习及多媒体库

注意：此处的libopencv-dev是系统级别的OpenCV，后续若使用Python的opencv-python可能会产生冲突，建议在虚拟环境中隔离。

---

第二部分：传统算法部署实战——SVM图像识别系统

本章节以部署一个局部放电图像识别系统为例，涉及scikit-learn、FastAPI。这是最简单的“复制-运行”类型部署。

2.1 项目结构解析

一个标准的非Docker算法项目应包含模型文件、依赖清单和启动脚本。

text

~/pd_recognition_system/
├── svm_fastapi.py          # API服务主程序
├── svm_pd_model/            # 预训练模型目录
│   ├── svm_model.pkl        # 训练好的SVM模型
│   ├── svm_scaler.pkl       # 数据标准化处理器
│   └── svm_pca.pkl          # PCA降维模型
├── requirements.txt         # Python依赖清单
└── test_dataset/            # 测试图片

2.2 虚拟环境：非Docker部署的“救命稻草”

由于是非Docker部署，为了防止污染系统Python（Ubuntu系统依赖Python环境），必须创建虚拟环境。

bash

# 进入项目目录
cd ~/pd_recognition_system

# 创建虚拟环境（使用系统Python3）
python3 -m venv svm_venv --system-site-packages
# 参数 --system-site-packages 允许访问系统库（如已安装的OpenCV），按需使用

# 激活环境
source svm_venv/bin/activate

# 确保pip是最新的，且使用国内源
pip install --upgrade pip setuptools wheel -i https://pypi.tuna.tsinghua.edu.cn/simple

2.3 安装依赖与运行

1. 编写requirements.txt：

   txt

   fastapi==0.104.1
   uvicorn[standard]==0.24.0
   python-multipart==0.0.6
   numpy==1.24.3
   scikit-learn==1.3.2
   opencv-python-headless==4.8.1.78  # 使用headless版本减少GUI依赖
   pillow==10.1.0
   joblib==1.3.2

2. 安装：

   bash

   pip install -r requirements.txt

   避坑指南：在ARM架构的香橙派上，scikit-learn 和 numpy 如果pip下载的是预编译的wheel包（manylinux），可能会因为CPU指令集不兼容（如缺少AVX指令）而崩溃。此时需要从源码编译，或安装conda来解决。若遇到Illegal instruction错误，请卸载后尝试：

   bash

   pip install --no-binary :all: scikit-learn numpy

   （这需要系统有足够的内存和编译环境，在2GB内存的开发板上可能失败，建议使用conda管理）

3. 编写服务启动脚本：
   确保svm_fastapi.py中模型路径使用相对路径，并正确加载pkl文件。

   python

   # 在代码中加载模型的部分
   import joblib
   import os
   
   BASE_DIR = os.path.dirname(os.path.abspath(__file__))
   MODEL_PATH = os.path.join(BASE_DIR, "svm_pd_model/svm_model.pkl")
   SCALER_PATH = os.path.join(BASE_DIR, "svm_pd_model/svm_scaler.pkl")
   
   model = joblib.load(MODEL_PATH)
   scaler = joblib.load(SCALER_PATH)

4. 启动服务：

   bash

   # 确保虚拟环境已激活
   uvicorn svm_fastapi:app --host 0.0.0.0 --port 8000 --reload

   此时，在局域网内访问 http://<香橙派IP>:8000/docs 即可看到FastAPI的自动生成文档。

---

第三部分：轻量级视觉模型部署——OpenCV与NPU加速

对于边缘端，视觉任务是最常见的。本章以人脸检测为例，对比CPU运行与NPU（针对RK3588）运行的差异。

3.1 CPU推理：基于OpenCV Haar Cascade

这是最快捷的方式，不依赖任何NPU驱动。

1. 下载预训练XML：

   bash

   wget https://raw.githubusercontent.com/opencv/opencv/master/data/haarcascades/haarcascade_frontalface_default.xml

2. 编写Python脚本 (face_detection_cpu.py)：

   python

   import cv2
   import sys
   
   # 加载分类器
   face_cascade = cv2.CascadeClassifier('haarcascade_frontalface_default.xml')
   
   # 打开摄像头 (通常0是板载摄像头，如果使用USB摄像头可能是1)
   cap = cv2.VideoCapture(0)
   cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)
   cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)
   
   while True:
       ret, frame = cap.read()
       if not ret:
           break
       gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
       faces = face_cascade.detectMultiScale(gray, 1.1, 5)
       
       for (x, y, w, h) in faces:
           cv2.rectangle(frame, (x, y), (x+w, y+h), (255, 0, 0), 2)
       
       cv2.imshow('Face Detection', frame)
       if cv2.waitKey(1) & 0xFF == ord('q'):
           break
   
   cap.release()
   cv2.destroyAllWindows()

3. 运行：

   bash

   python3 face_detection_cpu.py

3.2 NPU推理：针对RK3588的RKNN模型转换与部署

如果你使用的是Orange Pi 5 Plus (RK3588)，其内置的NPU能提供高达6 TOPS的算力，但必须将模型转换为.rknn格式。

注意：此过程需要在x86_64架构的PC虚拟机上进行模型转换，然后在ARM64的香橙派上运行。

3.2.1 在PC端（Ubuntu 20.04 x86_64）进行模型转换

1. 安装RKNN-Toolkit2：

   bash

   git clone https://github.com/rockchip-linux/rknn-toolkit2.git
   cd rknn-toolkit2
   # 安装系统依赖
   sudo apt-get install libxslt1-dev zlib1g-dev libglib2.0 libsm6 libgl1-mesa-glx libprotobuf-dev gcc
   
   # 进入对应Python版本的目录（以Python 3.8为例）
   cd rknn-toolkit2/packages
   pip3 install rknn_toolkit2-1.5.2-cp38-cp38-linux_x86_64.whl

2. 准备模型并转换（以YOLOv8为例）：
   将PyTorch或ONNX模型转换为RKNN。

   python

   # convert_to_rknn.py (在PC上运行)
   from rknn.api import RKNN
   
   # 创建RKNN对象
   rknn = RKNN(verbose=True)
   
   # 配置模型输入（预处理配置）
   rknn.config(mean_values=[[0, 0, 0]], std_values=[[255, 255, 255]], target_platform='rk3588')
   
   # 加载ONNX模型
   ret = rknn.load_onnx(model='./yolov8n.onnx')
   
   # 构建RKNN模型
   ret = rknn.build(do_quantization=True, dataset='./dataset.txt')  # dataset.txt为校准图片路径
   
   # 导出RKNN模型
   ret = rknn.export_rknn('./yolov8n_rk3588.rknn')
   
   rknn.release()

3.2.2 在香橙派上部署RKNN模型

1. 安装RKNN Runtime库：
   在香橙派的Ubuntu上，需要安装librknnrt.so。通常可以从官方的Debian仓库或下载的SDK中获取。

   bash

   # 假设已经从PC复制了runtime到开发板
   sudo cp librknnrt.so /usr/lib/
   sudo ldconfig
   
   # 或者通过pip安装对应的Python API
   pip install rknn-toolkit2-lite-1.5.2-cp310-cp310-linux_aarch64.whl

2. 编写推理脚本 (face_detection_npu.py)：

   python

   import cv2
   import numpy as np
   from rknnlite.api import RKNNLite  # 使用lite模式
   
   # 初始化
   rknn = RKNNLite()
   
   # 加载之前转换好的RKNN模型
   ret = rknn.load_rknn('./yolov8n_rk3588.rknn')
   
   # 初始化运行时环境（指定核心：0,1,2,3 或 RKNNLite.NPU_CORE_0）
   ret = rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0)
   
   # 打开摄像头
   cap = cv2.VideoCapture(0)
   
   while True:
       ret, frame = cap.read()
       if not ret:
           break
       
       # 预处理：调整大小并归一化（必须与config阶段一致）
       img = cv2.resize(frame, (640, 640))
       img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
       
       # NPU推理
       outputs = rknn.inference(inputs=[img])
       
       # 后处理（省略NMS和画框代码，根据模型输出格式解析）
       # ...
       
       cv2.imshow('NPU Face Detection', frame)
       if cv2.waitKey(1) & 0xFF == ord('q'):
           break
   
   rknn.release()
   cap.release()
   cv2.destroyAllWindows()

---

第四部分：大语言模型（LLM）部署——MiniCPM与昇腾CANN

在香橙派AI Studio或AIpro上部署LLM，需要充分利用昇腾的NPU。本章以部署MiniCPM-3B模型为例，展示非Docker环境下如何配置CANN工具链并启动OpenAI兼容的API服务。

4.1 昇腾CANN基础环境配置

CANN是昇腾AI处理器的底层使能软件，非Docker部署意味着我们要直接在系统中安装这些庞大的驱动和库。

1. 下载CANN Toolkit：
   前往昇腾社区下载对应版本的Ascend-cann-toolkit（注意选择linux-aarch64）。

   bash

   wget https://ascend-repo.obs.cn-north-4.myhuaweicloud.com/CANN/CANN%208.0.RC1/Ascend-cann-toolkit_8.0.RC1_linux-aarch64.run

2. 安装CANN：

   bash

   chmod +x Ascend-cann-toolkit_8.0.RC1_linux-aarch64.run
   # 安装到默认路径 /usr/local/Ascend
   sudo ./Ascend-cann-toolkit_8.0.RC1_linux-aarch64.run --install
   
   # 安装Kernels包（针对310B芯片）
   chmod +x Ascend-cann-kernels-310b_8.0.RC1_linux-aarch64.run
   sudo ./Ascend-cann-kernels-310b_8.0.RC1_linux-aarch64.run --install

3. 配置环境变量（关键步骤）：
   非Docker部署下，每次重启或新开终端都需要设置环境变量。建议写入~/.bashrc。

   bash

   echo 'source /usr/local/Ascend/ascend-toolkit/set_env.sh' >> ~/.bashrc
   source ~/.bashrc

   验证安装：npu-smi info 应该能看到NPU设备信息。

4.2 安装PyTorch与Ascend插件

昇腾通过torch-npu将NPU设备映射为PyTorch的Device。

1. 安装PyTorch（ARM版）：
   由于是ARM架构，不能直接使用pip官网的x86版本，需要使用华为或conda提供的版本。

   bash

   # 推荐使用Conda管理Python环境（避免系统Python冲突）
   wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh
   bash Miniconda3-latest-Linux-aarch64.sh
   
   conda create -n llm python=3.9
   conda activate llm
   
   # 安装PyTorch (aarch64版本)
   pip3 install torch==2.2.0 torchvision==0.17.0 torchaudio==2.2.0 --index-url https://download.pytorch.org/whl/cpu

2. 安装torch-npu：

   bash

   git clone https://gitee.com/ascend/pytorch.git -b v2.2.0-6.0.rc3  # 根据CANN版本选择分支
   cd pytorch
   bash ci/build.sh --python=3.9
   pip3 install dist/torch_npu-2.2.0.post3-cp39-cp39-linux_aarch64.whl

4.3 部署MiniCPM并提供API服务

这里采用类似rkllm_server_demo的思路，启动一个Flask服务器提供OpenAI兼容接口。

1. 模型准备：
   如果模型需要在昇腾上加速，通常需要转换为适配的格式（如MindSpore的.mindir或通过atb模型）。假设我们已经有了转换后的模型（或直接使用HuggingFace原始模型进行CPU推理，速度极慢）。

2. 编写Flask服务器（参考rkllm示例）：

   python

   # llm_server.py
   from flask import Flask, request, jsonify
   import torch
   import torch_npu
   from transformers import AutoModelForCausalLM, AutoTokenizer
   
   app = Flask(__name__)
   
   # 全局加载模型（在非Docker下，注意内存占用）
   model_path = "/path/to/MiniCPM3-4B"
   tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
   model = AutoModelForCausalLM.from_pretrained(model_path, torch_dtype=torch.float16, trust_remote_code=True)
   
   # 将模型迁移到NPU
   model = model.to('npu:0')
   model.eval()
   
   @app.route('/rkllm_chat', methods=['POST'])
   def chat():
       data = request.json
       messages = data.get('messages', [])
       prompt = messages[-1]['content'] if messages else ""
       
       # 简单的对话模板
       input_ids = tokenizer.encode(prompt, return_tensors='pt').to('npu:0')
       
       with torch.no_grad():
           outputs = model.generate(input_ids, max_new_tokens=256, do_sample=True)
       response = tokenizer.decode(outputs[0][input_ids.shape[1]:], skip_special_tokens=True)
       
       return jsonify({
           "choices": [{
               "message": {"content": response, "role": "assistant"}
           }]
       })
   
   if __name__ == '__main__':
       app.run(host='0.0.0.0', port=8080, threaded=False)  # 多线程可能和NPU有冲突

3. 启动与测试：

   bash

   # 安装依赖
   pip install flask transformers accelerate torch-npu
   
   # 启动服务
   python llm_server.py

   测试请求：

   bash

   curl -X POST http://127.0.0.1:8080/rkllm_chat \
     -H "Content-Type: application/json" \
     -d '{"messages":[{"role":"user","content":"你好，介绍一下你自己"}],"stream":false}'

4.4 性能调优与内存管理

由于是非Docker部署，资源竞争是最大的敌人。

1. CPU隔离与亲和性：
   为了防止其他进程干扰NPU的数据传输线程，可以使用taskset命令将LLM服务绑定到特定CPU核心。

   bash

   # 将服务绑定到CPU核心4-7
   taskset -c 4-7 python llm_server.py

2. 关闭Swap（或谨慎配置）：
   LLM推理时如果使用Swap，会导致性能急剧下降。如果内存不足，程序直接崩溃也比使用Swap好。

   bash

   sudo swapoff -a

   如果确实需要Swap（例如编译时），可以单独创建一个Swap文件，但不要在推理时启用。

3. 设置系统限制：
   对于大模型，文件打开数、内存锁定限制需要调高。

   bash

   # 编辑 /etc/security/limits.conf
   * soft nofile 65536
   * hard nofile 65536
   * soft memlock unlimited
   * hard memlock unlimited

---

第五部分：疑难杂症与系统固化

5.1 供电不足与自动重启

香橙派外接USB摄像头、NPU满载时功耗可能超过20W，必须使用官方推荐的12V/3A以上电源适配器，劣质电源会导致系统随机重启。

5.2 内核模块冲突

如果插入了多个USB设备（如摄像头、串口），设备节点可能变化。建议通过/dev/serial/by-id/或编写udev规则固定设备别名。

bash

# 查看串口设备
ls -l /dev/serial/by-id/

5.3 制作系统镜像备份

当你花费数天时间配置好所有环境后，一定要制作备份。下次直接烧录这个镜像即可，无需重复部署。

bash

# 在PC上读取SD卡，生成.img文件（假设SD卡为/dev/sdb）
sudo dd if=/dev/sdb of=orangepi_backup.img bs=4M status=progress
# 压缩镜像
gzip orangepi_backup.img

结语

非Docker部署算法模型于香橙派，是一次对Linux系统管理、硬件架构（ARMv8）、AI框架底层的全面挑战。它虽然不如Docker那样一键启动、环境隔离，但它赋予了开发者最大的硬件控制权——直接操作NPU、精细化管理内存、实现微秒级的延迟优化。