ARM64单板机本地大模型推理部署教程

作者:新兰2026.11.18 11:43浏览量:0

简介:本文面向 ARM64 单板计算机与迷你主机,讲清边缘设备离线推理怎么跑通:先确认架构与磁盘、内存水位,再安装 zstd 依赖、解压并锁定二进制路径 /usr/local/bin/runtime,随后用 systemd 默认监听 127.0.0.1 常驻服务、拉取轻量模型,并给出 systemctl、journalctl、ss、curl 可直接复制的上线验收清单,以及内存/延迟/磁盘的测量口径、备份回滚命令和磁盘不足、权限错误、服务启动失败的逐项排查思路。

一、部署对象与适用场景

本文要部署的是本地大模型推理运行时:一套跑在设备本地的软件组件,负责加载模型权重、对外提供本地推理接口,并以常驻系统服务的形式保活。目标是让一台 ARM64 边缘设备具备”本地拉取并运行轻量级语言模型”的能力,在弱网或完全离线时也能承接推理请求。

典型适用场景:数据不出本地的隐私敏感业务、离线/弱网的边缘 AI 部署、模型验证与学习实验、低成本硬件上的本地大模型服务。

先说明一点:这类运行时是第三方开源项目,本文用 runtime 作为通用占位命令名,统一抽象部署方法与运维逻辑,不涉及具体品牌与专有接口。实际执行时请以你选定项目的 --help 输出为准。

二、先核查环境,再动手安装

资源受限环境部署失败,九成出在装之前没看清家底。

  1. # 1. 确认架构(必须是 aarch64/arm64)
  2. uname -m
  3. dpkg --print-architecture # Debian/Ubuntu
  4. # 2. 确认磁盘,重点看根分区和 /tmp 落在哪个文件系统
  5. df -h /
  6. df -h /tmp
  7. findmnt /tmp # 若显示 tmpfs,说明是内存盘
  8. # 3. 确认内存与交换分区
  9. free -h
  10. swapon --show

判定边界(区分确定项与取决于项):

  • 确定:架构必须匹配。设备报 aarch64 就必须下 ARM64 包,下成 x86_64 一定跑不起来。
  • 确定:/tmp 若为 tmpfs,就不能在 /tmp 下载或解压,否则吃的是内存,会直接 OOM。
  • 取决于:网传”内存 2GB、磁盘 10GB”只是经验下限,真实需求取决于三件事——模型参数量、量化精度、并发数。以 7B 级模型、4bit(Q4)量化估算,权重约占磁盘 4GB,推理时内存驻留约 5–6GB;若换成 0.5B–1.5B 小模型,2GB 内存足够,磁盘 5GB 内也能跑通。上下文长度和并发请求数会进一步放大内存占用。所以:先定模型规格,再定硬件门槛,不要反过来。

三、扩容 Swap:让内存吃紧的设备能撑过加载

边缘设备默认 Swap 常常过小,解压大文件或加载权重时容易中途被杀。

  1. # 首选 fallocate;文件系统不支持时回退 dd(先备份 fstab,改错会导致无法启动)
  2. sudo fallocate -l 4G /swapfile 2>/dev/null || \
  3. sudo dd if=/dev/zero of=/swapfile bs=1M count=4096 status=progress
  4. sudo chmod 600 /swapfile
  5. sudo mkswap /swapfile
  6. sudo swapon /swapfile
  7. swapon --show && free -h # SIZE 出现 4G 即成功
  8. # 持久化:先备份,再写入,最后校验
  9. sudo cp -a /etc/fstab /etc/fstab.bak.$(date +%F)
  10. echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
  11. sudo findmnt --verify # 报 0 errors 再重启

回退方式:从 /etc/fstab 删掉该行 → sudo swapoff /swapfile → sudo rm /swapfile。注意 Swap 只是内存的磁盘扩展,能救急解压,但推理性能仍以物理内存为准。

