Qnn on huluhuluu

LLM QNN 插件推理流程

Thu, 04 Jun 2026 12:00:00 +0800

LLM QNN 插件推理流程

LLM QNN 插件推理流程

本篇梳理移动设备侧运行 QNN 后端主图 qnn/llm.mnn 时的代码路径。离线编译阶段会把部分子图编译成 QNN 后端使用的 qnn/*.bin 二进制文件，并把主图改写成调用插件算子 OpType_Plugin(type="QNN") 的形式。推理时，核心调用链路如下：

[LLM 生成层]
llm->response()
└── generate(input_ids)
    ├── embedding()
    └── forwardVec()
        └── forwardRaw()
            │
            ▼
[MNN Express Module 层]
Module::onForward()
├── [阶段 1: resize / 形状推导]
│   └── StaticModule::_resize()
│       └── ShapePlugin
│           └── PluginShapeRaw::compute()
│               └── 根据 allInputShape 选择 shapeIndex，并读取 o_<shapeIndex>_* 输出描述
│
└── [阶段 2: execute / 真正执行]
    └── StaticModule::_execute()
        └── CPUPlugin::onExecute()
            └── PluginExecuteRaw::compute()
                └── RawExecutorWrapper::invokModel()
                    └── QNN graphExecute()

1. `config_qnn.json` 配置

QNN 模型运行时一般使用 config_qnn.json 配置文件：

{
  "llm_model": "qnn/llm.mnn",
  "backend_type": "cpu",
  "chunk_limits": [128, 1]
}

LlmConfig::llm_model() 会把 llm_model 拼到模型目录下：

// transformers/llm/engine/src/llmconfig.hpp:279
std::string llm_model() const {
    return base_dir_ + config_.value("llm_model", "llm.mnn");
}

所以，最终加载主图路径就是 <model_dir>/qnn/llm.mnn，也就是 Llm::load() 里会用这个路径加载 Module：

// transformers/llm/engine/src/llm.cpp:280
std::string model_path = mConfig->llm_model();
...
mRuntimeManager->setExternalFile(mConfig->llm_weight());
mModule.reset(Module::load(inputNames, outputNames, model_path.c_str(), mRuntimeManager, &module_config));
mRuntimeManager->setExternalFile("");

这里加载的 qnn/llm.mnn 是一个带 QNN 插件算子的主图。同时，Llm::setRuntimeHint() 会设置 NPU 文件目录：

1
2

// transformers/llm/engine/src/llm.cpp:153
rtg->setExternalPath(mConfig->npu_model_dir(), MNN::Interpreter::EXTERNAL_NPU_FILE_DIR);

npu_model_dir() 默认返回模型的根目录：

// transformers/llm/engine/src/llmconfig.hpp:311
std::string npu_model_dir() const {
    return base_dir_ + config_.value("npu_model_dir", "");
}

这个路径会先写入 RuntimeManager 中：

// transformers/llm/engine/src/llm.cpp:153
rtg->setExternalPath(mConfig->npu_model_dir(), MNN::Interpreter::EXTERNAL_NPU_FILE_DIR);

// express/Executor.cpp:242
void Executor::RuntimeManager::setExternalPath(std::string path, int type) {
    if (type == MNN::Interpreter::EXTERNAL_NPU_FILE_DIR) {
        mInside->mContent->mNpuDir = path;
        return;
    }
    mInside->mContent->modes.setExternalPath(path, type);
}

后面 StaticModule 构造时会把它写到 CPU 后端的 pNPUModelDirPath：

1
2
3

// express/module/StaticModule.cpp:340
bnCache.cache.first->pNPUModelDirPath = rtm->getInside()->mContent->mNpuDir;
bnCache.cache.second->pNPUModelDirPath = rtm->getInside()->mContent->mNpuDir;

并在 QNN 插件读取 path 属性时，使用该目录拼出完整 .bin 路径，例如：

`1`	`<model_dir>/qnn/graph0.bin`

2. LLM 生成链路

文本输入最常见的入口是：

`1`	`llm->response(prompt);`

对应源码里，response(string) 会先按配置套 chat template，再使用 tokenizer 分词为 token id，最后转到 response(input_ids) 方法：

// transformers/llm/engine/src/llm.cpp:912
void Llm::response(const std::string& user_content, std::ostream* os, const char* end_with, int max_new_tokens) {
    auto prompt = user_content;
    if (mConfig->use_template()) {
        prompt = mPrompt->applyTemplate(user_content, true);
    }
    std::vector<int> input_ids = tokenizer_encode(prompt);
    response(input_ids, os, end_with, max_new_tokens);
}

在 response(input_ids) 方法中，会初始化一些记录的数据，随后继续走 generate(input_ids) 接口生成输出：

// transformers/llm/engine/src/llm.cpp:900
void Llm::response(const std::vector<int>& input_ids, std::ostream* os, const char* end_with, int max_new_tokens) {
    if (!end_with) { end_with = "\n"; }
    generate_init(os, end_with);
    generate(input_ids, max_new_tokens);
}

在 generate(input_ids) 里会根据 prompt 长度决定是一次 embedding，还是按 mBlockSize 分块：

// transformers/llm/engine/src/llm.cpp:786
mContext->history_tokens.insert(mContext->history_tokens.end(), input_ids.begin(), input_ids.end());
if(!passExecute) {
    if (0 == mBlockSize || input_ids.size() <= mBlockSize) {
        auto hidden_states = embedding(input_ids);
        return generate(hidden_states, max_tokens);
    }
    int total_size = (int)input_ids.size();
    int loop_size = UP_DIV(total_size, mBlockSize);
    for (int i = 0; i < loop_size; i++) {
        ...
        auto input_embeds = embedding(chunk_ids);
        generate(input_embeds, 0);
    }
}
generate(max_tokens);

3. `prefill` / `decode` 形状

Llm::set_config() 读取 chunk_limits 后，会排序并把最大值作为 mBlockSize，代码块如下：

// transformers/llm/engine/src/llm.cpp:104
if (mConfig->config_.document.HasMember("chunk_limits")) {
    auto& size_limit = mConfig->config_.document["chunk_limits"];
    ...
    for (auto iter = size_limit.GetArray().begin(); iter != size_limit.GetArray().end(); iter++) {
        mValidBlockSize.emplace_back(iter->GetInt());
    }
    ...
    std::sort(mValidBlockSize.begin(), mValidBlockSize.end());
    mBlockSize = mValidBlockSize[mValidBlockSize.size()-1];
}

以 chunk_limits: [128, 1] 为例，内部结果是：

1
2

mValidBlockSize = [1, 128]
mBlockSize = 128

这和离线导出阶段的两组形状对上：

阶段	`seq len`	作用
`prefill`	`128`	`prompt` 分块或 `pad` 后的大块前向
`decode`	`1`	自回归单 `token` 前向

forwardVec(input_embeds) 会按 mBlockSize 拆分长 prompt：

// transformers/llm/engine/src/llm.cpp:572
std::vector<VARP> Llm::forwardVec(MNN::Express::VARP input_embeds) {
    int seq_len = input_embeds->getInfo()->dim[mSeqLenIndex];
    if (0 == mBlockSize) {
        mMeta->add = seq_len;
        auto attention_mask = gen_attention_mask(seq_len);
        auto position_ids = gen_position_ids(seq_len);
        auto res = forwardRaw(input_embeds, attention_mask, position_ids);
        return res;
    }
    auto blockNumber = seq_len / mBlockSize;
    auto blockRemain = seq_len % mBlockSize;

整块部分直接按 mBlockSize 调 forwardRaw()：

// transformers/llm/engine/src/llm.cpp:604
for (int i=0; i<blockNumber; ++i) {
    logits.clear();
    mMeta->add = blockSize;
    auto embed = embeddings[i];
    auto attention_mask = gen_attention_mask(blockSize);
    auto position_ids = gen_position_ids(blockSize);
    logits = forwardRaw(embed, attention_mask, position_ids);
    ...
    updateContext(blockSize, 0);
}

剩余长度如果不是合法形状，会 pad 到 mValidBlockSize 中最近的合法大小：

// transformers/llm/engine/src/llm.cpp:623
if (!mValidBlockSize.empty()) {
    forwardSize = mValidBlockSize[mValidBlockSize.size()-1];
    for (int j=mValidBlockSize.size()-2; j>=0; --j) {
        if (mValidBlockSize[j] < blockRemain) {
            break;
        }
        forwardSize = mValidBlockSize[j];
    }
    if (blockRemain < forwardSize) {
        hasPad = true;
        auto dim = input_embeds->getInfo()->dim;
        dim[mSeqLenIndex] = forwardSize;
        auto newEmbed = _Input(dim, NCHW);
        ::memcpy(newEmbed->writeMap<void>(), input_embeds->readMap<void>(), input_embeds->getInfo()->size * sizeof(float));
        ::memset(newEmbed->writeMap<float>() + input_embeds->getInfo()->size, 0, (newEmbed->getInfo()->size - input_embeds->getInfo()->size) * sizeof(float));
        input_embeds = newEmbed;
    }
}

比如剩余 prompt 长度是 80，会 pad 到 128；decode 阶段长度是 1，直接匹配 1。

这个形状需要匹配离线导出时 compilefornpu 写入插件属性的 allInputShape。

4. 算子前向

forwardRaw() 构造主模型输入：

// transformers/llm/engine/src/llm.cpp:448
std::vector<Express::VARP> Llm::forwardRaw(Express::VARP hiddenState, Express::VARP mask, Express::VARP inputPos, Express::VARPS extraArgs) {
    Express::VARP logitsIndex;
    bool inDecode = mContext->gen_seq_len > 0;
    bool isAllLogists = mConfig->all_logits() ? true : (inDecode ? mInSpec : false);
    auto seqLen = hiddenState->getInfo()->dim[mSeqLenIndex];
    int seqLenKey = inDecode ? hiddenState->getInfo()->dim[mSeqLenIndex] : mPrefillKey;
    ...
std::vector<Express::VARP> inputs {
    hiddenState,
    mask,
    inputPos,
    logitsIndex
};

然后选择 Module 模块：

// transformers/llm/engine/src/llm.cpp:480
std::vector<Express::VARP> inputs {hiddenState, mask, inputPos, logitsIndex};
inputs.insert(inputs.end(), extraArgs.begin(), extraArgs.end());
std::vector<Express::VARP> outputs = selectModule->onForward(inputs);

这里的 selectModule 通常有两种：

prefill 走主 mModule；
decode 会按 (seqLenKey, isAllLogits) 从 mModulePool 里取 clone 出来的模块。

对应代码里，默认先使用 mModule，在没有 mValidBlockSize 的路径下会按输入长度等 key 复制模块：

// transformers/llm/engine/src/llm.cpp:455
auto moduleKey = std::make_pair(seqLenKey, isAllLogists);
std::shared_ptr<Module> selectModule = mModule;
if (mValidBlockSize.empty()) {
    if(mModulePool.find(moduleKey) == mModulePool.end()) {
        MNN_PRINT("Warning: module need new clone, cloning now.\n");
        mRuntimeManager->setHintPtr(Interpreter::KVCACHE_INFO, mMeta.get());
        mModulePool[moduleKey].reset(Module::clone(mModule.get()));
    }
    selectModule = mModulePool[moduleKey];
}

进入 Module::onForward() 后，实际对象通常是 StaticModule。StaticModule::onForward() 的核心顺序是：

// express/module/StaticModule.cpp:566
std::vector<Express::VARP> StaticModule::onForward(const std::vector<Express::VARP>& inputs) {
    ...
    Variable::compute(inputs);
    ...
    if (runResize) {
        code = _resize(inputs);
    }
    if (NO_ERROR == code && runCompute) {
        code = _execute();
    }

_resize() 会把输入 VARP 绑定到 Session 输入张量，并触发 mSession->resize()，从而向下执行 Pipeline::encode() 和 Pipeline::allocMemory()，完成创建算子 Execution 类的准备。对于 QNN 图来说，这里是在准备 OpType_Plugin 算子：

// express/module/StaticModule.cpp:521
for (int i = 0; i < inputs.size(); ++i) {
    ...
    if (_resizeTensor(mInputTensors[i], inputTensor, mSession.get(), nullptr)) {
        mSession->setNeedResize();
    }
}
mSession->getInfo(Interpreter::RESIZE_STATUS, &curStatus);
code = mSession->resize();

最终 _execute() 会调用 Session 的 run() 方法，执行流水线中的算子。这里使用 QNN 图时，对应的是 OpType_Plugin 算子的执行：

// express/module/StaticModule.cpp:550
ErrorCode StaticModule::_execute() {
    ErrorCode code;
    if (mResource->mModes.callBackMode == Interpreter::Session_Debug) {
        ...
        code = mSession->runWithCallBack(debug->before, debug->after);
    } else {
        code = mSession->run();
    }
    return code;
}

所以 QNN 插件会经历两个不同阶段：

resize 阶段：走 ShapePlugin -> PluginShapeRaw::compute()，确定输出形状；
execute 阶段：走 CPUPlugin::onExecute() -> PluginExecuteRaw::compute()，真正调用 QNN 计算图。

5. `resize` 阶段

上一节已经走到 StaticModule::_resize()：

StaticModule::onForward()
└── _resize(inputs)
    └── mSession->resize()
        └── Pipeline::encode()
            ├── ShapePlugin / PluginShapeRaw::compute()
            └── CPUPluginCreator -> CPUPlugin -> PluginExecuteRaw::init()

这里要分清两件事：

ShapePlugin 负责输出形状推导；
CPUPluginCreator 负责创建真正参与后续 execute 的 Execution。

这两件事都发生在 resize 这条链路上，所以第 5 节先看形状推导，再看 QNN 内核的注册和创建。

5.1 `ShapePlugin`

通用插件形状入口在 source/shape/ShapePlugin.cpp。它会从 Plugin 参数里读出 type，再用这个 type 找到对应的形状推导内核：

// source/shape/ShapePlugin.cpp:35
const Plugin* plugin_param = op->main_as<Plugin>();
std::shared_ptr<plugin::InferShapeKernel> kernel =
    getInferShapeKernel(plugin_param->type()->str());
...
plugin::InferShapeContext ctx(inputs, outputs);
for (const Attribute* attr : *(plugin_param->attr())) {
    ctx.setAttr(attr->key()->str(), attr);
}
bool status = kernel->compute(&ctx);

QNN 插件的 type 是 "QNN"。这个 type 对应的形状推导内核和计算内核都在 QNNBackend.cpp 里注册：

// source/backend/qnn/backend/QNNBackend.cpp:1837
#ifdef MNN_WITH_PLUGIN
plugin::InferShapeKernelRegister::add("QNN", []() {
    return new plugin::shape_inference::PluginShapeRaw;
});
plugin::ComputeKernelRegistry<plugin::backend::PluginExecuteRaw::KernelT>::add("QNN", []() {
    return new plugin::backend::PluginExecuteRaw;
});
#endif

这里注册了两条不同阶段的入口：

注册项	阶段	作用
`InferShapeKernelRegister::add("QNN", ...)`	`resize` / 形状推导	用 `allInputShape` 匹配当前输入形状，并写出输出形状
`ComputeKernelRegistry::add("QNN", ...)`	`resize` / `execute`	创建 `PluginExecuteRaw`，后面加载 `QNN` 上下文二进制并执行计算图

QNN 注册的 InferShapeKernelRegister 是 PluginShapeRaw::compute()，它会先调用 computeIndex()。这一步的输入是当前插件算子的输入张量形状：

// source/backend/qnn/backend/QNNBackend.cpp:361
static bool computeIndex(PluginContext* ctx, int & index) {
    const std::vector<Tensor *> & inputs = ctx->inputs();
    auto attrAllShape = ctx->getAttr("allInputShape");
    if (nullptr == attrAllShape || nullptr == attrAllShape->list() || nullptr == attrAllShape->list()->i()) {
        MNN_ERROR("MNN_QNN: Incorrect Plugin Op, can't find 'allInputShape' attr.\n");
        return false;
    }
    int dimSum = 0;
    for (int i = 0; i < inputs.size(); i++) {
        auto inputDim = inputs[i]->dimensions();
        dimSum += inputDim;
    }
    ...
}

随后与离线 compilefornpu 写进插件属性的多组合法输入 allInputShape 对比，找到匹配当前输入形状的 shapeIndex：

// source/backend/qnn/backend/QNNBackend.cpp:378
auto indexNumber = attrAllShape->list()->i()->size() / dimSum;
for (int si=0; si<indexNumber; ++si) {
    auto dstSi = attrAllShape->list()->i()->data() + si * dimSum;
    bool valid = true;
    for (int i=0; i<inputs.size(); ++i) {
        auto inputDim = inputs[i]->dimensions();
        for (int j = 0; j < inputDim; j++) {
            if (inputs[i]->length(j) != dstSi[j]) {
                valid = false;
                break;
            }
        }
        dstSi += inputDim;
        if (!valid) {
            break;
        }
    }
    if (valid) {
        index = si;
        return true;
    }
}

匹配成功后得到的 shapeIndex 是后面 QNN 路径的关键索引：

shapeIndex
├── resize 阶段: 读取 o_<shapeIndex>_<outputIndex> 写输出形状
├── PluginExecuteRaw::resize(): 记录 mShapeIndex
└── execute 阶段: 选择 mQnnGraphHandleVec[mShapeIndex]

因此，运行时输入形状必须能在 allInputShape 里找到，否则 QNN 插件的形状推导会失败。

当匹配到 shapeIndex 后，PluginShapeRaw::compute() 会读取 o_<shapeIndex>_<outputIndex>，把离线记录的输出类型、形状和格式写回当前输出张量：

// source/backend/qnn/backend/QNNBackend.cpp:403
bool PluginShapeRaw::compute(InferShapeContext* ctx) {
    ...
    int shapeIndex = 0;
    if (!(computeIndex(ctx, shapeIndex))) {
        MNN_ERROR("MNN_QNN: Failed to compute shape for Plugin Op.\n");
        return false;
    }

    std::string prefix = "o_" + std::to_string(shapeIndex) + "_";
    for (int i=0; i<ctx->outputs().size(); ++i) {
        auto dst = ctx->output(i);
        std::string key = prefix + std::to_string(i);
        auto attr = ctx->getAttr(key.c_str());
        ...
        auto blob = attr->tensor();
        dst->setType(blob->dataType());
        if (nullptr != blob->dims()) {
            dst->buffer().dimensions = blob->dims()->size();
            for (int j=0; j<blob->dims()->size(); ++j) {
                dst->setLength(j, blob->dims()->data()[j]);
            }
        } else {
            dst->buffer().dimensions = 0;
        }
        TensorUtils::getDescribe(dst)->dimensionFormat = blob->dataFormat();
    }
    return true;
}

5.2 创建 `QNN` 算子

形状推导完成后，Pipeline::encode() 还会为每个算子创建后端 Execution。这里不是直接手写调用 new CPUPlugin(...)，而是走 MNN 后端的通用算子创建路径：

Pipeline::encode()
└── OpCommonUtils::createExecutionWithExternal(...)
    └── backend->onCreate(inputs, outputs, op)
        └── CPUBackend::onCreate(...)
            └── gCreator[OpType_Plugin]->onCreate(...)
                └── CPUPluginCreator::onCreate(...)
                    └── new CPUPlugin(ctx)
                        └── getCPUComputeKernel("QNN")
                            └── ComputeKernelRegistry<CPUComputeKernel>::get("QNN")
                                └── new PluginExecuteRaw

在 Pipeline::encode() 里，当前 command 还没有 Execution 时，会调用 createExecutionWithExternal(...)：

// source/core/Pipeline.cpp:563
std::shared_ptr<BufferStorage> tmpStorage;
if (nullptr == iter.execution) {
    iter.execution.reset(OpCommonUtils::createExecutionWithExternal(
        mBackend.get(), iter.inputs, iter.outputs, iter.op, &loader, tmpStorage));
}

OpCommonUtils::createExecutionWithExternal(...) 对没有外部权重重建需求的算子，会直接转到后端的 onCreate(...)：

// source/core/OpCommonUtils.cpp:664
Execution* OpCommonUtils::createExecutionWithExternal(
    Backend* backend,
    const std::vector<Tensor*>& inputs,
    const std::vector<Tensor*>& outputs,
    const MNN::Op* op,
    FileLoader* externalFile,
    std::shared_ptr<BufferStorage>& tmpstore) {
    ...
    if (!hasExternal) {
        return backend->onCreate(inputs, outputs, op);
    }

当前模型运行在 CPU 后端上，所以这里进入 CPUBackend::onCreate(...)。它用 op->type() 去 gCreator 表里找创建器：

// source/backend/cpu/CPUBackend.cpp:720
Execution* CPUBackend::onCreate(const std::vector<Tensor*>& inputs, const std::vector<Tensor*>& outputs,
                                const MNN::Op* op) {
    ...
    auto opType = op->type();
    ...
    auto map  = gCreator;
    auto iter = map->find(opType);
    if (iter == map->end() ) {
        MNN_PRINT("Don't support type [%s]\n", MNN::EnumNameOpType(op->type()));
        return nullptr;
    }
    Execution* exe = nullptr;
    if (exe == nullptr) {
        exe = iter->second->onCreate(inputs, outputs, op, this);
    }
    return exe;
}

OpType_Plugin 对应的创建器在 CPUPlugin.cpp 文件尾部注册：

1
2

// source/backend/cpu/CPUPlugin.cpp:98
REGISTER_CPU_OP_CREATOR(CPUPluginCreator, OpType_Plugin);

这个宏展开后的核心动作是把 CPUPluginCreator 放进 CPUBackend::gCreator：

// source/backend/cpu/CPUBackend.hpp:218
#define REGISTER_CPU_OP_CREATOR(name, opType)     \
    void ___##name##__##opType##__() {            \
        static name _temp;\
        CPUBackend::addCreator(opType, &_temp); \
    }

所以对于 OpType_Plugin(type="QNN")，最终会调用 CPU 后端里的 CPUPluginCreator::onCreate(...)：

// source/backend/cpu/CPUPlugin.cpp:70
class CPUPluginCreator : public CPUBackend::Creator {
public:
    virtual Execution* onCreate(const std::vector<Tensor*>& inputs,
                                const std::vector<Tensor*>& outputs,
                                const MNN::Op* op, Backend* backend) const {
        ...
        const Plugin* plugin_param = op->main_as<Plugin>();
        const std::string& op_type = plugin_param->type()->str();
        std::unique_ptr<plugin::CPUKernelContext> ctx(
            new plugin::CPUKernelContext(op_type, backend, inputs, outputs, static_cast<CPUBackend *>(backend)->pNPUModelDirPath));

        for (const Attribute* attr : *(plugin_param->attr())) {
            ctx->setAttr(attr->key()->str(), attr);
        }
        return new CPUPlugin(std::move(ctx));
    }
};

这里把三类信息塞进了 CPUKernelContext：

op_type：这里是 "QNN"；
pNPUModelDirPath：模型目录，后面用来拼 QNN 计算图 qnn/graph0.bin；
插件属性：包括 path、inputs、outputs、allGraphName、allInputShape。

CPUPluginCreator::onCreate(...) 最后一行真正进入 CPUPlugin 构造函数。构造函数里会通过 op_type 找到 QNN 计算内核，并立刻调用 kernel_->init(...)：

// source/backend/cpu/CPUPlugin.cpp:27
class CPUPlugin : public Execution {
public:
    CPUPlugin(std::unique_ptr<plugin::CPUKernelContext> ctx)
        : Execution(ctx->backend()), ctx_(std::move(ctx)) {
        kernel_ = getCPUComputeKernel(ctx_->op_type());
        MNN_CHECK(nullptr != kernel_.get(),
                  "CPU compute kernel has not been registered for plugin op.");
        kernel_->init(ctx_.get());
        mNeedAllocIO = kernel_->needAllocIO();
    }

getCPUComputeKernel(...) 本身只是从 ComputeKernelRegistry 里按名字取工厂函数：

// source/backend/cpu/CPUPlugin.cpp:21
static std::shared_ptr<plugin::CPUComputeKernel> getCPUComputeKernel(
    const std::string& name) {
    return std::shared_ptr<plugin::CPUComputeKernel>(
        plugin::ComputeKernelRegistry<plugin::CPUComputeKernel>::get(name));
}

其 get(name) 会查 gFactoryMap，然后执行对应工厂函数：

// source/plugin/PluginKernel.cpp:48
PluginKernelT* ComputeKernelRegistry<PluginKernelT>::get(const std::string& name) {
    auto* gFactoryMap = ComputeKernelRegistry<PluginKernelT>::getFactoryMap();
    if (!gFactoryMap->count(name)) {
        MNN_PRINT("Factory has not been registered for name %s.", name.c_str());
        return nullptr;
    }
    return gFactoryMap->at(name)();
}

QNN 在前面注册过 "QNN" 这个工厂函数：

// source/backend/qnn/backend/QNNBackend.cpp:1841
plugin::ComputeKernelRegistry<plugin::backend::PluginExecuteRaw::KernelT>::add("QNN", []() {
    return new plugin::backend::PluginExecuteRaw;
});

所以这里的实际对象就是 PluginExecuteRaw。因此 CPUPlugin 构造函数里的 kernel_->init(ctx_.get()) 会动态分发到 PluginExecuteRaw::init(...)，执行加载 qnn/graph*.bin。

5.3 加载 `QNN` 图

PluginExecuteRaw::init() 先确保 QNN 全局上下文已经创建，然后用模型目录和插件属性 path 拼出 QNN 图的上下文二进制路径：

// source/backend/qnn/backend/QNNBackend.cpp:907
bool init(CPUKernelContext* ctx) override {
    if (QNN::gContext.deviceHandle == nullptr){
        QNN::createQnnContext();
    }
    auto path = MNNFilePathConcat(ctx->dir_path(), ctx->getAttr("path")->s()->str());

这里的路径关系是：

1
2
3

ctx->dir_path()              = <model_dir>
ctx->getAttr("path")->s()    = qnn/graph0.bin
最终 path                    = <model_dir>/qnn/graph0.bin

随后读取 allGraphName。一个 .bin 里可能包含多个计算图，比如 prefill 和 decode，所以运行时必须知道计算图名字顺序：

// source/backend/qnn/backend/QNNBackend.cpp:913
std::vector<std::string> allGraphName;
auto allGraphNameAttr = ctx->getAttr("allGraphName");
if (allGraphNameAttr && allGraphNameAttr->list() && allGraphNameAttr->list()->s()) {
    auto graphNames = allGraphNameAttr->list()->s();
    for (int i = 0; i < graphNames->size(); ++i) {
        allGraphName.push_back(graphNames->GetAsString(i)->str());
    }
} else {
    MNN_ERROR("MNN_QNN: Incorrect Plugin Op, can't find 'allGraphName' attr.\n");
    return false;
}

最后创建 RawExecutorWrapper，把上下文二进制交给 compileModel(...)：

1
2
3

// source/backend/qnn/backend/QNNBackend.cpp:952
mRawExecutor.reset(new RawExecutorWrapper());
return mRawExecutor->compileModel(path, binaryOffset, binarySize, allGraphName);

compileModel(...) 先读入 .bin。如果插件属性里有 offset / size，就从文件指定位置读取；否则直接 mmap 整个文件：

// source/backend/qnn/backend/QNNBackend.cpp:772
bool compileModel(const std::string& path, size_t offset, size_t size, const std::vector<std::string>& allGraphName) {
    mPath = path;
    void* buffer = nullptr;
    std::vector<char> bufferVec(size, 0);
    MMapReader reader;
    if (size > 0) {
        buffer = bufferVec.data();
        std::unique_ptr<FileLoader> binaryFile(new FileLoader(path.c_str()));
        binaryFile->offset((int64_t)offset);
        binaryFile->read((char *)buffer, (int64_t)size);
    } else {
        reader.open(path.c_str());
        buffer = reader.addr();
        size = reader.size();
    }

接着通过 QNN system API 解析二进制里的计算图元信息：

// source/backend/qnn/backend/QNNBackend.cpp:790
QnnSystemContext_Handle_t systemContextHandle = nullptr;
QNN::gContext.systemInterface.systemContextCreate(&systemContextHandle);
Qnn_ContextBinarySize_t binarySize = 0;
const QnnSystemContext_BinaryInfo_t* binaryInfo = nullptr;
CALL_QNN(QNN::gContext.systemInterface.systemContextGetBinaryInfo(
    systemContextHandle, buffer, size, &binaryInfo, &binarySize));
copyMetadataToGraphsInfo(binaryInfo, mGraphsInfo, mGraphCount);
QNN::gContext.systemInterface.systemContextFree(systemContextHandle);

然后校验二进制，并从二进制创建 QNN 上下文：

// source/backend/qnn/backend/QNNBackend.cpp:807
auto error = QNN::gContext.interface.contextValidateBinary(
    QNN::gContext.backendHandle,
    QNN::gContext.deviceHandle,
    mQnnContextConfig,
    buffer,
    size);
...
CALL_QNN(QNN::gContext.interface.contextCreateFromBinary(
    QNN::gContext.backendHandle,
    QNN::gContext.deviceHandle,
    mQnnContextConfig,
    buffer,
    size,
    &mQnnContextHandle,
    mQnnProfileHandle));

最后按 allGraphName 的顺序整理 mGraphsInfo，并取回每个计算图句柄：

// source/backend/qnn/backend/QNNBackend.cpp:820
std::vector<GraphInfo*> sortedGraphsInfo(mGraphCount, nullptr);
std::map<std::string, GraphInfo*> graphInfoMap;
for (int i = 0; i < mGraphCount; ++i) {
    graphInfoMap[mGraphsInfo[i]->graphName] = mGraphsInfo[i];
}

for (int i = 0; i < mGraphCount; ++i) {
    auto it = graphInfoMap.find(allGraphName[i]);
    MNN_ASSERT(it != graphInfoMap.end());
    sortedGraphsInfo[i] = it->second;
}
for (int i = 0; i < mGraphCount; i++) {
    CALL_QNN(QNN::gContext.interface.graphRetrieve(
        mQnnContextHandle,
        mGraphsInfo[i]->graphName,
        &(mQnnGraphHandleVec[i])));
}

这一步结束后，QNN 插件已经持有：

RawExecutorWrapper
├── mQnnContextHandle
├── mGraphsInfo[shapeIndex]
└── mQnnGraphHandleVec[shapeIndex]

后面 execute 阶段不再重新创建 QNN 计算图，而是根据 shapeIndex 选择已经取回的计算图句柄。

5.4 `PluginExecuteRaw::resize()`

CPUPlugin::onResize() 会把当前输入输出张量重置到 CPUKernelContext，再调用 QNN 内核的 resize()：

// source/backend/cpu/CPUPlugin.cpp:49
ErrorCode CPUPlugin::onResize(const std::vector<Tensor*>& inputs,
                              const std::vector<Tensor*>& outputs) {
    ctx_->reset(inputs, outputs);
    auto success = kernel_->resize(ctx_.get());
    ...
}

PluginExecuteRaw::resize() 会再次通过 computeIndex() 得到当前 shapeIndex，并保存到成员变量 mShapeIndex：

// source/backend/qnn/backend/QNNBackend.cpp:956
bool resize(CPUKernelContext* ctx) override {
    int shapeIndex = 0;
    if (!(shape_inference::computeIndex(ctx, shapeIndex))) {
        MNN_ERROR("MNN_QNN: Failed to execute Plugin Op.\n");
        return false;
    }
    mShapeIndex = shapeIndex;

随后读取插件属性里的 inputs / outputs。这些名字一般是 t<tensor_index>，由离线 compilefornpu 按主图张量索引写入：

// source/backend/qnn/backend/QNNBackend.cpp:964
auto inputs = ctx->getAttr("inputs")->list();
auto inputTensor = ctx->inputs();
MNN_ASSERT(inputs->s()->size() == inputTensor.size());
mInputs.resize(inputs->s()->size());
mRealInputs.resize(inputTensor.size());
for (int i=0; i<inputs->s()->size(); ++i) {
    mRealInputs[i].reset(new Tensor(inputTensor[i], Tensor::CAFFE));
    mInputs[i].second = inputs->s()->GetAsString(i)->str();
    mInputs[i].first = mRealInputs[i].get();
}

输出也是同样处理：

// source/backend/qnn/backend/QNNBackend.cpp:974
auto outputs = ctx->getAttr("outputs")->list();
auto outputTensor = ctx->outputs();
mOutputs.resize(outputs->s()->size());
MNN_ASSERT(outputs->s()->size() == outputTensor.size());
mRealOutputs.resize(outputTensor.size());
for (int i=0; i<outputs->s()->size(); ++i) {
    mRealOutputs[i].reset(new Tensor(outputTensor[i], Tensor::CAFFE));
    mOutputs[i].second = outputs->s()->GetAsString(i)->str();
    mOutputs[i].first = mRealOutputs[i].get();
}

这里保存的是 MNN 张量和 QNN 张量名的对应关系：

1
2
3

mRealInputs / mRealOutputs: 临时 Tensor，后面交给 QNN graphExecute 使用
mInputs / mOutputs: (临时 Tensor 指针, QNN tensor name)
mShapeIndex: 当前输入 shape 对应的 graph index

到这里，resize 阶段完成了三件事：输出形状已经确定，QNN 上下文二进制已经加载，当前形状的输入输出映射也准备好了。

6. `execute` 阶段

StaticModule::_execute() 最后会走到 Session::run()。当流水线执行到 OpType_Plugin(type="QNN") 时，CPU 后端调用的是 CPUPlugin::onExecute()：

// source/backend/cpu/CPUPlugin.cpp:59
ErrorCode CPUPlugin::onExecute(const std::vector<Tensor*>& inputs,
                               const std::vector<Tensor*>& outputs) {
    if (kernel_->compute(ctx_.get())) {
        return NO_ERROR;
    } else {
        MNN_ERROR("Plugin kernel compute failed with false returned.\n");
        return INVALID_VALUE;
    }
}

对 QNN 插件来说，这里的 kernel_ 就是前面 init 阶段创建好的 PluginExecuteRaw。

6.1 重新确认 `shapeIndex`

PluginExecuteRaw::compute() 开头会重新调用 computeIndex()，确认当前输入形状对应哪个计算图：

// source/backend/qnn/backend/QNNBackend.cpp:988
bool compute(CPUKernelContext* ctx) override {
    AUTOTIME;
    int shapeIndex = 0;
    if (!(shape_inference::computeIndex(ctx, shapeIndex))) {
        MNN_ERROR("MNN_QNN: Failed to execute Plugin Op.\n");
        return false;
    }
    std::string graphName = ctx->getAttr("allGraphName")->list()->s()->GetAsString(shapeIndex)->str();

当前源码后面传给 invokModel() 的是成员变量 mShapeIndex，也就是 resize 阶段记录的 shape index。compute() 里重新算出的局部 shapeIndex 主要用于读取 allGraphName 和调试打印。

6.2 准备输入输出 `Tensor`

compute() 里会重新创建一次实时输入输出张量映射。源码注释写的是 in-time inputs and outputs tensor：

// source/backend/qnn/backend/QNNBackend.cpp:997
// compute and alloc real in-time inputs and outputs tensor
{
    auto inputs = ctx->getAttr("inputs")->list();
    auto inputTensor = ctx->inputs();
    MNN_ASSERT(inputs->s()->size() == inputTensor.size());
    mInputs.resize(inputs->s()->size());
    mRealInputs.resize(inputTensor.size());
    for (int i=0; i<inputs->s()->size(); ++i) {
        mRealInputs[i].reset(new Tensor(inputTensor[i], Tensor::CAFFE));
        mInputs[i].second = inputs->s()->GetAsString(i)->str();
        mInputs[i].first = mRealInputs[i].get();
    }
    ...
}

这和 resize 阶段的映射逻辑有重复。resize 阶段先建立一次映射并记录 mShapeIndex；execute 阶段再基于当前 ctx->inputs() / ctx->outputs() 建立实时 Tensor，保证后面的拷贝和 QNN 的 clientBuf 绑定使用的是本次运行的缓冲区。

6.3 拷贝输入、执行 `QNN`、拷回输出

真正执行前，MNN 会先把当前输入张量拷到 mRealInputs：

// source/backend/qnn/backend/QNNBackend.cpp:1024
auto inputTensor = ctx->inputs();
auto outputTensor = ctx->outputs();

for (int i=0; i<mInputs.size(); ++i) {
    ctx->backend()->onCopyBuffer(inputTensor[i], mRealInputs[i].get());
}
mRawExecutor->invokModel(mInputs, mOutputs, mShapeIndex);
for (int i=0; i<mOutputs.size(); ++i) {
    ctx->backend()->onCopyBuffer(mRealOutputs[i].get(), outputTensor[i]);
}

随后在 invokModel() 里执行，最后把结果从 mRealOutputs 拷回 ctx->outputs()。

6.4 `invokModel()`执行入口

RawExecutorWrapper::invokModel() 先根据 shapeIndex 选择 QNN 计算图：

// source/backend/qnn/backend/QNNBackend.cpp:844
void invokModel(const std::vector<std::pair<const MNN::Tensor *, std::string>>& inputs, std::vector<std::pair<const MNN::Tensor *, std::string>>& outputs, int shapeIndex) {
    GraphInfo* graph = mGraphsInfo[shapeIndex];
    Qnn_GraphHandle_t qnnGraphHandle = mQnnGraphHandleVec[shapeIndex];

然后按张量名把 MNN 缓冲区绑定到 QNN 输入张量的 clientBuf：

// source/backend/qnn/backend/QNNBackend.cpp:849
for (int i=0; i<inputs.size(); ++i) {
    auto t = inputs[i].first;
    bool find = false;
    for (int j=0; j<graph->numInputTensors; ++j) {
        auto& dstT = graph->inputTensors[j];
        if (inputs[i].second == dstT.v1.name) {
            dstT.v1.clientBuf.data = t->host<void>();
            dstT.v1.clientBuf.dataSize = t->usize();
            find = true;
            break;
        }
    }
}

输出张量也是同样按名字绑定：

// source/backend/qnn/backend/QNNBackend.cpp:868
for (int i=0; i<outputs.size(); ++i) {
    auto t = outputs[i].first;
    bool find = false;
    for (int j=0; j<graph->numOutputTensors; ++j) {
        auto& dstT = graph->outputTensors[j];
        if (outputs[i].second == dstT.v1.name) {
            dstT.v1.clientBuf.data = t->host<void>();
            dstT.v1.clientBuf.dataSize = t->usize();
            find = true;
            break;
        }
    }
}

这里的名字来自离线阶段写进插件属性的 inputs / outputs。

6.5 `graphExecute()` 执行点

绑定完输入输出缓冲区后，RawExecutorWrapper::invokModel() 会调用 QNN 接口 graphExecute() 执行计算图：

// source/backend/qnn/backend/QNNBackend.cpp:887
CALL_QNN(QNN::gContext.interface.graphExecute(
    qnnGraphHandle,
    graph->inputTensors,
    graph->numInputTensors,
    graph->outputTensors,
    graph->numOutputTensors,
    mQnnProfileHandle,
    nullptr));
MNN::QNN::doProfile(QNN::gContext.interface, mQnnProfileHandle);

到这一行，计算已经交给了 QNN 后端：

通过 shapeIndex 选中了正确的 QNN 计算图句柄；
通过 inputs / outputs 名字把缓冲区绑到 QNN 张量；
把执行交给 QNN 运行时。

.bin 里面的 HTP 计算图执行由 QNN 后端负责。MNN 运行时在这里主要做计算图选择、缓冲区绑定和结果回拷。

7. 小结

把第 4 到第 6 节串起来看，QNN 插件的运行时路径是：

StaticModule::onForward()
├── _resize()
│   ├── ShapePlugin
│   │   └── PluginShapeRaw::compute()
│   │       ├── allInputShape -> shapeIndex
│   │       └── o_<shapeIndex>_* -> 输出 shape
│   │
│   └── Pipeline::encode() 创建 Plugin Execution
│       └── CPUPluginCreator
│           └── CPUPlugin
│               └── PluginExecuteRaw::init()
│                   └── RawExecutorWrapper::compileModel()
│                       ├── mmap/read qnn/graph*.bin
│                       ├── contextCreateFromBinary()
│                       └── graphRetrieve()
│
└── _execute()
    └── CPUPlugin::onExecute()
        └── PluginExecuteRaw::compute()
            ├── 准备实时输入输出 Tensor
            ├── onCopyBuffer(input -> mRealInputs)
            ├── RawExecutorWrapper::invokModel(mShapeIndex)
            │   ├── mQnnGraphHandleVec[mShapeIndex]
            │   ├── 绑定 QNN input/output clientBuf
            │   └── graphExecute()
            └── onCopyBuffer(mRealOutputs -> output)

LLM QNN 离线导出流程

Thu, 04 Jun 2026 12:00:00 +0800

LLM QNN 离线导出流程

LLM QNN 离线导出流程

本文记录 transformers/llm/export/npu/generate_llm_qnn.py 将 MNN 格式模型导出到 QNN 后端的链路。主要把 llm.mnn / llm.mnn.weight 文件转成 QNN 运行需要的两类产物：

qnn/llm.mnn：已经插入 OpType_Plugin(type="QNN") 的主模型；
qnn/*.bin：QNN HTP context binary，运行时由 QNN Plugin 直接加载执行。

整体流程分为四步：

generate_llm_qnn.py
  -> convert(args)
    -> makeIO(args)
    -> seperate(args)
    -> compile_qnn(args)
    -> output_qnn(args)

1. 入口参数

脚本入口在 transformers/llm/export/npu/generate_llm_qnn.py，常用参数如下：

参数	说明
`--model`	MNN LLM 模型目录
`--soc_id`	QNN 目标 SoC id
`--dsp_arch`	QNN DSP 架构，例如 `v75`、`v79`
`--mnn_path`	MNN build 目录，需要包含 `generateLlmIO` 和 `compilefornpu`
`--cache_path`	临时工作目录，默认 `tmp`
`--chunk_size`	写入 `config_qnn.json` 的 prefill shape，默认 `128`

脚本大量通过 os.getcwd() 拼路径，所以运行目录很重要。常见执行方式是从仓库根目录进入导出目录后运行。soc_id 和 dsp_arch 需要和目标 SoC / Hexagon 版本对应，可以参考 Qualcomm 官方设备信息：

cd ${MNN_ROOT}
cd transformers/llm/export

python3 npu/generate_llm_qnn.py \
  --model /data/HF_MODELS/Qwen3-1.7B-MNN \
  --soc_id 69 \
  --dsp_arch v79 \
  --mnn_path ../../../build/

模型目录至少需要这些文件，可以直接使用官方提供的模型 Qwen3-1.7B-MNN：

Qwen3-1.7B-MNN/
├── config.json
├── llm_config.json
├── tokenizer.txt
├── llm.mnn
└── llm.mnn.weight

npu_convert.py 还会读取 QNN_SDK_ROOT，所以开发机环境里需要先配置 QAIRT / QNN SDK。

2. Step1：生成 IO 样本

LLM QNN 导出从 convert(args) 方法开始。Step1 对应的是 makeIO(args)：

# transformers/llm/export/npu/generate_llm_qnn.py:67
def convert(args):
    cache = os.path.join(os.getcwd(), args.cache_path)
    os.makedirs(cache, exist_ok=True)
    print("Step1: Make IO")
    makeIO(args)

makeIO(args) 本身没有解析 llm_config.json，它只是拼出可执行文件 generateLlmIO 的路径（由主库编译产生，详见 QNN 模型导出），并把模型目录、输出目录和 chunk_size 传进去：

# transformers/llm/export/npu/generate_llm_qnn.py:10
def makeIO(args):
    exe = os.path.join(os.getcwd(), args.mnn_path, "generateLlmIO")
    output = os.path.join(args.cache_path, 'testdir')
    print(os.popen(exe + " " + args.model + " " + output + ' %d' %args.chunk_size).read())

所以 Step1 实际执行的命令可以展开成：

<cwd>/<mnn_path>/generateLlmIO \
  <model_dir> \
  tmp/testdir \
  <chunk_size>
# 如果没有 tmp/testdir 目录，可能需要手动创建

这里 <model_dir> 是整个 MNN LLM 模型目录，不是单独的 llm.mnn 文件。llm_config.json、llm.mnn、llm.mnn.weight 等文件会由 generateLlmIO 在模型目录内部继续读取。

generate_llm_qnn.py 只关心两个后续会被 compilefornpu 读取的样本目录：

用途	样本目录
prefill	`testdir/<chunk_size>`
decode	`testdir/1`

生成结果会落在 tmp/testdir 下，后续 compilefornpu 会按 testdir/1、testdir/<chunk_size> 读取这些输入输出样本。

生成结果包含两组不同长度的输入输出样本：

➜  export git:(master) ✗ ../../../build/generateLlmIO /data/HUGGINGFACE/Qwen3-1.7B-Eagle3-MNN tmp/testdir 128
blockSize=128 in main, 148
modelPath.c_str()=s /data/HUGGINGFACE/Qwen3-1.7B-Eagle3-MNN/llm.mnn in main, 152
llmConfigPath.c_str()=s /data/HUGGINGFACE/Qwen3-1.7B-Eagle3-MNN/llm_config.json in main, 153
Can't open file:/sys/devices/system/cpu/cpufreq/boost/affected_cpus
Can't open file:/sys/devices/system/cpu/cpufreq/ondemand/affected_cpus
CPU Group: [ 95  17  83  55  118  27  93  65  5  37  75  47  19  85  57  29  108  67  7  39  101  10  77  49  111  20  87  59  121  30  97  69  33  112  21  88  122  31  98  41  104  13  51  114  23  61  1  124  9  71  43  106  15  81  53  116  25  91  63  3  126  35  73  45  94  117  26  92  64  4  127  36  74  46  109  18  84  56  119  28  54  66  6  38  100  76  48  110  86  58  120  96  68  8  102  11  105  40  103  12  79  50  113  22  89  60  0  123  32  99  70  42  78  14  80  52  115  24  90  62  2  125  34  72  44  107  16  82 ], 1500000 - 2900000
The device supports: i8sdot:0, fp16:0, i8mm: 0, sve2: 0, sme2: 0
Successfully generate tmp/testdir/128/input.mnn and tmp/testdir/128/output.mnn.
Successfully generate tmp/testdir/1/input.mnn and tmp/testdir/1/output.mnn.

输入由 createInputsForLLM(...) 构造，输出由这些输入跑一次 LLM 网络前向得到：

// transformers/llm/engine/tools/generateLlmIO.cpp:117
{
    std::vector<MNN::Express::VARP> inputs;
    std::vector<MNN::Express::VARP> outputs;
    createInputsForLLM(blockSize, hiddenSize, attentionMaskType, false, inputs);
    outputs = net->onForward(inputs);
    saveInputOutputs(net->getInfo(), inputs, outputs, outputDir, blockSize);
}

// transformers/llm/engine/tools/generateLlmIO.cpp:125
{
    std::vector<MNN::Express::VARP> inputs;
    std::vector<MNN::Express::VARP> outputs;
    createInputsForLLM(1, hiddenSize, attentionMaskType, true, inputs);
    outputs = net->onForward(inputs);
    saveInputOutputs(net->getInfo(), inputs, outputs, outputDir, 1);
}

3. Step2：切图

convert(args) 的 Step2 直接调用 seperate(args)：

1
2
3

# transformers/llm/export/npu/generate_llm_qnn.py:76
print("Step2: Seperate Model")
seperate(args)

seperate(args) 先定位可执行文件 compilefornpu（由主库编译产生，详见 QNN 模型导出）和原始 llm.mnn，再写一个临时 qnn.json。这里的 seperate 是源码里的函数名拼写，文档里保持不改：

# transformers/llm/export/npu/generate_llm_qnn.py:15
def seperate(args):
    exe = os.path.join(os.getcwd(), args.mnn_path, "compilefornpu")
    model = os.path.join(os.getcwd(), args.model, 'llm.mnn')
    config = {
        "type":"QNN",
        "skips":[],
        "testdir":[],
        "cache":"qnn"
    }
    config['testdir'].append(os.path.join("testdir", '1'))
    config['testdir'].append(os.path.join("testdir", '%d' %args.chunk_size))

写出的配置内容对应下面这样：

{
  "type": "QNN",
  "skips": [],
  "testdir": [
    "testdir/1",
    "testdir/<chunk_size>"
  ],
  "cache": "qnn"
}

然后它在 tmp 目录下执行 compilefornpu：

# transformers/llm/export/npu/generate_llm_qnn.py:29
cache = os.path.join(os.getcwd(), args.cache_path)
with open(os.path.join(cache, 'qnn.json'), 'w') as f:
    f.write(json.dumps(config, indent=4))

process = subprocess.Popen(
    exe + ' ' + model + ' qnn/llm.mnn qnn.json',
    cwd = cache,
    shell=True
)

命令展开后是：

<build>/compilefornpu \
  <model_dir>/llm.mnn \
  qnn/llm.mnn \
  qnn.json

compilefornpu 的入口在 tools/cpp/compilefornpu.cpp。这一步会在原图上做三件事：

先根据输入输出 tensor 找出真正需要计算的 op；
再把连续可下沉的 op 区间整理成 SubModuleInfo；
最后把每个可下沉区间替换成一个 OpType_Plugin(type="QNN")。

代码调用关系如下：

generate_llm_qnn.py
└── seperate(args)                                      # 生成切图配置并启动 compilefornpu
    ├── 写 tmp/qnn.json                                # 告诉 compilefornpu 目标后端和测试 shape
    │   ├── type = "QNN"
    │   ├── testdir = ["testdir/1", "testdir/<chunk_size>"]
    │   └── cache = "qnn"
    │
    └── subprocess.Popen(...)
        └── compilefornpu <model_dir>/llm.mnn qnn/llm.mnn qnn.json
            │
            ├── main(argc, argv)                       # 切图工具主入口
            │   ├── 解析 qnn.json                      # 初始化 QNN 离线导出参数
            │   │   ├── gNPUType = MNN_CONVERT_QNN
            │   │   ├── gNeedOffline = true
            │   │   └── gCacheDir = "qnn"
            │   ├── 读取 testdir/*/input.mnn 和 output.mnn # 取得 decode / prefill 两组输入输出
            │   ├── Interpreter::createFromFile(srcMNN)    # 读取原始 llm.mnn
            │   ├── initConstTensorsNoAlloc(...)           # 标记常量 tensor
            │   └── _createSubModuleInfo(...)              # 生成候选子图列表
            │       ├── _collectNeededOps(...)             # 从输出反向追依赖 op
            │       ├── isBreakOp(...)                     # 遇到控制流 / 不支持 op 就切断
            │       ├── _splitSubModuleForShapeConst(...)  # shape 依赖输入内容时补切
            │       └── _computeTensorMask(...)            # 计算子图输入输出边界
            │
            ├── for 每组 testdir 输入 shape                  # 分别处理 decode / prefill
            │   ├── _getSubModuleIO(...)                    # 跑原图收集子图参考 IO
            │   │   └── 记录 KV state shape                 # KV 下沉时写 Plugin state
            │   ├── 过滤不含 Convolution 的子图              # 当前导出只保留卷积子图
            │   └── _compileSubModule(...)                  # 编译子图并生成 Plugin op
            │       ├── RuntimeManager(type = MNN_CONVERT_QNN)
            │       ├── setCache("qnn/graph*")              # 指定 QNN graph 源目录
            │       ├── Module::load(...)
            │       ├── Module::onForward(...)              # 触发 QNN convert backend 导出 graph
            │       └── 生成 OpType_Plugin(type="QNN")      # 用一个 Plugin 表示整段子图
            │
            ├── 用 Plugin 替换原始连续 op 区间               # 改写主图
            ├── _reIndexTensor(...) / _reOrderOp(...)       # 清理 tensor 并重排拓扑
            ├── 多 shape 结果用 _fuse(...) 合并 Plugin attr  # 合并 decode / prefill graph 信息
            ├── 写 qnn/llm.mnn                              # 插入 QNN Plugin 后的主模型
            └── 写 npu_postreat.json                        # 给 npu_convert.py 继续生成 context binary
                └── merge: qnn/graph*.bin -> [qnn/graph*, qnn/graph1_*, ...]

