RKLLM モデルデプロイ API 説明
修正履歴
| NO | バージョン | 修正内容 | 修正日 |
|---|---|---|---|
| 1 | Ver1.0 | 新規作成 | 2026/06/23 |
この文書の情報は、文書を改善するため、事前の通知なく変更されることがあります。最新版は弊社ホームページからご参照ください。
株式会社日昇テクノロジーの書面による許可のない複製は、いかなる形態においても厳重に禁じられています。
1. コールバック関数定義
コールバック関数は、モデルのリアルタイム出力結果を受け取るために使用します。RKLLM の初期化時にコールバック関数をバインドし、モデル推論中は結果が継続的にコールバック関数へ出力されます。各コールバックでは 1 つの token のみが返されます。
次のサンプルコードでは、コールバック関数によって推論結果をリアルタイムに端末へ出力します。
int callback(RKLLMResult* result, void* userdata, LLMCallStatestate){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 は状態フラグです。具体的な定義は次のとおりです。
表 1 LLMCallState 状態フラグ説明
| 項目 | 内容 |
|---|---|
| 列挙型定義 | LLMCallState |
| 説明 | 現在の RKLLM の実行状態を表します。 |
| 列挙値 | LLM_RUN_NORMAL：RKLLM モデルが現在推論中であることを示します。 LLM_RUN_FINISH：RKLLM モデルが現在の入力に対するすべての推論を完了したことを示します。 LLM_RUN_WAITING：現在 RKLLM がデコードした文字が完全な UTF-8 エンコードではなく、次回のデコード結果との結合を待つ必要があることを示します。 LLM_RUN_ERROR：RKLLM モデルの推論でエラーが発生したことを示します。 |
ユーザーは、コールバック関数を設計する際に、LLMCallState の状態に応じて異なる後処理を設定できます。
（2）RKLLMResult は戻り値の構造体です。具体的な定義は次のとおりです。
表 2 RKLLMResult 戻り値構造体説明
| 項目 | 内容 |
|---|---|
| 構造体定義 | RKLLMResult |
| 説明 | 現在の推論生成結果を返します。 |
| フィールド | const char text*：現在の推論で生成されたテキスト内容を表します。 int32_t token_id：現在の推論で生成された token ID を表します。 RKLLMResultLogits logits：現在の推論で生成された logits 情報を表します。RKLLMInferMode が RKLLM_INFER_GET_LOGITS に設定されている場合にのみ返されます。 RKLLMPerfStat perf：現在の推論終了時の性能統計データを表します。RKLLM_RUN_FINISH 状態の場合にのみデータが返されます。 |
（3）RKLLMResultLogits は戻り値の構造体です。具体的な定義は次のとおりです。
表 3 RKLLMResultLogits 戻り値構造体説明
| 項目 | 内容 |
|---|---|
| 構造体定義 | RKLLMResultLogits |
| 説明 | 現在の推論で生成された logits を返します。 |
| フィールド | const float logits*：現在の推論で生成された logits を表します。 int vocab_size：語彙表のサイズを表します。 int num_tokens：返却される token 数を表します。ユーザーは vocab_size と num_tokens に基づいて logits のサイズを算出できます。 |
ユーザーは、コールバック関数を設計する際に、RKLLMResult 内の値に応じて異なる後処理を設定できます。
2. パラメータ構造体 RKLLMParam 定義
構造体 RKLLMParam は、RKLLM の詳細情報を記述および定義するために使用します。具体的な定義は次のとおりです。
表 4 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 サンプリングは nucleus sampling とも呼ばれるテキスト生成手法で、累積確率が少なくとも p となる token 集合から次の token を選択します。token の確率とサンプリング対象数の両方を考慮することで、多様性と品質のバランスを取ります。値を大きくすると（例：0.95）生成文はより多様になり、値を小さくすると（例：0.5）より保守的な文になります。デフォルト値は 0.9 です。 float temperature：生成テキストのランダム性を制御するハイパーパラメータです。モデル出力 token の確率分布を調整することで機能します。温度が高い場合（例：1.5）、出力はよりランダムで創造的になり、次 token の選択時に低確率の候補もより多く考慮されるため、多様で予想外の出力が得られます。温度が低い場合（例：0.5）、出力はより集中し保守的になります。温度が 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：テキスト生成中に生成文の品質を期待範囲内に能動的に維持するアルゴリズムです。過度な繰り返し（boring trap）や不連続性（confusion trap）による低品質出力を避け、整合性と多様性のバランスを取ることを目的とします。値は {0, 1, 2} で、0 は無効、1 は mirostat、2 は mirostat 2.0 を使用します。 float mirostat_tau：mirostat の目標エントロピーを設定します。生成テキストの期待 perplexity を表し、整合性と多様性のバランスを制御します。値を小さくすると文はより集中し一貫性が高くなり、値を大きくするとより多様になりますが、一貫性が低下する可能性があります。デフォルト値は 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*：マルチモーダル入力における画像エンコードの内容マーカーを設定します。マルチモーダル入力モードでは設定が必要です。 n_keep：kv cache をクリアする際に先頭に保持する cache 数です。マルチターン対話では、設定する n_keep 値は system_prompt の長さ以上でなければなりません。 RKLLMExtendParam extend_param：推論を制御する特殊パラメータです。 |
表 5 RKLLMExtendParam 構造体パラメータ説明
| 項目 | 内容 |
|---|---|
| 構造体定義 | RKLLMExtendParam |
| 説明 | 推論を制御する特殊パラメータです。 |
| フィールド | int32_t base_domain_id：RKLLM モデルをどの domain から初期化するかを制御します。デフォルトは 0 です。 int8_t embed_flash：モデルの語彙表を flash に保存してメモリを節約するかどうかを制御します。0 は無効、1 は有効です。 int8_t enabled_cpus_num：推論時に使用する CPU 数を設定します。設定可能範囲はチップにより異なります。RK3588/3576 では 1〜8、RK3562 では 1〜4 で、デフォルトは 4 です。 uint32_t enabled_cpus_mask：使用する CPU コアをビットマスクで指定します。rkllm.h には CPU 番号を表すマクロが定義されており、CPU4|CPU5|CPU6|CPU7 の形式で設定します。 uint8_t n_batch：並列推論の batch 数を設定します。デフォルトは 1 です。 int8_t use_cross_attn：Cross Attention を有効にするかどうかを設定します。 |
実際のコード構築では、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;3. 入力構造体定義
異なる形式の入力データに対応するため、RKLLMInput 入力構造体が定義されています。現在、テキスト、画像とテキスト、Token ID、エンコードベクトルの 4 種類の入力形式を受け付けます。具体的な定義は次のとおりです。
表 6 RKLLMInput 構造体パラメータ説明
| 項目 | 内容 |
|---|---|
| 構造体定義 | RKLLMInput |
| 説明 | 異なる形式の入力データを受け取ります。 |
| フィールド | RKLLMInputType input_type：入力モードです。 const char role*：入力ロールです。選択可能値は [“user”, “tool”] です。 bool enable_thinking：Qwen3 モデルで thinking モードを使用するかどうかを指定します。 union：異なる入力データ型を格納します。具体的には次の形式を含みます。 - const char prompt_input*：テキストプロンプト入力です。自然言語テキストを渡します。 - RKLLMEmbedInput embed_input：埋め込みベクトル入力です。処理済みの特徴ベクトルを表します。 - RKLLMTokenInput token_input：Token 入力です。トークナイズ済みの Token シーケンスを渡します。 - RKLLMMultiModelInput multimodal_input：マルチモーダル入力です。画像とテキストの結合入力など、マルチモーダルデータを渡します。 |
表 7 RKLLMInputType 入力タイプ説明
| 項目 | 内容 |
|---|---|
| 列挙型定義 | RKLLMInputType |
| 説明 | 入力データタイプを表します。 |
| 列挙値 | RKLLM_INPUT_PROMPT：入力データが純粋なテキストであることを示します。 RKLLM_INPUT_TOKEN：入力データが Token ID であることを示します。 RKLLM_INPUT_EMBED：入力データがエンコードベクトルであることを示します。 RKLLM_INPUT_MULTIMODAL：入力データが画像とテキストであることを示します。 |
入力データが純粋なテキストの場合は、input_data を使用して直接入力します。入力データが Token ID、エンコードベクトル、または画像とテキストの場合、RKLLMInput は RKLLMTokenInput、RKLLMEmbedInput、RKLLMMultiModelInput の 3 つの入力構造体と組み合わせて使用します。具体的な説明は次のとおりです。
（1）RKLLMTokenInput は Token ID を受け取る入力構造体です。具体的な定義は次のとおりです。
表 8 RKLLMTokenInput 構造体パラメータ説明
| 項目 | 内容 |
|---|---|
| 構造体定義 | RKLLMTokenInput |
| 説明 | Token ID データを受け取ります。 |
| フィールド | int32_t input_ids*：入力 token IDs のメモリポインタです。 size_t n_tokens：入力データの token 数です。 |
（2）RKLLMEmbedInput はエンコードベクトルを受け取る入力構造体です。具体的な定義は次のとおりです。
表 9 RKLLMEmbedInput 構造体パラメータ説明
| 項目 | 内容 |
|---|---|
| 構造体定義 | RKLLMEmbedInput |
| 説明 | Embedding データを受け取ります。 |
| フィールド | float embed*：入力 token embedding のメモリポインタです。 size_t n_tokens：入力データの token 数です。 |
（3）RKLLMMultiModelInput は画像とテキストを受け取る入力構造体です。具体的な定義は次のとおりです。
表 10 RKLLMMultiModelInput 構造体パラメータ説明
| 項目 | 内容 |
|---|---|
| 構造体定義 | RKLLMMultiModelInput |
| 説明 | 画像とテキストのマルチモーダルデータを受け取ります。 |
| フィールド | char prompt*：入力テキストのメモリポインタです。 float image_embed*：入力画像 embedding のメモリポインタです。 size_t n_image_tokens：入力画像 embedding の token 数です。 size_t n_image：入力画像数です。連続した複数フレーム画像の入力をサポートします。 size_t image_width：入力画像の embedding 計算時の幅です。mrope 計算パラメータに使用します。 size_t image_height：入力画像の embedding 計算時の高さです。mrope 計算パラメータに使用します。 |
RKLLM は複数の推論モードをサポートしており、RKLLMInferParam 構造体が定義されています。現在、推論中にプリロードされた LoRA モデルと組み合わせて推論する、または Prompt Cache を保存して後続推論を高速化することができます。具体的な定義は次のとおりです。
表 11 RKLLMInferParam 構造体パラメータ説明
| 項目 | 内容 |
|---|---|
| 構造体定義 | RKLLMInferParam |
| 説明 | 異なる推論モードを定義します。 |
| フィールド | RKLLMInferMode mode：推論モードです。通常推論モード RKLLM_INFER_GENERATE と、追加で logits 値を取得する推論モード RKLLM_INFER_GET_LOGITS をサポートします。 RKLLMLoraParam lora_params*：推論時に使用する LoRA のパラメータ設定です。複数の LoRA をロードしている場合に、推論対象の LoRA を選択するために使用します。LoRA をロードしない場合は NULL を設定します。 RKLLMPromptCacheParam prompt_cache_params*：推論時に使用する Prompt Cache のパラメータ設定です。Prompt Cache を生成しない場合は NULL を設定します。 keep_history：推論時に履歴コンテキストを保持する必要があるかどうかを指定します。マルチターン対話では 1 に設定する必要があります。 |
表 12 RKLLMLoraParam 構造体パラメータ説明
| 構造体定義 | RKLLMLoraParam |
| 説明 | 推論時に使用する LoRA のパラメータを定義します。 |
| フィールド | const char* lora_adapter_name：推論時に使用する LoRA 名称です。 |
表 13 RKLLMPromptCacheParam 構造体パラメータ説明
| 項目 | 内容 |
|---|---|
| 構造体定義 | RKLLMPromptCacheParam |
| 説明 | 推論時に使用する Prompt Cache のパラメータを定義します。 |
| フィールド | int save_prompt_cache：推論時に Prompt Cache を保存するかどうかを指定します。1 は保存する、0 は保存しないことを示します。 const char prompt_cache_path*：Prompt Cache の保存パスです。未設定の場合はデフォルトで ”./prompt_cache.bin” に保存されます。 |
RKLLMPromptCacheParam の使用例は次のとおりです。
// 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.prompt_cache_params =&prompt_cache_params;4. モデル初期化
モデルを初期化する前に、あらかじめ LLMHandle ハンドルを定義する必要があります。このハンドルは、モデルの初期化、推論、リソース解放の各処理で使用します。正しいモデル推論フローでは、これら 3 つの処理で同一の LLMHandle ハンドルオブジェクトを使用する必要があります。モデル推論前に、ユーザーは rkllm_init() 関数を通じてモデル初期化を完了します。具体的な関数定義は次のとおりです。
表 14 rkllm_init 関数インターフェース説明
| 項目 | 内容 |
|---|---|
| 関数名 | rkllm_init |
| 説明 | RKLLM モデルの具体的なパラメータおよび関連する推論設定を初期化します。 |
| 引数 | LLMHandle handle*：モデルを該当ハンドルに登録し、後続の推論および解放呼び出しで使用します。 RKLLMParam param*：モデル定義のパラメータ構造体です。 LLMResultCallback callback：モデルのリアルタイム出力を受け取り処理するためのコールバック関数です。 |
| 戻り値 | 0 は初期化処理が正常に完了したことを示します。-1 は初期化失敗を示します。 |
サンプルコードは次のとおりです。
LLMHandle llmHandle = nullptr;rkllm_init(&llmHandle, ¶m, callback);5. モデル推論
RKLLM モデルの初期化処理が完了したら、rkllm_run() 関数を使用してモデル推論を実行できます。また、初期化時に事前定義したコールバック関数により、リアルタイム推論結果を処理できます。rkllm_run() の具体的な関数定義は次のとおりです。
表 15 rkllm_run 関数インターフェース説明
| 項目 | 内容 |
|---|---|
| 関数名 | rkllm_run |
| 説明 | 初期化済みの RKLLM モデルを呼び出して推論結果を生成します。 |
| 引数 | LLMHandle handle：モデル初期化時に登録された対象ハンドルです。 RKLLMInput rkllm_input*：モデル推論の入力データです。 RKLLMInferParam rkllm_infer_params*：モデル推論プロセスで渡すパラメータです。 void userdata*：ユーザー定義の関数ポインタです。デフォルトでは NULL に設定します。 |
| 戻り値 | 0 はモデル推論が正常に実行されたことを示します。-1 はモデル推論呼び出し失敗を示します。 |
6. モデル中断
モデル推論中、ユーザーは rkllm_abort() 関数を呼び出して推論プロセスを中断できます。具体的な関数定義は次のとおりです。
表 16 rkllm_abort 関数インターフェース説明
| 関数名 | rkllm_abort |
| 説明 | RKLLM モデルの推論プロセスを中断します。 |
| 引数 | LLMHandle handle：モデル初期化時に登録された対象ハンドルです。 |
| 戻り値 | 0 は RKLLM モデルの中断に成功したことを示します。-1 はモデル中断失敗を示します。 |
サンプルコードは次のとおりです。
// llmHandle はモデル初期化時に渡されたハンドルですrkllm_abort(llmHandle);7. モデルリソースの解放
すべてのモデル推論呼び出しが完了した後、ユーザーは rkllm_destroy() 関数を呼び出して RKLLM モデルを破棄し、確保された CPU および NPU 計算リソースを解放します。これにより、他のプロセスやモデルが計算リソースを利用できるようになります。具体的な関数定義は次のとおりです。
表 17 rkllm_destroy 関数インターフェース説明
| 関数名 | rkllm_destroy |
| 説明 | RKLLM モデルを破棄し、すべての計算リソースを解放します。 |
| 引数 | LLMHandle handle：モデル初期化時に登録された対象ハンドルです。 |
| 戻り値 | 0 は RKLLM モデルが正常に破棄・解放されたことを示します。-1 はモデル解放失敗を示します。 |
サンプルコードは次のとおりです。
// llmHandle はモデル初期化時に渡されたハンドルですrkllm_destroy(llmHandle);8. LoRA モデルのロード
RKLLM は、ベースモデルの推論と同時に LoRA モデルを推論することをサポートします。rkllm_run インターフェースを呼び出す前に、rkllm_load_lora インターフェースを使用して LoRA モデルをロードできます。RKLLM は複数の LoRA モデルのロードをサポートしており、rkllm_load_lora を 1 回呼び出すごとに 1 つの LoRA モデルをロードできます。具体的な関数定義は次のとおりです。
表 18 rkllm_load_lora 関数インターフェース説明
| 項目 | 内容 |
|---|---|
| 関数名 | rkllm_load_lora |
| 説明 | LoRA モデルをロードします。 |
| 引数 | LLMHandle handle：モデル初期化時に登録された対象ハンドルです。 RKLLMLoraAdapter lora_adapter*：LoRA モデルロード時のパラメータ設定です。 |
| 戻り値 | 0 は LoRA モデルが正常にロードされたことを示します。-1 はモデルロード失敗を示します。 |
表 19 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 failed\n");}9. Prompt Cache 管理
モデル推論プロセスでは、Prefill フェーズが大量の計算リソースと時間を消費することがあります。特に Prompt が長い場合、その影響は大きくなります。この処理を高速化するため、RKLLM はファイルからの Prompt Cache ロードをサポートしています。キャッシュ内の内容を再利用することで、Prefill フェーズの所要時間を大幅に削減し、全体的な推論効率を向上できます。rkllm_run インターフェースを呼び出して推論を行う前に、prompt_cache_params パラメータを正しく設定してください。この設定により、モデルは推論終了後に対応する Prompt Cache ファイルを生成できます。初回推論時、システムは自動的に Prompt Cache ファイルを生成します。このファイルには Prefill フェーズに必要な中間結果が含まれ、後続の推論で利用できます。後続の推論タスクでは、rkllm_load_prompt_cache インターフェースを呼び出して、以前に生成した Prompt Cache ファイルをロードできます。
具体的な関数定義は次のとおりです。
表 20 rkllm_load_prompt_cache 関数インターフェース説明
| 項目 | 内容 |
|---|---|
| 関数名 | rkllm_load_prompt_cache |
| 説明 | Prompt Cache をロードします。 |
| 引数 | LLMHandle handle：モデル初期化時に登録された対象ハンドルです。4. モデル初期化を参照してください。 const char prompt_cache_path*：ロードする Prompt Cache ファイルのパスです。 |
| 戻り値 | 0 は Prompt Cache が正常にロードされたことを示します。-1 はロード失敗を示します。 |
表 21 rkllm_release_prompt_cache 関数インターフェース説明
| 関数名 | rkllm_release_prompt_cache |
| 説明 | Prompt Cache を解放します。 |
| 引数 | LLMHandle handle：モデル初期化時に登録された対象ハンドルです。4. モデル初期化を参照してください。 |
| 戻り値 | 0 は Prompt Cache が正常に解放されたことを示します。-1 は解放失敗を示します。 |
注意：
RKLLM は、入力と prompt_cache
内で同一の部分を先頭から検出します。入力形式が PROMPT_PREFIX + text +
PROMPT_POSTFIX のように固定されている場合、PROMPT_PREFIX 部分のみで
Prompt Cache
を生成できます。ロード後の後続推論では、この部分の結果を再利用できます。
RKLLM は複数の Prompt Cache ファイル生成をサポートします。異なる Prompt
Cache
を使用する場合は、対応するファイルをロードするだけで利用できます。別の
Prompt Cache ファイルへ切り替える場合、またはロード済みの Prompt Cache
が不要になった場合は、rkllm_release_prompt_cache
インターフェースを明示的に呼び出して解放してください。
Prompt Cache をロードするサンプルコードは次のとおりです。
// Prompt Cache パラメータを初期化して設定し、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 cache の手動クリアをサポートしており、シングルターンおよびマルチターン対話で使用できます。キャッシュクリア機能を呼び出す際に keep_system_prompt を 1 に設定すると、system prompt（存在する場合）を保持します。そうでない場合は、キャッシュ全体をクリアします。関数定義は次のとおりです。
表 22 rkllm_clear_kv_cache 関数インターフェース説明
| 項目 | 内容 |
|---|---|
| 関数名 | rkllm_clear_kv_cache |
| 説明 | kv cache をクリアします。 |
| 引数 | LLMHandle handle：モデル初期化時に登録された対象ハンドルです。 keep_system_prompt：system prompt を保持するかどうかを指定します。 start_pos：削除する kv cache の開始 position ID です。start_pos の位置を含みます。使用しない場合は nullptr を明示的に設定してください。 end_pos：削除する kv cache の終了 position ID です。end_pos の位置は含みません。使用しない場合は nullptr を明示的に設定してください。 注意： 1. 指定位置の kv cache 削除は、シングルターンモードで推論一時停止機能を使用する場合にのみサポートされます。 2. 特定範囲 [start_pos, end_pos) を指定した場合、keep_system_prompt は無視され、指定範囲内の kv cache がクリアされます。 |
| 戻り値 | 0 は kv cache のクリア成功を示します。-1 はクリア失敗を示します。 |
11. Chat Template 設定
ユーザーがテキスト入力を使用する場合、RKLLM はデフォルトテキストを前処理します。前処理では、Hugging Face モデルの tokenizer_config.json ファイル内の chat_template フィールドに基づいて、プロンプトテンプレートを自動解析して適用します。カスタマイズが必要な場合は、次の関数で再設定できます。system_prompt はモデルの挙動を指示する system prompt、prompt_prefix はユーザー入力前の接頭辞、prompt_postfix はユーザー入力後の接尾辞です。具体的な関数定義は次のとおりです。ユーザーがテンプレートを再設定すると、enable_thinking オプションは無効になり、ユーザーはカスタム prompt 内で設定する必要があります。
表 23 rkllm_set_chat_template 関数インターフェース説明
| 項目 | 内容 |
|---|---|
| 関数名 | rkllm_set_chat_template |
| 説明 | プロンプトを設定します。 |
| 引数 | LLMHandle handle：モデル初期化時に登録された対象ハンドルです。 system_prompt：システムプロンプトです。 prompt_prefix：ユーザー入力の接頭辞です。 prompt_postfix：ユーザー入力の接尾辞です。 |
| 戻り値 | 0 は chat_template 設定成功を示します。-1 は設定失敗を示します。 |
12. Function Calling 設定
RKLLM は Function Calling により、モデルと外部システムの構造化された連携を実現します。これにより、大規模言語モデルの能力範囲を拡張し、知識補完や正確なデータ取得などのタスクにおける性能を向上させます。Function Calling モードを有効にすると、アプリケーションは関数定義をモデルへ渡します。モデルはユーザーの質問に基づいて関数呼び出しが必要かどうかを判断し、設定された形式で呼び出しリクエストを出力します。アプリケーションはモデルの意図に応じて該当関数を呼び出し、結果を返します。モデルは最終的にその結果に基づいて対話を継続します。
RKLLM がサポートする Function Calling 設定関数の定義は次のとおりです。
表 24 rkllm_set_function_tools 関数インターフェース説明
| 項目 | 内容 |
|---|---|
| 関数名 | rkllm_set_function_tools |
| 説明 | Function Calling の設定です。system prompt、ツール関数定義、ツール応答識別子を含みます。 |
| 引数 | LLMHandle handle：モデル初期化時に登録された対象ハンドルです。 system_prompt：システムプロンプトです。 tools：JSON 形式の関数定義文字列です。使用可能な関数の名称、機能、パラメータ形式を記述します。 tool_response_str：ツール関数呼び出し結果の識別タグです。通常の対話内容と区別するために使用します。 |
| 戻り値 | 0 は設定成功を示します。-1 は設定失敗を示します。 |
サンプルコードは次のとおりです。まず tools を設定します。
std::string system_prompt = "あなたは Alibaba Cloudによって作成された Qwen です。役に立つアシスタントです。\n\n現在の日付:2024-09-30";std::string tools = R"([{ "type": "function", "function": { "name": "get_current_temperature", "description": "指定された場所の現在の気温を取得します。", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "気温を取得する場所です。形式は \"City,State, Country\" です。" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "返却する気温の単位です。デフォルトは\"celsius\" です。" } }, "required": ["location"] } }},{ "type": "function", "function": { "name": "get_temperature_date", "description": "指定された場所と日付の気温を取得します。", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "気温を取得する場所です。形式は \"City,State, Country\" です。" }, "date": { "type": "string", "description": "気温を取得する日付です。形式は\"Year-Month-Day\" です。" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "返却する気温の単位です。デフォルトは\"celsius\" です。" } }, "required": ["location", "date"] } }}])";rkllm_set_function_tools(llmHandle, system_prompt.c_str(),tools.c_str(), "tool_response");次に、推論プロセスで rkllm_run と組み合わせて呼び出しチェーンを実現します。
// ユーザーからの質問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 ="サンフランシスコの現在の気温は何度ですか？明日はどうですか？";rkllm_run(llmHandle, &rkllm_input, &rkllm_infer_params,NULL);// 1 回目の rkllm_runは、呼び出す必要があるツール関数名を返します<tool_call>{"name": "get_current_temperature", "arguments": {"location": "SanFrancisco"}}</tool_call><tool_call>{"name": "get_temperature_date", "arguments": {"location": "SanFrancisco", "date": "2024-10-01"}}</tool_call>// ツール呼び出し結果を大規模言語モデルへ返します。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);// 最終結果"サンフランシスコの現在の気温は 26.1°C です。明日の気温は 25.9°Cと予想されます。"13. Cross Attention 設定
RKLLM は Cross Attention 推論をサポートします。ユーザーは次の関数を使用して、encoder が生成した K/V cache、mask、および位置情報を decoder へ入力し、Cross Attention 計算に利用できます。Cross Attention はカスタムモデル推論のみをサポートします。モデルの変換方法については 3.1.6 章を参照してください。
表 25 rkllm_set_cross_attn_params 関数インターフェース説明
| 項目 | 内容 |
|---|---|
| 関数名 | rkllm_set_cross_attn_params |
| 説明 | Cross Attention パラメータを設定します。 |
| 引数 | LLMHandle handle：モデル初期化時に登録された対象ハンドルです。 RKLLMCrossAttnParam cross_attn_params*：Cross Attention パラメータです。 |
| 戻り値 | 0 は設定成功を示します。-1 は設定失敗を示します。 |
表 26 RKLLMCrossAttnParam 構造体パラメータ説明
| 項目 | 内容 |
|---|---|
| 構造体定義 | RKLLMCrossAttnParam |
| 説明 | Cross Attention パラメータです。 |
| フィールド | - float encoder_k_cache*：encoder 出力の k 値 cache ポインタです。 - float encoder_v_cache*：encoder 出力の v 値 cache ポインタです。 - float encoder_mask*：encoder の attention mask です。 - int32_t encoder_pos*：encoder 入力 token の位置情報です。 - int num_tokens*：encoder の入力 token 数です。 |
14. マルチ batch 並列推論
RKLLM は複数 batch の同時推論をサポートします（batch 数は 8 以下を推奨します）。
2 つの batch を使用して推論するサンプルコードは次のとおりです。主なポイントは以下のとおりです。
-
モデル初期化時に param.extend_param.n_batch パラメータを 2 に設定します。
-
マルチ batch 推論では、入力 RLLLMInput と callback 内の RKLLMResult はいずれも n_batch サイズの配列になります。
-
callback ではすべての batch 推論結果が同期して返されます。ある batch で返された token ID が負数の場合、その batch の推論終了を示します。すべての batch の推論が終了した時点で推論が終了します。
-
callback 内で返却テキストを処理する場合、必ず返却された text が NULL ポインタでないことを確認してから代入処理を行います。
#include <string.h>#include <unistd.h>#include <string>#include "rkllm.h"#include <fstream>#include <iostream>#include <csignal>#include <vector>using namespace std;LLMHandle llmHandle = nullptr;std::string output_texts[10];int callback(RKLLMResult *result, void *userdata, LLMCallStatestate){ 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)); //全内容を 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 ="上の句：川辺で幾千もの帆が過ぎ行くのを見慣れている"; 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 はクリアされないため、ユーザーは入力を変更したうえで rkllm_run を再度呼び出し、推論を再開できます。
16. モデル性能データのコールバック
RKLLM は推論終了時に、単一推論の性能データを返すことをサポートします。返却データには、prefill と decode の推論総所要時間、token 数、メモリ使用量が含まれます。返却される構造体の定義は次のとおりです。
表 27 RKLLMPerfStat 構造体パラメータ説明
| 項目 | 内容 |
|---|---|
| 構造体定義 | RKLLMPerfStat |
| 説明 | モデル推論性能データを返します。 |
| フィールド | - float prefill_time_ms：prefill フェーズの総所要時間です。単位は ms です。 - int prefill_tokens：prefill フェーズの総 token 数です。 - float generate_time_ms：generate フェーズの総所要時間です。 - int generate_tokens：generate フェーズで生成された総 token 数です。 - float memory_usage_mb：推論プロセスにおける VmHWM メモリサイズです。単位は MB です。 |