1. 回調(diào)函數(shù)定義

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

示例代碼如下，該回調(diào)函數(shù)將輸出結(jié)果實時地打印輸出到終端中：

int callback(RKLLMResult* result, void* userdata, LLMCallState state) { if(state == LLM_RUN_NORMAL){ printf("%s", result->text); } if (state == LLM_RUN_FINISH) { printf("finish\n"); } else if (state == LLM_RUN_ERROR){ printf("\run error\n"); } return 0; }

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

用戶在回調(diào)函數(shù)的設(shè)計過程中，可以根據(jù) LLMCallState 的不同狀態(tài)設(shè)置不同的后處理行為。
（2）RKLLMResult 是返回值結(jié)構(gòu)體，其具體定義如下：

（3）RKLLMResultLogits 是返回值結(jié)構(gòu)體，其具體定義如下：

用戶在回調(diào)函數(shù)的設(shè)計過程中，可以根據(jù) RKLLMResult 中值設(shè)置不同的后處理行為。

2. 參數(shù)結(jié)構(gòu)體 RKLLMParam 定義

結(jié)構(gòu)體 RKLLMParam 用于描述、定義 RKLLM 的詳細信息，具體的定義如下：

在實際的代碼構(gòu)建中，RKLLMParam 需要調(diào)用 rkllm_createDefaultParam()函數(shù)來初始化定義，并根據(jù)需求設(shè)置相應(yīng)的模型參數(shù)。示例代碼如下

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

3. 輸入結(jié)構(gòu)體定義

為適應(yīng)不同的輸入數(shù)據(jù)，定義了 RKLLMInput 輸入結(jié)構(gòu)體，目前可接受文本、圖片和文本、Token id 以及編碼向量四種形式的輸入，具體的定義如下：

當輸入數(shù)據(jù)是純文本時，使用 input_data 直接輸入；當輸入數(shù)據(jù)是 Token id、編碼向量以及圖 片和文本時，RKLLMInput 需要搭配RKLLMTokenInput, RKLLMEmbedInput 以及RKLLMMultiModelInput 三個輸入結(jié)構(gòu)體使用，具體的介紹如下：
（1）RKLLMTokenInput 是接收 Token id 的輸入結(jié)構(gòu)體，具體的定義如下：

（2）RKLLMEmbedInput 是接收編碼向量的輸入結(jié)構(gòu)體，具體的定義如下：

（3）RKLLMMultiModelInput 是接收圖片和文本的輸入結(jié)構(gòu)體，具體的定義如下：

RKLLM 支持不同的推理模式，定義了 RKLLMInferParam 結(jié)構(gòu)體，目前可支持在推理過程與預加載的 LoRA 模型聯(lián)合推理，或保存 Prompt Cache 用于后續(xù)推理加速，具體的定義如下：

使用 RKLLMPromptCacheParam 的示例如下：

//初始化并設(shè)置 Prompt Cache 參數(shù)（如果需要使用 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.prompt_cache_params = &prompt_cache_params;

4. 初始化模型

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

示例代碼如下：

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

5. 模型推理

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

6. 模型中斷

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

示例代碼如下：

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

7. 釋放模型資源

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

示例代碼如下：

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

8. LoRA 模型加載

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

加載 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 failed\n"); }

9. Prompt Cache 管理

在模型推理過程中，Prefill 階段通常消耗大量的計算資源和時間，特別是在 Prompt 很長的情況下。為了加速這一過程，RKLLM 支持文件加載 Prompt Cache，通過復用緩存中的內(nèi)容，可以顯著減少 Prefill 階段的耗時，從而提升整體推理效率。在調(diào)用 rkllm_run 接口進行推理之前，請確保正確配置 prompt_cache_params 參數(shù)。這一步驟允許模型在推理結(jié)束后生成對應(yīng)的 Prompt Cache 文件。當首次運行推理時，系統(tǒng)會自動生成一個 Prompt Cache 文件。該文件包含了 Prefill 階段所需的中間結(jié)果，以便后續(xù)使用。在后續(xù)的推理任務(wù)中，可以通過調(diào)用 rkllm_load_prompt_cache 接口加載之前生成的 Prompt Cache 文件。
具體的函數(shù)定義如下：

注意：
RKLLM 會從頭開始檢測輸入與 prompt_cache 中相同的部分，假設(shè)您的輸入格式固定為PROMPT_PREFIX + text + PROMPT_POSTFIX，您可以僅對 PROMPT_PREFIX 部分生成Prompt Cache，加載后在后續(xù)的推理中即可復用這部分結(jié)果。
RKLLM 支持生成多個 Prompt Cache 文件。在需要使用不同的 Prompt Cache 時，只需加載對應(yīng)的文件即可。當需要切換到另一個 Prompt Cache 文件或不再需要使用加載的 PromptCache 時，請顯式調(diào)用 rkllm_release_prompt_cache 接口進行釋放。
加載 Prompt Cache 的示例代碼如下：

