182X 模型调用详解：像调云端 API 一样用 OpenAI 接口跑板端模型

前一篇的九个 SKILL，背后都是模型在 RK182X NPU 上推理。SKILL 是封装好的用法，那平台本身的模型调用接口是什么样的？这篇讲清楚：M5-182X-A1 作为跑大模型的平台，给你三种调用方式——命令行测试、HTTP API、Web 界面。跑哪个模型不重要，接口是通用的；下文用 Model Zoo 里的 Qwen3-1.7B 和 MobileNet V2 做示例。

本章完整文档：《RK182X 系列 LLM 推理》、《RK182X 系列 CNN 推理》（生态平台 wiki） 前置条件：NPU 服务正常（systemctl is-active rknn3.service 为 active）；示例模型已部署（获取方式见篇④《模型转换》）。

（一）方式一：命令行，先测平台跑得怎么样

rknn3_llm_demo 是 LLM 的基准测试工具，接模型四件套就能跑：

rknn3_llm_demo \
  -m  <模型目录>/Qwen3-1.7B/Qwen3-1.7B.rknn \
  -w  <模型目录>/Qwen3-1.7B/Qwen3-1.7B.weight \
  -tk <模型目录>/Qwen3-1.7B/Qwen3-1.7B.tokenizer.gguf \
  -em <模型目录>/Qwen3-1.7B/Qwen3-1.7B.embed.bin \
  -c  0xff \
  -ctx 16384 \
  -no 4096

跑完输出一份测试汇总（wiki 实测）：

===== RKNN3_LLM_TEST Results Summary =====

Model: Qwen3-1.7B
DeviceID: 0004:41:00.0
TTFT: 63.208 ms
TPOT: 8.636 ms
Prefill: 253.132 tokens/s
TPS: 115.798 tokens/s
TotalTime: 607.262 ms
TotalRuns: 1
AvgMemoryUsage: unavailable
AvgNpuUtilization: unavailable

这份输出的用途是验收平台：换模型、换板子、改配置之后跑一遍，前后对比就知道变化在哪。

必须搞懂的参数：-c 是核掩码

LLM 和 CNN 的 -c 规则放在一起才好理解：

规则一句话：-c 必须匹配模型编译时声明的核数——不是 NPU 物理核数，更不是上下文长度。传错就报错：传 1 报 core_mask 1 is not match with npu core number 8!；把上下文数值传进去（如 8192）报 core_mask 8192 is not match with npu core number 8——上下文在模型编译时写死，运行时用 -ctx 指定。

（二）方式二：HTTP API，把模型接进你的应用

rkllm3-server 提供 OpenAI 兼容 API——这是平台最有用的接口：任何用 OpenAI SDK 写的应用，把地址指过来就能用，应用侧零改造。

启动服务：

rkllm3-server \
  -m <模型目录>/Qwen3-1.7B/Qwen3-1.7B.rknn \
  --weight <模型目录>/Qwen3-1.7B/Qwen3-1.7B.weight \
  --vocab <模型目录>/Qwen3-1.7B/Qwen3-1.7B.tokenizer.gguf \
  --embed <模型目录>/Qwen3-1.7B/Qwen3-1.7B.embed.bin \
  --host 0.0.0.0 --port 8080 \
  -c 0xff

注意：--help 里 -c 的文字描述写的是 --ctx-size，实测按 NPU core mask 处理——wiki 明确记录了这一差异，别被帮助文字带偏。

两个接口：

# 列出模型
curl http://localhost:8080/v1/models

# 对话推理
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen","messages":[{"role":"user","content":"你好"}]}'

Python 接入（官方 openai 库，改个 base_url 就行）：

from openai import OpenAI

client = OpenAI(base_url="http://<设备IP>:8080/v1", api_key="none")

response = client.chat.completions.create(
    model="qwen",
    messages=[
        {"role": "system", "content": "你是一个助手"},
        {"role": "user", "content": "你好"},
    ],
    max_tokens=100,
)
print(response.choices[0].message.content)

模型文件就是篇④见过的四件套（.rknn / .weight / .tokenizer.gguf / .embed.bin）。

（三）方式三：Web 界面，不写代码直接用

平台还带一个 Flask + 原生前端的轻量 Web 聊天界面，对接 rkllm3-server 的 API，支持自然语言对话和模拟设备控制：

cd <工程目录>
bash start.sh

浏览器访问 http://<设备IP>:7080。

（四）CNN 模型怎么调

视觉类模型走另一套 demo。Model Zoo 里的 MobileNet V2 已预装（FP16 版）：

/userdata/RK1820_RK1828_AI_SDK/examples/gstreamer/MobilenetV2/
├── mobilenetv2-12.rknn     60,352 B    # FP16 模型结构
├── mobilenetv2-12.weight   7,037,440 B # FP16 模型权重
├── labels.txt              21 KB       # ImageNet 1000 类标签
└── config.json                          # 模型配置

推理测试（单张图片分类）：

rknn3_cnn_demo \
  -m /userdata/RK1820_RK1828_AI_SDK/examples/gstreamer/MobilenetV2/mobilenetv2-12.rknn \
  -w /userdata/RK1820_RK1828_AI_SDK/examples/gstreamer/MobilenetV2/mobilenetv2-12.weight \
  -i /rockchip-test/npu2/model/cat_224x224.jpg \
  -c 1 \
  -cl 10 \
  -mm

10 次循环平均结果（wiki 实测，FP16 单核）：

-mm 需要 sudo（普通用户报 Permission denied），推理本身不需要 root。INT8 版本 SDK 未预装，需按篇④自行转换。

（五）两种接口怎么选

应用集成选 Python API，对外提供对话服务选 HTTP。三种调用方式共用同一个 NPU，接口不同、底层相同。

（六）常见的坑

（七）总结

三种调用方式覆盖了平台使用的主要场景：测性能、接应用、直接聊。接口是固定的，模型是可换的——这篇讲的调用方法，换成 Model Zoo 里任何一个模型（Qwen2.5、Qwen3-4B……）或者你自己转的模型（篇④），照用不误。

想跑自己的模型？下一篇《模型转换》。