四、安装依赖与运行时二进制

  1. # 1. 装依赖:zstd 用于解压 .tar.zst,curl 用于验证
  2. command -v zstd >/dev/null || { sudo apt-get update && sudo apt-get install -y zstd; }
  3. command -v curl >/dev/null || { sudo apt-get update && sudo apt-get install -y curl; }
  4. # 2. 回到物理磁盘目录下载(弱网可换镜像加速源,地址按通用镜像实践选择)
  5. cd ~/
  6. wget <镜像加速源>/<runtime-linux-arm64.tar.zst> -O ~/runtime.tar.zst
  7. sha256sum ~/runtime.tar.zst # 与发布页校验值比对,不一致请勿继续
  8. # 3. 显式指定 zstd 解压,否则 tar 无法识别算法
  9. sudo mkdir -p /opt/runtime_temp
  10. sudo tar -I zstd -xf ~/runtime.tar.zst -C /opt/runtime_temp
  11. # 4. 确认二进制真实路径后再安装到 PATH 中的标准位置
  12. find /opt/runtime_temp -maxdepth 3 -type f -perm -u+x
  13. sudo install -m 0755 /opt/runtime_temp/runtime /usr/local/bin/runtime
  14. /usr/local/bin/runtime --version # 能打印版本号才算装好
  15. # 5. 清理,回收磁盘
  16. sudo rm -rf /opt/runtime_temp ~/runtime.tar.zst

install -m 0755 同时完成复制与权限设置,比 cp -r 更不容易漏掉可执行位——这正是后面 ExecStart 路径找不到或直接退出的常见原因。

五、配置系统服务(默认只监听本机)

  1. # 专用低权限用户,不可登录
  2. sudo useradd -r -s /usr/sbin/nologin -d /usr/share/runtime runtime
  3. sudo mkdir -p /usr/share/runtime && sudo chown -R runtime:runtime /usr/share/runtime
  4. sudo tee /etc/systemd/system/runtime.service > /dev/null << 'EOF'
  5. [Unit]
  6. Description=Local Model Inference Runtime Service
  7. After=network-online.target
  8. Wants=network-online.target
  9. [Service]
  10. User=runtime
  11. Group=runtime
  12. WorkingDirectory=/usr/share/runtime
  13. ExecStart=/usr/local/bin/runtime serve
  14. Restart=always
  15. RestartSec=3
  16. Environment="RUNTIME_HOST=127.0.0.1:11500"
  17. NoNewPrivileges=true
  18. PrivateTmp=true
  19. ProtectSystem=strict
  20. ReadWritePaths=/usr/share/runtime
  21. [Install]
  22. WantedBy=multi-user.target
  23. EOF
  24. sudo systemctl daemon-reload
  25. sudo systemctl enable --now runtime

关键取舍:RUNTIME_HOST 默认给 127.0.0.1:11500,只有本机可访问。多数推理运行时默认不带任何认证,一旦写成 0.0.0.0,同网段任何人都能直接调用你的模型和算力。确实需要跨机访问时,按下面顺序加固,不要裸开端口:

  1. 先用 sudo ufw allow from 192.168.1.0/24 to any port 11500 之类做来源白名单;
  2. 前置反向代理(如 nginx)加 TLS 与 Token/Basic Auth,运行时本身保持只听 127.0.0.1;
  3. 或走 WireGuard / Tailscale 等私有网络,完全不对公网映射端口;
  4. 上线后用 ss -lntp 和一次外网探测确认端口没有意外暴露。

六、拉取并运行模型

  1. # 先看帮助,模型名以运行时自己的模型库为准
  2. /usr/local/bin/runtime --help
  3. /usr/local/bin/runtime pull --help
  4. # 以低权限用户拉取并运行一个十亿参数以内的小模型(示例名,按实际注册表替换)
  5. sudo -u runtime runtime pull qwen2.5:0.5b
  6. sudo -u runtime runtime run qwen2.5:0.5b

拉取失败先看模型是否超出磁盘余量,再看 /usr/share/runtime 是否对 runtime 用户可写。

七、上线验证:可直接复制的验收清单