// 初始化并設(shè)置 Prompt Cache 參數(shù),并調(diào)用 run 接口生成 prompt cache 文件 RKLLMPromptCacheParam prompt_cache_params; // 是否保存 prompt cache prompt_cache_params.save_prompt_cache = true; // 若需要保存 prompt cache, 指定 cache 文件絕對路徑 prompt_cache_params.prompt_cache_path = "/data/prompt_cache.bin"; rkllm_infer_params.prompt_cache_params = &prompt_cache_params; rkllm_infer_params.mode = RKLLM_INFER_GENERATE; rkllm_input.input_type = RKLLM_INPUT_PROMPT; rkllm_input.prompt_input = (char *)prompt.c_str(); rkllm_run(llmHandle, &rkllm_input, &rkllm_infer_params, NULL); // 加載 prompt cache 文件，減少 prefill 耗時 rkllm_load_prompt_cache(llmHandle, "./prompt_cache.bin"); if (ret != 0) { printf("\nload Prompt Cache failed\n"); } rkllm_run(llmHandle, &rkllm_input, &rkllm_infer_params, NULL);

10. KV Cache 管理

RKLLM 支持手動清除 KV 緩存，可用于單輪和多輪對話。在調(diào)用清除緩存功能時，如果keep_system_prompt 設(shè)置為 1，則會保留系統(tǒng)提示詞（如果存在）；否則，將清空整個緩存。函數(shù)定義如下：

11. Chat Template 設(shè)置

當用戶使用文本輸入時，RKLLM 會對默認文本進行前處理，前處理時會根據(jù) Hugging Face模型 tokenizer_config.json 文件中的 chat_template 字段，自動解析并應(yīng)用提示詞模板。如需自定義，可使用以下函數(shù)進行重置，其中，system_prompt 作為系統(tǒng)提示詞，用于指導模型行為，prompt_prefix 為用戶輸入前綴，prompt_postfix 為用戶輸入后綴，具體的函數(shù)定義如下。當用戶重置模板后，enable_thinking 選項將失效，用戶需要在自定義的 prompt 中進行配置。

12. Function Calling 設(shè)置

RKLLM 支持通過 Function Calling 實現(xiàn)模型與外部系統(tǒng)的結(jié)構(gòu)化交互，擴展大模型能力邊界，提升模型在知識補充、數(shù)據(jù)精確獲取等任務(wù)中的表現(xiàn)。當啟用 Function Calling 模式后，應(yīng)用程序可將函數(shù)定義傳入模型，模型根據(jù)用戶提問判斷是否需要調(diào)用函數(shù)，并根據(jù)設(shè)定的格式輸出調(diào)用請求。應(yīng)用程序根據(jù)模型意圖調(diào)用相應(yīng)函數(shù)并將結(jié)果返回，模型最終基于結(jié)果繼續(xù)對話。
RKLLM 支持的 Function Calling 設(shè)置函數(shù)定義如下：

示例代碼如下： 首先配置 tools std::string system_prompt = "You are Qwen, created by Alibaba Cloud. You are a helpful assistant.\n\nCurrent Date: 2024-09-30"; std::string tools = R"([ { "type": "function", "function": { "name": "get_current_temperature", "description": "Get current temperature at a location.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The location to get the temperature for, in the format "City, State, Country"." }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "The unit to return the temperature in. Defaults to "celsius"." } }, "required": ["location"] } } }, { "type": "function", "function": { "name": "get_temperature_date", "description": "Get temperature at a location and date.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The location to get the temperature for, in the format "City, State, Country"." }, "date": { "type": "string", "description": "The date to get the temperature for, in the format "Year-Month-Day"." }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "The unit to return the temperature in. Defaults to "celsius"." } }, "required": ["location", "date"] } } } ])"; rkllm_set_function_tools(llmHandle, system_prompt.c_str(), tools.c_str(), "tool_response");

接下來，在推理過程中配合 rkllm_run 實現(xiàn)調(diào)用鏈：

// 用戶提問 RKLLMInferParam rkllm_infer_params; memset(&rkllm_infer_params, 0, sizeof(RKLLMInferParam)); rkllm_infer_params.mode = RKLLM_INFER_GENERATE; rkllm_infer_params.keep_history = 0; RKLLMInput rkllm_input; rkllm_input.input_type = RKLLM_INPUT_PROMPT; rkllm_input.enable_thinking = false; rkllm_input.role = "user"; rkllm_input.prompt_input = "What's the temperature in San Francisco now? How about tomorrow?"; rkllm_run(llmHandle, &rkllm_input, &rkllm_infer_params, NULL); // 第一次調(diào)用 rkllm_run 會返回需要調(diào)用的工具函數(shù)名 {"name": "get_current_temperature", "arguments": {"location": "San Francisco"}} {"name": "get_temperature_date", "arguments": {"location": "San Francisco", "date": "2024-10-01"}} // 將工具調(diào)用結(jié)果返回給大模型，role 必須配置為 tool rkllm_input.role = "tool"; rkllm_input.prompt_input = R"([ { "temperature": 26.1, "location": "San Francisco", "unit": "celsius" }, { "temperature": 25.9, "location": "San Francisco", "date": "2024-09-30", "unit": "celsius" } ])"; rkllm_run(llmHandle, &rkllm_input, &rkllm_infer_params, NULL); // 最終結(jié)果 "The current temperature in San Francisco is 26.1°C. Tomorrow, the temperature is expected to be 25.9°C."

