1. RKLLM簡介

1.1 RKLLM工具鏈介紹

1.1.1 RKLLM-Toolkit功能介紹

RKLLM-Toolkit 是為用戶提供在計算機上進行大語言模型的量化、轉換的開發套件。通過該 工具提供的 Python 接口可以便捷地完成以下功能：

（1）模型轉換：支持將 Hugging Face 和 GGUF 格式的大語言模型（Large Language Model, LLM） 轉換為 RKLLM 模型，目前支持的模型包括 LLaMA, Qwen, Qwen2, Phi-2, Phi-3, ChatGLM3, Gemma, Gemma2, InternLM2, MiniCPM 和 MiniCPM3，轉換后的 RKLLM 模型能夠在 Rockchip NPU 平臺上加載使用。

（2）量化功能：支持將浮點模型量化為定點模型，目前支持的量化類型包括 w4a16 、wa4a16分組量化(支持的分組數為32,64,128)、w8a8、w8a8分組量化(支持的分組數為128,256,512)。

1.1.2 RKLLM Runtime功能介紹

RKLLM Runtime 主 要 負 責 加 載 RKLLM-Toolkit 轉換得到的 RKLLM 模型，并在RK3576/RK3588 板端通過調用 NPU 驅動在 Rockchip NPU 上實現 RKLLM 模型的推理。在推理 RKLLM 模型時，用戶可以自行定義 RKLLM 模型的推理參數設置，定義不同的文本生成方式， 并通過預先定義的回調函數不斷獲得模型的推理結果。

1.2 RKLLM開發流程介紹

