告别部署繁琐：LlamaPi 一键搭建本地 Agent 推理底座

一、端侧大模型落地的三道门槛

端侧 AI 与本地 Agent 正在快速落地，各类端侧硬件的 NPU 推理算力也得到大幅提升。但不少开发者在实际落地时依旧要面对重重门槛，整个流程耗时长、上手门槛高，阻碍了端侧大模型与 Agent 项目的快速验证。

常见门槛	具体表现	LlamaPi 的对应能力
模型获取与转换	手动下载权重、反复调试模型转换、转换后精度受损	模型库一键下载，按平台提供已适配的模型格式
推理环境搭建	手写 NPU 推理代码、依赖冲突、硬件算力无法充分释放	单条命令拉起推理服务，运行时自动对接 NPU
长期运行与调度	部署不稳定、启停靠手工、重启后需重新加载	服务调度 + 持久化部署（开机自动加载）

LlamaPi 的思路是把复杂的部署流程封装简化，为开发者提供一套开箱即用的离线私有 Agent 推理底座。

二、一条命令跑起本地模型

以往端侧部署大模型，需要手动完成模型下载、格式转换、推理环境配置等一连串操作。LlamaPi 把这套流程收敛为单条命令：

# 以 Qwen3.5-4B 为例：自动拉取模型 + 启动本地推理服务
llamapi run qwen3.5-4b

执行命令后，LlamaPi 会自动把模型拉取至本地，并依托端侧 NPU 硬件加速，快速提供高性能的本地大模型推理服务。对于不希望使用命令行的用户，它还配套了桌面客户端应用，提供可视化图形界面，点选操作即可完成模型运行与对话交互，降低上手门槛。

三、整体架构：三层结构

分层	组件	说明
应用层	OpenCode / OpenClaw / Hermes Agent / 其他 OpenAI 兼容应用	通过 OpenAI 兼容 API 把推理请求发给 LlamaPi
兼容层	LlamaPi 推理服务	对内统一完成模型管理与服务调度，对外提供 OpenAI 兼容 API
硬件层	RK3588 / RK1828 / RK1820 等	NPU 硬件加速，按平台加载对应格式的模型

上层各类第三方应用通过 OpenAI 兼容 API 将推理请求发送给 LlamaPi；LlamaPi 对内统一完成模型管理、服务调度，把推理任务交付给设备的 NPU 完成加速计算，推理结果再原路返回给上层应用。

四、模型库管理：查询 / 下载 / 清理

在端侧开发过程中，往往会同时测试多款不同的大模型。LlamaPi 具备完整的模型管理能力，帮助开发者完成模型的查询、下载与清理，不必手动维护零散的权重文件。

命令	作用
llamapi list	列出本地已下载的所有模型
llamapi list --online	查看适配当前设备的全部可用模型，包含尚未下载的模型
llamapi pull <model_name>	下载指定模型至设备本地
llamapi rm <model_name>	从设备上删除指定模型

llamapi list --online 会同时给出模型对应的推理平台与体积，便于评估是否适配当前硬件：

实测设备上可用的模型清单如下（PLATFORM 列表示该条目对应的推理后端与芯片组合）：

MODEL	PLATFORM	SIZE	LOCAL
bge-m3	rknn2/rk3588	1.1 GB	installed
gemma4:e4b	rknn3/rk1828	–	not installed
gemma4:12b	rknn3/rk1828	–	not installed
qwen3:0.6b	rkllm/rk3588	–	not installed
qwen3:0.6b	rknn3/rk1828	–	not installed
qwen3:1.7b	rkllm/rk3588	–	not installed
qwen3:1.7b	rknn3/rk1828	–	not installed
qwen3:4b	rkllm/rk3588	–	not installed
qwen3:4b	rknn3/rk1828	–	not installed
qwen3:8b	rknn3/rk1828	–	not installed
qwen3-vl:4b	rknn3/rk1828	–	not installed
qwen3.5:0.8b	rkllm/rk3588	1.5 GB	installed
qwen3.5:0.8b	rknn3/rk1828	1.1 GB	installed
qwen3.5:2b	rkllm/rk3588	–	not installed
qwen3.5:2b	rknn3/rk1828	–	not installed
qwen3.5:4b	rkllm/rk3588	–	not installed
qwen3.5:4b	rknn3/rk1828	3.9 GB	installed
qwen3.5:9b	rknn3/rk1828	–	not installed
qwen3.5:27b	rknn3/rk1828	–	not installed
qwen3.8:27b	rknn3/rk1828	16.8 GB	installed