检查项 命令 期望结果
服务状态 systemctl status runtime --no-pager Active: active (running)
启动原因 systemctl show -p ExecMainStartTimestamp runtime 时间符合预期,非刚被拉起
日志 journalctl -u runtime -n 50 --no-pager 无 error/panic,无反复重启
端口 `ss -lntp \ grep 11500` LISTEN 且地址为 127.0.0.1:11500
接口 curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:11500/ 返回 2xx/404,说明端口通
模型列表 curl -sS http://127.0.0.1:11500/v1/models 能列出已拉取模型
推理链路 sudo -u runtime runtime run <模型名> 正常输出文本
资源水位 free -h; df -h / 内存有余量、根分区未接近满

非 root 用户看日志需要加入 systemd-journal 组。只有以上全部通过,才算”跑通”。

八、性能与成本测量口径

  1. # 进程级内存/CPU 占用
  2. ps -o pid,pcpu,pmem,rss,etime,cmd -C runtime
  3. # 推理延迟(端到端与首字)
  4. curl -o /dev/null -s -w 'ttfb=%{time_starttransfer}s total=%{time_total}s\n' \
  5. http://127.0.0.1:11500/v1/chat/completions -H 'Content-Type: application/json' -d '{...}'
  6. # 模型磁盘占用
  7. du -sh /usr/share/runtime/* | sort -h

判定触发条件:进程 RSS 超过物理内存 80%、swap 使用量持续上涨、或单次响应延迟超过业务可接受值,就该降模型参数量、缩短上下文长度或限制并发数,而不是先加内存。

九、升级、备份与回滚

  1. # 升级前备份二进制与服务配置
  2. sudo cp -a /usr/local/bin/runtime /usr/local/bin/runtime.bak
  3. sudo cp -a /etc/systemd/system/runtime.service /etc/systemd/system/runtime.service.bak
  4. # 出现异常时回滚
  5. sudo install -m 0755 /usr/local/bin/runtime.bak /usr/local/bin/runtime
  6. sudo cp -a /etc/systemd/system/runtime.service.bak /etc/systemd/system/runtime.service
  7. sudo systemctl daemon-reload
  8. sudo systemctl restart runtime
  9. systemctl status runtime --no-pager && journalctl -u runtime -n 30 --no-pager

十、磁盘不足、权限错误、服务启动失败如何排查

现象 可能原因 处置动作
解压报空间不足 在 /tmp(tmpfs)操作,吃的是内存 cd ~/ 后重试,并 df -h / 确认余量
加载模型被中断 内存不足触发 OOM `dmesg -T \ tail -20` 确认,扩 Swap 或换更小/更低量化模型
tar: Cannot exec: No such file 缺 zstd 依赖 command -v zstd 检查并安装
服务启动即退出 二进制路径不存在或无可执行位 确认 /usr/local/bin/runtime --version 可运行,检查 -m 0755
Permission denied 服务用户无权写模型目录 chown -R runtime:runtime /usr/share/runtime
端口无法访问 监听地址或防火墙 ss -lntp 看监听地址,检查 ufw/安全组
架构不匹配 下成 x86_64 包 uname -m 校验后重新下载 ARM64 包
重启后服务异常 fstab 写错或 Swap 未生效 findmnt --verify,用 /etc/fstab.bak.* 回滚

十一、长期运维要点

  • 稳定性:保留 Restart=always,配合健康检查与日志告警,关注异常重启次数;
  • 安全:服务只监听必要地址,仅开放必要端口,推理接口不要直接暴露公网;
  • 容量:模型越多磁盘占用越大,定期清理无用权重,按设备容量规划可容纳的模型数量与规格;
  • 功耗:边缘设备 7×24 运行需关注功耗与散热降频对推理延迟的影响。

十二、总结

在 ARM64 边缘设备上跑通本地大模型推理,难点集中在”架构匹配、磁盘空间、内存水位”三处。先把 uname -m、df -h、free -h 看清,再决定模型规格;用 install -m 0755 把二进制固定到 /usr/local/bin/runtime,避免服务因路径或权限起不来;默认只监听 127.0.0.1,需要跨机时再叠加白名单、反代与认证;最后用 status、journalctl、ss、curl 四件套做可复制的验收,并保留二进制与配置的备份以便随时回滚。这套流程同样适用于任何资源受限设备的边缘 AI 部署模板,替换模型名与端口即可复用。