(1）模型轉換：

在這一階段，用戶提供的 Hugging Face 格式的大語言模型將會被轉換為 RKLLM 格式，以便在 Rockchip NPU 平臺上進行高效的推理。這一步驟包括：

獲取原始模型：1、開源的 Hugging Face 格式的大語言模型；2、自行訓練得到的大語 言模型，要求模型保存的結構與 Hugging Face 平臺上的模型結構一致；3、GGUF 模型，目前 僅支持 q4_0 和 fp16 類型模型；

模型加載：通過 rkllm.load_huggingface()函數加載 huggingface 格式模型，通過rkllm.load_gguf()函數加載 GGUF 模型；

模型量化配置：通過 rkllm.build() 函數構建 RKLLM 模型，在構建過程中可選擇是否進行模型量化來提高模型部署在硬件上的性能，以及選擇不同的優化等級和量化類型。

模型導出：通過 rkllm.export_rkllm() 函數將 RKLLM 模型導出為一個.rkllm 格式文件， 用于后續的部署。

(2）板端部署運行：

這個階段涵蓋了模型的實際部署和運行。它通常包括以下步驟：

模型初始化：加載 RKLLM 模型到 Rockchip NPU 平臺，進行相應的模型參數設置來定義所需的文本生成方式，并提前定義用于接受實時推理結果的回調函數，進行推理前準備。

模型推理：執行推理操作，將輸入數據傳遞給模型并運行模型推理，用戶可以通過預先定義的回調函數不斷獲取推理結果。

模型釋放：在完成推理流程后，釋放模型資源，以便其他任務繼續使用 NPU 的計算資源。以上這兩個步驟構成了完整的 RKLLM 開發流程，確保大語言模型能夠成功轉換、調試，并 最終在 Rockchip NPU 上實現高效部署。

1.3 資料下載

模型文件、模型轉換與部署代碼的百度網盤下載鏈接(比較大，可以選擇來下載):https://pan.baidu.com/s/13CHxaF-Cyp4tYxXpksD8LA?pwd=1234 （提取碼：1234 ）

1.4 開發環境搭建

1.4.1 RKLLM-Toolkit安裝

本節主要說明如何通過 pip 方式來安裝 RKLLM-Toolkit，用戶可以參考以下的具體流程說明完成 RKLLM-Toolkit 工具鏈的安裝。

工具安裝包鏈接: https://pan.baidu.com/s/1y5ZN5sl4e3HJI5d9Imt4pg?pwd=1234（提取碼: 1234）。

1.4.1.1 安裝miniforge3工具

為防止系統對多個不同版本的 Python 環境的需求，建議使用 miniforge3 管理 Python 環境。 檢查是否安裝 miniforge3 和 conda 版本信息，若已安裝則可省略此小節步驟。

下載 miniforge3 安裝包：

wget -c https://mirrors.bfsu.edu.cn/github-release/conda-forge/miniforge/LatestRelease/Miniforge3-Linux-x86_64.sh

安裝miniforge3:

chmod 777 Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh

1.4.1.2 創建 RKLLM-Toolkit Conda 環境

進入 Conda base 環境:

source ~/miniforge3/bin/activate

創建一個 Python3.8 版本（建議版本）名為 RKLLM-Toolkit 的 Conda 環境:

conda create -n RKLLM-Toolkit python=3.8

進入 RKLLM-Toolkit Conda 環境:

conda activate RKLLM-Toolkit

1.4.1.3 安裝RKLLM-Toolkit

在 RKLLM-Toolkit Conda 環境下使用 pip 工具直接安裝所提供的工具鏈 whl 包，在安裝過程 中，安裝工具會自動下載 RKLLM-Toolkit 工具所需要的相關依賴包。

pip3 install nvidia_cublas_cu12-12.1.3.1-py3-none-manylinux1_x86_64.whl
pip3 install torch-2.1.0-cp38-cp38-manylinux1_x86_64.whl
pip3 install rkllm_toolkit-1.1.4-cp38-cp38-linux_x86_64.whl

若在安裝的過程中，某些文件安裝很慢，可以登錄python官網單獨下載:

https://pypi.org/

執行以下命令沒有報錯，則安裝成功。

1.5 AI模型轉換

本章主要說明如何實現Hugging Face格式的大語言模型（Large Language Model, LLM）

如何轉換為RKLLM模型，目前支持的模型包括 LLaMA, Qwen, Qwen2, Phi-2, Phi-3, ChatGLM3, Gemma, InternLM2 和 MiniCPM。

1.5.1 模型下載

本節提供兩種大模型文件，Hugging face的原始模型和轉換完成的NPU模型。

下載鏈接: https://pan.baidu.com/s/14BDYQBOMTTK7jtsSa8evHw?pwd=1234 （提取碼: 1234）。

1.5.2 模型轉換

下載完成后模型和腳本放到同一個目錄:

在RKLLM-Toolkit環境，執行以下指令進行模型轉換:

至此模型轉換成功,生成Qwen.rkllm NPU化的大模型文件：

test.py轉換腳本如下所示, 用于轉換Qwen-1_8B-Chat模型:

from rkllm.api import RKLLM
from datasets import load_dataset
from transformers import AutoTokenizer
from tqdm import tqdm
import torch
from torch import nn
import os
# os.environ['CUDA_VISIBLE_DEVICES']='1'

'''
https://huggingface.co/Qwen/Qwen-1_8B-Chat
從上面網址中下載Qwen模型
'''

modelpath = '/home/developer/RKLLM-Toolkit/Qwen-1_8B-Chat'
# modelpath = "./path/to/Qwen-1.8B-F16.gguf"
llm = RKLLM()

# Load model
# Use 'export CUDA_VISIBLE_DEVICES=2' to specify GPU device
# options ['cpu', 'cuda']
ret = llm.load_huggingface(model=modelpath, model_lora = None, device='cpu')
# ret = llm.load_gguf(model = modelpath)
if ret != 0:
    print('Load model failed!')
    exit(ret)

# Build model
dataset = "./data_quant.json"
# Json file format, please note to add prompt in the input，like this:
# [{"input":"Human: 你好！nAssistant: ", "target": "你好！我是人工智能助手KK！"},...]

qparams = None
# qparams = 'gdq.qparams' # Use extra_qparams
ret = llm.build(do_quantization=True, optimization_level=1, quantized_dtype='w4a16',
                quantized_algorithm='normal', target_platform='rk3576', num_npu_core=2, extra_qparams=qparams, dataset=None)

if ret != 0:
    print('Build model failed!')
    exit(ret)

# Evaluate Accuracy
def eval_wikitext(llm):
    seqlen = 512
    tokenizer = AutoTokenizer.from_pretrained(
        modelpath, trust_remote_code=True)
    # Dataset download link:
    # https://huggingface.co/datasets/Salesforce/wikitext/tree/main/wikitext-2-raw-v1
    testenc = load_dataset(
        "parquet", data_files='./wikitext/wikitext-2-raw-1/test-00000-of-00001.parquet', split='train')
    testenc = tokenizer("nn".join(
        testenc['text']), return_tensors="pt").input_ids
    nsamples = testenc.numel() // seqlen
    nlls = []
    for i in tqdm(range(nsamples), desc="eval_wikitext: "):
        batch = testenc[:, (i * seqlen): ((i + 1) * seqlen)]
        inputs = {"input_ids": batch}
        lm_logits = llm.get_logits(inputs)
        if lm_logits is None:
            print("get logits failed!")
            return
        shift_logits = lm_logits[:, :-1, :]
        shift_labels = batch[:, 1:].to(lm_logits.device)
        loss_fct = nn.CrossEntropyLoss().to(lm_logits.device)
        loss = loss_fct(
            shift_logits.view(-1, shift_logits.size(-1)), shift_labels.view(-1))
        neg_log_likelihood = loss.float() * seqlen
        nlls.append(neg_log_likelihood)
    ppl = torch.exp(torch.stack(nlls).sum() / (nsamples * seqlen))
    print(f'wikitext-2-raw-1-test ppl: {round(ppl.item(), 2)}')

# eval_wikitext(llm)


# Chat with model
messages = "<|im_start|?>system You are a helpful assistant.<|im_end|?><|im_start|?>user你好！n<|im_end|?><|im_start|?>assistant"
kwargs = {"max_length": 128, "top_k": 1, "top_p": 0.8,
          "temperature": 0.8, "do_sample": True, "repetition_penalty": 1.1}
# print(llm.chat_model(messages, kwargs))


# Export rkllm model
ret = llm.export_rkllm("./Qwen_w4a16.rkllm")
if ret != 0:
    print('Export model failed!')
    exit(ret)

1.6 模型轉換API說明

1.6.1 RKLLM 初始化

在這一部分，用戶需要先初始化 RKLLM 對象，這是整個工作流的第一步。在示例代碼中使用 RKLLM()構造函數來初始化 RKLLM 對象：

rkllm = RKLLM()

1.6.2 模型加載

在 RKLLM 初始化完成后，用戶需要調用 rkllm.load_huggingface()函數來傳入模型的具體路徑，RKLLM-Toolkit 即可根據對應路徑順利加載 Hugging Face 或 GGUF 格式的大語言模型，從而順利完成后續的轉換、量化操作，具體的函數定義如下：

表 1 load_huggingface 函數接口說明

示例代碼如下：

ret = rkllm.load_huggingface(
   model = './huggingface_model_dir', 
   model_lora = './huggingface_lora_model_dir'
   )
if ret != 0:
   print('Load model failed!')

表 2 load_gguf 函數接口說明

示例代碼如下：

ret = rkllm.load_gguf(model = './model-Q4_0.gguf')
if ret != 0:
   print('Load model failed!')

1.6.3 RKLLM 模型的量化構建

用戶在通過 rkllm.load_huggingface()函數完成原始模型的加載后，下一步就是通過 rkllm.build()函數實現對 RKLLM 模型的構建。構建模型時，用戶可以選擇是否進行量化，量化有助于減小模型的大小和提高在 Rockchip NPU 上的推理性能。rkllm.build()函數的具體定義如下：

表 3 build 函數接口說明

示例代碼如下：

ret = rkllm.build(
       do_quantization=True,
       optimization_level=1,
       quantized_dtype='w8a8',
       quantized_algorithm="normal",
       num_npu_core=3,
       extra_qparams=None,
       dataset="quant_data.json",
       hybrid_rate=0,
       target_platform='rk3588')
if ret != 0:
   print('Build model failed!')

1.6.4 導出 RKLLM 模型

用戶在通過 rkllm.build()函數構建了 RKLLM 模型后，可以通過 rkllm.export_rkllm()函數將RKNN 模型保存為一個.rkllm 文件，以便后續模型的部署。rkllm.export_rkllm()函數的具體參數定義如下：

表 4 export_rkllm 函數接口說明

示例代碼如下：

ret = rkllm.export_rkllm(export_path = './model.rkllm'）
if ret != 0:
   print('Export model failed!')

1.6.5 仿真精度評估

用戶在通過 rkllm.build()函數構建了 RKLLM 模型后，可以通過 rkllm.get_logits()函數在 PC端進行仿真精度評估，rkllm.get_logits()函數的具體參數定義如下：

使用此函數進行 wikitext 數據集 ppl 測試示例代碼如下：

ef eval_wikitext(llm):
  seqlen = 512
  tokenizer = AutoTokenizer.from_pretrained(
     modelpath,
     trust_remote_code=True
     )
  #Dataset download link: 
  #https://huggingface.co/datasets/Salesforce/wikitext/tree/main/wiki
text-2-raw-v1
   testenc = load_dataset("parquet", data_files='./wikitext/wikitext-
2-raw-1/test-00000-of-00001.parquet', split='train')
   testenc = tokenizer(
      "nn".join(testenc['text']), 
      return_tensors="pt").input_ids
 nsamples = testenc.numel() // seqlen
 nlls = []
 for i in tqdm(range(nsamples), desc="eval_wikitext: "):
    batch = testenc[:, (i * seqlen): ((i + 1) * seqlen)]
    inputs = {"input_ids": batch}
    lm_logits = llm.get_logits(inputs)
    if lm_logits is None:
       print("get logits failed!")
       return 
    shift_logits = lm_logits[:, :-1, :]
    shift_labels = batch[:, 1:].to(lm_logits.device)
    loss_fct = nn.CrossEntropyLoss().to(lm_logits.device)
    loss = loss_fct(shift_logits.view(-1, shift_logits.size(-1)), 
shift_labels.view(-1))
    neg_log_likelihood = loss.float() * seqlen
    nlls.append(neg_log_likelihood)
   ppl = torch.exp(torch.stack(nlls).sum() / (nsamples * seqlen))
   print(f'wikitext-2-raw-1-test ppl: {round(ppl.item(), 2)}')

1.6.6 仿真模型推理

用戶在通過 rkllm.build()函數構建了 RKLLM 模型后，可以通過 rkllm.chat_model()函數在 PC端進行仿真推理，rkllm.chat_model()函數的具體參數定義如下：

示例代碼如下：

args ={
   "max_length":128,
   "top_k":1,
   "temperature":0.8,
   "do_sample":True,
   "repetition_penalty":1.1
   }
mesg = "Human: 今天天氣怎么樣？nAssistant:"
print(llm.chat_model(mesg, args))

以上的這些操作涵蓋了 RKLLM-Toolkit 模型轉換、量化的全部步驟，根據不同的需求和應用場景，用戶可以選擇不同的配置選項和量化方式進行自定義設置，方便后續進行部署。

1.7 AI模型部署

本章主要說明RKLLM格式的通義千問NPU大模型如何運行在EASY-EAI-Orin-Nano硬件上。

1.7.1 快速上手

1.7.1.1 源碼下載以及例程編譯

本節提供轉換成功的通義千問大模型文Qwen_w4a16.rkllm及對應的C/C++程序部署代碼。

下載鏈接:https://pan.baidu.com/s/19GZ_UjsA-IjA9zf10ZZ93w?pwd=1234（提取碼: 1234）。

然后把例程【復制粘貼】到nfs掛載目錄中。（不清楚目錄如何構建的，可以參考《入門指南/開發環境準備/nfs服務搭建與掛載》）。特別注意:源碼目錄和模型最好cp到板子上，如/userdata，否則在nfs目錄執行大模型會導致模型初始化過慢。

進入到開發板對應的例程目錄執行編譯操作，具體命令如下所示：

cd /userdata/rkllm-demo
./build.sh

1.7.1.2 例程運行及效果

進入例程的rkllm-demo/rkllm-demo_release目錄，執行下方命令，運行示例程序：

cd rkllm-demo_release/
ulimit -HSn 102400 
./rkllm-demo Qwen_w4a16.rkllm 256 512

至此可以進行對話測試了，試著輸入“如何制作PCB板？”。回答如下所示:

1.7.2 RKLLM算法例程

例程目錄為rkllm-demo/src/main.cpp，操作流程如下。

具體代碼如下所示:

#include 
#include 
#include 
#include "rkllm.h"
#include 
#include 
#include 
#include 

#define PROMPT_TEXT_PREFIX "<|im_start|?>system You are a helpful assistant. <|im_end|?> <|im_start|?>user"
#define PROMPT_TEXT_POSTFIX "<|im_end|?><|im_start|?>assistant"


using namespace std;
LLMHandle llmHandle = nullptr;

void exit_handler(int signal)
{
    if (llmHandle != nullptr)
    {
        {
            cout last_hidden_layer.embd_size != 0 && result->last_hidden_layer.num_tokens != 0) {
            int data_size = result->last_hidden_layer.embd_size * result->last_hidden_layer.num_tokens * sizeof(float);
            printf("ndata_size:%d",data_size);
            std::ofstream outFile("last_hidden_layer.bin", std::ios::binary);
            if (outFile.is_open()) {
                outFile.write(reinterpret_cast(result->last_hidden_layer.hidden_states), data_size);
                outFile.close();
                std::cout text);
    }
}

int main(int argc, char **argv)
{
    if (argc < 4) {
        std::cerr  pre_input;
    pre_input.push_back("把下面的現代文翻譯成文言文: 到了春風和煦，陽光明媚的時候，湖面平靜，沒有驚濤駭浪，天色湖光相連，一片碧綠，廣闊無際；沙洲上的鷗鳥，時而飛翔，時而停歇，美麗的魚游來游去，岸上與小洲上的花草，青翠欲滴。");
    pre_input.push_back("以詠梅為題目，幫我寫一首古詩，要求包含梅花、白雪等元素。");
    pre_input.push_back("上聯: 江邊慣看千帆過");
    pre_input.push_back("把這句話翻譯成中文: Knowledge can be acquired from many sources. These include books, teachers and practical experience, and each has its own advantages. The knowledge we gain from books and formal education enables us to learn about things that we have no opportunity to experience in daily life. We can also develop our analytical skills and learn how to view and interpret the world around us in different ways. Furthermore, we can learn from the past by reading books. In this way, we won't repeat the mistakes of others and can build on their achievements.");
    pre_input.push_back("把這句話翻譯成英文: RK3588是新一代高端處理器，具有高算力、低功耗、超強多媒體、豐富數據接口等特點");
    cout 

	

	1.8 模型部署API說明

	1.8.1 回調函數定義

	回調函數是用于接收模型實時輸出的結果。在初始化 RKLLM 時回調函數會被綁定，在模型推理過程中不斷將結果輸出至回調函數中，并且每次回調只返回一個 token。

	示例代碼如下，該回調函數將輸出結果實時地打印輸出到終端中：

	
void callback(RKLLMResult* result, void* userdata, LLMCallState state)
{
   if(state == LLM_RUN_NORMAL){
      printf("%s", result->text);
      for (int i=0; inum; i++) {
          printf("token_id: %d logprob: %f", result->tokens[i].id, 
          result->tokens[i].logprob);
      }
   }
   if (state == LLM_RUN_FINISH) {
      printf("finishn");
   } else if (state == LLM_RUN_ERROR){
      printf("run errorn");
   }
}

	

	(1）LLMCallState 是一個狀態標志，其具體定義如下：

	表 1 LLMCallState 狀態標志說明

				枚舉定義
			

				LLMCallState
		

				描述
			

				用于表示當前 RKLLM 的運行狀態。
		

				枚舉值
			

				0, LLM_RUN_NORMAL, 表示 RKLLM 模型當前正在推理中；

				1, LLM_RUN_FINISH, 表示 RKLLM 模型已完成當前輸入的全部推理；

				2, LLM_RUN_WAITING, 表示當前 RKLLM 解碼出的字符不是完整 UTF8 編碼，需等待與下一次解碼拼接；

				3, LLM_RUN_ERROR, 表示 RKLLM 模型推理出現錯誤；
		

	用戶在回調函數的設計過程中，可以根據 LLMCallState 的不同狀態設置不同的后處理行為；

	(2）RKLLMResult 是返回值結構體，其具體定義如下：

	表 2 RKLLMResult 返回值結構體說明

				結構體定義
			

				RKLLMResult
		

				描述
			

				用于返回當前推理生成結果。
		

				字段
			

				0, text, 表示當前推理生成的文本內容；

				1, token_id, 表示當前推理生成的 token id；
		

	1.8.2 參數結構體 RKLLMParam 定義

	結構體 RKLLMParam 用于描述、定義 RKLLM 的詳細信息，具體的定義如下：

	表 2 RKLLMParam 結構體參數說明

				結構體定義
			

				RKLLMParam
		

				描述
			

				用于定義 RKLLM 模型的各項細節參數。
		

				字段
			

				const char* model_path: 模型文件的存放路徑；

				int32_t max_context_len: 設置推理時的最大上下文長度；

				int32_t max_new_tokens: 用于設置模型推理時生成 token 的數量上限；

				int32_t top_k: top-k 采樣是一種文本生成方法，它僅從模型預測概率最高的 k個 token 中選擇下一個 token。該方法有助于降低生成低概率或無意義 token 的風險。更高的值（如 100）將考慮更多的 token 選擇，導致文本更加多樣化；而更低的值（如 10）將聚焦于最可能的 token，生成更加保守的文本。默認值為40；

				float top_p: top-p 采樣，也被稱為核心采樣，是另一種文本生成方法，從累計概率至少為 p 的一組 token 中選擇下一個 token。這種方法通過考慮 token 的概率和采樣的 token 數量在多樣性和質量之間提供平衡。更高的值（如 0.95）使得生成的文本更加多樣化；而更低的值（如 0.5）將生成更加保守的文本。默認值為 0.9；

				float temperature: 控制生成文本隨機性的超參數，它通過調整模型輸出token的概率分布來發揮作用；更高的溫度（如 1.5）會使輸出更加隨機和創造性，當溫度較高時，模型在選擇下一個 token 時會考慮更多可能性較低的選項，從而產生更多樣和意想不到的輸出；更低的溫度（例 0.5）會使輸出更加集中、保守，較低的溫度意味著模型在生成文本時更傾向于選擇概率高的 token，從而導致更一致、更可預測的輸出；溫度為 0 的極端情況下，模型總是選擇最有可能的下一個 token，這會導致每次運行時輸出完全相同；為了確保隨機性和確定性之間的平衡，使輸出既不過于單一和可預測，也不過于隨機和雜亂，默認值為 0.8；

				float repeat_penalty: 控制生成文本中 token 序列重復的情況，幫助防止模型生成重復或單調的文本。更高的值（例如 1.5）將更強烈地懲罰重復，而較低的值（例如 0.9）則更為寬容。默認值為 1.1；

				float frequency_penalty: 單詞/短語重復度懲罰因子，減少總體上使用頻率較高的單詞/短語的概率，增加使用頻率較低的單詞/短語的可能性，這可能會使生成的文本更加多樣化，但也可能導致生成的文本難以理解或不符合預期。設置范圍為[-2.0, 2.0]，默認為 0；

				int32_t mirostat: 在文本生成過程中主動維持生成文本的質量在期望的范圍內的算法，它旨在在連貫性和多樣性之間找到平衡，避免因過度重復（無聊陷阱）或不連貫（混亂陷阱）導致的低質量輸出；取值空間為{0, 1, 2}, 0 表示不啟動該算法，1 表示使用 mirostat 算法，2 則表示使用 mirostat2.0 算法；

				float mirostat_tau: 選項設置 mirostat 的目標熵，代表生成文本的期望困惑度。調整目標熵可以控制生成文本中連貫性與多樣性的平衡。較低的值將導致文本更加集中和連貫，而較高的值將導致文本更加多樣化，可能連貫性較差。默認值是 5.0；

				float mirostat_eta: 選項設置 mirostat 的學習率，學習率影響算法對生成文本反饋的響應速度。較低的學習率將導致調整速度較慢，而較高的學習率將使算法更加靈敏。默認值是 0.1；

				bool skip_special_token: 是否跳過特殊 token 不輸出,例如結束符號等;

				bool is_async: 是否使用異步模式;

				const char* img_start: 選項設置多模態輸入圖像編碼的起始標志符，在多模態輸入模式下需要配置；

				const char* img_end: 選項設置多模態輸入圖像編碼的終止標志符，在多模態輸入模式下需要配置；

				const char* img_content: 選項設置多模態輸入圖像編碼的內容標志符，在多模態輸入模式下需要配置；
		

	在實際的代碼構建中，RKLLMParam 需要調用 rkllm_createDefaultParam()函數來初始化定義，并根據需求設置相應的模型參數。示例代碼如下：

	
RKLLMParam param = rkllm_createDefaultParam();
param.model_path = "model.rkllm";
param.top_k = 1;
param.max_new_tokens = 256;
param.max_context_len = 512;

	

	1.8.3 輸入結構體定義

	為適應不同的輸入數據，定義了 RKLLMInput 輸入結構體，目前可接受文本、圖片和文本、Token id 以及編碼向量四種形式的輸入，具體的定義如下：

	表 3 RKLLMInput 結構體參數說明

				結構體定義
			

				RKLLMInput
		

				描述
			

				用于接收不同形式的輸入數據。
		

				字段
			

				RKLLMInputType input_type: 輸入模式；

				union: 用于存儲不同的輸入數據類型，具體包含以下幾種形式：

				- const char* prompt_input: 文本提示輸入，用于傳遞自然語言文本；

				- RKLLMEmbedInput embed_input: 嵌入向量輸入，表示已處理的特征向量；

				- RKLLMTokenInput token_input: Token 輸入，用于傳遞 Token 序列；

				- RKLLMMultiModelInput multimodal_input: 多模態輸入，可傳遞多模態數據，如圖片和文本的聯合輸入。
		

	表 4 RKLLMInputType 輸入類型說明

				枚舉定義
			

				RKLLMInputType
		

				描述
			

				用于表示輸入數據類型。
		

				枚舉值
			

				0, RKLLM_INPUT_PROMPT, 表示輸入數據是純文本；

				1, RKLLM_INPUT_TOKEN, 表示輸入數據是 Token id；

				2, RKLLM_INPUT_EMBED, 表示輸入數據是編碼向量；

				3, RKLLM_INPUT_MULTIMODAL, 表示輸入數據是圖片和文本；
		

	當輸入數據是純文本時，使用 input_data 直接輸入；當輸入數據是 Token id、編碼向量以及圖片 和 文 本 時 ， RKLLMInput 需 要 搭 配 RKLLMTokenInput, RKLLMEmbedInput 以 及RKLLMMultiModelInput 三個輸入結構體使用，具體的介紹如下：

	(1）RKLLMTokenInput 是接收 Token id 的輸入結構體，具體的定義如下：

	表 5 RKLLMTokenInput 結構體參數說明

				結構體定義
			

				RKLLMTokenInput
		

				描述
			

				用于接收 Token id 數據。
		

				字段
			

				int32_t* input_ids: 輸入 token ids 的內存指針；

				size_t n_tokens: 輸入數據的 token 數量；
		

	(2）RKLLMEmbedInput 是接收編碼向量的輸入結構體，具體的定義如下：

	表 6 RKLLMEmbedInput 結構體參數說明

				結構體定義
			

				RKLLMEmbedInput
		

				描述
			

				用于接收 Embedding 數據。
		

				字段
			

				float* embed: 輸入 token embedding 的內存指針；

				size_t n_tokens: 輸入數據的 token 數量；
		

	(3）RKLLMMultiModelInput 是接收圖片和文本的輸入結構體，具體的定義如下：

	表 7 RKLLMMultiModelInput 結構體參數說明

				結構體定義
			

				RKLLMMultiModelInput
		

				描述
			

				用于接收圖片和文本多模態數據。
		

				字段
			

				char* prompt: 輸入文本的內存指針；

				float* image_embed: 輸入圖片 embedding 的內存指針；

				size_t n_image_tokens: 輸入圖片 embedding 的 token 數量；
		

	純文本輸入示例代碼如下：

	
// 提前定義 prompt 前后的文本預設值
#define PROMPT_TEXT_PREFIX "<|im_start|?>system You are a helpful 
assistant. <|im_end|?> <|im_start|?>user"
#define PROMPT_TEXT_POSTFIX "<|im_end|?><|im_start|?>assistant"

// 定義輸入的 prompt 并完成前后 prompt 的拼接
string input_str = "把這句話翻譯成英文：RK3588 是新一代高端處理器，具有高算力、
低功耗、超強多媒體、豐富數據接口等特點";
input_str = PROMPT_TEXT_PREFIX + input_str + PROMPT_TEXT_POSTFIX;

RKLLMInput rkllm_input;
rkllm_input.input_data = (char*)input_str.c_str();
rkllm_input.input_type = RKLLM_INPUT_PROMPT;

// 初始化 infer 參數結構體
RKLLMInferParam rkllm_infer_params;
memset(&rkllm_infer_params, 0, sizeof(RKLLMInferParam)); // 將所有內容初
始化為 0
rkllm_infer_params.mode = RKLLM_INFER_GENERATE;

	

	圖片和文本多模態輸入示例代碼如下，注意多模態輸入的 prompt 中需要加入占位符用于標示圖像編碼插入的位置：

	
// 提前定義 prompt 前后的文本預設值
#define PROMPT_TEXT_PREFIX "<|im_start|?>system You are a helpful 
assistant. <|im_end|?> <|im_start|?>user"
#define PROMPT_TEXT_POSTFIX "<|im_end|?><|im_start|?>assistant"

RKLLMInput rkllm_input;

// 定義輸入的 prompt 并完成前后 prompt 的拼接
string input_str = "Please describe the image shortly.";
input_str = PROMPT_TEXT_PREFIX + input_str + PROMPT_TEXT_POSTFIX;
rkllm_input.multimodal_input.prompt = (char*)input_str.c_str();

rkllm_input.multimodal_input.n_image_tokens = 256;
int rkllm_input_len = multimodal_input.n_image_tokens * 3072;
rkllm_input.multimodal_input.image_embed = (float 
*)malloc(rkllm_input_len * sizeof(float));
FILE *file;
file = fopen("models/image_embed.bin", "rb");
fread(rkllm_input.multimodal_input.image_embed, sizeof(float), 
rkllm_input_len, file);
fclose(file);

rkllm_input.input_type = RKLLM_INPUT_MULTIMODAL;

// 初始化 infer 參數結構體
RKLLMInferParam rkllm_infer_params;
memset(&rkllm_infer_params, 0, sizeof(RKLLMInferParam)); // 將所有內容初
始化為 0
rkllm_infer_params.mode = RKLLM_INFER_GENERATE;

	

	RKLLM 支持不同的推理模式，定義了 RKLLMInferParam 結構體，目前可支持在推理過程與預加載的 LoRA 模型聯合推理，或保存 Prompt Cache 用于后續推理加速，具體的定義如下：

	表 8 RKLLMInferParam 結構體參數說明

				結構體定義
			

				RKLLMInferParam
		

				描述
			

				用于定義不同的推理模式。
		

				字段
			

				RKLLMInferMode mode: 推理模式，當前僅支持 RKLLM_INFER_GENERATE 模式；

				RKLLMLoraParam* lora_params: 推理時使用的 LoRA 的參數配置，用于在加載多個 LoRA 時選擇需要推理的 LoRA，若無需加載 LoRA 則設為 NULL 即可；

				RKLLMPromptCacheParam* prompt_cache_params: 推理時使用Prompt Cache的參數配置，若無需生成 Prompt Cache 則設為 NULL 即可；
		

	表 9 RKLLMLoraParam 結構體參數說明

				結構體定義
			

				RKLLMLoraParam
		

				描述
			

				用于定義推理時使用 LoRA 的參數；
		

				字段
			

				const char* lora_adapter_name: 推理時使用的 LoRA 名稱
		

	表 10 RKLLMInferParam 結構體參數說明

				結構體定義
			

				RKLLMPromptCacheParam
		

				描述
			

				用于定義推理時使用 Prompt Cache 的參數；
		

				字段
			

				int save_prompt_cache: 是否在推理時保存 Prompt Cache, 1 為需要, 0 為不需要；

				const char* prompt_cache_path: Prompt Cache 保存路徑, 若未設置則默認保存到"./prompt_cache.bin"中;
		

	使用 InferRaram 的示例如下：

	
// 1. 初始化并設置 LoRA 參數（如果需要使用 LoRA）
RKLLMLoraParam lora_params;
lora_params.lora_adapter_name = "test"; // 指定用于推理的 lora 名稱
// 2. 初始化并設置 Prompt Cache 參數（如果需要使用 prompt cache）
RKLLMPromptCacheParam prompt_cache_params;
prompt_cache_params.save_prompt_cache = true; // 是否保存 prompt cache
prompt_cache_params.prompt_cache_path = "./prompt_cache.bin"; // 若需要
保存 prompt cache, 指定 cache 文件路徑
rkllm_infer_params.mode = RKLLM_INFER_GENERATE;
rkllm_infer_params.lora_params = &lora_params;
rkllm_infer_params.prompt_cache_params = &prompt_cache_params;

	

	1.8.4 初始化模型

	在進行模型的初始化之前，需要提前定義 LLMHandle 句柄，該句柄用于模型的初始化、推理和資源釋放過程。注意，正確的模型推理流程需要統一這 3 個流程中的 LLMHandle 句柄對象。在模型推理前，用戶需要通過 rkllm_init()函數完成模型的初始化，具體函數的定義如下：

	表 11 rkllm_init 函數接口說明

				函數名
			

				rkllm_init
		

				描述
			

				用于初始化 RKLLM 模型的具體參數及相關推理設置。
		

				參數
			

				LLMHandle* handle: 將模型注冊到相應句柄中，用于后續推理、釋放調用；

				RKLLMParam* param: 模型定義的參數結構體；

				LLMResultCallback callback: 用于接受處理模型實時輸出的回調函數；
		

				返回值
			

				0 表示初始化流程正常；-1 表示初始化失敗；
		

	示例代碼如下：

	
LLMHandle llmHandle = nullptr;
rkllm_init(&llmHandle, ?m, callback);

	

	1.8.5 模型推理

	用戶在完成 RKLLM 模型的初始化流程后，即可通過 rkllm_run()函數進行模型推理，并可以通過初始化時預先定義的回調函數對實時推理結果進行處理；rkllm_run()的具體函數定義如下：

	表 12 rkllm_run 函數接口說明

				函數名
			

				rkllm_run
		

				描述
			

				調用完成初始化的 RKLLM 模型進行結果推理；
		

				參數
			

				LLMHandle handle: 模型初始化注冊的目標句柄；

				RKLLMInput* rkllm_input: 模型推理的輸入數據；

				RKLLMInferParam* rkllm_infer_params: 模型推理過程中的參數傳遞；

				void* userdata: 用戶自定義的函數指針，默認設置為 NULL 即可；
		

				返回值
			

				0 表示模型推理正常運行；-1 表示調用模型推理失敗；
		

	模型推理的示例代碼如下：

	
#define PROMPT_TEXT_PREFIX "<|im_start|?>system You are a helpful 
assistant. <|im_end|?> <|im_start|?>user"
#define PROMPT_TEXT_POSTFIX "<|im_end|?><|im_start|?>assistant"

string input_str = "把這句話翻譯成英文：RK3588 是新一代高端處理器，具有高算力、
低功耗、超強多媒體、豐富數據接口等特點";
input_str = PROMPT_TEXT_PREFIX + input_str + PROMPT_TEXT_POSTFIX;

// 初始化 infer 參數結構體
RKLLMInferParam rkllm_infer_params;
memset(&rkllm_infer_params, 0, sizeof(RKLLMInferParam));
rkllm_infer_params.mode = RKLLM_INFER_GENERATE;
// 1. 初始化并設置 LoRA 參數（如果需要使用 LoRA）
RKLLMLoraParam lora_params;
lora_params.lora_adapter_name = "test"; // 指定用于推理的 lora 名稱
// 2. 初始化并設置 Prompt Cache 參數（如果需要使用 prompt cache）
RKLLMPromptCacheParam prompt_cache_params;
prompt_cache_params.save_prompt_cache = true; // 是否保存 prompt cache
prompt_cache_params.prompt_cache_path = "./prompt_cache.bin";

rkllm_infer_params.mode = RKLLM_INFER_GENERATE;
// rkllm_infer_params.lora_params = &lora_params;
// rkllm_infer_params.prompt_cache_params = &prompt_cache_params;
rkllm_infer_params.lora_params = NULL;
rkllm_infer_params.prompt_cache_params = NULL;

RKLLMInput rkllm_input;
rkllm_input.input_type = RKLLM_INPUT_PROMPT;
rkllm_input.prompt_input = (char *)text.c_str();

rkllm_run(llmHandle, &rkllm_input, &rkllm_infer_params, NULL);

	

	1.8.6 模型中斷

	在進行模型推理時，用戶可以調用 rkllm_abort()函數中斷推理進程，具體的函數定義如下：

	表 13 rkllm_ abort 函數接口說明

				函數名
			

				rkllm_ abort
		

				描述
			

				用于中斷 RKLLM 模型推理進程。
		

				參數
			

				LLMHandle handle: 模型初始化注冊的目標句柄；
		

				返回值
			

				0 表示 RKLLM 模型中斷成功；-1 表示模型中斷失敗；
		

	示例代碼如下：

	
// 其中 llmHandle 為模型初始化時傳入的句柄
rkllm_abort(llmHandle);

	

	1.8.7 釋放模型資源

	在完成全部的模型推理調用后，用戶需要調用 rkllm_destroy()函數進行 RKLLM 模型的銷毀，并釋放所申請的 CPU、NPU 計算資源，以供其他進程、模型的調用。具體的函數定義如下：

	表 14 rkllm_ destroy 函數接口說明

				函數名
			

				rkllm_ destroy
		

				描述
			

				用于銷毀 RKLLM 模型并釋放所有計算資源。
		

				參數
			

				LLMHandle handle: 模型初始化注冊的目標句柄；
		

				返回值
			

				0 表示 RKLLM 模型正常銷毀、釋放；-1 表示模型釋放失敗；
		

	示例代碼如下：

	
// 其中 llmHandle 為模型初始化時傳入的句柄
rkllm_destroy(llmHandle);

	

	1.8.8 LoRA 模型加載

	RKLLM 支持在推理基礎模型的同時推理 LoRA 模型，可以在調用 rkllm_run 接口前通過rkllm_load_lora 接口加載 LoRA 模型。RKLLM 支持加載多個 LoRA 模型，每調用一次rkllm_load_lora 可加載一個 LoRA 模型。具體的函數定義如下：

	表 15 rkllm_load_lora 函數接口說明

				函數名
			

				rkllm_load_lora
		

				描述
			

				用于加載 LoRA 模型。
		

				參數
			

				LLMHandle handle: 模型初始化注冊的目標句柄；

				RKLLMLoraAdapter* lora_adapter: 加載 LoRA 模型時的參數配置;
		

				返回值
			

				0 表示 LoRA 模型正常加載；-1 表示模型加載失敗；
		

	表 16 RKLLMLoraAdapter 結構體參數說明

				結構體定義
			

				RKLLMLoraAdapter
		

				描述
			

				用于配置加載 LoRA 時的參數。
		

				字段
			

				const char* lora_adapter_path: 待加載 LoRA 模型的路徑；

				const char* lora_adapter_name: 待加載 LoRA 模型的名稱, 由用戶自定義, 用于后續推理時選擇指定 LoRA;

				float scale: LoRA 模型在推理過程中對基礎模型參數進行調整的幅度;
		

	加載 LoRA 的示例代碼如下：

	
RKLLMLoraAdapter lora_adapter;
memset(&lora_adapter, 0, sizeof(RKLLMLoraAdapter));
lora_adapter.lora_adapter_path = "lora.rkllm";
lora_adapter.lora_adapter_name = "lora_name";
lora_adapter.scale = 1.0;
ret = rkllm_load_lora(llmHandle, &lora_adapter);
if (ret != 0) {
   printf("nload lora failedn");
}

	

	1.8.9 Prompt Cache 加載

	RKLLM 支持加載預生成的 Prompt Cache 文件，以此加速模型 Prefill 階段的推理。具體的函數定義如下：

	表 17 rkllm_load_prompt_cache 函數接口說明

				函數名
			

				rkllm_load_prompt_cache
		

				描述
			

				用于加載 Prompt Cache。
		

				參數
			

				LLMHandle handle: 模型初始化注冊的目標句柄，可見 4. 初始化模型；

				const char* prompt_cache_path: 待加載 Prompt Cache 文件的路徑;
		

				返回值
			

				0 表示 Prompt Cache 模型正常加載；-1 表示模型加載失敗；
		

	表 18 rkllm_release_prompt_cache 函數接口說明

				函數名
			

				rkllm_release_prompt_cache
		

				描述
			

				用于釋放 Prompt Cache。
		

				參數
			

				LLMHandle handle: 模型初始化注冊的目標句柄，可見 4. 初始化模型；
		

				返回值
			

				0 表示 Prompt Cache 模型正常釋放；-1 表示模型釋放失敗；
		

	加載 Prompt Cache 的示例代碼如下：

	
rkllm_load_prompt_cache(llmHandle, "./prompt_cache.bin");
if (ret != 0) {
printf("nload Prompt Cache failedn");
}

審核編輯 黃宇