从清单可以看出两条典型路线：

平台	承载硬件	覆盖规模	适用场景
rkllm/rk3588	主控 NPU	0.6B ~ 4B	轻量对话、低功耗常驻任务
rknn2/rk3588	主控 NPU（v2 运行时）	向量/嵌入类模型	语义检索、知识库 embedding
rknn3/rk1828	M.2 NPU 加速卡	0.6B ~ 27B	大模型对话、多模态、代码 Agent

同一模型往往会在不同平台上分别提供条目，便于按实际硬件选择对应的版本。

五、服务调度：加载 / 卸载 / 开机自启

完成模型下载之后，还需要灵活管控模型的运行状态：包括加载启动、停止释放、查看当前正在运行的模型，或是配置设备开机自动加载模型。在桌面客户端中可以直接对已下载模型执行加载、卸载、设置开机自启，并直观查看当前运行状态。

客户端「部署管理」页面中的模型组信息如下（1 个运行中 · 共 4 个模型组）：

模型组 ID	MODEL	TYPE	PLATFORM	STATUS	实例
qwen3.8:27b@rknn3-rk1828	qwen3.8:27b	chat	rknn3/rk1828	运行中	1
qwen3.5:4b@rknn3-rk1828	qwen3.5:4b	chat	rknn3/rk1828	未加载	–
qwen3.5:0.8b@rkllm-rk3588	qwen3.5:0.8b	chat	rkllm/rk3588	未加载	–
bge-m3@rknn2-rk3588	bge-m3	embedding	rknn2/rk3588	未加载	–

命令行同样覆盖全部调度能力，适合快速调试与脚本化运维：

命令	作用
llamapi ps	查看设备上当前已经部署运行的模型状态
llamapi load <model_name>	加载并启动本地已下载的指定模型
llamapi unload <model_name>	卸载正在运行的模型，释放硬件资源
llamapi enable <model_name>	设置模型持久化部署，设备重启后自动加载该模型

llamapi ps 的输出包含模型 ID、MODEL、TYPE、PLATFORM、STATUS 与实例数，另有一列 ENABLE 表示是否已设为开机自启。上述实测中，27B 模型处于 active 状态、1 个实例；unload 后立即释放，随后可用 load 拉起另一个模型。

六、接入第三方应用：OpenAI 兼容 API

当模型在设备内部署完成后，LlamaPi 会自动输出 OpenAI 兼容 API，无需额外开发，就可以将本地端侧推理能力对接各类第三方 AI 应用，快速搭建完整的离线私有 AI 工作流。

配置项	填写内容
服务提供方	OpenAI 或 OpenAI-compatible
自定义服务地址（Base URL / API Endpoint）	http://<设备 IP>:9265/v1
模型 ID	通过 llamapi ps 命令或客户端「部署管理」页查看

第三方应用配置流程：

步骤	操作
1	在第三方应用中选择 OpenAI 或 OpenAI-compatible 服务提供方
2	找到自定义服务地址（Base URL / API Endpoint）配置项，填入 http://<设备 IP>:9265/v1
3	填写对应的模型 ID，模型 ID 可通过 llamapi ps 命令或在客户端部署管理页面中查看
4	保存后即可在应用内调用本地模型，构建离线私有 AI 工作流

七、命令速查表

分类	命令	说明
快速启动	llamapi run <model>	拉取模型并直接运行
模型查询	llamapi list	列出本地已下载的模型
模型查询	llamapi list --online	查看当前设备全部可用模型
模型管理	llamapi pull <model>	下载指定模型
模型管理	llamapi rm <model>	删除指定模型
服务调度	llamapi ps	查看运行中的模型状态
服务调度	llamapi load <model>	加载并启动模型
服务调度	llamapi unload <model>	卸载模型、释放资源
持久化	llamapi enable <model>	设备重启后自动加载
应用接入	OpenAI 兼容 API	http://<设备 IP>:9265/v1

八、小结

LlamaPi 把端侧大模型部署中「模型下载 → 格式转换 → NPU 推理 → 服务接口」这几段最耗时的流程做了封装：单条命令即可拉起本地推理服务；模型库与部署管理覆盖查询、下载、清理、加载、卸载与开机自启；对外通过 OpenAI 兼容 API 直接对接 OpenCode、OpenClaw、Hermes Agent 等第三方应用。对于需要离线、私有化、低门槛验证端侧大模型与本地 Agent 的场景，这是一条值得尝试的路径。