13. Cross attention 設(shè)置

RKLLM 支持 cross attention 推理，用戶可以通過如下函數(shù)將 encoder 生成的 K/V 緩存、掩碼以及位置信息輸入給解碼器用于交叉注意力計算。cross attention 只支持自定義模型推理，模型的轉(zhuǎn)換方式詳見 3.1.6 章節(jié)。

14. 多 batch 并行推理

RKLLM 支持同時推理多個 batch（建議 batch 數(shù)量不超過 8）。
使用兩個 batch 進行推理的示例代碼如下，主要為：

• 模型初始化時需要將 param.extend_param.n_batch 參數(shù)設(shè)置為 2；
• 使用多 batch 進行推理時，輸入 RLLLMInput 和 callback 中的 RKLLMResult 均為n_batch 大小的數(shù)組；
• callback 中所有 batch 推理結(jié)果同步返回，當某個 batch 返回的 token id 為負數(shù)時，表示該 batch 推理結(jié)束，所有 batch 都推理結(jié)束時才會終止推理；
• 在 callback 中處理返回的文本時，必須先判斷返回的 text 是否為空指針，再進行賦值操作。

#include #include #include #include "rkllm.h" #include #include #include #include using namespace std; LLMHandle llmHandle = nullptr; std::string output_texts[10]; int callback(RKLLMResult *result, void *userdata, LLMCallState state) { if (state == RKLLM_RUN_FINISH) { printf("\nrkllm run finish\n"); } else if (state == RKLLM_RUN_ERROR) { printf("\nrkllm run error\n"); } else if (state == RKLLM_RUN_NORMAL) { RKLLMResult batch1 = result[0]; RKLLMResult batch2 = result[1]; if (batch1.text) { output_texts[0] += batch1.text; printf("batch 0 %s\n", output_texts[0].c_str()); } if (batch2.text) { output_texts[1] += batch2.text;; printf("batch 1 %s\n", output_texts[1].c_str()); } } return 0; } int main(int argc, char **argv) { if (argc < 4) { std::cerr << "Usage: " << argv[0] << " model_path max_new_tokens max_context_len\n"; return 1; } RKLLMParam param = rkllm_createDefaultParam(); param.model_path = argv[1]; param.top_k = 1; param.top_p = 0.95; param.temperature = 0.8; param.repeat_penalty = 1.1; param.frequency_penalty = 0.0; param.presence_penalty = 0.0; param.max_new_tokens = std::atoi(argv[2]); param.max_context_len = std::atoi(argv[3]); param.skip_special_token = true; param.extend_param.base_domain_id = 0; param.extend_param.embed_flash = 1; param.extend_param.n_batch = 2; int ret = rkllm_init(&llmHandle, ?m, callback); if (ret == 0){ printf("rkllm init success\n"); } else { printf("rkllm init failed\n"); exit_handler(-1); } RKLLMInput rkllm_input[2]; memset(&rkllm_input, 0, sizeof(RKLLMInput)*2); RKLLMInferParam rkllm_infer_params; memset(&rkllm_infer_params, 0, sizeof(RKLLMInferParam)); // 將所有內(nèi)容初始化為 0 output_texts[0].clear(); output_texts[1].clear(); rkllm_infer_params.mode = RKLLM_INFER_GENERATE; rkllm_infer_params.keep_history = 0; rkllm_input[0].input_type = RKLLM_INPUT_PROMPT; rkllm_input[0].role = "user"; rkllm_input[0].enable_thinking = false; rkllm_input[0].prompt_input = "上聯(lián): 江邊慣看千帆過"; rkllm_input[1].input_type = RKLLM_INPUT_PROMPT; rkllm_input[1].role = "user"; rkllm_input[1].enable_thinking = false; rkllm_input[1].prompt_input = "以詠梅為題目，幫我寫一首古詩，要求包含梅花、白雪等元素。"; printf("robot: "); rkllm_run(llmHandle, &rkllm_input[0], &rkllm_infer_params, NULL); rkllm_destroy(llmHandle); return 0; }

15. 模型暫停推理

RKLLM 支持在單輪模式中暫停推理，具體為在 callback 中 return 1。暫停推理時，kv cache不會被清除，用戶可以繼續(xù)更改輸入后，調(diào)用 rkllm_run 恢復推理。

16. 模型性能數(shù)據(jù)回調(diào)

RKLLM 支持在推理結(jié)束時返回單次推理性能數(shù)據(jù)，包括 prefill 和 decode 推理總耗時、token數(shù)量和內(nèi)存占用，返回的結(jié)構(gòu)體定義如下：