3.1 QNN 离线模式

compilefornpu 的命令格式是：

// tools/cpp/compilefornpu.cpp:836
int main(int argc, const char* argv[]) {
    if (argc < 3) {
        MNN_PRINT("Usage: ./compilefornpu src.mnn dst.mnn npu.json\n");
        return 0;
    }
    const char* srcMNN = argv[1];
    const char* dstMNN = argv[2];

当 qnn.json 里写的是 "type": "QNN" 时，代码会把后端类型设成 MNN_CONVERT_QNN，并打开 gNeedOffline：

// tools/cpp/compilefornpu.cpp:859
gNPUName = document["type"].GetString();
if (gNPUName == "QNN") {
    MNN_PRINT("Convert for QNN, QualComn's NPU\n");
    gNPUType = MNN_CONVERT_QNN;
    gNeedOffline = true;
    gOfflieSrc = "";
    gOfflieDst = "bin";
}

gNeedOffline = true 之后，_compileSubModule(...) 会通过一次 Module::onForward() 触发 QNN convert 后端导出 graph 材料。

3.2 读取 testdir

generate_llm_qnn.py 写入了两组 testdir：

"testdir": [
  "testdir/1",
  "testdir/<chunk_size>"
]

compilefornpu 会逐个读取里面的 input.mnn 和 output.mnn：

// tools/cpp/compilefornpu.cpp:898
if (document.HasMember("testdir")) {
    auto testdir = document["testdir"].GetArray();
    for (auto iter = testdir.Begin(); iter != testdir.End(); iter++) {
        std::string dirname = iter->GetString();
        auto subinputs = MNN::Express::Variable::load((dirname + "/input.mnn").c_str());
        inputs.emplace_back(subinputs);
        inputNames.clear();
        for (int i=0; i<subinputs.size(); ++i) {
            inputNames.emplace_back(subinputs[i]->name());
        }
        auto outputs = MNN::Express::Variable::load((dirname + "/output.mnn").c_str());
        outputNames.clear();
        for (int i=0; i<outputs.size(); ++i) {
            outputNames.emplace_back(outputs[i]->name());
        }
    }
}

这里的 input.mnn / output.mnn 提供了：

主图输入名；
主图输出名；
decode / prefill 两组真实输入 shape 和数据；

3.3 生成候选子图列表

compilefornpu 使用 _createSubModuleInfo(...) 生成需要转换的候选子图列表，流程如下。

3.3.1 反向收集 op

切图的第一步是 _collectNeededOps(...)。它先给输入和输出 tensor 打标记，再从 outputIndexes 反向追溯数据依赖，直到遇到 inputIndexes：

// tools/cpp/compilefornpu.cpp:261
static std::vector<SubModuleInfo> _createSubModuleInfo(
    const Net* net,
    const std::set<int>& inputIndexes,
    const std::set<int>& outputIndexes,
    const std::set<int>& noComputeIndexes,
    std::shared_ptr<Schedule::ScheduleInfo> sharedConst) {
    std::vector<SubModuleInfo> submodule;
    auto selectOps = _collectNeededOps(net, inputIndexes, outputIndexes);
    // ...
}

// tools/cpp/compilefornpu.cpp:116
static std::vector<int> _collectNeededOps(
    const MNN::Net* net,
    const std::set<int>& inputIndexes,
    const std::set<int>& outputIndexes) {
    // 0: not set, 1: output, 2:input
    std::vector<int> tensorMask(net->tensorName()->size());
    ...
    for (auto v : outputIndexes) {
        tensorMask[v] = 1;
    }
    for (auto v : inputIndexes) {
        tensorMask[v] = 2;
    }

接着沿着输出到输入的方向反复传播标记：如果某个 op 的输出已经被标成需要保留，就把这个 op 标成需要计算，并继续把它的输入 tensor 标成依赖项：

// tools/cpp/compilefornpu.cpp:134
do {
    change = false;
    for (int i=0; i<opMask.size(); ++i) {
        ...
        if (nullptr != op->outputIndexes()) {
            for (int j=0; j<op->outputIndexes()->size(); ++j) {
                auto index = op->outputIndexes()->data()[j];
                if (tensorMask[index] == 1) {
                    opMask[i] = 1;
                    change = true;
                }
            }
        }
        if (nullptr != op->inputIndexes() && opMask[i]) {
            for (int j=0; j<op->inputIndexes()->size(); ++j) {
                auto index = op->inputIndexes()->data()[j];
                if (tensorMask[index] != 2) {
                    tensorMask[index] = 1;
                }
            }
        }
    }
} while (change);

3.3.2 按 break op 切图

_createSubModuleInfo(...) 会按原图 op 顺序扫描上一步采集的算子 selectOps：普通 op 缓存到 current.opList；遇到 break op，就先把前面的连续算子保存成一个子模块，再把这个 break op 单独保存成一个 SubModuleInfo：

// tools/cpp/compilefornpu.cpp:267
for (int si=0; si<selectOps.size(); ++si) {
    auto i = selectOps[si];
    auto op = net->oplists()->GetAs<Op>(i);
    if (isBreakOp(op)) {
        if (current.opList.size() > 0) {
            submodule.emplace_back(std::move(current));
        }
        SubModuleInfo controlOp;
        controlOp.opList = {i};
        controlOp.isBreak = true;
        ...
        submodule.emplace_back(std::move(controlOp));
        continue;
    }
    current.opList.emplace_back(i);
}

isBreakOp(...) 的判别规则是，控制流算子属于 break op，例如 OpType_While、OpType_If 等：

// tools/cpp/compilefornpu.cpp:102
static bool isBreakOp(const Op* op) {
    bool isWhileControlflow = false;
    if (op->type() == OpType_While && op->main_as_WhileParam() != nullptr) {
        isWhileControlflow = true;
    }
    if (op->type() == OpType_If || isWhileControlflow || op->type() == OpType_Where || op->type() == OpType_Segment || op->type() == OpType_Unique || op->type() == OpType_NonMaxSuppressionV2) {
        return true;
    }
    if (!_npuSupportOp(op)) {
        return true;
    }
    return false;
}

对当前 QNN LLM 导出，需要注意 Attention + kv_cache。默认配置下，使用 KV cache 的注意力算子会被 _npuSupportOp(...) 判成不支持，随后被 isBreakOp(...) 切断：

// tools/cpp/compilefornpu.cpp:89
static bool _npuSupportOp(const Op* op) {
    if (gMaxKVSize > 0) {
        return true;
    }
    if (op->type() == OpType_Attention) {
        auto attn = op->main_as_AttentionParam();
        if (nullptr != attn && attn->kv_cache()) {
            return false;
        }
    }
    return true;
}

3.3.3 补切动态 shape

第一次切图主要看 op 类型。接下来还会用 _splitSubModuleForShapeConst(...) 做第二次切分：

1
2

// tools/cpp/compilefornpu.cpp:295
submodule = _splitSubModuleForShapeConst(submodule, net, sharedConst);

这一步处理的是“shape 推导依赖输入内容”的 op。判断入口在 _findBreakIndex(...)：

// tools/cpp/compilefornpu.cpp:214
int inputNum = op->inputIndexes()->size();
auto dims = SizeComputer::needInputContent(op, inputNum);
for (auto index : dims) {
    if (index < inputNum) {
        if (constMask[op->inputIndexes()->data()[index]] != 1) {
            res.emplace_back(v);
            break;
        }
    }
}

含义是：如果某个 op 的 shape 计算需要读取输入 tensor 的内容，并且这个输入不是常量，就把这个 op 作为切分点。这样可以避免把动态 shape / 内容相关 shape 逻辑直接塞进 NPU 子图里。

3.3.4 计算子图边界

SubModuleInfo 里真正描述切图边界的是：

// tools/cpp/compilefornpu.cpp:56
struct SubModuleInfo {
    std::vector<int> opList;
    std::vector<int> inputs;
    std::vector<int> outputs;
    std::vector<int> tensorMask;
    bool isBreak = false;
};

每个连续子图的 inputs / outputs 都是根据子图内部 op 的 tensor 使用情况计算出来。_computeTensorMask(...) 会先给 tensor 打标记，含义如下：

1
2
3

1: 这个 tensor 被当前子图消费，是子图输入
2: 这个 tensor 由当前子图产生，是子图输出
3: 这个 tensor 既被当前子图消费又由当前子图产生，是子图内部中间 tensor

对应代码在 _createSubModuleInfo(...) 里：

// tools/cpp/compilefornpu.cpp:299
if (!m.isBreak) {
    _computeTensorMask(m, net);
    for (int i=0; i<m.tensorMask.size(); ++i) {
        if (1 == m.tensorMask[i]) {
            if (noComputeIndexes.find(i) != noComputeIndexes.end()) {
                continue;
            }
            m.inputs.emplace_back(i);
            continue;
        }
        if (2 == m.tensorMask[i]) {
            m.outputs.emplace_back(i);
            continue;
        }
        if (3 == m.tensorMask[i]) {
            if (outputIndexes.find(i) != outputIndexes.end()) {
                m.outputs.emplace_back(i);
            }
        }
    }
}

产生的边界规则可以写成：

子图消费、但不是子图内部产生的 tensor，是子图输入；
子图产生、并且需要给后续 op 或最终输出使用的 tensor，是子图输出；
子图内部产生又内部消费的 tensor，是中间 tensor，默认不暴露；
如果某个中间 tensor 被后续子图需要，代码会把它补进前一个子图的 outputs，对应逻辑如下：

// tools/cpp/compilefornpu.cpp:348
for (int sub=0; sub < moduleIndex; ++sub) {
    if (submodule[sub].tensorMask.empty()) {
        continue;
    }
    if (submodule[sub].tensorMask[index] == 2) {
        find = true;
        break;
    }
    if (submodule[sub].tensorMask[index] == 3) {
        submodule[sub].outputs.emplace_back(index);
        submodule[sub].tensorMask[index] = 2;
        find = true;
        break;
    }
}

compilefornpu 切图时不按层数、名字或者固定 pattern 切分，而是按 tensor 的数据依赖关系确定子图边界。

3.4 过滤非卷积子图

_createSubModuleInfo(...) 得到的是候选子图。还有一个过滤条件：如果候选子图里没有 OpType_Convolution，就重新标记成 isBreak = true：

// tools/cpp/compilefornpu.cpp:1068
bool hasConvolution = false;
for (auto opIndex : subModulesInfo[i].opList) {
    auto op = net->oplists()->GetAs<Op>(opIndex);
    if (op->type() == OpType_Convolution) {
        hasConvolution = true;
        break;
    }
}
if (!hasConvolution) {
    subModulesInfo[i].isBreak = true;
}

这个过滤的效果是：只转换含有卷积算子的子图，其他子图直接保留在主图中。

3.5 收集子图 IO

切图完成后，主流程会按每一组 testdir 输入跑所有子图：

// tools/cpp/compilefornpu.cpp:1040
for (int inputIndex=0; inputIndex < inputs.size(); ++inputIndex) {
    std::map<int, MNN::Express::VARP> stackes;
    ...
    std::vector<SubModuleIO> moduleIO(subModulesInfo.size());
    for (int i=0; i<subModulesInfo.size(); ++i) {
        auto& current = subModulesInfo[i];
        std::vector<MNN::Express::VARP> subInputs;
        for (auto index : current.inputs) {
            subInputs.emplace_back(stackes[index]);
        }
        moduleIO[i] = _getSubModuleIO(subInputs, current, bufferPair.first, bufferPair.second, srcMNN);
        for (int j=0; j<current.outputs.size(); ++j) {
            stackes.insert(std::make_pair(current.outputs[j], moduleIO[i].outputs[j]));
        }
    }

这里的 stackes 是一个 tensor index -> VARP 表。每跑完一个子图，就把它的输出放回 stackes，给后续子图继续使用。

_getSubModuleIO(...) 会用原始 MNN 模型加载当前子图的输入输出名，然后跑 CPU/default 路径得到参考输出：

// tools/cpp/compilefornpu.cpp:399
static SubModuleIO _getSubModuleIO(
    std::vector<MNN::Express::VARP> inputs,
    const SubModuleInfo& info,
    const void* buffer,
    size_t bufferSize,
    std::string srcpath) {
    ...
    std::shared_ptr<MNN::Express::Module> m(
        MNN::Express::Module::load(inputNames, outputNames, (const uint8_t*)buffer, bufferSize, rtmgr),
        MNN::Express::Module::destroy);
    ...
    auto outputs = m->onForward(inputs);
    io.inputs = inputs;
    io.outputs.resize(outputs.size());
    for (int i=0; i<outputs.size(); ++i) {
        io.outputs[i] = MNN::Express::_Clone(outputs[i], true);
    }
    return io;
}

如果子图里有带 kv_cache 的 Attention，这里还会通过 callback 记录 KV state 的形状：

// tools/cpp/compilefornpu.cpp:419
MNN::TensorCallBackWithInfo beforeCallBack = [&](const std::vector<MNN::Tensor*>& ntensors, const MNN::OperatorInfo* info) {
    auto opName = info->name();
    if (info->type() != "Attention") {
        return true;
    }
    if (attentionNames.find(opName) != attentionNames.end()) {
        auto query = ntensors[0];
        auto key = ntensors[1];
        auto value = ntensors[2];
        int seq_len = query->length(1);
        auto numHead = query->length(2);
        auto headDim = query->length(3);
        auto kvNumHead = key->length(2);
        std::vector<int> kvDims = {kvNumHead, 1, 1, headDim};
        io.kvcache.emplace_back(kvDims);
    }
    return true;
};

3.6 编译并替换 Plugin

真正触发 QNN 导出的是 _compileSubModule(...)：

// tools/cpp/compilefornpu.cpp:450
static std::unique_ptr<MNN::OpT> _compileSubModule(
    const SubModuleIO& io,
    SubModuleInfo& info,
    const void* buffer,
    size_t bufferSize,
    const std::string& path,
    std::string srcpath,
    const std::string& targetNpuPath,
    float& cpuTotal,
    float& npuTotal,
    int shapeIndex,
    std::string graphicName) {

该方法的核心调用在下面这段，其中 config.type = MNN_CONVERT_QNN：

// tools/cpp/compilefornpu.cpp:470
MNN::ScheduleConfig config;
config.type = gNPUType;
std::shared_ptr<MNN::Express::Executor::RuntimeManager> rtmgr(
    MNN::Express::Executor::RuntimeManager::createRuntimeManager(config));
rtmgr->setExternalFile((srcpath + ".weight").c_str());
rtmgr->setCache(path.c_str());
rtmgr->setHint(MNN::Interpreter::KVCACHE_SIZE_LIMIT, gMaxKVSize);
MNN::Express::Module::Config mdconfig;
mdconfig.shapeMutable = false;
std::shared_ptr<MNN::Express::Module> m(
    MNN::Express::Module::load(inputNames, outputNames, (const uint8_t*)buffer, bufferSize, rtmgr, &mdconfig),
    MNN::Express::Module::destroy);
auto predict = m->onForward(io.inputs);
if (gNeedOffline) {
    break;
}

这里的 onForward(io.inputs) 不只是为了拿一次输出。对于 QNN 离线导出，它的主要作用是驱动一次 StaticModule 前向，让 QNN convert 后端根据当前子图输入 shape 生成子图 graph 材料。因为 gNeedOffline == true，触发导出后会直接 break，不会继续做误差检查和测速。

导出完成后，_compileSubModule(...) 会创建一个新的 Plugin op：

// tools/cpp/compilefornpu.cpp:532
std::unique_ptr<MNN::OpT> op(new OpT);
op->inputIndexes = info.inputs;
op->outputIndexes = info.outputs;
op->name = targetNpuPath;
op->type = MNN::OpType_Plugin;
op->main.type = MNN::OpParameter_Plugin;
op->main.value = new MNN::PluginT;
auto extra = op->main.AsPlugin();
extra->type = gNPUName;

这个 Plugin 保留了原子图的输入输出 tensor index，相当于用一个 op 占住原来整段子图的输入输出边界。写入的关键 attr 包括：

attr	作用
`path`	最终 QNN binary 的相对路径，例如 `qnn/graph0.bin`
`inputs`	Plugin 输入对应的 QNN tensor 名，一般是 `t<tensor_index>`
`outputs`	Plugin 输出对应的 QNN tensor 名
`allGraphName`	`.bin` 内多个 graph 的名字顺序
`allInputShape`	当前 graph 对应的输入 shape
`o_<shapeIndex>_<outputIndex>`	当前 shape 下输出 tensor 的形状、类型和 format
`state`	KV cache state 信息，存在 KV 下沉时使用

以 inputs / outputs 为例，代码直接用子图边界 tensor index 生成 QNN tensor 名：

// tools/cpp/compilefornpu.cpp:547
attr->key = "inputs";
attr->list.reset(new ListValueT);
attr->list->s.resize(inputNames.size());
for (int i=0; i<inputNames.size(); ++i) {
    attr->list->s[i] = std::string("t") + std::to_string(info.inputs[i]);
}

// tools/cpp/compilefornpu.cpp:625
attr->key = "outputs";
attr->list.reset(new ListValueT);
attr->list->s.resize(outputNames.size());
for (int i=0; i<outputNames.size(); ++i) {
    attr->list->s[i] = std::string("t") + std::to_string(info.outputs[i]);
}

随后发生主图替换：

// tools/cpp/compilefornpu.cpp:1124
for (int moduleIndex=0; moduleIndex<subModulesInfo.size(); ++moduleIndex) {
    auto moduleInfo = subModulesInfo[moduleIndex];
    if (moduleInfo.isBreak) {
        continue;
    }
    for (auto& index : moduleInfo.opList) {
        dstNet->oplists[index].reset();
    }
    dstNet->oplists[moduleInfo.opList[0]] = std::move(npuOps[moduleIndex]);
}

替换关系如下：

原始连续 op 区间:
  opA -> opB -> opC

替换后:
  Plugin(type="QNN", inputs=原区间输入, outputs=原区间输出)

然后再调用 _reIndexTensor(...) 和 _reOrderOp(...) 清理未使用 tensor，并重新拓扑排序：

1
2
3

// tools/cpp/compilefornpu.cpp:1140
_reIndexTensor(dstNet.get());
_reOrderOp(dstNet.get());

3.7 onForward 生成 graph 材料

_compileSubModule(...) 里的 onForward(io.inputs) 走的是一次真实的 MNN 模块执行入口，但在 MNN_CONVERT_QNN 后端下，执行的重点不是计算数值结果，而是触发 QNN graph 的构建和记录。

完整调用关系可以看成：

_compileSubModule(...)
├── RuntimeManager(type = MNN_CONVERT_QNN)
├── rtmgr->setCache("qnn/graph0")
│   └── QnnRuntime::onSetCachePath(...)
│       └── QNNConvertor::OutputDir = "qnn/graph0"
├── Module::load(...)
└── m->onForward(io.inputs)
    └── StaticModule::onForward(...)
        ├── Variable::compute(inputs)
        ├── StaticModule::_resize(inputs)
        │   └── Session::resize()
        │       ├── Pipeline::encode(...)
        │       │   └── 把 ScheduleInfo 整理成 command buffer
        │       └── Pipeline::allocMemory(...)
        │           ├── QnnBackend::onResizeBegin()
        │           │   └── graphCreate(...)
        │           │       └── QNNConvertor::RecordBegin(...)
        │           ├── Execution::onResize(...)
        │           │   └── QNNCommonExecution::onEncode(...)
        │           │       ├── tensorCreateGraphTensor(...)
        │           │       │   └── QNNConvertor::RecordTensor(...)
        │           │       └── graphAddNode(...)
        │           │           └── QNNConvertor::RecordNode(...)
        │           └── QnnBackend::onResizeEnd()
        │               └── graphFinalize(...)
        │                   └── QNNConvertor::RecordEnd()
        └── StaticModule::_execute()
            └── Session::run()
                └── QNN convert 模式下 graphExecute(...) 不走真实 QNN 执行

创建 RuntimeManager 时，config.type = gNPUType。QNN 导出场景下，这个类型就是 MNN_CONVERT_QNN；setCache(path) 传入的是当前子图 graph 源目录，例如 qnn/graph0：

// tools/cpp/compilefornpu.cpp:470
MNN::ScheduleConfig config;
config.type = gNPUType;
std::shared_ptr<MNN::Express::Executor::RuntimeManager> rtmgr(
    MNN::Express::Executor::RuntimeManager::createRuntimeManager(config));
rtmgr->setExternalFile((srcpath + ".weight").c_str());
rtmgr->setCache(path.c_str());

setCache(path) 最终会进入 QnnRuntime::onSetCachePath(...)，并把这个路径记录到 QNNConvertor::OutputDir。后续所有 RecordTensor(...) / RecordNode(...) 写文件时都会落到这个目录：

// source/backend/qnn/backend/QNNBackend.cpp:1726
bool QnnRuntime::onSetCachePath(const char* path, int mode) {
#ifdef ENABLE_QNN_CONVERT_MODE
    MNN_ASSERT(path != nullptr);
    QNNConvertor::OutputDir = std::string(path);
    MNNCreateDir(path);
#endif
    return true;
}

onForward(io.inputs) 进入 StaticModule 后，先根据 io.inputs 里的真实输入张量更新子图输入 shape。_resize(...) 里会把外部 VARP 对应的 tensor 形状同步到 mInputTensors，一旦 shape 变化就标记 Session 需要 resize：

// express/module/StaticModule.cpp:530
if (_resizeTensor(mInputTensors[i], inputTensor, mSession.get(), nullptr)) {
    mSession->setNeedResize();
}
...
code = mSession->resize();

所以 testdir/1 和 testdir/<chunk_size> 会在这里进入 Session::resize()，分别生成 decode / prefill 两份 graph 材料。

Session::resize() 接着会先调用 encode，再调用 allocMemory：

// source/core/Session.cpp:285
if (mNeedResize) {
    bool debug = mCallBackMode == Interpreter::Session_Debug;
    for (auto& iter : mPipelines) {
        auto error = iter->encode(debug, permitCodegen);
        ...
    }
    mNeedResize = false;
    mNeedMalloc = true;
    firstMalloc = true;
}
if (mNeedMalloc) {
    for (auto& iter : mPipelines) {
        auto error = iter->allocMemory(firstMalloc, forbidReplace);
        ...
    }
}

Pipeline::encode(...) 的作用是把 ScheduleInfo 里的 op / tensor 依赖整理成 MNN 内部的 command buffer。后续 allocMemory(...) 会基于这些 command 创建后端算子 Execution，并调用每个 Execution 的 onResize(...)：

// source/core/Pipeline.cpp:537
static ErrorCode _createExecutions(
    Schedule::PipelineInfo& mInfo,
    const std::string& externalFile,
    std::vector<std::shared_ptr<BufferStorage>>& extraStorage) {
    ...
    iter.execution.reset(OpCommonUtils::createExecutionWithExternal(
        mBackend.get(), iter.inputs, iter.outputs, iter.op, &loader, tmpStorage));
}

// source/core/Pipeline.cpp:962
mBackend->onResizeBegin();
...
auto code = iter.execution->onResize(iter.workInputs, iter.workOutputs);
...
auto code = mBackend->onResizeEnd();

在 QNN 后端下，这些 Execution 通常就是对应的 QNN 执行器，例如 QNNConvolution。后续会在 onResize() 里把它们编码成 QNN graph 节点。

onResize() 前后还会配合两个 backend 生命周期回调：QnnBackend::onResizeBegin() 创建 QNN graph；QnnBackend::onResizeEnd() finalize graph：

// source/backend/qnn/backend/QNNBackend.cpp:1141
void QnnBackend::onResizeBegin() {
    clean();
    createContextAndGraph();
    return;
}

// source/backend/qnn/backend/QNNBackend.cpp:1147
ErrorCode QnnBackend::onResizeEnd() {
    buildOutputCast();
    buildOutputDequant();
    finalizeGraph();
    ...
}

QNN convert 模式的“记录动作”是通过 QNN API 函数表替换实现的。QNN_INTERFACE_VER_TYPE 本身是一张函数表，QnnBackend 后续调用 graphCreate(...)、graphAddNode(...)、tensorCreateGraphTensor(...) 时，都是从 mQnnInterface 这张表里取函数。

在普通 QNN 推理模式下，createQnnContext() 会从真实 QNN SDK 里拿 interface provider；在 ENABLE_QNN_CONVERT_MODE 下，qnnInterface 会被设置成 MNN 自己定义的 gQnnConvertorInterface：

// source/backend/qnn/backend/QNNBackend.cpp:43
#ifndef ENABLE_QNN_CONVERT_MODE
{
    QnnInterface_t** interfaceProviders = nullptr;
    uint32_t numProviders = 0;
    if (QNN::QnnInterface_getProviders((const QnnInterface_t***)&interfaceProviders, &numProviders) != QNN_SUCCESS) {
        ...
    }
    ...
    qnnInterface = interfaceProviders[pIdx]->QNN_INTERFACE_VER_NAME;
}
#else
    qnnInterface = QNN::gQnnConvertorInterface;
#endif

QnnRuntime::create(...) 会把 gContext.interface 传进 QnnRuntime，构造函数里再保存到 mQnnInterface：

// source/backend/qnn/backend/QNNBackend.cpp:1711
QnnRuntime* QnnRuntime::create(const Backend::Info& info) {
    if (QNN::gContext.deviceHandle == nullptr){
        QNN::createQnnContext();
    }
    return new QnnRuntime(info, gContext.interface, gContext.logHandle, gContext.backendHandle, gContext.deviceHandle);
}

// source/backend/qnn/backend/QNNBackend.cpp:1635
QnnRuntime::QnnRuntime(
    const Backend::Info& info,
    QNN_INTERFACE_VER_TYPE qnnInterface,
    Qnn_LogHandle_t qnnLogHandle,
    Qnn_BackendHandle_t qnnBackendHandle,
    Qnn_DeviceHandle_t qnnDeviceHandle) {
    ...
    mQnnInterface = qnnInterface;
}

所以 QnnBackend 里的调用代码不需要区分“真实 SDK”还是“离线导出”。它仍然写成：

// source/backend/qnn/backend/QNNBackend.cpp:1489
CALL_QNN(mRuntime->mQnnInterface.graphAddNode(mQnnGraphHandle, opConfig));

// source/backend/qnn/backend/QNNBackend.cpp:1532
CALL_QNN(mRuntime->mQnnInterface.tensorCreateGraphTensor(mQnnGraphHandle, staticTensor));

区别只在 mQnnInterface 指向哪张函数表。gQnnConvertorInterface 把这些 QNN API 槽位填成了 convertor 函数：

// source/backend/qnn/convertor/QNNConvertorInterface.cpp:96
QNN_INTERFACE_VER_TYPE gQnnConvertorInterface = {
    ...
    /* graphCreate */                            QnnConvertorGraph_Create,
    /* graphAddNode */                           QnnConvertorGraph_AddNode,
    /* graphFinalize */                          QnnConvertorGraph_Finalize,
    ...
    /* tensorCreateGraphTensor */                QnnConvertorTensor_CreateGraphTensor,
    ...
};

真实 QNN SDK 返回的 interface 和 gQnnConvertorInterface 是同一个类型：QNN_INTERFACE_VER_TYPE。这个类型本质上是一组函数指针槽位，只要每个槽位填进去的函数签名匹配，后续调用方就不需要知道这个函数来自真实 QNN SDK，还是来自 MNN 的 convertor。

可以用一个简化版结构理解：

struct QnnInterfaceLike {
    Qnn_ErrorHandle_t (*graphCreate)(...);
    Qnn_ErrorHandle_t (*graphAddNode)(Qnn_GraphHandle_t graphHandle, Qnn_OpConfig_t opConfig);
    Qnn_ErrorHandle_t (*graphFinalize)(...);
    Qnn_ErrorHandle_t (*tensorCreateGraphTensor)(Qnn_GraphHandle_t graph, Qnn_Tensor_t* tensor);
};

真实 QNN SDK 会提供一张类似这样的表：

QnnInterfaceLike realQnnInterface = {
    QnnGraph_Create,
    QnnGraph_AddNode,
    QnnGraph_Finalize,
    QnnTensor_CreateGraphTensor,
};

而 MNN convert 模式自己构造了一张同类型的表：

QnnInterfaceLike convertInterface = {
    QnnConvertorGraph_Create,
    QnnConvertorGraph_AddNode,
    QnnConvertorGraph_Finalize,
    QnnConvertorTensor_CreateGraphTensor,
};

QnnBackend 后续只持有 mQnnInterface，调用时等价于：

1
2

auto fn = mRuntime->mQnnInterface.graphAddNode;
fn(mQnnGraphHandle, opConfig);

如果 mQnnInterface 保存的是 gQnnConvertorInterface，这里的 fn 就是 QnnConvertorGraph_AddNode，调用链等价于：

mRuntime->mQnnInterface.graphAddNode(...)
    == gQnnConvertorInterface.graphAddNode(...)
    == QnnConvertorGraph_AddNode(...)
    -> QNNConvertor::RecordNode(opConfig)

这些 convertor 函数不会真正调用 QNN SDK，而是转成 QNNConvertor::Record*：

// source/backend/qnn/convertor/QNNConvertorInterface.cpp:58
Qnn_ErrorHandle_t QnnConvertorGraph_Create(...) {
    *graphHandle = NOTNULL;
    QNNConvertor::RecordBegin(graphName);
    return QNN_SUCCESS;
}

// source/backend/qnn/convertor/QNNConvertorInterface.cpp:76
Qnn_ErrorHandle_t QnnConvertorGraph_AddNode(Qnn_GraphHandle_t graphHandle, Qnn_OpConfig_t opConfig) {
    QNNConvertor::RecordNode(opConfig);
    return QNN_SUCCESS;
}

// source/backend/qnn/convertor/QNNConvertorInterface.cpp:90
Qnn_ErrorHandle_t QnnConvertorTensor_CreateGraphTensor(Qnn_GraphHandle_t graph, Qnn_Tensor_t* tensor) {
    QNNConvertor::RecordTensor(tensor);
    return QNN_SUCCESS;
}

QNN convert 模式复用了原来的 backend 建图路径，同时把 QNN SDK 函数表换成了 convertor 函数表。

每个 QNN Execution 的 onResize(...) 会继续调用自己的 onEncode(...)，把当前 MNN op 翻译成 QNN tensor 和 QNN node。公共入口在 QNNCommonExecution：

// source/backend/qnn/execution/QNNCommonExecution.cpp:19
ErrorCode QNNCommonExecution::onResize(
    const std::vector<Tensor *> &inputs,
    const std::vector<Tensor *> &outputs) {
    this->setNodeName(mOp, inputs, outputs);
    ErrorCode result = this->onEncode(inputs, outputs);
    ...
    return NO_ERROR;
}

例如卷积 op 会通过注册器创建 QNNConvolution：

// source/backend/qnn/execution/QNNConvolution.cpp:748
class QNNConvolutionCreator : public QnnBackend::Creator {
public:
    virtual QNNCommonExecution * onCreate(
        const std::vector<Tensor*>& inputs,
        const std::vector<Tensor*>& outputs,
        const MNN::Op* op,
        Backend* backend) const override {
        ...
        return new QNNConvolution(backend, op);
    }
};

REGISTER_QNN_OP_CREATOR(QNNConvolutionCreator, OpType_Convolution)

在具体 onEncode(...) 里，权重、bias、临时 tensor 会通过 createStaticTensor(...) / createStaticFloatTensor(...) 注册成 QNN tensor，算子本身会通过 addNodeToGraph(...) 注册成 QNN node：

// source/backend/qnn/execution/QNNCommonExecution.cpp:68
void QNNCommonExecution::createStaticTensor(
    const std::string & name,
    Qnn_DataType_t dataType,
    const std::vector<uint32_t> & dimensions,
    const void * buffer,
    Qnn_QuantizeParams_t quantizeParam) {
    std::string tensorName = mNodeName + "_" + name;
    std::shared_ptr<QNNTensorWrapper> tensorWrapper =
        QNNTensorWrapper::createStaticTensor(tensorName, dataType, dimensions, buffer, quantizeParam);
    mBackend->addStaticTensorToGraph(tensorWrapper->getNativeTensor());
    ...
}

// source/backend/qnn/execution/QNNCommonExecution.cpp:167
mBackend->addNodeToGraph(
    mOpConfigVersion,
    mNodeName.c_str(),
    mPackageName.c_str(),
    mNodeType.c_str(),
    mParams,
    mInputs,
    mOutputs);

这些调用最终进入 QnnBackend，再通过 mQnnInterface 转到 convertor 函数表里的 tensorCreateGraphTensor(...) 和 graphAddNode(...)：

// source/backend/qnn/backend/QNNBackend.cpp:1472
void QnnBackend::addNodeToGraph(
    Qnn_OpConfigVersion_t version,
    const char* nodeName,
    const char* packageName,
    const char* nodeType,
    std::vector<Qnn_Param_t> & params,
    std::vector<Qnn_Tensor_t> & inputs,
    std::vector<Qnn_Tensor_t> & outputs) {
    ...
    CALL_QNN(mRuntime->mQnnInterface.graphAddNode(mQnnGraphHandle, opConfig));
}

// source/backend/qnn/backend/QNNBackend.cpp:1530
void QnnBackend::addStaticTensorToGraph(Qnn_Tensor_t * staticTensor) {
    MNN_ASSERT(staticTensor->v1.type == QNN_TENSOR_TYPE_STATIC);
    CALL_QNN(mRuntime->mQnnInterface.tensorCreateGraphTensor(mQnnGraphHandle, staticTensor));
}

QNNConvertor 的 RecordBegin(...) / RecordTensor(...) / RecordNode(...) / RecordEnd(...) 会把这些调用整理成内部 QNNCommand。每个 QNNCommand 再交给 Translate(cmd)，写进当前 graph 的 .cpp：

// source/backend/qnn/convertor/QNNConvertor.cpp:57
void QNNConvertor::RecordBegin(const char* graphName) {
    MNN_ASSERT(!(QNNConvertor::OutputDir.empty()));
    QNNTranslator::GraphNameSymbol = GetLastDirName(QNNConvertor::OutputDir);
    ...
    std::string cppFilePath = MNNFilePathConcat(
        QNNConvertor::OutputDir,
        QNNTranslator::GraphNameSymbol + ".cpp");
    QNNConvertor::CppFilePointer = std::fopen(cppFilePath.c_str(), "w");
}

// source/backend/qnn/convertor/QNNConvertor.cpp:79
void QNNConvertor::RecordTensor(const Qnn_Tensor_t * tensor) {
    ...
    QNNConvertor::Translate(cmd);
    if (cmd.commandTensor.type == Qnn_Convertor_Tensor_t::TENSOR_STATIC) {
        QNNConvertor::DumpBuffer(
            cmd.commandTensor.name,
            cmd.commandTensor.clientBuf.data,
            cmd.commandTensor.clientBuf.dataSize);
    }
}

// source/backend/qnn/convertor/QNNConvertor.cpp:124
void QNNConvertor::RecordNode(const Qnn_OpConfig_t & opConfig) {
    ...
    QNNConvertor::Translate(cmd);
}

每个记录函数都包括Translate(cmd)方法，其本身分两步：

调用 QNNTranslator::TranslateCommand(cmd)，把 QNNCommand 翻译成一组 C++ 源码行；
把这些源码行追加到 CppBuffer，再通过 fwrite(...) 写入 CppFilePointer。

// source/backend/qnn/convertor/QNNConvertor.cpp:159
void QNNConvertor::Translate(const QNNCommand & cmd) {
    std::vector<std::string> cppLines = QNNTranslator::TranslateCommand(cmd);
    for (const std::string& line : cppLines) {
        QNNConvertor::CppBuffer.append(line);
        QNNConvertor::CppBuffer.push_back('\n');
    }
    size_t written = std::fwrite(
        QNNConvertor::CppBuffer.data(),
        1,
        QNNConvertor::CppBuffer.size(),
        QNNConvertor::CppFilePointer);
    ...
    QNNConvertor::CppBuffer.clear();
}

TranslateCommand(...) 按命令类型分发：

// source/backend/qnn/convertor/QNNConvertor.cpp:195
std::vector<std::string> QNNTranslator::TranslateCommand(const QNNCommand & cmd) {
    switch (cmd.type) {
        case QNNCommandTypeBegin:
            return QNNTranslator::TranslateBegin();
        case QNNCommandTypeTensor:
            return QNNTranslator::TranslateTensor(cmd.commandTensor);
        case QNNCommandTypeNode:
            return QNNTranslator::TranslateNode(cmd.commandNode);
        case QNNCommandTypeEnd:
            return QNNTranslator::TranslateEnd();
        ...
    }
}

这几类命令对应的输出内容是：

命令	翻译函数	写入 `.cpp` 的内容
`QNNCommandTypeBegin`	`TranslateBegin()`	`#include`、`QnnModel_composeGraphs(...)` 函数头、`QnnModel graph*` 初始化
`QNNCommandTypeTensor`	`TranslateTensor(...)`	`Qnn_Tensor_t` 定义、维度、数据类型、量化参数、`addTensor(...)`
`QNNCommandTypeNode`	`TranslateNode(...)`	node 的 params / inputs / outputs 数组，以及 `graph.addNode(...)`
`QNNCommandTypeEnd`	`TranslateEnd()`	`getGraphInfoFromModels(...)`、`QnnModel_freeGraphsInfo(...)` 和函数收尾

以 tensor 和 node 为例，TranslateTensor(...) 会生成 Qnn_Tensor_t 并在需要时写入 addTensor(...)：

// source/backend/qnn/convertor/QNNConvertor.cpp:254
std::vector<std::string> QNNTranslator::TranslateTensor(const QNNCommandTensor& cmdT) {
    ...
    result.push_back("  Qnn_Tensor_t " + tensorNameSymbol + " = QNN_TENSOR_INIT;");
    ...
    result.push_back("  " + tensorNameSymbol + ".v1.name = \"" + sName +"\";");
    result.push_back("  " + tensorNameSymbol + ".v1.type = " + QNNTranslator::MapTensorType(cmdT.type) + ";");
    result.push_back("  " + tensorNameSymbol + ".v1.dataType = " + QNNTranslator::MapDataType(cmdT.dataType) + ";");
    ...
    if (shouldBeAdded) {
        result.push_back("  VALIDATE(" + QNNTranslator::GraphNameSymbol + ".addTensor(\"" + sName + "\", " + tensorNameSymbol + "), err);");
    }
    return result;
}

TranslateNode(...) 会生成 params_*、inputs_*、outputs_*，再写一行 addNode(...)：

// source/backend/qnn/convertor/QNNConvertor.cpp:303
std::vector<std::string> QNNTranslator::TranslateNode(const QNNCommandNode& cmdN) {
    ...
    APPEND_VECTOR(result, QNNTranslator::TranslateNodeParamArray(...));
    APPEND_VECTOR(result, QNNTranslator::TranslateNodeInputArray(...));
    APPEND_VECTOR(result, QNNTranslator::TranslateNodeOutputArray(...));
    result.push_back("  VALIDATE(" + QNNTranslator::GraphNameSymbol + ".addNode(QNN_OPCONFIG_VERSION_1, \"" + sName + "\", \"" + std::string(cmdN.packageName) + "\", \"" + std::string(cmdN.typeName) + "\",");
    ...
    return result;
}

.raw 文件不是 Translate(cmd) 写的，而是 RecordTensor(...) 遇到 TENSOR_STATIC 时额外调用 DumpBuffer(...) 写出来：

// source/backend/qnn/convertor/QNNConvertor.cpp:117
if (cmd.commandTensor.type == Qnn_Convertor_Tensor_t::TENSOR_STATIC) {
    QNNConvertor::DumpBuffer(
        cmd.commandTensor.name,
        cmd.commandTensor.clientBuf.data,
        cmd.commandTensor.clientBuf.dataSize);
}

// source/backend/qnn/convertor/QNNConvertor.cpp:173
void QNNConvertor::DumpBuffer(const char * name, const void * buffer, size_t size) {
    std::string dataPath = MNNFilePathConcat(QNNConvertor::OutputDir, std::string(name) + ".raw");
    FILE* fp = std::fopen(dataPath.c_str(), "wb");
    ...
    std::fwrite(buffer, 1, size, fp);
}

所以 Step2 生成的 graph 源目录可以这样理解：

graph*.cpp：RecordBegin/RecordTensor/RecordNode/RecordEnd -> Translate(cmd) 逐段写出来的 QNN model 源码；
*.raw：RecordTensor(...) 遇到 static tensor 时，把常量 buffer 单独 dump 出来的二进制数据。

因此这一句代码：

1
2

// tools/cpp/compilefornpu.cpp:479
auto predict = m->onForward(io.inputs);

会让 QNN 后端看到具体输入 / 输出 tensor 形状、常量权重和每个 op 的参数，并把这些信息记录成 qnn/graph*/graph*.cpp 和 qnn/graph*/*.raw。

3.8 合并多 shape

因为 testdir 有 decode 和 prefill 两组输入，main 会为每组输入都生成一个 dstNet：

// tools/cpp/compilefornpu.cpp:1040
for (int inputIndex=0; inputIndex < inputs.size(); ++inputIndex) {
    ...
    allNets.emplace_back(std::move(dstNet));
}

第一组 shape 生成 graph0，第二组 shape 会生成类似 graph1_0 的 graph 名：

// tools/cpp/compilefornpu.cpp:1094
if (inputIndex == 0) {
    srcPath = gCacheDir + "/" + gGraphName +  std::to_string(npuIndex);
    graphicName = gGraphName +  std::to_string(npuIndex);
} else {
    srcPath = gCacheDir + "/" + gGraphName + std::to_string(inputIndex) + "_" +  std::to_string(npuIndex);
    graphicName = gGraphName + std::to_string(inputIndex) + "_" +  std::to_string(npuIndex);
}

最后 _fuse(...) 会把后续 shape 的 Plugin attr 合并回第一组 dstNet：

// tools/cpp/compilefornpu.cpp:1145
auto dstNet = allNets[0].get();
for (int i=1; i<allNets.size(); ++i) {
    _fuse(dstNet, allNets[i].get());
    allNets[i].reset();
}

_fuse(...) 会跳过 inputs / outputs，只追加 allGraphName、allInputShape、o_<shapeIndex>_<outputIndex> 这类 shape 相关 attr：

// tools/cpp/compilefornpu.cpp:690
for (auto&& srcAttr : src->attr) {
    if (srcAttr->key == "inputs" || srcAttr->key == "outputs") {
        continue;
    }
    auto dstIter = dstKeys.find(srcAttr->key);
    if (dstIter == dstKeys.end()) {
        dst->attr.emplace_back(std::move(srcAttr));
        continue;
    }
    if (dstIter->second->list != nullptr && srcAttr->list != nullptr) {
        dstIter->second->list->s.insert(dstIter->second->list->s.end(), srcAttr->list->s.begin(), srcAttr->list->s.end());
        dstIter->second->list->i.insert(dstIter->second->list->i.end(), srcAttr->list->i.begin(), srcAttr->list->i.end());
    }
}

这一步结束后，qnn/llm.mnn 里的同一个 Plugin 会同时保存 decode / prefill 两组 graph：

Plugin(type="QNN")
├── path: qnn/graph0.bin
├── allGraphName: [graph0, graph1_0, ...]
├── allInputShape: [decode 输入 shape..., prefill 输入 shape...]
└── o_0_0 / o_1_0 / ...: 不同 shape 下的输出描述

3.9 产物

Step2 结束时，真正落盘的产物有三类：

tmp/
├── qnn/
│   ├── llm.mnn                 # 插入 Plugin(type="QNN") 后的主图
│   ├── graph0/                 # 第一组 shape 的 QNN graph 源目录
│   │   ├── graph0.cpp
│   │   └── *.raw
│   └── graph1_0/               # 第二组 shape 的 QNN graph 源目录
│       ├── graph1_0.cpp
│       └── *.raw
└── npu_postreat.json           # Step3 合成 context binary 的 merge 配置

4. npu_postreat.json 的作用

compilefornpu 还会写 npu_postreat.json，里面最重要的是 merge：

{
  "type": "QNN",
  "merge": {
    "qnn/graph0.bin": [
      "qnn/graph0",
      "qnn/graph1_0"
    ]
  },
  "cache": "qnn"
}

merge 的含义是：

`1`	`最终生成的 QNN binary -> 参与合并的 graph 源目录列表`

一个 Plugin 可能对应多组 shape。离线阶段先为每个 shape 生成 graph 源目录，再通过 merge 合成一个 context binary。运行时通过 shapeIndex 选择 .bin 里的具体 graph handle。

5. Step3：生成 context binary

convert(args) 的 Step3 调用 compile_qnn(args)：

1
2
3

# transformers/llm/export/npu/generate_llm_qnn.py:81
print("Step3: Compile to QNN")
compile_qnn(args)

compile_qnn(args) 会从 args.mnn_path 反推出源码树里的 source/backend/qnn/npu_convert.py 路径，并在 tmp 目录下执行它：

# transformers/llm/export/npu/generate_llm_qnn.py:39
def compile_qnn(args):
    exe = os.path.join(os.getcwd(), args.mnn_path, "..", "source", "backend", "qnn", "npu_convert.py")
    cache = os.path.join(os.getcwd(), args.cache_path)
    process = subprocess.Popen(
        "python3 " + exe + ' npu_postreat.json %d ' %args.soc_id + ' ' + args.dsp_arch,
        cwd = cache,
        shell=True
    )

命令展开后是：

python3 <repo>/source/backend/qnn/npu_convert.py \
  npu_postreat.json \
  <soc_id> \
  <dsp_arch>

到 Step3 时，compilefornpu 已经把 MNN 子图导出成 QNN graph 的源码材料。npu_convert.py 会继续调用 QNN SDK，把这些材料编译成运行时可直接加载的 HTP context binary。

整体调用关系是：

npu_postreat.json
└── merge: qnn/graph0.bin -> [qnn/graph0, qnn/graph1_0, ...]  # 一个 Plugin 的多组 shape graph
    ├── for each graph 源目录
    │   ├── tar *.raw -> graph*.bin                            # 打包 graph 依赖的 raw 常量数据
    │   ├── qnn-model-lib-generator
    │   │   ├── -c graph*.cpp                                  # QNN graph C++ 源码
    │   │   ├── -b graph*.bin                                  # 上一步打包的 raw 数据
    │   │   └── -> x86_64-linux-clang/libgraph*.so             # 生成 QNN model library
    │   └── 记录 graph name 和 lib 路径
    │
    └── qnn-context-binary-generator
        ├── --model libgraph0.so,libgraph1_0.so,...             # 多个 shape graph 一起写入 context
        ├── --backend <QNN_SDK_ROOT>/lib/.../libQnnHtp.so        # 目标 HTP backend
        ├── --config_file ./context_config.json                 # 指向 HTP backend extension 配置
        ├── --binary_file graph0
        └── --output_dir qnn
            └── qnn/graph0.bin                                  # 最终 Plugin 加载的 context binary

5.1 读取后处理配置

npu_convert.py 一开始从环境变量和命令参数读取输入：

# source/backend/qnn/npu_convert.py:8
qnn_sdk = os.environ["QNN_SDK_ROOT"]
with open(sys.argv[1]) as f:
    post_treat = json.load(f)
soc_id = int(sys.argv[2])
dsp_arch = sys.argv[3]

sys.argv[1] 就是 npu_postreat.json。soc_id 和 dsp_arch 来自导出命令参数，用来写入 HTP backend 的设备配置。

随后脚本定位 QNN SDK 的两个工具，并取出 merge：

# source/backend/qnn/npu_convert.py:15
qnn_bin_path = os.path.join(qnn_sdk, 'bin', 'x86_64-linux-clang')
qnnModelLibGenerator = os.path.join(qnn_bin_path, 'qnn-model-lib-generator')
qnnContextBinaryGenerator = os.path.join(qnn_bin_path, 'qnn-context-binary-generator')
merges = post_treat["merge"]

merge 的 key 是最终要生成的 context binary 路径，例如 qnn/graph0.bin；value 是这个 binary 内要合并的 graph 源目录，例如 qnn/graph0 和 qnn/graph1_0。

5.2 写 QNN context 配置

脚本会生成两个配置文件。

第一个是 context_config.json，它只负责告诉 qnn-context-binary-generator 去哪里加载 HTP backend extension：

# source/backend/qnn/npu_convert.py:23
context_config = {
    "backend_extensions": {
        "shared_library_path": os.path.join(qnn_sdk, "lib","x86_64-linux-clang","libQnnHtpNetRunExtensions.so"),
        "config_file_path": "./htp_backend_extensions.json"
    }
}
htp_so = os.path.join(qnn_sdk, 'lib','x86_64-linux-clang','libQnnHtp.so')

第二个是 htp_backend_extensions.json 的主体配置：

# source/backend/qnn/npu_convert.py:33
htp_backend_extensions = {
    "graphs": [
        {
            "vtcm_mb": 8,
            "O": 3.0,
            "fp16_relaxed_precision": 1,
            "hvx_threads": 4
        }
    ],
    "devices": [
        {
            "soc_id": soc_id,
            "dsp_arch": dsp_arch,
            "cores": [
                {
                    "core_id": 0,
                    "perf_profile": "burst",
                    "rpc_control_latency": 100
                }
            ]
        }
    ],
    "context": {
        "weight_sharing_enabled": True
    }
}

这些配置会进入 QNN context binary 生成过程。graphs 里是 HTP graph 编译参数；devices 里绑定目标 SoC 和 DSP 架构；weight_sharing_enabled 表示同一个 context 里的多个 graph 可以共享权重。

5.3 生成每个 graph 的 model library

接下来脚本遍历 post_treat["merge"]。每个 key 对应一个最终 .bin，每个 src 对应一个 graph 源目录：

# source/backend/qnn/npu_convert.py:60
for key in post_treat["merge"]:
    srcs = merges[key]
    dst = key
    dstname = key.split('/')
    dstname = dstname[len(dstname)-1]
    dstname = dstname.replace('.bin', '')

以 qnn/graph0.bin -> [qnn/graph0, qnn/graph1_0] 为例，dstname 会变成 graph0。这个名字后续会作为 qnn-context-binary-generator --binary_file graph0 的参数。

然后对每个 graph 源目录打包 .raw：

# source/backend/qnn/npu_convert.py:69
for i,src in enumerate(srcs):
    graphname = src.split('/')
    graphname = graphname[len(graphname)-1]
    graphs.append(graphname)
    workdir = os.path.join(os.getcwd(), src)
    workdirs.append(workdir)
    print(subprocess.run("tar -cf " + graphname + '.bin' + ' *.raw', cwd=workdir, capture_output=True, text=True, shell=True))

graphname 是 graph0、graph1_0 这样的名字。workdir 目录里已经有 Step2 导出的 graphname.cpp 和若干 .raw 文件，.raw 是 QNN graph 依赖的常量数据。脚本先把这些 .raw 打包成 graphname.bin，给下一步的 qnn-model-lib-generator 使用。

随后调用 qnn-model-lib-generator：

# source/backend/qnn/npu_convert.py:80
compile_cmd = 'python3 ' + qnnModelLibGenerator + ' -c ' + os.path.join(workdir, graphname + '.cpp') + ' -b ' + os.path.join(workdir, graphname + '.bin') + ' -t x86_64-linux-clang -o ' + workdir
print(os.popen(compile_cmd).read())
libs.append(os.path.join(workdir, 'x86_64-linux-clang', 'lib' + graphname + '.so'))

这一步的输入是：

graphname.cpp：Step2 由 QNN convert backend 导出的 graph 构建代码；
graphname.bin：刚才打包出来的 raw 常量数据；
x86_64-linux-clang：生成 host 侧工具可加载的 model library。

输出是 workdir/x86_64-linux-clang/libgraphname.so。这个 .so 还不是运行时最终加载的产物，它只是 qnn-context-binary-generator 的输入。

5.4 合成 context binary

同一个 key 下的所有 graph 源目录都编译出 libgraph*.so 后，脚本会把 graph 名字写入 htp_backend_extensions.json：

# source/backend/qnn/npu_convert.py:85
htp_backend_extensions['graphs'][0]['graph_names'] = graphs
with open('htp_backend_extensions.json', 'w') as f:
    f.write(json.dumps(htp_backend_extensions, indent=4))

graphs 顺序很重要。compilefornpu 写入 Plugin attr 时，也会保存同一组 allGraphName：

// tools/cpp/compilefornpu.cpp:556
attr->key = "allGraphName";
attr->list.reset(new ListValueT);
attr->list->s = {graphicName};

多 shape 合并时，_fuse(...) 会把后续 shape 的 allGraphName 追加进去。运行时 QNN Plugin 会读取 allGraphName，并按这个顺序重新排列 context binary 里的 graph 信息：

// source/backend/qnn/backend/QNNBackend.cpp:913
std::vector<std::string> allGraphName;
auto allGraphNameAttr = ctx->getAttr("allGraphName");
if (allGraphNameAttr && allGraphNameAttr->list() && allGraphNameAttr->list()->s()) {
    auto graphNames = allGraphNameAttr->list()->s();
    for (int i = 0; i < graphNames->size(); ++i) {
        allGraphName.push_back(graphNames->GetAsString(i)->str());
    }
}

最后脚本把所有 libgraph*.so 拼成逗号分隔的 --model 参数，调用 qnn-context-binary-generator：

# source/backend/qnn/npu_convert.py:88
libsStr = ""
for i in range(0, len(libs)):
    if i > 0:
        libsStr+=','
    libsStr += libs[i]
print(os.popen(qnnContextBinaryGenerator + ' --model ' + libsStr + ' --backend '+ htp_so + ' --binary_file ' + dstname + ' --config_file ./context_config.json ' + ' --output_dir ' + cache_dir).read())

展开后大致是：

qnn-context-binary-generator \
  --model <tmp>/qnn/graph0/x86_64-linux-clang/libgraph0.so,<tmp>/qnn/graph1_0/x86_64-linux-clang/libgraph1_0.so \
  --backend <QNN_SDK_ROOT>/lib/x86_64-linux-clang/libQnnHtp.so \
  --binary_file graph0 \
  --config_file ./context_config.json \
  --output_dir qnn

输出目录由 npu_postreat.json 里的 "cache": "qnn" 决定：

# source/backend/qnn/npu_convert.py:19
cache_dir = 'res'
if 'cache' in post_treat:
    cache_dir = post_treat['cache']

最终产物会写到：

`1`	`tmp/qnn/graph0.bin`

这就是 Plugin attr 里的 path: qnn/graph0.bin 对应的文件。

5.5 运行时使用 binary

运行时 QNN Plugin 初始化时，会从 Plugin attr 里读 path 和 allGraphName，然后调用 RawExecutorWrapper::compileModel(...)：

// source/backend/qnn/backend/QNNBackend.cpp:911
auto path = MNNFilePathConcat(ctx->dir_path(), ctx->getAttr("path")->s()->str());
...
mRawExecutor.reset(new RawExecutorWrapper());
return mRawExecutor->compileModel(path, binaryOffset, binarySize, allGraphName);

compileModel(...) 会读取 context binary，并通过 QNN API 从 binary 里恢复 context 和 graph handle：

// source/backend/qnn/backend/QNNBackend.cpp:797
CALL_QNN(QNN::gContext.systemInterface.systemContextGetBinaryInfo(systemContextHandle, buffer, size, &binaryInfo,&binarySize));
copyMetadataToGraphsInfo(binaryInfo, mGraphsInfo, mGraphCount);

// source/backend/qnn/backend/QNNBackend.cpp:816
CALL_QNN(QNN::gContext.interface.contextCreateFromBinary(QNN::gContext.backendHandle, QNN::gContext.deviceHandle, mQnnContextConfig, buffer, size, &mQnnContextHandle, mQnnProfileHandle));

然后按 allGraphName 的顺序取出每个 graph handle：

// source/backend/qnn/backend/QNNBackend.cpp:826
for (int i = 0; i < mGraphCount; ++i) {
    auto it = graphInfoMap.find(allGraphName[i]);
    MNN_ASSERT(it != graphInfoMap.end());
    sortedGraphsInfo[i] = it->second;
}
for (int i = 0; i < mGraphCount; i++) {
    CALL_QNN(QNN::gContext.interface.graphRetrieve(mQnnContextHandle, mGraphsInfo[i]->graphName, &(mQnnGraphHandleVec[i])));
}

所以 Step3 生成的 qnn/graph0.bin 不是普通权重文件，而是一个 QNN HTP context binary。它里面可以包含多个 graph，分别对应 decode / prefill 等不同输入 shape。执行时，Plugin 通过 shapeIndex 选择 mQnnGraphHandleVec[shapeIndex] 去调用 QNN graph。

6. Step4：移动产物并写 config_qnn.json

最后 convert(args) 调用 output_qnn(args) 做收尾：

1
2
3

# transformers/llm/export/npu/generate_llm_qnn.py:85
print("Step4: Move result file to ", args.model)
output_qnn(args)

output_qnn(args) 先把临时目录里的 qnn 移到模型目录（tmp/qnn -> <model_dir>/qnn）：

# transformers/llm/export/npu/generate_llm_qnn.py:47
def output_qnn(args):
    if os.path.exists(os.path.join(args.model, 'qnn')):
        shutil.rmtree(os.path.join(args.model, 'qnn'))
    shutil.move(os.path.join(args.cache_path, 'qnn'), os.path.join(args.model, 'qnn'))

然后脚本直接写出一个新的 config_qnn.json，不是读取 config.json 后做增量修改：

# transformers/llm/export/npu/generate_llm_qnn.py:51
config_npu = {
    "llm_model": "qnn/llm.mnn",
    "backend_type": "cpu",
    "thread_num": 1,
    "precision": "low",
    "chunk_limits":[args.chunk_size, 1],
    "memory": "low",
    "sampler_type": "penalty",
    "penalty": 1.1
}
with open(os.path.join(args.model, "config_qnn.json"), 'w') as f:
    f.write(json.dumps(config_npu, indent = 4))
shutil.rmtree(args.cache_path)

其中最关键的字段是：

{
  "llm_model": "qnn/llm.mnn",
  "chunk_limits": [128, 1]
}

实际运行时还需要确认 config_qnn.json 里有正常的运行配置，例如：

{
  "llm_model": "qnn/llm.mnn",
  "backend_type": "cpu",
  "thread_num": 1,
  "precision": "low",
  "chunk_limits": [128, 1],
  "memory": "low",
  "sampler_type": "penalty",
  "penalty": 1.1
}

这里 backend_type 写成 cpu 是正常的。外层 MNN 主图仍然由 CPU backend 执行；真正下沉到 QNN 的部分已经变成 Plugin(type="QNN")，运行时会由 Plugin 机制加载 qnn/*.bin 并调用 QNN graph。

7. 最终目录结构

完成后，模型目录会变成类似这样：

Qwen3-1.7B-MNN/
├── config.json
├── config_qnn.json
├── llm_config.json
├── tokenizer.txt
├── llm.mnn
├── llm.mnn.weight
└── qnn/
    ├── llm.mnn
    ├── graph0.bin
    └── graph*.bin

整个离线执行链路如下：

generate_llm_qnn.py 负责编排；
generateLlmIO 负责造多 shape 样本；
compilefornpu 负责切图、导出 QNN graph 材料并改写 MNN 主图；
npu_convert.py 负责调用 QNN SDK 生成最终 HTP context binary。

以 llm_demo 为例的 QNN 后端运行

Wed, 27 May 2026 12:00:00 +0800

QNN 后端运行

QNN 后端运行

以 transformers/llm/engine/demo/llm_demo.cpp 为例，在 Android 设备上执行 QNN 后端流程：服务器交叉编译 -> 构建 QNN 模型 -> adb push 推送到手机 -> 端侧设备运行。需要准备下面环境：

adb devices 能看到目标设备，本文测试设备为 adb connect 127.0.0.1:40404
ANDROID_NDK 已配置，参考交叉编译环境配置
QNN_SDK_ROOT 已配置，参考QNN环境配置

整体构建流程参考官方文档。

1. 环境

以下面环境为例：

开发机(编译设备)：Ubuntu 22.04
测试机(目标设备)：arm64-v8a + SM8750
QNN SDK：/root/qairt/2.40.0.251030
编译目录：project/android/build_64
手机测试目录：/data/local/tmp/mnn-llm-qnn
测试模型：taobao-mnn/Qwen3-1.7B-MNN

首先需要拉取仓库到编译设备,当前测试分支是8d9f6131ac3ea61cde7e1d0edab52f56c7420926：

`1`	`➜ git clone https://github.com/alibaba/MNN`

这次设备侧属性如下：

➜ adb connect 127.0.0.1:40404
➜ adb shell "cat /sys/devices/soc0/soc_id; getprop ro.soc.model; getprop ro.product.cpu.abi"
618
SM8750
arm64-v8a

在服务器准备原始测试模型Qwen3-1.7B-MNN，目录结构至少包含这些文件：

Qwen3-1.7B-MNN/
├── config.json         # 运行时配置 包括后端设置、线程数、采样参数等
├── llm_config.json     # 导出时写入的模型元信息
├── tokenizer.txt       # 分词器文件
├── llm.mnn             # 模型计算图
└── llm.mnn.weight      # 模型权重

建议使用hf-mirror镜像站下载：

wget https://hf-mirror.com/hfd/hfd.sh && chmod a+x hfd.sh # 下载工具脚本

export HF_ENDPOINT=https://hf-mirror.com # 设置 Hugging Face 镜像站点
./hfd.sh taobao-mnn/Qwen3-1.7B-MNN # 下载模型到当前目录

2. 交叉编译

QNN 后端的运行需要准备两类产物：

Android 设备侧运行的 llm_demo和所需的MNN编译产生动态库
导出的QNN模型和依赖的QNN动态库

2.1 交叉编译 `llm_demo`

QNN 版 llm_demo 编译时需要打开 MNN_QNN 和 MNN_WITH_PLUGIN。在编译设备执行：

# 要求 QNN_SDK_ROOT 已配置，指向 QAIRT SDK 根目录
cd ${MNN_ROOT}
cd project/android
mkdir -p build_64
cd build_64

# 交叉编译 Android arm64 版本的 QNN llm_demo
# 这里同步会编译模型转换工具，后续生成 QNN 模型时会用到
# 记住当前的目录
../build_64.sh -DMNN_QNN=ON -DMNN_WITH_PLUGIN=ON -DMNN_BUILD_LLM=ON -DMNN_LOW_MEMORY=ON

这次构建结束后，设备运行只用到了下面两个产物：

`1`	`ls -lh llm_demo libMNN.so`

2.2 导出 QNN 模型

导出QNN模型依赖主库编译产生的工具，需要先在服务器编译工具，注意这不是交叉编译

cd ${MNN_ROOT}
mkdir build && cd build
cmake .. -DMNN_QNN=ON -DMNN_QNN_CONVERT_MODE=ON -DMNN_BUILD_TOOLS=ON -DMNN_BUILD_LLM=ON
make -j256

MNN使用python脚本按 NPU 格式导出 MNN 模型。先安装python依赖：

cd ${MNN_ROOT}  
cd ./transformers/llm/export
conda create -n mnn python=3.11 -y
conda activate mnn
uv pip install -r requirements.txt

再从MNN模型目录导出 QNN 模型，参数说明参考, soc和Hexagon版本参考（这一步导出会出现部分导出错误的节点，MNN会把这部分计算交给CPU处理，导出没有失败）

cd ${MNN_ROOT}
cd transformers/llm/export
export MODEL_DIR=/data/HF_MODELS/Qwen3-1.7B-MNN
python3 npu/generate_llm_qnn.py \
  --model "$MODEL_DIR" \
  --soc_id=69 \
  --dsp_arch=v79 \
  --mnn_path ../../../build/
  # 最后的参数是前面服务器上产生编译工具的路径，脚本会调用工具生成 QNN 模型并放在 `qnn/` 目录下

直接下载的 taobao-mnn/Qwen3-1.7B-MNN 使用 tokenizer.txt，config_qnn.json 不需要额外写 tokenizer_file。如果是自己用 llmexport.py 导出的模型，分词器可能是 tokenizer.mtok，这时需要给 config_qnn.json 补上：

{
  "llm_model": "qnn/llm.mnn",
  "backend_type": "cpu",
  "thread_num": 1,
  "precision": "low",
  "chunk_limits": [
    128,
    1
  ],
  "memory": "low",
  "sampler_type": "penalty",
  "penalty": 1.1,
  "tokenizer_file": "tokenizer.mtok"
}

QNN 模型准备完成后，目录至少包含这些文件：

Qwen3-1.7B-MNN/
├── config_qnn.json     # QNN 运行配置
├── llm_config.json     # 导出时写入的模型元信息
├── tokenizer.txt       # 直接下载模型的分词器文件
├── llm.mnn.weight      # 模型权重，也包含 tie_embeddings 使用的 embedding 数据
└── qnn/
    ├── llm.mnn         # QNN Plugin 替代模型
    ├── graph0.bin
    ├── graph1.bin
    └── ...             # QNN 离线产物

config_qnn.json 里的 backend_type 通常仍然是 cpu。这是 QNN LLM 离线产物的运行方式：QNN 图已经封装进 qnn/llm.mnn，外层还是通过 CPU 后端加载 Plugin，本次 Qwen3-1.7B 生成的 qnn/ 目录约 3.3G。

3. 推送并运行

3.1 推送编译产物、模型和 QNN 依赖

llm_demo 不是静态单文件程序，除了可执行文件本身，还需要把 MNN 动态库、QNN 动态库、QNN 离线模型一起推送到手机。

下面命令按本次 SM8750/v79 测试环境整理, 按需要修改对应的环境变量：

export PHONE_DIR=/data/local/tmp/mnn-llm-qnn
export PHONE_MODEL_DIR=$PHONE_DIR/model/Qwen3-1.7B-MNN
export BUILD_DIR=/workspace/code/MNN/project/android/build_64
export MODEL_DIR=/data/HF_MODELS/Qwen3-1.7B-MNN
export QNN_SDK_ROOT=/root/qairt/2.40.0.251030
export HEXAGON_ARCH=79

# 创建手机侧目录
adb shell "rm -rf $PHONE_DIR && mkdir -p $PHONE_MODEL_DIR"

# 推送二进制和 MNN 动态库
# 如果是静态链接版本，llm_demo 会比较大，但不需要推其余动态库
adb push "$BUILD_DIR/llm_demo" "$PHONE_DIR/"
adb push "$BUILD_DIR/libMNN.so" "$PHONE_DIR/"
# adb push "$BUILD_DIR/libllm.so" "$PHONE_DIR/"
# adb push "$BUILD_DIR/libMNN_Express.so" "$PHONE_DIR/"

# 推送 QNN 运行库
adb push "$QNN_SDK_ROOT/lib/aarch64-android/libQnnHtp.so" "$PHONE_DIR/"
adb push "$QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpV${HEXAGON_ARCH}Stub.so" "$PHONE_DIR/"
adb push "$QNN_SDK_ROOT/lib/hexagon-v${HEXAGON_ARCH}/unsigned/libQnnHtpV${HEXAGON_ARCH}Skel.so" "$PHONE_DIR/"
adb push "$QNN_SDK_ROOT/lib/aarch64-android/libQnnSystem.so" "$PHONE_DIR/"

# 推送 QNN 运行需要的最小模型文件
adb push "$MODEL_DIR/config_qnn.json" "$PHONE_MODEL_DIR/"
adb push "$MODEL_DIR/llm_config.json" "$PHONE_MODEL_DIR/"
adb push "$MODEL_DIR/tokenizer.txt" "$PHONE_MODEL_DIR/"
adb push "$MODEL_DIR/llm.mnn.weight" "$PHONE_MODEL_DIR/"
adb push "$MODEL_DIR/qnn" "$PHONE_MODEL_DIR/"

# 准备一个文件输入，便于首次验证
printf 'hello\n' > prompt.txt
adb push prompt.txt "$PHONE_DIR/"

# 给可执行文件加权限
adb shell "chmod +x $PHONE_DIR/llm_demo"

HEXAGON_ARCH 必须和设备、QNN 模型生成参数匹配。本次如果误推 V75 库，会在 logcat 里看到 Stub lib id mismatch，随后 QNN 初始化失败。

3.2 运行

QNN LLM 运行时传入 config_qnn.json，不要传普通 config.json。

adb shell "cd $PHONE_DIR && \
export LD_LIBRARY_PATH=$PHONE_DIR && \
export ADSP_LIBRARY_PATH=$PHONE_DIR && \
./llm_demo $PHONE_MODEL_DIR/config_qnn.json $PHONE_DIR/prompt.txt"

测试后有正常输出：

config path is /data/local/tmp/mnn-llm-qnn/model/Qwen3-1.7B-MNN/config_qnn.json
Prepare for tuning opt Begin
Prepare for tuning opt End
prompt file is /data/local/tmp/mnn-llm-qnn/prompt.txt
Hello! How can I assist you today?

prompt tokens num = 9
decode tokens num = 217
prefill speed = 37.52 tok/s
decode speed = 15.03 tok/s

llm_demo 还支持交互运行模式：

adb shell
cd /data/local/tmp/mnn-llm-qnn
export LD_LIBRARY_PATH=/data/local/tmp/mnn-llm-qnn
export ADSP_LIBRARY_PATH=/data/local/tmp/mnn-llm-qnn
./llm_demo /data/local/tmp/mnn-llm-qnn/model/Qwen3-1.7B-MNN/config_qnn.json

进入交互模式后，直接输入问题即可。

QNN HTP OpPackage Softmax 源码分析

Mon, 27 Apr 2026 10:10:00 +0800

QNN HTP OpPackage Softmax 源码分析

这篇为对照源码/qairt/2.40.0.251030/examples/QNN/OpPackage/HTP/ExampleOpPackageSoftmax.cpp 学习QNN如何自定义Softmax算子。它涵盖了：

Softmax 在 HTP OpPackage 里的注册方式
Softmax 参数顺序
Softmax -> Softmax_fp 的图改写规则
普通 reference 版本
FP16 + HVX 近似版本

1. 源码分析

1.1 头文件

源码开头包含了几类 HTP core 头文件：

#include "HTP/core/constraints.h"
#include "HTP/core/op_package_feature_support.h"
#include "HTP/core/op_register_ext.h"
#include "HTP/core/optimize.h"
#include "HTP/core/simple_reg.h"

可以按职责理解：

头文件	作用
`constraints.h`	给优化规则写匹配条件，例如 dtype、scalar、常量值
`op_package_feature_support.h`	OpPackage 特性支持相关定义
`op_register_ext.h`	注册自定义 op 的宏
`optimize.h`	图优化和 pattern rewrite 的宏
`simple_reg.h`	简化注册接口

这些宏不是普通 C++ 函数调用风格，而是 HTP backend 给 OpPackage 暴露的一套 DSL。

1.2 算子定义

1.2.1 算子定义

源码第 27 行：

`1`	`BEGIN_PKG_OP_DEFINITION(PKG_Softmax);`

这行给当前源文件里的 op 定义起内部名字 PKG_Softmax。它后面要和 ExampleOpPackageInterface.cpp 里的：

`1`	`DECLARE_PKG_OPS_OPTS_LIST(PKG_Softmax)`

对应起来。即Softmax.cpp 里声明了包内容，Interface.cpp 把这个包内容挂到最终 OpPackage 接口里。

源码第 29 行：

`1`	`DEF_PACKAGE_PARAM_ORDER("Softmax", "beta", false, nullptr, "axis", false, nullptr)`

定义了 Softmax 的参数顺序。它说明 Softmax 最多关心两个参数：

beta
axis

Interface.cpp 的 validateOpConfig() 对应这个约定：Softmax 允许 numOfParams <= 2。

1.2.2 函数声明

源码第 32 到 36 行先声明两个实现：

template <typename T_Ttype>
int softmaxWithbetaWrapper(T_Ttype &out, const T_Ttype &in, const Tensor &beta);

template <typename OutTtype, typename InTtype>
int softmax_fp_impl(OutTtype &out, const InTtype &in, const Tensor &beta);

它们代表两条路径：

softmaxWithbetaWrapper()：普通模板路径，内部调用 reference 写法。
softmax_fp_impl()：FP16 快路径，内部调用 softmax_hf_approx()。

1.2.3 注册 Softmax 算子

源码第 43 到 44 行：

1
2

DEF_PACKAGE_OP(softmaxWithbetaWrapper<Tensor>, "Softmax")
DEF_PACKAGE_OP((softmaxWithbetaWrapper<QuantUint8Tensor>), "Softmax")

把函数模板实例注册成名为 Softmax 的 op 实现。

源码第 56 到 59 行：

DEF_PACKAGE_OP_AND_COST_AND_FLAGS((softmaxWithbetaWrapper<PlainFloatTensor>),
                                  "Softmax",
                                  SNAIL,
                                  Flags::RESOURCE_HVX)

也注册 Softmax，但多了两个信息：

SNAIL：成本模型里比较慢的实现。
Flags::RESOURCE_HVX：这个实现会占用 HVX 资源。

1.2.4 Tensor 属性

源码第 61 行：

`1`	`DEF_TENSOR_PROPERTIES(Op("Softmax", "in", "Beta"), Flat(""), MainMemory(""))`

定义 Softmax 的 tensor 属性：

匹配 Softmax(in, Beta) 这种形式。
Flat("*") 表示相关 tensor 使用 flat 形态。
MainMemory("*") 表示相关 tensor 在 main memory。

这里的 * 是 pattern 里的通配符，HTP graph optimizer 会拿这些属性判断某个 op 实现能不能接住当前图里的 tensor。

1.2.5 注册 Softmax_fp 算子

源码第 64 到 72 行注册了两个 Softmax_fp：

DEF_PACKAGE_OP_AND_COST_AND_FLAGS((softmax_fp_impl<PlainFloat16Tensor, PlainFloat16Tensor>),
                                  "Softmax_fp",
                                  FAST,
                                  Flags::RESOURCE_HVX)

DEF_PACKAGE_OP_AND_COST_AND_FLAGS((softmax_fp_impl<PlainFloat16Tensor_TCM, PlainFloat16Tensor_TCM>),
                                  "Softmax_fp",
                                  FAST,
                                  Flags::RESOURCE_HVX)

这两条都标成 FAST，说明作者希望真正的 float 计算最后走 Softmax_fp。

区别在 tensor 类型：

PlainFloat16Tensor：普通 FP16 tensor。
PlainFloat16Tensor_TCM：放在 TCM 里的 FP16 tensor。

TCM(Tightly Coupled Memory) 是 HTP/DSP 侧更靠近计算单元的片上存储。这里注册 TCM 版本，是为了让 optimizer 在合适的内存布局下能选更快路径。

1.3 算子优化

1.3.1 float32 -> fp16

源码第 77 到 93 行是一条关键优化规则：

DEF_PACKAGE_OPTIMIZATION_WITH_FLAGS(
    GRAPH_CLEANUP,
    relaxed_precision_flag,
    Op("Softmax", "In", "Beta", "axis"),
    AND(EQ(DTYPE_OF("In"), DType::Float32), EQ(DTYPE_OF("*"), DType::Float32)),
    ... Op("Softmax_fp", WITH_SIZE("In", Op(FROM_DEFAULT_PACKAGE("Cast"), "In")), "Beta") ...)

它做的事情是：

Softmax(float32 In, Beta, axis)
-> Cast(In -> float16)
-> Softmax_fp(float16, Beta)
-> Cast(output -> float32)

触发条件是：

输入 In 是 Float32
输出也是 Float32
启用了 relaxed_precision_flag

所以这里不是无条件把 float32 改成 fp16，而是在精度允许时，把主计算切到 HTP 更友好的 FP16 实现。

1.3.2 折叠前置乘法

源码第 95 到 110 行：

Op("Softmax_fp",
   Op(FROM_DEFAULT_PACKAGE("QNN_OP_ELEMENT_WISE_MULTIPLY"),
      "In",
      Op(FROM_DEFAULT_PACKAGE("QNN_OP_CAST"), OPCONST("MaybeScalarVal"))),
   "Beta")

它匹配这种图：

`1`	`Softmax_fp(Multiply(In, Cast(scalar)), Beta)`

如果 MaybeScalarVal 是正的 float32 scalar，就改写成：

`1`	`Softmax_fp(In, Beta * scalar)`

写成公式形式就是：

$$ \exp(\beta \cdot x') $$

其输入前面有一个正标量乘法：

$$ x' = s \cdot x $$

那就可以变成：

$$ \exp(\beta \cdot s \cdot x) $$

也就是把 s 合进 beta。

1.3.3 默认参数规整

源码第 112 到 117 行有两条更简单的 rewrite：

DEF_PACKAGE_OPTIMIZATION(QNN,
                         Op("Softmax", "In"),
                         OK,
                         Op("Softmax", "In", gen_ConstScalar_f32(1.0f)))

DEF_PACKAGE_OPTIMIZATION(QNN, Op("Softmax", "In", "Beta", "axis"), OK, Op("Softmax", "In", "Beta"))

第一条把：

`1`	`Softmax(In) -> Softmax(In, 1.0f)`

第二条把：

`1`	`Softmax(In, Beta, axis) -> Softmax(In, Beta)`

这个例子里的实现实际按最后一维做 softmax，没有使用 axis 参数。

1.3.4 `softmax_hf_approx()` 总览

源码第 119 行开始是 FP16 快路径核心：

`1`	`void softmax_hf_approx(Float16 pout, const Float16 pin, float scale, int length)`

输入含义：

pin：一段 FP16 输入。
pout：一段 FP16 输出。
scale：外部传入的缩放系数，后面由 beta 和 interface_scale() 合成。
length：最后一维长度，也就是 softmax 的归一化长度。

整体流程对应普通 softmax：

max = reduce_max(x)
y = approx_exp(scale * (x - max))
sum = reduce_sum(y)
out = y / sum

只是这里全部手写成 HVX vector intrinsic。

1.4 伪代码

算子真正执行的核心计算是：

`1`	`softmax(x) = exp(scale * (x - max(x))) / sum(exp(scale * (x - max(x))))`

这几段伪代码的调用关系是：

softmax_fp_impl()
  └── 遍历输入 tensor 的 [B, H, W, D] 外层切片[B, H, W]
      └── 对每个连续的最后一维 [D] 切片调用 softmax_hf_approx()
          ├── reduce max 计算最大值
          ├── approx_exp2() 近似计算 exp 的主体
          ├── reduce sum 求和
          └── 原地归一化输出

其中 approx_exp2() 不是源码里的真实函数名，而是为了说明第 184 到 266 行的指数近似逻辑抽出来的概念函数。源码里这些逻辑直接内联写在 softmax_hf_approx() 的主循环中。

1.4.1 `softmax_fp_impl()` 伪代码

softmax_fp_impl() 本身不直接写 HVX 算法。它负责遍历输入的外层维度，把每个最后一维切片交给 softmax_hf_approx()：

function softmax_fp_impl(out, in, beta_tensor):
    # 输出 tensor 的 shape 和输入一致。
    out.shape = in.shape

    # 示例实现按 4D tensor 处理：[B, H, W, D]。
    # D 是最后一维，也是 softmax 的归一化维度。
    B, H, W, D = in.shape

    # beta 是 softmax 指数缩放参数。
    # interface_scale 是输入 tensor 接口层的 scale，需要合进总 scale。
    scale = in.interface_scale() * beta_tensor[0]

    # 每个 [b, h, w, :] 是一段连续的 D 维 fp16 buffer。
    for b in 0 .. B-1:
      for h in 0 .. H-1:
        for w in 0 .. W-1:
            # 当前最后一维切片的输入/输出首地址。
            pin  = &in[b, h, w, 0]
            pout = &out[b, h, w, 0]

            # 对这个 D 维切片做 softmax。
            softmax_hf_approx(
                pout,
                pin,
                scale,
                length = D
            )

也就是说，这个示例实现里的归一化维度是最后一维 D。

1.4.2 `softmax_hf_approx()` 总体伪代码

softmax_hf_approx() 是真正的 FP16 + HVX 快路径。忽略向量 intrinsic 的细节，它做的是稳定版 softmax：

`1`	`out[i] = exp(scale * (in[i] - max(in))) / sum_j exp(scale * (in[j] - max(in)))`

伪代码如下：

function softmax_hf_approx(pout, pin, scale, length):
    # 换底：后面用 2^x 近似来实现 e^x。
    log2_scale = scale / ln(2)

    # 拟合 2^x 的三阶多项式系数，不是标准 Taylor 系数。
    c0 = 1.0
    c1 = 0.692850309695840
    c2 = 0.237504551482093
    c3 = 0.046751431261525

    # pass 1: 找 max，避免 exp 溢出。
    # 源码中每次读 64 个 fp16，先得到 vector 形式的部分最大值。
    xmax_vec = fp16_negative_infinity
    for block in pin split by 64 fp16 elements:
        x = load_fp16_vector(block)
        x = mask_tail_if_needed(x)
        xmax_vec = vector_max_fp16(xmax_vec, x)

    # 把 vector lane 内的最大值继续横向归约成一个标量 max。
    xmax = horizontal_max_fp16(xmax_vec)

    # pass 2: 计算未归一化 exp，并累加 sum。
    # pout 先被当成临时 buffer 保存 exp 近似值。
    sum_vec = 0
    for block in pin split by 64 fp16 elements:
        x = load_fp16_vector(block)
        x = mask_tail_if_needed(x)

        # 稳定版 softmax 的核心：先减全局 max。
        xd = x - xmax

        # fp16 扩展成两组 qf32，方便做指数近似。
        lo_qf32, hi_qf32 = widen_fp16_to_two_qf32_vectors(xd)

        # 进入 base-2 指数域。
        z_lo = lo_qf32 * log2_scale
        z_hi = hi_qf32 * log2_scale

        # 源码第 184 到 266 行内联做了这个近似。
        exp_lo = approx_exp2(z_lo)
        exp_hi = approx_exp2(z_hi)

        # 暂存未归一化 exp 到 pout。
        y_fp16 = narrow_qf32_pair_to_fp16(exp_lo, exp_hi)
        store_fp16(pout_block, y_fp16)

        # 同时累加 softmax 分母。
        sum_vec += exp_lo
        sum_vec += exp_hi

    # 把 vector 形式的部分和横向归约成标量 sum。
    sum = horizontal_sum_qf32(sum_vec)
    recip = 1.0 / sum

    # pass 3: 原地归一化。
    # pout 当前保存的是 exp 近似值，乘以 1/sum 后才是最终 softmax。
    for block in pout split by 64 fp16 elements:
        y = load_fp16_vector(block)
        lo_qf32, hi_qf32 = widen_fp16_to_two_qf32_vectors(y)

        out_lo = lo_qf32 * recip
        out_hi = hi_qf32 * recip

        out_fp16 = narrow_qf32_pair_to_fp16(out_lo, out_hi)
        store_fp16(pout_block, out_fp16)

1.4.3 `approx_exp2()` 伪代码

源码里没有单独的 approx_exp2() 函数，但第 184 到 266 行实际在做类似事情。先把自然指数换底：

$$ e^x = 2^{x / \ln 2} $$

所以 kernel 里要近似的是 2^z。抽象成伪代码：

function approx_exp2(z):
    # z 是 base-2 指数域的输入。
    # 源码先把 qf32 转成便于按 float32 bit 位拆分的形式。
    z_as_float = convert_qf32_to_float_bits(z)

    # 拆出 float32 exponent bits。
    exponent_bits = get_float_exponent_bits(z_as_float)

    # 限制 exponent，让多项式输入落在较小范围。
    exponent_limit = min(exponent_bits, 126 << 23)
    exponent_delta = exponent_bits - exponent_limit

    # 用受限 exponent 重组规格化输入。
    z_norm = replace_exponent(z_as_float, exponent_limit)

    # Horner 形式计算三阶多项式：
    # p = c0 + c1*z_norm + c2*z_norm^2 + c3*z_norm^3
    p = c3 * z_norm
    p = p + c2
    p = p * z_norm
    p = p + c1
    p = p * z_norm
    p = p + c0

    # repeated squaring：先构造多个幂次候选。
    p2  = p   * p
    p4  = p2  * p2
    p8  = p4  * p4
    p16 = p8  * p8
    p32 = p16 * p16
    p64 = p32 * p32

    # 根据 exponent_delta 选择对应幂次，恢复更大范围的指数效果。
    if exponent_delta == 1 << 23:
        return p2
    if exponent_delta == 2 << 23:
        return p4
    if exponent_delta == 3 << 23:
        return p8
    if exponent_delta == 4 << 23:
        return p16
    if exponent_delta == 5 << 23:
        return p32
    if exponent_delta > 5 << 23:
        return p64

    return p

1.5 算子实现

1.5.1 exp 近似

源码第 124 到 130 行：

scale /= float(log(2.0));
c0.f = 1.f;
c1.f = 0.692850309695840;
c2.f = 0.237504551482093;
c3.f = 0.046751431261525;

这里把自然指数换到底数 2 的指数域：

$$ e^x = 2^{x / \ln 2} $$

然后，构造类似 2^x 的多项式近似。如下，c0/c1/c2/c3 是三阶多项式系数：

$$ c0 + c1 \cdot x + c2 \cdot x^2 + c3 \cdot x^3 $$

实际上，这里会先给$x$做上下范围的限制（$x = 2^k \times r$），然后用多项式近似小范围值$2 ^ r$，最后由于$2^x = 2^{2^k \cdot r} = (2^r)^{2^k}$，所以通过 repeated squaring 的方式构造 $p^2$、$p^4$、$p^8$… 来恢复更大范围的指数效果（就是前面的${2^k}$的指数部分）。

1.5.2 找最大值

源码第 132 到 151 行完成 reduce max。

第 133 行：

`1`	`HVX_Vector xmax = Q6_Vh_vsplat_R(0xFC00);`

0xFC00 是 half precision 的负无穷。Q6_Vh_vsplat_R() 把这个 16-bit 值广播到整个 HVX vector。

第 136 到 140 行每次读 64 个 FP16，寻找当前切片的最大值：

for (int d = length; d > 63; d -= 64) {
    HVX_Vector xinval = vmemu(iptr);
    iptr++;
    xmax = Q6_Vhf_vmax_VhfVhf(xmax, xinval);
}

这里 Vhf 可以读成 vector half float。Q6_Vhf_vmax_VhfVhf 就是对两个 half-float vector 做逐元素 max。

第 141 到 145 行处理最后不足 64 个元素的情况：

if ((length & 63) != 0) {
    HVX_Vector xinval         = vmemu(iptr);
    HVX_VectorPred qfinalmask = Q6_Q_vsetq2_R(length * 2);

    // mask 外的位置填成当前 xmax，避免尾部无效数据影响 max。
    xinval = Q6_V_vmux_QVV(qfinalmask, xinval, xmax);
    xmax   = Q6_Vhf_vmax_VhfVhf(xmax, xinval);
}

第 147 到 151 行把 vector 里的多个 lane 继续横向归约成一个最大值。

// 横向归约：把 vector 内多个 lane 的最大值继续合并成一个 xmax。
int nshift = 2;
for (int i = 0; i < 6; i++) {
    HVX_VectorPair temps = Q6_W_vshuff_VVR(xmax, xmax, nshift);
    xmax = Q6_Vhf_vmax_VhfVhf(Q6_V_lo_W(temps), Q6_V_hi_W(temps));
    nshift <<= 1;
}

1.5.3. 计算未归一化 exp

源码第 154 到 285 行是 softmax_hf_approx() 的主计算部分。它做的是：

1
2

tmp_i = approx_exp(scale * (x_i - max))
sum   = sum_i tmp_i

这里的 tmp_i 会先暂存到 pout，下一节再除以 sum。

进入主循环前，源码先准备常量、系数、指针和累加器：

// zero vector，后面用于类型转换、加法归一化和清尾部 lane。
HVX_Vector vzero = Q6_V_vzero();

// fp16 的 1.0，0x3c00 是 half precision 1.0 的 bit pattern。
HVX_Vector voneh = Q6_Vh_vsplat_R(0x3c00);

// 把三阶多项式系数广播到 HVX vector。
HVX_Vector f0 = Q6_V_vsplat_R(c0.i);
HVX_Vector f1 = Q6_V_vsplat_R(c1.i);
HVX_Vector f2 = Q6_V_vsplat_R(c2.i);
HVX_Vector f3 = Q6_V_vsplat_R(c3.i);

// 这些 mask/常量用于拆 float32 的指数位和尾数部分。
HVX_Vector c7f800000 = Q6_V_vsplat_R(0x7f800000);
HVX_Vector c807fffff = Q6_V_vsplat_R(0x807fffff);

// vbeta 是已经除以 ln(2) 后的 scale：
// exp(scale_orig * x) = 2^((scale_orig / ln2) * x)
HVX_Vector vbeta = Q6_Vqf32_vadd_VsfVsf(Q6_V_vsplat_R(scaleu.i), vzero);

// 126 << 23 对应 float32 exponent field 的一个上限基准。
// 后面会用它限制/拆分指数部分，避免近似计算范围过大。
HVX_Vector c126 = Q6_V_vsplat_R(126 << 23);

// c1w, c2w, ... c5w 是指数位差值的比较常量。
// 后面根据 xexp 的大小选择 p、p^2、p^4、...、p^64。
HVX_Vector c1w = Q6_V_vsplat_R(1 << 23);
HVX_Vector c2w = Q6_Vw_vadd_VwVw(c1w, c1w);
HVX_Vector c3w = Q6_Vw_vadd_VwVw(c2w, c1w);
HVX_Vector c4w = Q6_Vw_vadd_VwVw(c3w, c1w);
HVX_Vector c5w = Q6_Vw_vadd_VwVw(c4w, c1w);

// vsumf 累加当前 softmax 切片所有未归一化 exp 的和。
HVX_Vector vsumf = Q6_V_vzero();

// optr 指向输出 buffer。此时输出 buffer 被用作 tmp buffer，
// 用来暂存未归一化的 exp 近似值。
HVX_Vector *optr = (HVX_Vector *)pout;
iptr = (HVX_Vector *)pin;

主循环每轮处理 64 个 FP16。第一步是读取输入并减最大值：

for (int d = length; d > 0; d -= 64) {
  HVX_Vector x, x0, x1, p0, p1;
  HVX_VectorPair xdiff, p10;
  HVX_VectorPred q0, q1;

  // 读取当前 64 个 fp16 输入。
  x = vmemu(iptr);
  iptr++;

  // 稳定版 softmax 的关键：
  // xd = x - max(x)
  HVX_Vector xd = Q6_Vqf16_vsub_VhfVhf(x, xmax);

  // 把 fp16 差值扩展成两组 qf32 数据。
  // 返回 HVX_VectorPair，后面分别处理 lo/hi 两半。
  xdiff = Q6_Wqf32_vmpy_Vqf16Vhf(xd, voneh);

接着乘以 vbeta，进入 2^x 的近似域：

  // x0/x1 = (x - max) * scale / ln(2)
  x0 = Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_V_lo_W(xdiff), vbeta);
  x0 = Q6_Vsf_equals_Vqf32(x0);

  x1 = Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_V_hi_W(xdiff), vbeta);
  x1 = Q6_Vsf_equals_Vqf32(x1);

后面这组 bit 操作是在拆 float32 的指数位和规格化尾数。直观理解是：把 2^x 的计算拆成“较小范围的多项式近似”和“指数缩放/幂次恢复”两部分。

  // 取出 float32 的 exponent bits。
  HVX_Vector x0exp = Q6_V_vand_VV(x0, c7f800000);
  HVX_Vector x1exp = Q6_V_vand_VV(x1, c7f800000);

  // 把 exponent 限制到 c126 以内，构造后续多项式的输入范围。
  HVX_Vector x0explimit = Q6_Vw_vmin_VwVw(x0exp, c126);
  HVX_Vector x1explimit = Q6_Vw_vmin_VwVw(x1exp, c126);

  // xexp 保存剩余的指数位差值，用于后面选择 p^2/p^4/...。
  x0exp = Q6_Vw_vsub_VwVw(x0exp, x0explimit);
  x1exp = Q6_Vw_vsub_VwVw(x1exp, x1explimit);

  // xnorm 是规格化后的多项式输入。
  HVX_Vector x0norm = Q6_V_vor_VV(Q6_V_vand_VV(c807fffff, x0), x0explimit);
  HVX_Vector x1norm = Q6_V_vor_VV(Q6_V_vand_VV(c807fffff, x1), x1explimit);

然后用 Horner 形式计算三阶多项式：

  // p0 = ((c3 * x0norm + c2) * x0norm + c1) * x0norm + c0
  // 即 p0 = c0 + c1*x + c2*x^2 + c3*x^3
  p0 = Q6_Vqf32_vmpy_VsfVsf(x0norm, f3);
  p0 = Q6_Vqf32_vadd_Vqf32Vsf(p0, f2);
  x0norm = Q6_Vqf32_vadd_VsfVsf(x0norm, vzero);
  p0 = Q6_Vqf32_vmpy_Vqf32Vqf32(p0, x0norm);
  p0 = Q6_Vqf32_vadd_Vqf32Vsf(p0, f1);
  p0 = Q6_Vqf32_vmpy_Vqf32Vqf32(p0, x0norm);
  p0 = Q6_Vqf32_vadd_Vqf32Vsf(p0, f0);

  // p1 对应 vector 的另一半，计算方式相同。
  p1 = Q6_Vqf32_vmpy_VsfVsf(x1norm, f3);
  p1 = Q6_Vqf32_vadd_Vqf32Vsf(p1, f2);
  x1norm = Q6_Vqf32_vadd_VsfVsf(x1norm, vzero);
  p1 = Q6_Vqf32_vmpy_Vqf32Vqf32(p1, x1norm);
  p1 = Q6_Vqf32_vadd_Vqf32Vsf(p1, f1);
  p1 = Q6_Vqf32_vmpy_Vqf32Vqf32(p1, x1norm);
  p1 = Q6_Vqf32_vadd_Vqf32Vsf(p1, f0);

接下来反复平方，构造 p^2 到 p^64。这一步服务于前面拆出来的 exponent 差值：指数位差值越大，就选择更高次的平方结果。

  // 构造 p0^2, p0^4, p0^8, p0^16, p0^32, p0^64。
  HVX_Vector p0_2  = Q6_Vqf32_vmpy_Vqf32Vqf32(p0, p0);
  p0_2             = Q6_Vqf32_vadd_Vqf32Vsf(p0_2, vzero);
  HVX_Vector p0_4  = Q6_Vqf32_vmpy_Vqf32Vqf32(p0_2, p0_2);
  p0_4             = Q6_Vqf32_vadd_Vqf32Vsf(p0_4, vzero);
  HVX_Vector p0_8  = Q6_Vqf32_vmpy_Vqf32Vqf32(p0_4, p0_4);
  p0_8             = Q6_Vqf32_vadd_Vqf32Vsf(p0_8, vzero);
  HVX_Vector p0_16 = Q6_Vqf32_vmpy_Vqf32Vqf32(p0_8, p0_8);
  p0_16            = Q6_Vqf32_vadd_Vqf32Vsf(p0_16, vzero);
  HVX_Vector p0_32 = Q6_Vqf32_vmpy_Vqf32Vqf32(p0_16, p0_16);
  p0_32            = Q6_Vqf32_vadd_Vqf32Vsf(p0_32, vzero);
  HVX_Vector p0_64 = Q6_Vqf32_vmpy_Vqf32Vqf32(p0_32, p0_32);

  // p1^2 ... p1^64 同理。
  HVX_Vector p1_2  = Q6_Vqf32_vmpy_Vqf32Vqf32(p1, p1);
  p1_2             = Q6_Vqf32_vadd_Vqf32Vsf(p1_2, vzero);
  HVX_Vector p1_4  = Q6_Vqf32_vmpy_Vqf32Vqf32(p1_2, p1_2);
  p1_4             = Q6_Vqf32_vadd_Vqf32Vsf(p1_4, vzero);
  HVX_Vector p1_8  = Q6_Vqf32_vmpy_Vqf32Vqf32(p1_4, p1_4);
  p1_8             = Q6_Vqf32_vadd_Vqf32Vsf(p1_8, vzero);
  HVX_Vector p1_16 = Q6_Vqf32_vmpy_Vqf32Vqf32(p1_8, p1_8);
  p1_16            = Q6_Vqf32_vadd_Vqf32Vsf(p1_16, vzero);
  HVX_Vector p1_32 = Q6_Vqf32_vmpy_Vqf32Vqf32(p1_16, p1_16);
  p1_32            = Q6_Vqf32_vadd_Vqf32Vsf(p1_32, vzero);
  HVX_Vector p1_64 = Q6_Vqf32_vmpy_Vqf32Vqf32(p1_32, p1_32);

根据 x0exp/x1exp 的值选择对应幂次：

  // 如果 xexp == 1 << 23，选择 p^2。
  q0 = Q6_Q_vcmp_eq_VwVw(x0exp, c1w);
  q1 = Q6_Q_vcmp_eq_VwVw(x1exp, c1w);
  p0 = Q6_V_vmux_QVV(q0, p0_2, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_2, p1);

  // 如果 xexp == 2 << 23，选择 p^4。
  q0 = Q6_Q_vcmp_eq_VwVw(x0exp, c2w);
  q1 = Q6_Q_vcmp_eq_VwVw(x1exp, c2w);
  p0 = Q6_V_vmux_QVV(q0, p0_4, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_4, p1);

  // 后面依次选择 p^8、p^16、p^32。
  q0 = Q6_Q_vcmp_eq_VwVw(x0exp, c3w);
  q1 = Q6_Q_vcmp_eq_VwVw(x1exp, c3w);
  p0 = Q6_V_vmux_QVV(q0, p0_8, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_8, p1);

  q0 = Q6_Q_vcmp_eq_VwVw(x0exp, c4w);
  q1 = Q6_Q_vcmp_eq_VwVw(x1exp, c4w);
  p0 = Q6_V_vmux_QVV(q0, p0_16, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_16, p1);

  q0 = Q6_Q_vcmp_eq_VwVw(x0exp, c5w);
  q1 = Q6_Q_vcmp_eq_VwVw(x1exp, c5w);
  p0 = Q6_V_vmux_QVV(q0, p0_32, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_32, p1);

  // 如果指数差值更大，选择 p^64。
  q0 = Q6_Q_vcmp_gt_VwVw(x0exp, c5w);
  q1 = Q6_Q_vcmp_gt_VwVw(x1exp, c5w);
  p0 = Q6_V_vmux_QVV(q0, p0_64, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_64, p1);

最后把这一轮的未归一化 exp 写到 pout，并累加到 vsumf：

  if (d >= 64) {
    // p0/p1 合成一个 vector pair，转成 fp16 后写到 pout。
    // 注意：这里的 pout 暂时保存的是未归一化 exp，不是最终 softmax。
    p10 = Q6_W_vcombine_VV(p1, p0);
    q6op_vstu_AV(optr, Q6_Vhf_equals_Wqf32(p10));
    optr++;

    // 累加 softmax 分母。
    vsumf = Q6_Vqf32_vadd_Vqf32Vqf32(vsumf, p0);
    vsumf = Q6_Vqf32_vadd_Vqf32Vqf32(vsumf, p1);
  } else {
    // 尾部不足 64 个 fp16 时，用 predicate 清掉无效 lane。
    // 这里 qf32 每个 lane 是 4 字节，所以 mask 长度乘 4。
    HVX_VectorPred Q0 = Q6_Q_vsetq2_R(4 * (((d & 63) + 1) / 2));
    HVX_VectorPred Q1 = Q6_Q_vsetq2_R(4 * (((d & 63) + 0) / 2));
    p0                = Q6_V_vmux_QVV(Q0, p0, vzero);
    p1                = Q6_V_vmux_QVV(Q1, p1, vzero);

    // 只累加有效 lane。
    vsumf             = Q6_Vqf32_vadd_Vqf32Vqf32(vsumf, p0);
    vsumf             = Q6_Vqf32_vadd_Vqf32Vqf32(vsumf, p1);

    // 只写回有效 fp16 元素。
    p10               = Q6_W_vcombine_VV(p1, p0);
    q6op_vstu_variable_ARV(optr, 2 * (d & 63), Q6_Vhf_equals_Wqf32(p10));
    optr++;
  }
}

1.5.4 sum 并归一化

源码第 287 到 292 行把 vsumf 横向归约，得到整段 softmax 的分母：

// vsumf 是 vector 形式的部分和。这里把 vector 内所有 lane 继续横向相加。
for (int i = 0, nshift = 4; i < 5; i++) {
  HVX_VectorPair temps = Q6_W_vshuff_VVR(vsumf, vsumf, nshift);
  vsumf                = Q6_Vqf32_vadd_Vqf32Vqf32(Q6_V_lo_W(temps), Q6_V_hi_W(temps));
  nshift <<= 1;
}

// 转成 scalar float 格式，便于从 lane 0 取出。
vsumf = Q6_Vsf_equals_Vqf32(vsumf);

第 295 到 297 行取出 sum 并求倒数：

// 横向归约后，每个 lane 都等价地携带总和；取 lane 0 即可。
sum.i = Q6_R_vextract_VR(vsumf, 0);
sum_recip.f = 1.0f / sum.f;

// 把 1/sum 广播成 vector，后面逐元素乘。
HVX_Vector vrecip = Q6_Vqf32_vadd_VsfVsf(Q6_V_vsplat_R(sum_recip.i), vzero);
HVX_Vector *ioptr = (HVX_Vector *)pout;

第 300 到 314 行第二次遍历输出 buffer，把前面暂存的 exp 乘以 1 / sum。这里的输入和输出都是 pout，相当于原地归一化：

// 处理完整的 64 个 fp16 block。
for (int d = length; d > 63; d -= 64) {
  // 从 pout 读取前一节暂存的未归一化 exp，并扩展到 qf32。
  HVX_VectorPair xx = Q6_Wqf32_vmpy_VhfVhf(vmemu(&ioptr[0]), voneh);

  // lo/hi 两半分别乘以 1/sum。
  HVX_Vector xl =
      Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_Vqf32_vadd_Vqf32Vsf(Q6_V_lo_W(xx), vzero), vrecip);
  HVX_Vector xh =
      Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_Vqf32_vadd_Vqf32Vsf(Q6_V_hi_W(xx), vzero), vrecip);

  // 合并并转回 fp16，写回最终 softmax 输出。
  xx = Q6_W_vcombine_VV(xh, xl);
  q6op_vstu_AV(ioptr, Q6_Vhf_equals_Wqf32(xx));
  ioptr++;
}

// 处理尾部不足 64 个 fp16 的 block。
if ((length & 63) != 0) {
  HVX_VectorPair xx = Q6_Wqf32_vmpy_VhfVhf(vmemu(&ioptr[0]), voneh);
  HVX_Vector xl =
      Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_Vqf32_vadd_Vqf32Vsf(Q6_V_lo_W(xx), vzero), vrecip);
  HVX_Vector xh =
      Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_Vqf32_vadd_Vqf32Vsf(Q6_V_hi_W(xx), vzero), vrecip);

  xx = Q6_W_vcombine_VV(xh, xl);

  // 只写回有效的 fp16 元素。
  q6op_vstu_variable_ARV(ioptr, (length & 63) * 2, Q6_Vhf_equals_Wqf32(xx));
}

这一步对应：

$$ out_i = \frac{\exp(scale \cdot (x_i - max))}{\sum_j \exp(scale \cdot (x_j - max))} $$

1.5.5 `softmax_fp_impl()`

源码第 318 到 333 行是 Softmax_fp 的外层调度函数。它本身不写 HVX 计算细节，只负责按 [B, H, W] 遍历，把每段最后一维切片交给 softmax_hf_approx()：

template <typename OutTtype, typename InTtype>
int softmax_fp_impl(OutTtype &out, const InTtype &in, const Tensor &beta) {
  // 输出 shape 与输入一致。
  out.set_dims(in);

  // 示例实现按 4D tensor 处理：[B, H, W, D]。
  // softmax 固定沿最后一维 D 做。
  auto [b_in, h_in, w_in, d_in] = in.dims();

  // beta 是 softmax 的指数缩放参数。
  // interface_scale 是输入 tensor 接口层的 scale，这里合进总 scale。
  float scale = in.interface_scale() * beta(0, 0, 0, 0);

  // 外层 B/H/W 逐切片遍历。
  // 每个切片是一段连续的 D 维 fp16 数据。
  for (Idx b = 0; b < b_in; b++) {
    for (Idx h = 0; h < h_in; h++) {
      for (Idx w = 0; w < w_in; w++) {
        using T                               = typename InTtype::element_type;

        // 当前 [b, h, w, :] 的输入首地址。
        const T *pin                          = &in.get_raw(b, h, w, 0);

        // 当前 [b, h, w, :] 的输出首地址。
        typename OutTtype::element_type *pout = &out.get_raw(b, h, w, 0);

        // 对最后一维做 softmax。
        softmax_hf_approx(pout, pin, scale, d_in);
      }
    }
  }
  return GraphStatus::Success;
}

也就是说，这个示例的 Softmax_fp 固定做最后一维 softmax；axis 在前面的优化规则里已经被规整掉了。

1.6 reference 版本

源码第 337 到 367 行是普通 C++ 版本：

template <typename Ttype>
int softmax_impl(Ttype &out, const Ttype &in, const float beta) {
  // debuglog("reference softmax (%s)", __PRETTY_FUNCTION__);
  out.set_dims(in);
  // 示例实现按 4D tensor 处理：[B, H, W, D]。
  auto [b_in, h_in, w_in, d_in] = in.dims();
  for (Idx b = 0; b < b_in; b++) {
    for (Idx h = 0; h < h_in; h++) {
      for (Idx w = 0; w < w_in; w++) {
        float max = in(b, h, w, 0);
        // 先找最大值，保证数值稳定。
        for (Idx d = 0; d < d_in; d++) {
          float const inval = in(b, h, w, d);
          max               = fmaxf(inval, max);
        }
        float sum = 0;
        // 计算未归一化的 exp 并且求和
        for (Idx d = 0; d < d_in; d++) {
          float const inval = in(b, h, w, d);
          sum += (out(b, h, w, d) = expf(beta * (inval - max)));
        }
        float const sum_recip = 1.0f / sum;
        // 归一化
        for (Idx d = 0; d < d_in; d++) {
          float const outval = out(b, h, w, d);
          out(b, h, w, d)    = outval * sum_recip;
        }
      }
    }
  }
  return GraphStatus::Success;
}

先找最大值
计算 exp(beta * (x - max))
求和
除以 sum

softmaxWithbetaWrapper() 只是把 Tensor beta 里的第一个 scalar 取出来，再调用这个 reference 实现。

2. `Q6_Vqf32_vmpy_Vqf32Vqf32` 等类型

这不是 QNN API，也不是 C++ 标准库函数。它是 Qualcomm Hexagon/HVX intrinsic。

可以按名字拆：

Q6_ Vqf32 _vmpy_ Vqf32 Vqf32
|   |       |      |     |
|   |       |      |     +-- 第二个输入类型：qf32 vector
|   |       |      +-------- 第一个输入类型：qf32 vector
|   |       +--------------- 操作：vector multiply
|   +----------------------- 返回类型：qf32 vector
+--------------------------- Hexagon Q6 intrinsic 前缀

这里几个缩写大致这样读：

片段	含义
`Q6`	Hexagon Q6 intrinsic 前缀
`V`	HVX vector
`W`	HVX vector pair
`R`	scalar register
`Q`	predicate/mask
`vmpy`	vector multiply
`vadd`	vector add
`Vhf`	vector half-float
`Vqf32`	vector qfloat32/内部扩展浮点表示
`Vsf`	vector single-float

所以在这份 softmax 里，Q6_Vqf32_vmpy_Vqf32Vqf32(a, b) 主要出现在三类地方：

把 (x - max) 乘以 beta 缩放。
多项式近似里做乘法。
最后把未归一化输出乘以 1 / sum。

直觉上可以把它当成：

1
2

for each lane:
  out[i] = a[i] * b[i]

但它的真实数据格式、lane 数、舍入行为、饱和行为要以 Hexagon intrinsic 文档为准。

QNN MatMul 权重静态化与输入化

Mon, 27 Apr 2026 10:00:00 +0800

QNN MatMul 权重静态化与输入化

MatMul 里，把矩阵权重做成 QNN_TENSOR_TYPE_STATIC，和把权重做成 QNN_TENSOR_TYPE_APP_WRITE的区别：

纯图拓扑几乎不变，变的是图里携带的数据和运行时绑定方式。
如果看上下文缓存、模型库或打包后的 so 体积，静态权重通常更大。
如果看 NPU 上多次重复推理的执行时间，静态权重通常更容易快。

1. 两种写法

在 QNN 环境里，MatMul 可以写成两种方式：

// 静态权重
Qnn_Tensor_t weightTensor = makeTensor("weight",
                                      QNN_TENSOR_TYPE_STATIC,
                                      QNN_DATATYPE_FLOAT_32,
                                      weightDims.data(),
                                      kTensorRank,
                                      weightData.data(),
                                      static_cast<uint32_t>(weightData.size() * sizeof(float)));

// 权重输入
Qnn_Tensor_t weightTensor = makeTensor("weight",
                                      QNN_TENSOR_TYPE_APP_WRITE,
                                      QNN_DATATYPE_FLOAT_32,
                                      weightDims.data(),
                                      kTensorRank,
                                      nullptr,
                                      0);

两种方式的异同主要体现在：

MatMul 的节点数和边数不变。
生成出来的模型库、上下文二进制、或者打包后的 so 体积，静态权重会明显更大。
运行时输入列表里，输入化权重会多一份外部输入。

计算时间： 静态权重可以让后端提前看到常量值，很多后端会在 finalize 或编译阶段做常量相关处理，比如预打包、布局转换、融合和缓存。

build/finalize 可能更慢
上下文缓存可能更大
这部分成本通常只付一次

图大小： 输入权重每次都要作为 graph input 绑定和传输，静态权重则直接复用后端已经接收和准备好的常量。所以在重复推理场景里，静态权重速度更占优：

少一次大块权重输入
少一次权重 buffer 绑定/校验
少一次 host 到 NPU 侧的数据准备机会
更容易命中后端内部的权重布局缓存

如果权重特别大，这个差距会更明显。

2. 在线构图bench

源码放在：

`1`	`blog/qnn-matmul-weight-static/weight_static_benchmark.cpp`

它在同一个进程里构建两张 MatMul 图，分别是：

static：weight 是 QNN_TENSOR_TYPE_STATIC，构图时权重数据直接挂在张量里。
app_write：weight 是 QNN_TENSOR_TYPE_APP_WRITE，构图时权重张量不带数据；每轮执行时把权重数据作为输入传进去。

两张图使用同样的 M/K/N、同样的输入数据、同样的权重数据和同一个 HTP backend。输出表里重点看这些列：

precision：本轮测试的张量精度，支持 fp32/fp16/int8/int16。
ctx_bin(MB)：QnnContext_getBinarySize() 返回的上下文缓存大小，按 1024 * 1024 转成 MB 显示。
static(MB)：注册到图里的静态权重 payload 大小，按 MB 显示。
runtime(MB)：每次执行需要从应用侧传入的输入大小，按 MB 显示。
final(ms)：QnnGraph_finalize() 耗时。
first(ms)：第一次 QnnGraph_execute() 耗时。
exec(ms)：多轮 QnnGraph_execute() 的均值和标准差。
precision_error_summary：按精度汇总所有 OK case 的误差；max_err 是该精度下最大的最大误差，avg_mean_err 是该精度下 mean_err 的平均值。

每个 precision + weight_mode 会单独跑一行。benchmark 默认测试：

`1`	`fp32,fp16,int8,int16`

如果只想跑某些精度，用：

`1`	`--precisions fp16,int8,int16`

2.1 编译

这个 benchmark 由仓库根目录的 CMakeLists.txt 统一管理, Android 交叉编译:

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_ROOT/build/cmake/android.toolchain.cmake \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-28

cmake --build build --target qnn_weight_static_benchmark -j4

2.2 推送到设备

把 benchmark、HTP 后端库和 C++ runtime 推到设备：

export DEVICE_ROOT=/data/local/tmp/qnn_matmul_weight_static
adb -s 127.0.0.1:40404 shell "mkdir -p $DEVICE_ROOT"

adb -s 127.0.0.1:40404 push \
  build/qnn_weight_static_benchmark \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtp.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpPrepare.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpV79Stub.so \
  $QNN_SDK_ROOT/lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so \
  $DEVICE_ROOT/

如果你的 SoC 不是 v79，需要把 libQnnHtpV79Stub.so 和 lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so 换成对应架构。

在 HTP/NPU 后端（SM8750 / HTP v79 上执行：）运行：

adb -s 127.0.0.1:40404 shell "
  cd /data/local/tmp/qnn_matmul_weight_static && \
  export LD_LIBRARY_PATH=\$PWD && \
  export ADSP_LIBRARY_PATH=\$PWD && \
  ./qnn_weight_static_benchmark \
    --backend ./libQnnHtp.so \
    --m 512 --k 2048 --n 2048 \
    --warmup 3 --iters 5 \
    --precisions fp32,fp16,int8,int16
"
# --m 512 --k 2048 --n 6144 \
# --m 512 --k 6144 --n 2048 \
# --m 512 --k 2048 --n 2048 \
# --m 1 --k 151936 --n 2048 \

输出结构如下。下面这份是 SM8750 / HTP v79 上的小矩阵 smoke test；这个 runtime 接受了 fp32 的 QNN API 张量配置，但这不等价于 HTP 内部在做原生 FP32 MatMul。

QNN MatMul Weight Static Benchmark
backend_path : ./libQnnHtp.so
backend_kind : NPU
htp_soc_model: 69
htp_arch     : 79
shape        : A[512, 2048] x B[2048, 6144] -> C[512, 6144]
warmup       : 3
iterations   : 5

precision weight     status             valid       ctx(ms)     build(ms)     final(ms)     first(ms)          exec(ms)      free(ms)    ctx_bin(MB)     static(MB)    runtime(MB)       max_err      mean_err
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
fp32      static     OK                  PASS        0.0292       85.0602      545.1886       10.1046    6.0671±0.8934       24.0706         4.3086        48.0000         4.0000        0.0026        0.0007
fp32      app_write  OK                  PASS        0.0377        0.4305      396.2505       52.3059   38.2210±2.6300       36.8942         0.2852         0.0000        52.0000        0.0026        0.0007
fp16      static     OK                  PASS        0.0377       14.0695      139.9085        7.3569    4.8455±0.0422       24.6860         4.3008        24.0000         2.0000        0.0026        0.0007
fp16      app_write  OK                  PASS        0.0391        0.3680     4126.0704       28.9443   23.9732±1.2695       52.0595         0.5664         0.0000        26.0000        0.0026        0.0007
int8      static     OK                  FAIL        0.0661        9.2544     1559.6377       16.3176   18.0157±5.1124       32.5441         8.6641        12.0000         1.0000        6.7834        2.2220
int8      app_write  OK                  FAIL        0.0447        0.3903      529.9657       35.4261   26.7496±4.7284       36.0866         0.3633         0.0000        13.0000        6.7834        2.2220
int16     static     OK                  PASS        0.0375       13.8047      482.1438       25.6598   22.8528±3.7121       28.8608         4.4336        24.0000         2.0000        0.0071        0.0027
int16     app_write  OK                  PASS        0.0357        0.4098     2056.0973       99.2368 122.3321±13.6945       63.8079         1.2305         0.0000        26.0000        0.0141        0.0054

context_binary_status
  fp32      static     ok
  fp32      app_write  ok
  fp16      static     ok
  fp16      app_write  ok
  int8      static     ok
  int8      app_write  ok
  int16     static     ok
  int16     app_write  ok

precision_error_summary
precision      cases       max_err      avg_mean_err
----------------------------------------------------
fp32              2        0.0026            0.0007
fp16              2        0.0026            0.0007
int8              2        6.7834            2.2220
int16             2        0.0141            0.0041

QNN MatMul Weight Static Benchmark
backend_path : ./libQnnHtp.so
backend_kind : NPU
htp_soc_model: 69
htp_arch     : 79
shape        : A[512, 6144] x B[6144, 2048] -> C[512, 2048]
warmup       : 3
iterations   : 5

precision weight     status             valid       ctx(ms)     build(ms)     final(ms)     first(ms)          exec(ms)      free(ms)    ctx_bin(MB)     static(MB)    runtime(MB)       max_err      mean_err
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
fp32      static     OK                  PASS        0.0252       84.7228      715.4846       12.0498   11.9023±1.6982       31.6374        12.8633        48.0000        12.0000        0.0016        0.0005
fp32      app_write  OK                  PASS        0.0217        0.2437      196.9550       59.2926   39.9130±2.8257       20.9656         0.1562         0.0000        60.0000        0.0016        0.0005
fp16      static     OK                  PASS        0.0311       12.2270      196.3642       20.4973   10.8049±1.6617       26.2479        12.8047        24.0000         6.0000        0.0016        0.0005
fp16      app_write  OK                  PASS        0.0383        0.3783     2350.6353       45.8905   30.1110±6.5165       31.6772         0.2305         0.0000        30.0000        0.0016        0.0005
int8      static     OK                  PASS        0.0663        8.6619     1950.1152       32.4290   27.9270±8.7762       32.5944        12.2031        12.0000         3.0000        0.0351        0.0121
int8      app_write  OK                  PASS        0.0647        0.4667     8905.2090       39.7415   29.3041±6.1805       46.4648         0.5898         0.0000        15.0000        0.0351        0.0121
int16     static     OK                  PASS        0.0379       16.8233     1472.6296       45.7644   73.8026±4.9664       46.2043        13.2148        24.0000         6.0000        0.0071        0.0028
int16     app_write  OK                  PASS        0.0384        0.3794    16282.6409      247.3371 263.2424±21.9484      168.4643         7.4531         0.0000        30.0000        0.0140        0.0055

context_binary_status
  fp32      static     ok
  fp32      app_write  ok
  fp16      static     ok
  fp16      app_write  ok
  int8      static     ok
  int8      app_write  ok
  int16     static     ok
  int16     app_write  ok

precision_error_summary
precision      cases       max_err      avg_mean_err
----------------------------------------------------
fp32              2        0.0016            0.0005
fp16              2        0.0016            0.0005
int8              2        0.0351            0.0121
int16             2        0.0140            0.0042

3. 离线构图

前面的 benchmark 比较的是在线构图后的 STATIC 和 APP_WRITE。为了更接近部署场景，新加了一个独立程序：

`1`	`blog/qnn-matmul-weight-static/weight_switch_benchmark.cpp`

它默认尝试三种运行模式，输出里的 mode 名称简化成：

app_write：一张图，weight 是 QNN_TENSOR_TYPE_APP_WRITE；每轮执行前从磁盘读 input/weight 数据，再把当前权重作为第二个输入传给 QnnGraph_execute()。
static_load：每个权重编译一张 STATIC 图，导出 context binary 并写到磁盘；每轮执行前临时读取一个 binary，再做 contextCreateFromBinary + graphRetrieve + execute + free。
update_static(不支持暂时)：一张图，weight 是 QNN_TENSOR_TYPE_UPDATEABLE_STATIC；每轮执行前从磁盘读新权重，调用 QnnTensor_updateGraphTensors()，再 QnnGraph_finalize() 让更新生效，然后执行。

三种模式使用同样的 M/K/N、同样的输入数据、同样的权重数据和同一个 backend。程序会先为每个 shape + precision 生成公共 tensor/expected-output 文件，然后释放 fp32 参考数据和常驻权重 payload；各模式在计时路径里再按需从磁盘读取当前 input、weight、expected output 或 graph binary。这样可以避免测试时把所有权重和所有参考输出长期留在 CPU 内存里。

实际在 SM8750 / HTP v79 上测试时，update_static 的 UPDATEABLE_STATIC + updateGraphTensors + finalize 路径会被 HTP 拒绝，所以程序会把这一行标成 SKIP，并且不会因为这个已知不支持路径返回失败。输出表里重点看这些列：

precision：本轮测试的张量精度，默认是 fp16/int8/int16。
prep(ms)：模式自己的准备阶段耗时，包括构图、导出 binary 等一次性工作；公共 tensor/expected-output 文件生成在各 mode 计时前完成，不计入这一列，且不包含单独列出的 final(ms)。
ssd_d(ms)：每轮从磁盘读取 input/weight 数据的时间。
ssd_g(ms)：每轮从磁盘读取 graph binary 的时间；只有 static_load 会有这一列。
htp_w(ms)：把图或权重真正写入 backend 的时间；static_load 里是 contextCreateFromBinary + graphRetrieve，update_static 里是 updateGraphTensors + finalize。
final(ms)：构图后的首次 QnnGraph_finalize() 总耗时。
first(ms)：第一轮完整路径耗时。
exec(ms)：纯 QnnGraph_execute() 的均值和标准差。
binary(B)：导出的 context binary 总大小。
static(B)：静态权重占用的 payload 字节数。
runtime(B)：每轮执行时应用侧需要准备的输入字节数。
--m 512 --k 2048 --n 6144: 测试shape

3.1 编译

这个 benchmark 也由仓库根目录的 CMakeLists.txt 统一管理，Android 交叉编译：

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_ROOT/build/cmake/android.toolchain.cmake \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-28

cmake --build build --target qnn_weight_switch_benchmark -j4

3.2 推送到设备

把 benchmark、HTP 后端库和 C++ runtime 推到设备：

export DEVICE_ROOT=/data/local/tmp/qnn_static_binary_switch
adb -s 127.0.0.1:40404 shell "mkdir -p $DEVICE_ROOT"

adb -s 127.0.0.1:40404 push \
  build/qnn_weight_switch_benchmark \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtp.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpPrepare.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpV79Stub.so \
  $QNN_SDK_ROOT/lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so \
  $DEVICE_ROOT/

如果你的 SoC 不是 v79，需要把 libQnnHtpV79Stub.so 和 lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so 换成对应架构。

在 HTP/NPU 后端运行：

adb -s 127.0.0.1:40404 shell "
  cd /data/local/tmp/qnn_static_binary_switch && \
  export LD_LIBRARY_PATH=\$PWD && \
  export ADSP_LIBRARY_PATH=\$PWD && \
  ./qnn_weight_switch_benchmark \
    --backend ./libQnnHtp.so \
    --precisions fp16,int8,int16
"

这个程序默认只把结果打印到 stdout，不会额外写日志文件。只有显式传 --log <path> 时才会把同样的结果落盘。

程序运行过程中会为了测量切换开销，临时写出 input / weight / expected-output / static graph binary 等中间文件；正常退出或异常退出时都会自动清理这些本地临时文件，不会在当前目录长期残留。

QNN 文档

Fri, 17 Apr 2026 14:10:00 +0800

QNN 文档阅读

QNN SDK 的核心文档在目录 $QNN_SDK_ROOT/docs/QNN/ 下, 这里的 api-rst 和 OpDef 的核心文档在官网上没有。

OpDef： “算子定义和后端支持” 文档，包括 Op 在不同设备的支持性、约束等信息。
api-rst： “API 参考” 文档，包括各个 api 的参数、功能、返回值等细节。

1. OpDef

下面以 MatMul，介绍一下 OpDef 里都有什么内容，在主文档 $QNN_SDK_ROOT/docs/QNN/OpDef/MasterOpDef.html?highlight=matmul#matmul 中可以看到算子 MatMul 的定义和输入输出参数等信息，如下图。可以看到算子定义矩阵乘法为$C = A \times B + b$, 有额外参数 transpose_in0 和 transpose_in1，控制输入矩阵的转置方式，从而影响计算结果。

这里的输入参数的数据类型是后端特定的，而不同后端又有自己特定的文档描述算子的支持情况和约束条件，例如 HTP 后端的 MatMul 算子定义和约束条件可以在 $QNN_SDK_ROOT/docs/QNN/OpDef/HtpOpDefSupplement.html?highlight=matmul#matmul 看到。

1.1 数据结构

首先是输入输出的数据结构，如下图, 当前 HTP 后端支持的数据格式是 FP16/INT16/INT8，

1.2 约束说明

HTP 后端对 MatMul 计算的数据维度不超过5维，另外对于各个精度的输入输出也有不同的约束，具体可以看下图。

这里针对不同的输入有不同的量化限制

2. api-rst

以 QnnGraph_addNode 接口为例展开，可以通过搜索直接搜索 api 接口，如下接下来查看 QnnGraph_addNode 接口的定义，可以看到该接口的参数和返回值等信息，如下图, 其输入参数为图句柄 Qnn_GraphHandle_t 和节点信息结构体 Qnn_OpConfig_t，返回值为状态码 Qnn_ErrorHandle_t。可以继续深入，点击 Qnn_OpConfig_t 可以跳转到对应的结构体的定义，查看其字段信息，如下图, 该结构体包含了节点的版本和对应版本的结构体，当前只有 Qnn_OpConfig_v1_t 版本的字段信息。继续点击查看 Qnn_OpConfig_v1_t 结构体的定义，可以看到该结构体包含了节点的名称、算子名称、额外输入参数数量、额外输入参数信息(上面提到的 transpose_in0 和 transpose_in1 就是这个参数)、输入张量指针、输出张量指针等字段信息，如下图。可以继续向下追溯张量结构体的结构。

3. 量化

在算子定义中看到了量化方法的约束，接下来顺着 Qnn_TensorV1_t 张量分析量化方式，从下面入口查看 Qnn_QuantizeParams_t 量化参数的定义结构体包括定义方式、量化方式、量化参数，共有8中量化方式，包括缩放量化(Qnn_ScaleOffset_t)、零点量化(Qnn_AxisScaleOffset_t)等, 具体可以继续深入查看，例如 Qnn_AxisScaleOffset_t 结构体的定义如下图, 该结构体包含了量化轴、量化参数数量、缩放值与零点值等字段信息。继续深入可以看到量化公式$floatValue = (quantizedValue + offset) * scale$，如下图,

4. 数据类型

在算子定义中看到了数据类型的约束，但是查文档只能查到粗糙的枚举类型，没有具体刻画各个数据类型的细节，如下图

话又说回来了，这么大文档直接喂给 codex 查更方便，

Qnn_DataType_t 的分类定义在 /root/qairt/2.40.0.251030/include/QNN/QnnTypes.h:103：

INT_*: 有符号整数，精确整数语义

UINT_*: 无符号整数，精确整数语义

FLOAT_*: 浮点

SFIXED_POINT_*: 有符号定点/量化类型

UFIXED_POINT_*: 无符号定点/量化类型

BOOL_8

STRING

QNN 环境准备与 python实例

Wed, 01 Apr 2026 15:30:00 +0800

QNN 环境准备与 MatMul 端侧实例

这篇把 QNN 介绍和QNN实例里的在线构图执行方式通过QNN 提供的python工具链实现

执行环境如下
- 宿主机：Ubuntu 22.04 x86_64
- QNN SDK：2.40.0.251030, python 3.10 ABI
- Android NDK：android-ndk-r29
- SoC：SnapDragon 8 elite, Chip: SM8750, Hexagon Arch: v79
- Backend：CPU/GPU/HTP

1. 环境配置

使用 QNN 的 python 工具链，执行

cd /root/qairt/2.40.0.251030/bin # 根据实际路径修改
source envsetup.sh 

# 这会设置python环境变量，确保后续命令能找到正确的python依赖
➜  ✗ echo $PYTHONPATH    
/root/qairt/2.40.0.251030/lib/python/:/root/qairt/2.40.0.251030/benchmarks/QNN/

接下来的操作依赖pytorch包，通过脚本检查环境：

# 查看环境检查结果
➜  ✗ ${QAIRT_SDK_ROOT}/bin/envcheck -a
Checking Android NDK Environment
--------------------------------------------------------------
[INFO] Found ndk-build at /root/android-ndk/android-ndk-r29/ndk-build and ANDROID_NDK_ROOT is also set.
--------------------------------------------------------------

Checking Clang Environment
--------------------------------------------------------------
[INFO] Found clang++ at /usr/bin/clang++
--------------------------------------------------------------

Checking TensorFlow Environment
--------------------------------------------------------------
[ERROR] Unable to import tensorflow using python3.
--------------------------------------------------------------

Checking TFLite Environment
--------------------------------------------------------------
[ERROR] Unable to import tflite using python3.
--------------------------------------------------------------

Checking ONNX Environment
--------------------------------------------------------------
[ERROR] Unable to import onnx using python3.
--------------------------------------------------------------

Checking PyTorch Environment
--------------------------------------------------------------
PyTorch is set-up successfully
--------------------------------------------------------------

可以通过python虚拟环境管理包，依赖版本在官方文档标出

conda create -n qnn python=3.10 -y  # 创建python3.10的虚拟环境
conda activate qnn  # 激活虚拟环境
export UV_INDEX_URL=https://pypi.mirrors.ustc.edu.cn/simple/ # 设置国内镜像源
uv pip install torch==1.13.1

2. 执行流程

QNN 提供了从模型转换到设备执行的python全链路工具，流程如下：

宿主机环境
-> 生成 MatMul 计算图
-> 转成 QNN model.cpp/.bin
-> 生成 aarch64-android 模型库
-> 推到 Android 设备
-> 用 qnn-net-run 执行
-> 回拉输出并和 NumPy 基线对比

2.1 生成 MatMul 计算图

目前计算图最常用的是 ONNX 格式，下面的脚本使用pytorch生成一个最小的 MatMul 计算图并且导出。

from pathlib import Path

import numpy as np
import torch

root = Path("matmul-demo/model")
root.mkdir(parents=True, exist_ok=True)

# 设置随机数种子，确保每次生成的输入和权重都一样
rng = np.random.default_rng(0)
A = rng.normal(size=(1, 128)).astype(np.float32)
B = rng.normal(size=(128, 64)).astype(np.float32)
bias = rng.normal(size=(64,)).astype(np.float32)

# 定义 MatMul 模型
class MatMulModel(torch.nn.Module):
    def __init__(self, weight: np.ndarray, bias_value: np.ndarray):
        super().__init__()
        self.register_buffer("weight", torch.from_numpy(weight))
        self.register_buffer("bias", torch.from_numpy(bias_value))

    def forward(self, x):
        return torch.matmul(x, self.weight) + self.bias

model = MatMulModel(B, bias).eval()
input_tensor = torch.from_numpy(A)

with torch.no_grad():
    Y = model(input_tensor).cpu().numpy()
# 导出 ONNX 模型
torch.onnx.export(
    model,
    input_tensor,
    str(root / "matmul.onnx"),
    input_names=["A"],
    output_names=["Y"],
    opset_version=13,
    do_constant_folding=False,
)
# 保存输入和参考输出
A.tofile(root / "input.raw")
np.save(root / "reference.npy", Y)
(root / "input_list.txt").write_text(str((root / "input.raw").resolve()) + "\n")

2.2 转成 QNN 计算图格式

1
2
3

$QNN_SDK_ROOT/bin/x86_64-linux-clang/qnn-onnx-converter \
  --input_network matmul-demo/model/matmul.onnx \
  --output_path matmul-demo/build/fp32/matmul_fp32.cpp

2.3 编译

$QNN_SDK_ROOT/bin/x86_64-linux-clang/qnn-model-lib-generator \
  -c matmul-demo/build/fp32/matmul_fp32.cpp \
  -b matmul-demo/build/fp32/matmul_fp32.bin \
  -t aarch64-android \
  -o matmul-demo/build/fp32/model_libs

2.4 执行

下面统一测试 fp32 精度，并分别在 CPU/GPU/NPU 三个后端执行。

首先推送需要的动态库、执行文件、模型库和输入数据到设备：

export DEVICE_ROOT=/data/local/tmp/qnn_matmul
adb -s 127.0.0.1:40404 shell "mkdir -p $DEVICE_ROOT/cpu $DEVICE_ROOT/gpu $DEVICE_ROOT/npu"

adb -s 127.0.0.1:40404 push \
  $QNN_SDK_ROOT/bin/aarch64-android/qnn-net-run \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnCpu.so \
  matmul-demo/build/fp32/model_libs/aarch64-android/libmatmul_fp32.so \
  matmul-demo/model/input.raw \
  $DEVICE_ROOT/cpu/

adb -s 127.0.0.1:40404 push \
  $QNN_SDK_ROOT/bin/aarch64-android/qnn-net-run \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnGpu.so \
  matmul-demo/build/fp32/model_libs/aarch64-android/libmatmul_fp32.so \
  matmul-demo/model/input.raw \
  $DEVICE_ROOT/gpu/

adb -s 127.0.0.1:40404 push \
  $QNN_SDK_ROOT/bin/aarch64-android/qnn-net-run \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtp.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpPrepare.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpV79Stub.so \
  $QNN_SDK_ROOT/lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so \
  matmul-demo/build/fp32/model_libs/aarch64-android/libmatmul_fp32.so \
  matmul-demo/model/input.raw \
  $DEVICE_ROOT/npu/

# 准备输入列表
adb -s 127.0.0.1:40404 shell "cd $DEVICE_ROOT/cpu && printf '%s\n' input.raw > input_list.txt"
adb -s 127.0.0.1:40404 shell "cd $DEVICE_ROOT/gpu && printf '%s\n' input.raw > input_list.txt"
adb -s 127.0.0.1:40404 shell "cd $DEVICE_ROOT/npu && printf '%s\n' input.raw > input_list.txt"

然后分别执行三组测试。

CPU：

adb -s 127.0.0.1:40404 shell "
  cd $DEVICE_ROOT/cpu && \
  export LD_LIBRARY_PATH=$DEVICE_ROOT/cpu && \
  ./qnn-net-run \
    --model libmatmul_fp32.so \
    --backend libQnnCpu.so \
    --input_list input_list.txt \
    --output_dir output
"

GPU：

adb -s 127.0.0.1:40404 shell "
  cd $DEVICE_ROOT/gpu && \
  export LD_LIBRARY_PATH=$DEVICE_ROOT/gpu && \
  ./qnn-net-run \
    --model libmatmul_fp32.so \
    --backend libQnnGpu.so \
    --input_list input_list.txt \
    --output_dir output
"

NPU：

adb -s 127.0.0.1:40404 shell "
  cd $DEVICE_ROOT/npu && \
  export LD_LIBRARY_PATH=$DEVICE_ROOT/npu && \
  export ADSP_LIBRARY_PATH=$DEVICE_ROOT/npu && \
  ./qnn-net-run \
    --model libmatmul_fp32.so \
    --backend libQnnHtp.so \
    --input_list input_list.txt \
    --output_dir output
"

2.5. 验证输出

分别回拉 CPU/GPU/NPU 三组输出：

mkdir -p matmul-demo/device/{cpu,gpu,npu}
adb -s 127.0.0.1:40404 pull $DEVICE_ROOT/cpu/output matmul-demo/device/cpu
adb -s 127.0.0.1:40404 pull $DEVICE_ROOT/gpu/output matmul-demo/device/gpu
adb -s 127.0.0.1:40404 pull $DEVICE_ROOT/npu/output matmul-demo/device/npu

然后做一个简单对比：

from pathlib import Path
import numpy as np

ref = np.load("matmul-demo/model/reference.npy").reshape(-1)

for name, atol in [("cpu", 1e-6), ("gpu", 1e-5), ("npu", 1e-4)]:
    out_path = next(Path(f"matmul-demo/device/{name}/output").rglob("*.raw"))
    out = np.fromfile(out_path, dtype=np.float32).reshape(-1)
    max_abs_err = np.max(np.abs(out - ref))
    mean_abs_err = np.mean(np.abs(out - ref))
    is_close = np.allclose(out, ref, atol=atol, rtol=0.0)
    print(
        name,
        "pass=",
        is_close,
        "atol=",
        atol,
        "max_abs_err=",
        max_abs_err,
        "mean_abs_err=",
        mean_abs_err,
    )

测试结果如下，误差npu最大：

1
2
3

cpu pass= False atol= 1e-06 max_abs_err= 4.7683716e-06 mean_abs_err= 1.2996607e-06
gpu pass= True atol= 1e-05 max_abs_err= 5.722046e-06 mean_abs_err= 1.6018748e-06
npu pass= False atol= 0.0001 max_abs_err= 0.009534836 mean_abs_err= 0.0027581714

通过该工具链可以把torch模型导出onnx算子图，转换编译并使用qnn-net-run在端侧npu上使用，缺点是灵活度不够

QNN 环境准备与实例

Wed, 01 Apr 2026 15:30:00 +0800

QNN 环境准备与在线构图 MatMul 示例

这篇把 QNN 介绍里的在线构图执行方式整理成一个最小 C++ 示例，并且把同一份代码在CPU、 GPU、HTP 上跑通。

执行环境如下
- 宿主机：Ubuntu 22.04 x86_64
- QNN SDK：2.40.0.251030
- Android NDK：android-ndk-r29
- SoC：SnapDragon 8 elite, Chip: SM8750, Hexagon Arch: v79
- Backend：CPU/GPU/HTP

1. 环境配置

QNN 开发需要在有 QNN SDK 的宿主机（Host Device）开发，编译等完成后推送到有高通硬件的目标机器（Target Device）上运行，大致如下图。

图 1. QNN 宿主机与目标设备开发流程。

1.1 QNN 环境配置

方式一: 下载解压QNN SDK：在 QNN SDK 网站可以直接通过 Get Software 下载最新版的 QNN SDK。如果需要旧版本，需要注册高通账号，在 Qualcomm® software center 中找对应版本下载。 图 2. QNN SDK 下载页面。 部分受限的高通软件/工具需要向高通销售团队 申请访问权限。
- 找个路径解压 SDK, 获得一个类似 /root/qairt/2.40.0.251030 的路径
- 配置环境变量：cd /root/qairt/2.40.0.251030/bin && source envsetup.sh 包括了 QNN_SDK_ROOT 环境变量和一些工具链路径，配置在 ~/.bashrc 或者 ~/.zshrc 里会更方便一些。
- 安装依赖：sudo /root/qairt/2.40.0.251030/bin/check-linux-dependency.sh
- 检查环境：/root/qairt/2.40.0.251030/bin/envcheck -c
- 后续 python 需要使用给定的依赖版本

方式二: qsc安装:Qualcomm Software Center有cli版本供linux环境安装,

# 下载安装
➜ curl -L https://softwarecenter.qualcomm.com/api/download/software/tools/Qualcomm_Software_Center/Linux/Debian/latest.deb -o qsc_installer.deb
➜ sudo apt install ./qsc_installer.deb

# 登录
➜ qsc-cli login -u <your username>
➜ qsc-cli sdk --help
Usage: qsc-cli sdk [options] [command]

Sdk workflows

Options:
  -h,--help            Display help for this command

Commands:
  license              Activate, deactivate, or list sdk licenses
  download [options]   Download a sdk or its release notes
  install [options]    Install a sdk
  uninstall [options]  Uninstall the currently installed sdk
  info [options]       Show information for available or installed sdks

Refer to "qsc-cli sdk <command> --help" for more details and sample usage

➜ qsc-cli sdk info # 查看可用的SDK列表
[Info]: Starting qsc-cli version 1.26.6...
Audio1.x
HexagonSDK4.x
HexagonSDK5.x
HexagonSDK6.x
LPAI
qualcomm_ai_engine_direct
Qualcomm_AI_Runtime_Community
Qualcomm_AI_Runtime_SDK
Qualcomm_Aware_Location_Android_LocationProvider
Qualcomm_Aware_Location_Android_SDK
Qualcomm_Aware_Location_Embedded_Client
Qualcomm_Aware_Location_Evaluation_Tools
Qualcomm_Aware_Location_Native_SDK
Qualcomm_IRF_SDK
Qualcomm_IRP_SDK
qualcomm_neural_processing_sdk
qualcomm_neural_processing_sdk_public
QualcommSimulationPlatformSDK

# 查看sdk使用命令 
➜  ~ qsc-cli sdk info --help
Usage: qsc-cli sdk info [options]

Show information for available or installed sdks

Options:
  -n, --name <string>  Name of the sdk
  -c, --components     Display components information
  --json               Display information in JSON format
  --installed          Display only installed sdks information
  --latest-version     Display only latest available version
  -h,--help            Display help for this command

Example command to display all sdks: qsc-cli sdk info

Example command: qsc-cli sdk info --name <string> --latest-version

Example command: qsc-cli sdk info --name <string> --components --installed --json

➜  ~ qsc-cli sdk info -n Qualcomm_AI_Runtime_SDK # 查看可安装版本
[Info]: Starting qsc-cli version 1.26.6...


Name                   : Qualcomm_AI_Runtime_SDK
Installed version      : None
Available version(s)   : 2.45.40.260406
                        2.45.1.260416
                        2.45.0.260326
                        2.44.0.260225
                        2.43.1.260218
                        2.43.0.260128
                        2.42.0.251225
                        2.41.0.251128
                        2.40.1.251119
                        2.40.0.251030
                        2.39.3.251009
                        2.39.0.250926
                        2.38.1.251113
                        2.38.0.250901
                        2.37.1.250807
                        2.37.0.250724
                        2.36.4.250725
                        2.36.3.250722
                        2.36.1.250708
                        2.36.0.250627
                        2.35.6.250717
                        2.35.3.250617
                        2.35.0.250530
                        2.34.2.250528
                        2.34.1.250516
                        2.34.0.250424
                        2.33.2.250410
                        2.33.0.250327
                        2.32.6.250402
                        2.32.0.250228

➜ qsc-cli sdk install --help # 查看安装SDK的命令和参数
Usage: qsc-cli sdk install [options]

Install a sdk

Options:
  -n, --name <string>               Name of the sdk
  --activate-default-license        Activate default license before installation
  -rv, --required-version <string>  Preferred version
  --config <string>                 Configuration file or settings to use during install
  --path <path>                     Preferred install path
  -f, --force                       Force installation despite script or add-on errors
  -s, --silent                      Install sdk silently without any user prompts
  -h,--help                         Display help for this command

Example command: qsc-cli sdk install --name <string> --required-version <string> --config <string> --silent --force --activate-default-license

➜ qsc-cli sdk install -n Qualcomm_AI_Runtime_SDK --path /root/QNN -rv 2.40.0.251030 # 安装指定版本的QNN SDK到/root/QNN目录
[Info]: Starting qsc-cli version 1.26.6...
[Info] : Downloading package file for product Qualcomm_AI_Runtime_SDK for version 2.40.0.251030
[Info] : Downloading... 100%
[Info] : Downloaded package file to /tmp/QIKCache/88f4a6db-ddff-11ef-9172-02ddcb07e973/8f369776-b87d-11f0-ae67-064291a33d05/Qualcomm_AI_Runtime_SDK.2.40.0.251030.Linux-AnyCPU.qik

Access to and use of tools managed by the Qualcomm Package Manager are subject to the terms and conditions of the corresponding agreement(s) in place with Qualcomm Technologies, Inc. or its affiliates.
Unauthorized access or use is prohibited. Information such as tool version, operating system, user ID, company ID, IP address, computer mac address, date, timestamp, or features and functions of our tools that you use may be collected for internal business purposes or tool improvements and is subject to the Qualcomm Privacy Policy [http://www.qualcomm.com/site/privacy].
By accessing or using this tool, you agree to the foregoing.
Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries. All rights reserved.


Accept and continue with installation [y/n] : y

[Warning] : Qualcomm_AI_Runtime_SDK is of the ExtractOnly type. The install command will automatically perform the extraction
[Info] : Step 1 of 7: Checking environment
[Info] : Step 2 of 7: Checking previous version
[Info] : Step 3 of 7: Checking dependencies
[Info] : Step 4 of 7: Preparing system
[Info] : Step 5 of 7: Extracting files
[Info] : Step 6 of 7: Configuring system
[Info] : Step 7 of 7: Finishing installation
[Info] : SUCCESS: Installed Qualcomm_AI_Runtime_SDK.Core at /root/QNN
[Info] : Log File Location: file:///var/tmp/qcom/qik/logs/462d10c5-b37e-4089-9e16-5056800f0869/qiktool.20260428.1.log

通过这个方式安装也需要自己设置环境变量，目录在/root/QNN/bin/envsetup.sh 这个路径是因为安装时指定了路径，这样激活的环境变量和前面略有不同，使用起来要注意，也可以自己设置相同名称的环境变量。

1.2 Android 交叉编译环境配置

步骤1：下载最新版软件包，获取地址（选择对应平台最新稳定版，点击后出现 “Android 软件开发套件许可协议”，勾选后鼠标右键下载按钮可以复制下载链接）

# 服务器端运行
# 到指定目录下载并解压 `android_ndk`
cd ~ && mkdir android_ndk && cd ~/android_ndk
wget https://googledownloads.cn/android/repository/android-ndk-r29-linux.zip
unzip android-ndk-r29-linux.zip # 这个文件名和下载的版本有关
# 删除压缩包
rm android-ndk-r29-linux.zip # 这个文件名和下载的版本有关

# 进入并记住解压后的目录
# 在目录里用 `pwd` 命令可以获取绝对路径
cd android-ndk-r29 # 这个目录和下载的版本有关，可以通过 `ls -lah` 显示目录

步骤2：配置环境变量

# 服务器端运行
# 通常会配置 `ANDROID_NDK_ROOT` 环境变量
# 但 `MNN` 中在 `project/android/build_64.sh` 使用的是 `$ANDROID_NDK` 环境变量，所以都设置一下
➜ export ANDROID_NDK="$HOME/android_ndk/android-ndk-r29" # 环境变量
➜ $ANDROID_NDK/ndk-build --version  # 验证环境变量
GNU Make 4.3
Built for x86_64-pc-linux-gnu
Copyright (C) 1988-2020 Free Software Foundation,  Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY,  to the extent permitted by law.

# 在命令行单次export只会在当前命令行有效 新开的终端不生效
# 需要把环境变量写到 `shell` 的配置文件中，`bash` 对应 `~/.bashrc`，`zsh` 对应 `~/.zshrc`
# !!注意这里重定向是重定向文件末尾 '>>' 符号
echo 'export ANDROID_NDK="$HOME/android_ndk/android-ndk-r29"' >> ~/.zshrc # 环境变量
echo 'export ANDROID_NDK_ROOT="$HOME/android_ndk/android-ndk-r29"'  >> ~/.zshrc # 环境变量
echo 'export PATH="$ANDROID_NDK:$PATH"' >> ~/.zshrc
# 验证
➜  ndk-build
Android NDK: Could not find application project directory !
Android NDK: Please define the NDK_PROJECT_PATH variable to point to it.
/root/android_ndk/android-ndk-r29/build/core/build-local.mk:151: *** Android NDK: Aborting    .  Stop.

2. 执行流程

下面的示例是计算$C = A \times B$，对应的执行链如下：

动态加载 `backend` 动态库
-> QnnInterface_getProviders()
-> QnnBackend_create()
-> QnnContext_create()
-> QnnGraph_create()
-> QnnTensor_createGraphTensor()
-> QnnGraph_addNode()
-> QnnGraph_finalize()
-> QnnGraph_execute()
-> 校验输出

对照执行流程图为： 图 3. QNN 在线构图执行流程。

2.1 初始化

下面例子调用的内置 MatMul 算子，无需注册自定义算子，所以初始化阶段相对简单，主要是创建上下文、设备、图等资源：

qnnInterface.logCreate(qnnLogCallback, logLevel, &logger);          // 注册log
qnnInterface.backendCreate(logger, nullptr, &backend);              // 创建backend
qnnInterface.deviceCreate(logger, configs, &device);                // 创建设备
qnnInterface.contextCreate(backend, device, nullptr, &context);     // 创建上下文
qnnInterface.graphCreate(context, "matmul_graph", nullptr, &graph); // 创建图

2.2 图构建

2.2.1 创建张量

在 QNN 图里，这三个张量分别对应：

A：QNN_TENSOR_TYPE_APP_WRITE
B：QNN_TENSOR_TYPE_STATIC
C：QNN_TENSOR_TYPE_APP_READ

    
// 构建测试数据和张量描述
constexpr uint32_t kRows      = 32;
constexpr uint32_t kInner     = 128;
constexpr uint32_t kCols      = 64;
constexpr uint32_t kTensorRank = 2;
std::vector<float> inputData  = makeInputData(kRows * kInner, 23, 11.0f);
std::vector<float> weightData = makeInputData(kInner * kCols, 17, 9.0f);
std::vector<float> outputData(kRows * kCols, std::numeric_limits<float>::quiet_NaN());

std::array<uint32_t, kTensorRank> inputDims  = {kRows, kInner};
std::array<uint32_t, kTensorRank> weightDims = {kInner, kCols};
std::array<uint32_t, kTensorRank> outputDims = {kRows, kCols};

// 创建tensor描述
Qnn_Tensor_t inputTensor = makeTensor("input",
                                      QNN_TENSOR_TYPE_APP_WRITE,
                                      QNN_DATATYPE_FLOAT_32,
                                      inputDims.data(),
                                      kTensorRank,
                                      nullptr,
                                      0);
Qnn_Tensor_t weightTensor = makeTensor("weight",
                                        QNN_TENSOR_TYPE_STATIC,
                                        QNN_DATATYPE_FLOAT_32,
                                        weightDims.data(),
                                        kTensorRank,
                                        weightData.data(),
                                        static_cast<uint32_t>(weightData.size() * sizeof(float)));
Qnn_Tensor_t outputTensor = makeTensor("output",
                                        QNN_TENSOR_TYPE_APP_READ,
                                        QNN_DATATYPE_FLOAT_32,
                                        outputDims.data(),
                                        kTensorRank,
                                        nullptr,
                                        0);

/* Tensor构造函数需要绑定多个config信息
  Qnn_Tensor_t makeTensor(const char* name,
                      Qnn_TensorType_t type,
                      Qnn_DataType_t dataType,
                      uint32_t* dimensions,
                      uint32_t rank,
                      void* data,
                      uint32_t dataSize) {
    Qnn_Tensor_t tensor = QNN_TENSOR_INIT;
    tensor.version      = QNN_TENSOR_VERSION_1; // 张量版本
    tensor.v1.name      = name;
    tensor.v1.type      = type;
    tensor.v1.dataFormat = QNN_TENSOR_DATA_FORMAT_FLAT_BUFFER; // 内存类型
    tensor.v1.dataType   = dataType;
    tensor.v1.rank       = rank; // 张量维度数量
    tensor.v1.dimensions = dimensions; // 张量维度信息
    tensor.v1.memType    = QNN_TENSORMEMTYPE_RAW; // 内存分配方式
    tensor.v1.clientBuf.data = data; // 这里的data是一个指针，指向实际的数据buffer
    tensor.v1.clientBuf.dataSize = dataSize; // buffer的大小，单位是字节
    return tensor;
  }
*/

// 把张量注册到图里
qnnInterface.tensorCreateGraphTensor(graph, &inputTensor);
qnnInterface.tensorCreateGraphTensor(graph, &weightTensor);
qnnInterface.tensorCreateGraphTensor(graph, &outputTensor);

Qnn_Tensor_t 是一个 union，底层可以使用 Qnn_TensorV1_t 或者 Qnn_TensorV2_t 两种版本的结构体来描述张量信息。
Qnn_TensorMemType_t 共有三种方式，QNN_TENSORMEMTYPE_RAW 提供原始指针，QNN_TENSORMEMTYPE_MEMHANDLE 提供内存对象，可以在 QNN 设备间内存共享，QNN_TENSORMEMTYPE_RETRIEVE_RAW 通过回调函数提供原始指针。
clientBuf 字段也是一个 union，还可以使用 memHandle 对应上面的内存对象。这里的 weight 张量是静态的，所以在注册的时候就把 data buffer 绑定上了；而 input 和 output 张量是动态的，可以先注册一个不带 data buffer 的描述，等到执行阶段再绑定真正的 buffer。

2.2.2 创建节点

节点定义也需要绑定很多信息：

// 目前只有v1版本
Qnn_OpConfig_t opConfig = QNN_OPCONFIG_INIT; 
opConfig.v1.name          = "matmul_0";
opConfig.v1.packageName   = QNN_OP_PACKAGE_NAME_QTI_AISW;
opConfig.v1.typeName      = QNN_OP_MAT_MUL;
opConfig.v1.numOfParams   = 0;       // 额外参数数量
opConfig.v1.params        = nullptr; // 额外参数数据
// 绑定输入输出张量
opConfig.v1.numOfInputs   = static_cast<uint32_t>(nodeInputs.size()); 
opConfig.v1.inputTensors  = nodeInputs.data();
opConfig.v1.numOfOutputs  = static_cast<uint32_t>(nodeOutputs.size());
opConfig.v1.outputTensors = nodeOutputs.data();

// 把节点加入图中
qnnInterface.graphAddNode(graph, opConfig);

2.4 完成构图并执行

完成构图后就可以执行图计算：

// 图构建完成后，调用 finalize 把图定型
qnnInterface.graphFinalize(graph, nullptr, nullptr);

// 构建执行张量，绑定真正的输入输出 buffer
Qnn_Tensor_t executeInput = makeExecuteTensor(
    inputTensor, inputData.data(), inputData.size() * sizeof(float));
Qnn_Tensor_t executeOutput = makeExecuteTensor(
    outputTensor, outputData.data(), outputData.size() * sizeof(float));

// 执行图计算
qnnInterface.graphExecute(graph,
                          &executeInput,
                          1,
                          &executeOutput,
                          1,
                          nullptr,
                          nullptr);

QnnTensor_createGraphTensor() 注册的是图里的张量元信息，不是这次执行的 I/O buffer。
真正的数据 buffer 是在 makeExecuteTensor() 之后、QnnGraph_execute() 之前才绑定进去的。

2.5 资源释放

逐步释放上下文等资源

qnnInterface.contextFree(context, nullptr);
qnnInterface.deviceFree(device);
qnnInterface.deviceFreePlatformInfo(logger, platformInfo);
qnnInterface.backendFree(backend);
qnnInterface.logFree(logger);

3. 构建

📦 先准备环境变量，通常只需要把 QNN_SDK_ROOT 指向 QNN SDK 路径就行了, 或者使用前面的 cd /root/qairt/2.40.0.251030/bin && source envsetup.sh 来加载一系列环境变量。保证echo $QNN_SDK_ROOT && echo ANDROID_NDK_ROOT能正确输出 SDK和NDK 路径。
🛠️ 交叉编译, 这里同时使用了 QNN SDK 和 Android NDK 的工具链文件。
📱 这里统一使用根目录 build/。host 和 Android 交叉编译都走这个目录，但切换 toolchain 前需要先清理旧缓存。

⚠️ shell 续行的反斜杠 \ 后面不要直接跟注释，否则后续 -D... 参数会被 shell 当成单独命令执行。

# 确保环境变量正常
# export QNN_SDK_ROOT=/root/qairt/2.40.0.251030
# export ANDROID_NDK_ROOT=/root/android-ndk/android-ndk-r29

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK_ROOT/build/cmake/android.toolchain.cmake" \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-31 \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

cmake --build build -j4 --target qnn_online_matmul

✅ 推送到手机的可执行文件应该来自当前 Android 配置的 build/，不能把宿主机 x86_64 产物直接推到 Android 设备上。
✅ 如果刚刚把 build/ 配成 host，再切到 Android，先删掉 build/CMakeCache.txt 或整个 build/ 再重新配置。

4. 目标设备运行

把依赖的动态库等文件推送给 adb 设备
运行时需要设置环境变量 LD_LIBRARY_PATH 指向动态库所在目录，ADSP_LIBRARY_PATH 指向 HTP 相关库所在目录（如果需要跑 HTP 的话），以保证动态库能被正确加载到内存里。

4.1 GPU 测试

QNN 默认的 GPU 后端是 Opencl，依赖部分动态库，需要推送 GPU 运行所需文件：

export GPU_DIR=/data/local/tmp/qnn_online_matmul_gpu # 设备侧的目录，可以根据需要修改
adb -s 127.0.0.1:40404 shell "mkdir -p $GPU_DIR"     # 这里的adb命令需要根据实际情况修改，确保能连接到目标设备

adb -s 127.0.0.1:40404 push \
  build/qnn_online_matmul \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnGpu.so \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $GPU_DIR/

执行设备侧的 GPU 测试：

> adb -s 127.0.0.1:40404 shell "
  cd $GPU_DIR && \
  export LD_LIBRARY_PATH=$GPU_DIR && \
  ./qnn_online_matmul ./libQnnGpu.so --dump-backend-info
"

Backend Info
backend_path  : ./libQnnGpu.so
backend_kind  : GPU
provider_count: 1
provider[0]
  backend_id        : 4 (GPU)
  provider_name     : GPU_QTI_AISW
  core_api_version  : 2.30.0
  backend_api_ver   : 3.12.0
  selected          : yes
selected_core_api   : 2.30.0
selected_backend_api: 3.12.0
backend_build_id: v2.40.0.251030114326_189385
api_entries
  propertyHasCapability             yes
  backendGetApiVersion              yes
  backendGetBuildId                 yes
  deviceCreate                      yes
  deviceGetPlatformInfo             yes
  contextCreate                     yes
  graphCreate                       yes
  tensorCreateGraphTensor           yes
  graphFinalize                     yes
  graphExecute                      yes
capabilities
  device_api_group                  supported
  backend_support_op_package        supported
  backend_support_composition       supported
  context_support_caching           supported
  graph_support_execute             supported
  graph_support_async_execution     not_supported
  graph_support_online_prepare      supported
  tensor_support_context_tensors    supported
  tensor_support_dynamic_dimensions not_supported
QNN online MatMul example
backend_path : ./libQnnGpu.so
backend_kind : GPU
tolerance    : 0.0001
shape        : A[32, 128] x B[128, 64] -> C[32, 64]
max_abs_err  : 0.00000119
mean_abs_err : 0.00000028
validation   : PASS
output[0:8]  : -1.58585858 1.19191921 0.87878758 -2.18181872 0.25252536 1.82828355 0.31313074 -0.17171730

Time Breakdown
stage                           time(us)
----------------------------------------
load_backend_library               15900
resolve_qnn_interface                  5
backend_create                     48781
dump_backend_info                     63
device_create                        268
context_create                        19
graph_create                          17
tensor_create                       2360
graph_add_node                        18
graph_finalize                    331536
graph_execute                        571
result_validate                       25

4.2 HTP 测试

推送 HTP 运行所需文件：

export HTP_DIR=/data/local/tmp/qnn_online_matmul_htp
adb -s 127.0.0.1:40404 shell "mkdir -p $HTP_DIR"

adb -s 127.0.0.1:40404 push \
  build/qnn_online_matmul \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtp.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpPrepare.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpV79Stub.so \
  $QNN_SDK_ROOT/lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $HTP_DIR/

执行设备侧的 HTP 测试：

adb -s 127.0.0.1:40404 shell "
  cd $HTP_DIR && \
  export LD_LIBRARY_PATH=$HTP_DIR && \
  export ADSP_LIBRARY_PATH=$HTP_DIR && \
  ./qnn_online_matmul ./libQnnHtp.so --dump-backend-info
"

Backend Info
backend_path  : ./libQnnHtp.so
backend_kind  : NPU
provider_count: 1
provider[0]
  backend_id        : 6 (HTP)
  provider_name     : HTP_QTI_AISW
  core_api_version  : 2.30.0
  backend_api_ver   : 5.40.0
  selected          : yes
selected_core_api   : 2.30.0
selected_backend_api: 5.40.0
backend_build_id: v2.40.0.251030114326_189385
api_entries
  propertyHasCapability             yes
  backendGetApiVersion              yes
  backendGetBuildId                 yes
  deviceCreate                      yes
  deviceGetPlatformInfo             yes
  contextCreate                     yes
  graphCreate                       yes
  tensorCreateGraphTensor           yes
  graphFinalize                     yes
  graphExecute                      yes
capabilities
  device_api_group                  supported
  backend_support_op_package        supported
  backend_support_composition       supported
  context_support_caching           supported
  graph_support_execute             supported
  graph_support_async_execution     not_supported
  graph_support_online_prepare      supported
  tensor_support_context_tensors    not_supported
  tensor_support_dynamic_dimensions supported
QNN online MatMul example
backend_path : ./libQnnHtp.so
backend_kind : NPU
htp_soc_model: 69
htp_arch     : 79
tolerance    : 0.005
shape        : A[32, 128] x B[128, 64] -> C[32, 64]
max_abs_err  : 0.00183558
mean_abs_err : 0.00050184
validation   : PASS
output[0:8]  : -1.58691406 1.19140625 0.87841797 -2.18164062 0.25244141 1.82910156 0.31274414 -0.17224121

Time Breakdown
stage                           time(us)
----------------------------------------
load_backend_library                 869
resolve_qnn_interface                  4
backend_create                       931
dump_backend_info                     63
device_create                     102422
context_create                        80
graph_create                      203671
tensor_create                         58
graph_add_node                        39
graph_finalize                      9320
graph_execute                       2531
result_validate                       64

如果你需要看更细的 backend 日志，可以额外加：

`1`	`export QNN_LOG_LEVEL=debug`

4.3 CPU 测试

推送 CPU 运行所需文件：

export CPU_DIR=/data/local/tmp/qnn_online_matmul_cpu
adb -s 127.0.0.1:40404 shell "mkdir -p $CPU_DIR"

adb -s 127.0.0.1:40404 push \
  build/qnn_online_matmul \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnCpu.so \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $CPU_DIR/

执行设备侧的 CPU 测试：

adb -s 127.0.0.1:40404 shell "
  cd $CPU_DIR && \
  export LD_LIBRARY_PATH=$CPU_DIR && \
  ./qnn_online_matmul ./libQnnCpu.so --dump-backend-info
"

Backend Info
backend_path  : ./libQnnCpu.so
backend_kind  : CPU
provider_count: 1
provider[0]
  backend_id        : 3 (CPU)
  provider_name     : CPU_QTI_AISW
  core_api_version  : 2.30.0
  backend_api_ver   : 1.1.0
  selected          : yes
selected_core_api   : 2.30.0
selected_backend_api: 1.1.0
backend_build_id: v2.40.0.251030114326_189385
api_entries
  propertyHasCapability             yes
  backendGetApiVersion              yes
  backendGetBuildId                 yes
  deviceCreate                      yes
  deviceGetPlatformInfo             yes
  contextCreate                     yes
  graphCreate                       yes
  tensorCreateGraphTensor           yes
  graphFinalize                     yes
  graphExecute                      yes
capabilities
  device_api_group                  not_supported
  backend_support_op_package        supported
  backend_support_composition       supported
  context_support_caching           supported
  graph_support_execute             supported
  graph_support_async_execution     not_supported
  graph_support_online_prepare      supported
  tensor_support_context_tensors    supported
  tensor_support_dynamic_dimensions supported
QNN online MatMul example
backend_path : ./libQnnCpu.so
backend_kind : CPU
tolerance    : 0.0001
shape        : A[32, 128] x B[128, 64] -> C[32, 64]
max_abs_err  : 0.00000000
mean_abs_err : 0.00000000
validation   : PASS
output[0:8]  : -1.58585882 1.19191945 0.87878734 -2.18181849 0.25252527 1.82828319 0.31313115 -0.17171681

Time Breakdown
stage                           time(us)
----------------------------------------
load_backend_library                2295
resolve_qnn_interface                  4
backend_create                       597
dump_backend_info                     54
device_create                          1
context_create                         7
graph_create                        1938
tensor_create                         42
graph_add_node                       117
graph_finalize                        32
graph_execute                       1066
result_validate                       47

5. `benchmark`

基于上述示例构建了一个测试不同精度/后端性能的benchmark，方便快速做端侧验证和横向对比。🧪

5.1 编译

Android 交叉编译：

# 确保环境变量正常
# export QNN_SDK_ROOT=/root/qairt/2.40.0.251030
# export ANDROID_NDK_ROOT=/root/android-ndk/android-ndk-r29

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK_ROOT/build/cmake/android.toolchain.cmake" \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-31 \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

cmake --build build -j4 --target qnn_precision_benchmark

5.2 命令行参数

qnn_precision_benchmark 支持以下参数：

--backend <path>         指定 backend 动态库路径
--dump-backend-info      打印 provider、interface、capability 信息
--m <rows>               左矩阵行数，默认 256
--k <inner>              矩阵归约维度，默认 512
--n <cols>               右矩阵列数，默认 512
--warmup <count>         预热次数，默认 3
--iters <count>          正式计时轮数，默认 10
--precisions <list>      精度列表，默认 fp32,int8,int16,fp16

如果要快速查看后端信息，也可以在运行前设置：

`1`	`export QNN_DUMP_BACKEND_INFO=1`

5.3 执行

下面的命令把可执行文件和三种后端需要的动态库一次性推到同一个目录：

export BENCH_DIR=/data/local/tmp/qnn_precision_benchmark
adb -s 127.0.0.1:40404 shell "mkdir -p $BENCH_DIR"

adb -s 127.0.0.1:40404 push \
  build/qnn_precision_benchmark \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnCpu.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnGpu.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtp.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpPrepare.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpV79Stub.so \
  $QNN_SDK_ROOT/lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $BENCH_DIR/

5.3.1 CPU 测试

adb -s 127.0.0.1:40404 shell "
  cd $BENCH_DIR && \
  export LD_LIBRARY_PATH=$BENCH_DIR && \
  ./qnn_precision_benchmark \
    --backend ./libQnnCpu.so \
    --m 64 --k 128 --n 128 \
    --warmup 1 --iters 3
"

5.3.2 GPU 测试

adb -s 127.0.0.1:40404 shell "
  cd $BENCH_DIR && \
  export LD_LIBRARY_PATH=$BENCH_DIR && \
  ./qnn_precision_benchmark \
    --backend ./libQnnGpu.so \
    --m 64 --k 128 --n 128 \
    --warmup 1 --iters 3
"

5.3.3 HTP 测试

adb -s 127.0.0.1:40404 shell "
  cd $BENCH_DIR && \
  export LD_LIBRARY_PATH=$BENCH_DIR && \
  export ADSP_LIBRARY_PATH=$BENCH_DIR && \
  ./qnn_precision_benchmark \
    --backend ./libQnnHtp.so \
    --m 64 --k 128 --n 128 \
    --warmup 1 --iters 3
"

5.6 支持矩阵

以 MatMul 为例，当前文档和实际测试对应的支持范围如下：

✅ CPU：支持 fp32/int8，int16/fp16 会显示为 UNSUPPORTED
✅ GPU：支持 fp32/fp16，int8/int16 会显示为 UNSUPPORTED
✅ HTP：文档矩阵按 fp16/int8/int16 处理；如果 fp32 在你的设备上显示 OK，它表示 QNN runtime 接受了 QNN_DATATYPE_FLOAT_32 的图配置，不等价于 HTP 内部在做原生 FP32 MatMul

这里的 UNSUPPORTED 现在优先来自 backendValidateOpConfig() 的运行时探测；如果探测接口不可用，或者目标端 Android + HTP + int8 MatMul 会在 libQnnHtpPrepare.so 的探测路径里崩溃，就回退到文档支持矩阵，再以实际建图执行结果为准。fp32 OK 只能说明 API 层配置可执行；要判断内部实际精度，需要结合 HTP OpDef、backend profiling/log 和最终误差。⚠️

5.7 输出怎么看

输出示例如下：

QNN MatMul Precision Benchmark
backend_kind : NPU
backend_path : ./libQnnHtp.so
htp_soc_model: 69
htp_arch     : 79
shape        : A[64, 128] x B[128, 128] -> C[64, 128]
warmup       : 1
iterations   : 3

Results
precision status              init(ms)     build(ms)              exec(ms)     release(ms)     total(ms)     max_abs_err    mean_abs_err
----------------------------------------------------------------------------------------------------------------------------------------
int8      OK                  205.5645        9.0797        0.7750±0.0580         22.4316      242.4618          0.0271          0.0080
int16     OK                   35.2989       30.6419        0.8010±0.1014         20.8287       94.3954          0.0042          0.0017
fp16      OK                   28.1247       29.3391        0.7863±0.0760         21.3840       86.8039          0.0017          0.0004
fp32      OK                  175.9133       10.8606        0.7313±0.0520         22.8998      214.1842          0.0017          0.0004

GPU Results
precision status              init(ms)     build(ms)              exec(ms)     release(ms)     total(ms)     max_abs_err    mean_abs_err
----------------------------------------------------------------------------------------------------------------------------------------
fp16      OK                    5.7818      340.2971        0.2037±0.0488          2.9731      350.4211          0.0017          0.0004
fp32      OK                    6.0046      332.3594        0.3467±0.2124          2.9880      343.1908          0.0000          0.0000
CPU Results
precision status              init(ms)     build(ms)              exec(ms)     release(ms)     total(ms)     max_abs_err    mean_abs_err
----------------------------------------------------------------------------------------------------------------------------------------
int8      OK                   15.4623        0.2046        0.0167±0.0081          0.5728       17.1529          0.0398          0.0115
fp32      OK                   12.4459        0.2005        0.9967±0.0615          0.2930       17.3047          0.0000          0.0000

各列的含义如下：

init/build/release/total (ms)：初始化、建图、资源释放和总耗时
exec(ms)：多轮 QnnGraph_execute() 的平均值和标准差，格式是 mean±std
max_abs_err：输出和 float 参考值的最大绝对误差
mean_abs_err：输出和 float 参考值的平均绝对误差

QNN 介绍

Wed, 01 Apr 2026 15:00:00 +0800

QNN 介绍与 API 执行流程

1. QNN 是什么

QNN SDK 是 Qualcomm 官方提供的多设备推理开发套件，支持 Android 和 Linux 端的 CPU、GPU、HTP 等后端。如图 1 所示，它在应用和具体硬件之间提供了一层统一抽象，让上层尽量使用同一套接口。

图 1. QNN 软件架构示意。

可以把 QNN 理解成两层：

上层是一套统一的 C API。
下层是不同硬件后端的实现，最常见的是 CPU、GPU 和 HTP。

QNN 想做的是把“计算描述”和“硬件执行”拆开。应用层尽量复用同一套接口，而底层切换后端时，主要差异体现在：

加载的后端动态库不同。
计算图是否能被编译到目标硬件不同。
张量的数据类型、量化参数和内存描述要求不同。

下面列出部分支持的高通平台，详细列表可以参考官方文档。

表 1. 部分支持的 Snapdragon 平台

Snapdragon Device/Chip	Supported Toolchains	SOC Model	Hexagon Arch	LPAI Arch
SD 8 Elite Gen 5 (SM8850)	`aarch64-android`	87	V81	v6
SD 8 Elite (SM8750)	`aarch64-android`	69	V79	v5
SD 8 Gen 3 (SM8650)	`aarch64-android`	57	V75	–

2. 关键组件

QNN 文档把 API 组件分成了 Core、Utility、System 三类。
如图 2 所示，Core 负责执行主链，Utility 负责性能分析和日志，System 负责运行时配套能力。

图 2. QNN API 组件分类。

2.1 Core 组件

QnnBackend 顶层 QNN API 组件之一。大多数 QNN API 都要求先初始化后端；同时也提供 OpPackage 注册相关能力。
QnnDevice 顶层 QNN API 组件之一，用来描述设备和多核资源。一个平台可能包含多个设备，每个设备又可能包含多个核心；同时还提供性能控制能力。
QnnContext 为计算图和执行操作提供执行环境。计算图以及跨图共享的张量都创建在同一个上下文中；上下文还可以被缓存成二进制形式，供后续更快加载。
QnnGraph 提供可组合的计算图 API。计算图创建在上下文内部，由节点和张量组成；调用 finalize 之后才进入可执行状态。
QnnGlobalConfig 用于设置全局配置参数。
QnnTensor 用来表示静态常量数据，或者输入输出激活数据。张量可以具有 Context 作用域，也可以具有 Graph 作用域；同一个上下文下的多个计算图可以共享 Context 作用域张量。
QnnOpPackage 提供后端使用已注册算子包库的接口，这部分也对应自定义算子的扩展能力。

2.2 Utility 组件

QnnProfile 提供性能分析能力，用来评估计算图和操作的性能，包括时间和内存。
QnnLog 提供日志输出能力，QnnBackend 和 QnnOpPackage 都可以使用，并且它可以早于 QnnBackend 初始化。

2.3 System 组件

QnnProperty 提供能力查询接口，客户端可以在不初始化 QnnBackend 的情况下直接查询后端能力。
QnnMem 用来把外部分配的内存注册到后端。
QnnSignal 提供信号对象管理能力，用来控制其他组件的执行。

3. 执行路径

QNN 常见执行路径可以分成两类：

在线构图执行
离线缓存执行

3.1 在线构图执行

在线构图执行流程如图 3 所示。

图 3. QNN 在线构图执行流程。

3.1.1 初始化与算子包注册

运行 QNN 时，一般先创建 QnnBackend。
如果需要日志能力，可以更早初始化 QnnLog；如果需要自定义算子，则在后端创建之后注册 QnnOpPackage；随后创建 QnnContext。

3.1.2 构图与定型

在 QnnContext 中，通过 QnnGraph_create() 创建一张空计算图，随后逐步往图中添加张量和节点，最终形成完整计算图。
图构建完成之后，再调用 QnnGraph_finalize() 完成图定型，并触发后续的图优化和编译工作。

QNN 对张量类型做了明确区分：

图输入张量：QNN_TENSOR_TYPE_APP_WRITE
图输出张量：QNN_TENSOR_TYPE_APP_READ
图内部中间张量：QNN_TENSOR_TYPE_NATIVE
静态常量张量：QNN_TENSOR_TYPE_STATIC
用来连接多个计算图的上下文张量：QNN_TENSOR_TYPE_APP_READWRITE

这里有几个特别重要的约束：

张量名字在同一个上下文内必须唯一，重名属于未定义行为。
QNN 没有提供删除已注册节点或张量的 API。
往图里添加节点时，顺序应该遵守依赖顺序。

3.1.3 图执行

计算图构建完成之后，应用就可以开始执行。QNN 提供两类执行接口：

同步执行：QnnGraph_execute()
异步执行：QnnGraph_executeAsync()

异步接口会额外带上一组通知参数，用来在执行结束时通知应用。

3.1.4 资源释放

执行完成之后，应用可以通过 QnnContext_free() 销毁自己创建的上下文。
上下文被释放时，它持有的计算图也会一起销毁。

之后，再通过 QnnBackend_free() 释放后端句柄。
这一步会让整个后端相关的资源和句柄失效。

3.2 离线缓存执行

3.2.1 上下文缓存

QNN 允许应用把已经构好的计算图和上下文缓存成二进制形式，供后续复用。

图 4. QNN 上下文缓存流程。

在建图完成之后，可以通过 QnnContext_getBinary() 获取上下文的二进制形式；如果需要预估缓存大小，则可以先调用 QnnContext_getBinarySize()。
把这份二进制数据保存下来，就完成了上下文缓存。

3.2.2 缓存加载与执行

QNN 也可以直接跳过建图部分，加载前面生成好的上下文二进制数据，然后直接进入执行阶段，如图 5 所示。

图 5. QNN 缓存加载执行流程。

这条路径里最关键的几个接口是：

QnnContext_createFromBinary()：从缓存二进制恢复上下文。
QnnGraph_retrieve()：从上下文中取回已经完成定型的计算图。
QnnSystemContext_getBinaryInfo()：读取上下文二进制中的图和张量元信息。

这里还有一个容易漏掉的点：

自定义 OpPackage 不会随着上下文一起缓存。
加载缓存执行时，仍然需要手动调用 QnnBackend_registerOpPackage() 重新注册。

Qnn on huluhuluu

LLM QNN 插件推理流程

LLM QNN 插件推理流程

1. config_qnn.json 配置

2. LLM 生成链路

3. prefill / decode 形状

4. 算子前向

5. resize 阶段

5.1 ShapePlugin

5.2 创建 QNN 算子

5.3 加载 QNN 图

5.4 PluginExecuteRaw::resize()

6. execute 阶段

6.1 重新确认 shapeIndex

6.2 准备输入输出 Tensor

6.3 拷贝输入、执行 QNN、拷回输出

6.4 invokModel()执行入口

6.5 graphExecute() 执行点

7. 小结

LLM QNN 离线导出流程

LLM QNN 离线导出流程

1. 入口参数

2. Step1：生成 IO 样本

3. Step2：切图

3.1 QNN 离线模式

3.2 读取 testdir

3.3 生成候选子图列表

3.3.1 反向收集 op

3.3.2 按 break op 切图

3.3.3 补切动态 shape

3.3.4 计算子图边界

3.4 过滤非卷积子图

3.5 收集子图 IO

3.6 编译并替换 Plugin

3.7 onForward 生成 graph 材料

3.8 合并多 shape

3.9 产物

4. npu_postreat.json 的作用

5. Step3：生成 context binary

5.1 读取后处理配置

5.2 写 QNN context 配置

5.3 生成每个 graph 的 model library

5.4 合成 context binary

5.5 运行时使用 binary

6. Step4：移动产物并写 config_qnn.json

7. 最终目录结构

以 llm_demo 为例的 QNN 后端运行

QNN 后端运行

1. 环境

2. 交叉编译

2.1 交叉编译 llm_demo

2.2 导出 QNN 模型

3. 推送并运行

3.1 推送编译产物、模型和 QNN 依赖

3.2 运行

QNN HTP OpPackage Softmax 源码分析

QNN HTP OpPackage Softmax 源码分析

1. 源码分析

1.1 头文件

1.2 算子定义

1.2.1 算子定义

1.2.2 函数声明

1.2.3 注册 Softmax 算子

1.2.4 Tensor 属性

1.2.5 注册 Softmax_fp 算子

1.3 算子优化

1.3.1 float32 -> fp16

1.3.2 折叠前置乘法

1.3.3 默认参数规整

1.3.4 softmax_hf_approx() 总览

1.4 伪代码

1.4.1 softmax_fp_impl() 伪代码

1.4.2 softmax_hf_approx() 总体伪代码

1.4.3 approx_exp2() 伪代码

1.5 算子实现

1.5.1 exp 近似

1.5.2 找最大值

1.5.3. 计算未归一化 exp

1.5.4 sum 并归一化

1.5.5 softmax_fp_impl()

1. `config_qnn.json` 配置

3. `prefill` / `decode` 形状

5. `resize` 阶段

5.1 `ShapePlugin`

5.2 创建 `QNN` 算子

5.3 加载 `QNN` 图

5.4 `PluginExecuteRaw::resize()`

6. `execute` 阶段

6.1 重新确认 `shapeIndex`

6.2 准备输入输出 `Tensor`

6.3 拷贝输入、执行 `QNN`、拷回输出

6.4 `invokModel()`执行入口

6.5 `graphExecute()` 执行点

2.1 交叉编译 `llm_demo`

1.3.4 `softmax_hf_approx()` 总览

1.4.1 `softmax_fp_impl()` 伪代码

1.4.2 `softmax_hf_approx()` 总体伪代码

1.4.3 `approx_exp2()` 伪代码

1.5.5 `softmax_fp_impl()`

2. `Q6_Vqf32_vmpy_Vqf32Vqf32` 等类型

5. `benchmark`