Skip to content
日昇 Docs

RKLLM Model Conversion API Reference

Revision History

NOVersionRevision DetailsDate
1Ver1.0New document2026/06/21

The information in this document may be changed without prior notice for document improvement. Please refer to the company website for the latest version.

Reproduction in any form without written permission from Nissho Technology Co., Ltd. is strictly prohibited.

1. RKLLMのinitialization

　　This section、ワークflow全体の最初のステップas、RKLLMオブジェクトをinitializationするis required。sample codeでは、RKLLM()コンストラクタを使用してRKLLMオブジェクトをinitializationしています。

2. モデルの読み込み

　　RKLLMのinitialization後、rkllm.load_huggingface()functionを呼び出し、モデルへの特定のpathを渡すis required。RKLLM-Toolkitは、指定されたpathに基づいて、Hugging Face形式alsoはGGUF形式のlarge language modelを正常に読み込み、後続の変換andquantization処理をスムーズに完了させることがcan。具体的なfunction定義はthe followingのとおりです。

　　

表 1 load_huggingface functioninterface specification

function nameload_huggingface
descriptionopen-sourceの Hugging Face 形式のlarge language modelをloadします。
parametermodel: LLM モデルのfilepath。後続の変換・quantization処理のin order toにモデルをloadします。
model_lora: LoRA 重みのfilepath。変換時、model は対応する base model のpathを指しているis required。
device: model conversion時に使用するデバイスを指定します。cuda と cpu の 2 種類をsupports。
dtype: 重みのdata型を指定します。指定可能なvalueは float32、float16、bfloat16 です。float16 と bfloat16 は VRAM 使用量を削減canが、quantizationaccuracyが低下する可能性があります。
custom_config: customモデルの設定fileです。詳細は「custommodel conversion」章をrefer to。
load_weight: 重みをloadするかどうかを指定します。False に設定したwhen、実際の重みはloadされません。
return value0 はモデルload成功、-1 はモデルload失敗をindicates。

sample codeはas follows。

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

表 2 load_gguf functioninterface specification

function nameload_gguf
descriptionopen-sourceの GGUF 形式のlarge language modelをloadします。対応するnumbervalue型は q4_0 と fp16 の 2 種類です。GGUF 形式の LoRA モデルも、このインターフェースを使用して RKLLM モデルへ変換can。
parametermodel: GGUF モデルのfilepath。
return value0 はモデルload成功、-1 はモデルload失敗をindicates。

sample codeはas follows。

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

3. モデルbuild

rkllm.load_huggingface() functionで元モデルをloadした後、the followingステップas rkllm.build() functionを使用し、RKLLM モデルをbuildします。build時にはquantizationを行うかどうかを選択can。quantizationはモデルサイズの削減、and Rockchip NPU 上でのinference性能向上に有効です。rkllm.build() functionの定義はas follows。

表 3 build functioninterface specification

function namebuild
descriptionRKLLM モデルをbuildし、変換処理の中で具体的なquantization設定を定義します。
parameterdo_quantization: モデルにquantization処理を適用するかどうかを制御します。True に設定することを推奨します。
optimization_level: quantizationaccuracy最適化を行うかどうかを指定します。設定valueは {0, 1} from選択します。0 は最適化なし、1 はaccuracy最適化をindicates。accuracy最適化by、モデルのinference性能が低下する可能性があります。
quantized_dtype: quantizationの具体的な型を指定します。currentサポートされるquantization型は “w4a16”, “w4a16_g32”, “w4a16_g64”, “w4a16_g128”, “w8a8”, “w8a8_g128”, “w8a8_g256”, “w8a8_g512” です。“w4a16” は重みを 4bit quantizationし、アクティベーションはquantizationしないことをindicates。“w4a16_g64” は重みを group size=64 の 4bit グループquantizationとし、アクティベーションはquantizationしないことをindicates。“w8a8” は重みとアクティベーションをいずれも 8bit quantizationすることをindicates。“w8a8_g128” は重みとアクティベーションをいずれも group size=128 の 8bit グループquantizationにすることをindicates。current、RK3576 と RV1126B プラットフォームでは “w4a16”, “w4a16_g32”, “w4a16_g64”, “w4a16_g128”, “w8a8” の 5 種類をsupports。RK3588 では “w8a8”, “w8a8_g128”, “w8a8_g256”, “w8a8_g512” の 4 種類をsupports。RK3562 では “w8a8”, “w4a16_g32”, “w4a16_g64”, “w4a16_g128”, “w4a8_g32” をsupports。GGUF モデルの q4_0 に対応するquantization型は “w4a16_g32” です。なお、group size は線形層のoutput次元で割り切れる必要があり、割り切れないwhenはサポートされません。
quantized_algorithm: quantizationaccuracy最適化アルゴリズムを指定します。選択可能な設定は “normal”, “grq”, “gdq” です。すべてのquantization型で normal を選択can。一方、gdq と grq は w4a16 and w4a16 グループquantizationのみをsupports。gdq と grq は計算負荷が高いin order to、GPU による高速化が必須です。grq は gdq と比較して処理速度が速く、VRAM 使用量も少ないin order to、4bit quantizationでは grq を優先的に試すことを推奨します。LoRA モジュールを利用してquantizationaccuracyをさらに向上させることもcan。他の LoRA モデルを読み込まないwhen、“normal_r[164]”, “grq_r[164]”, “gdq_r[1~64]” などのアルゴリズムを使用can。例as “normal_r8”, “grq_r8”, “gdq_r8” があります。最終的にquantizationモデルと LoRA モデルがexportされ、runtime は 2 つのモデルをloadしてinferenceをexecutionします。
num_npu_core: model inferenceで使用する NPU コアnumberを指定します。“RK3576” の選択肢は [1,2]、“RK3588” の選択肢は [1,2,3]、“RK3562” の選択肢は [1]、“RV1126B” の選択肢は [1] です。
extra_qparams: gdq/grq アルゴリズムを使用すると、.qparams 拡張子のquantization重みcachefileがgenerationされます。このparameterに *.qparams のpathを指定することで、モデルの再exportが可能になります。
dataset: quantizationキャリブレーション用dataセットを指定します。形式は JSON です。内容例では input が質問であり、プロンプトを付加するis required。target は回答です。複numberdataは {} の辞書形式でリストにsaveします。例：[{“input”:“今日の天気はどうですか？”,“target”:“今日は晴れです。”},…]
hybrid_rate: グループquantizationと非グループquantizationのハイブリッド比率を指定します（範囲は [0,1)）。quantization型が w4a16/w8a8 のwhen、この比率に基づいて w4a16 グループquantization / w8a8 グループquantizationを混在させ、accuracyを向上させます。quantization型が w4a16 グループ / w8a8 グループのwhen、この比率に基づいて w4a16/w8a8 を混在させ、inference性能を向上させます。hybrid_rate が 0 のwhen、ハイブリッドquantizationは行われません。
target_platform: モデルをexecutionするハードウェアプラットフォームを指定します。選択可能な設定は “RK3576”, “RK3588”, “RK3562”, “RV1126B” です。
max_context: コンtext長の上限valueを指定します。最大 16384 toサポートされ、32 の倍numberにアライメントされているis required。
return value0 はmodel conversion・quantization成功、-1 はmodel conversion失敗をindicates。

sample codeはas follows。

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!')

4. モデルexport

rkllm.build() functionで RKLLM モデルをbuildした後、rkllm.export_rkllm() functionを使用して RKLLM モデルを .rkllm fileassavecan。saveされたモデルは、後続のデプロイandinference呼び出しにis used。rkllm.export_rkllm() functionのparameter定義はas follows。

表 4 export_rkllm functioninterface specification

function nameexport_rkllm
description変換・quantization済みの RKLLM モデルをsaveし、後続のinference呼び出しで使用できるようにします。
parameterexport_path: exportする RKLLM モデルfileのsavepathを指定します。LoRA モデルは _lora サフィックス付きの RKLLM モデルas自動saveされます。
return value0 はモデルのexport・save成功、-1 はモデルexport失敗をindicates。

sample codeはas follows。

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

5. GPTQ model conversion

aboveツールで提供されるquantizationアルゴリズムを使用してmodel conversionを行うだけでなく、AutoGPTQ などのopen-sourcequantizationツールを用いて、あらかじめ浮動小number点モデルを 4bit/8bit の重みにquantizationし（Hugging Face 形式でsaveするis required）、その後 RKLLM モデルへ変換することもcan。AutoGPTQ で浮動小number点モデルをquantizationする際は、the followingのparameter設定を確認してください。

bits=4
sym=true
group_size=32/64/128
desc_act=false
bits=8
sym=true
group_size=128/256/512
desc_act=false

Hugging Face 形式の GPTQ モデルを RKLLM へ変換するsample codeはas follows。

modelpath = '/path/to/Model-Instruct-GPTQ-Int4'
llm = RKLLM()
ret = llm.load_huggingface(model=modelpath, model_lora = None,
device='cuda')
if ret != 0:
    print('Load model failed!')
    exit(ret)
## Build model
dataset = None
qparams = None
target_platform = "RK3576"
optimization_level = 1
quantized_dtype = "w4a16_g32" #w4a16_g64 or w4a16_g128
quantized_algorithm = "normal"
num_npu_core = 2
ret = llm.build(
    do_quantization=True,
    optimization_level=optimization_level,
    quantized_dtype=quantized_dtype,
    quantized_algorithm=quantized_algorithm,
    target_platform=target_platform,
    num_npu_core=num_npu_core,
    extra_qparams=qparams,
    dataset=dataset
)
if ret != 0:
    print('Build model failed!')
    exit(ret)
## Export rkllm model
ret = llm.export_rkllm(


f"./{os.path.basename(modelpath)}_{quantized_dtype}_{target_platform}.rkllm"
)
if ret != 0:
    print('Export model failed!')
    exit(ret)

6. custommodel conversion

モデル構造alsoは名称を変更したwhenでも、変更後の全体アーキテクチャがthe followingの構成に従っていれば、custommodel conversionfunctionを使用してモデルを変換can。

TOKEN_EMBD
↓
embd_scale(optional)
↓
┌─ x
│ ↓
│ ATTN_NORM
│ ↓
│ attn
│ ↓
│ ATTN_POST_NORM(optional)
│ ↓
│ hidden_state_scale(optional)
│ ↓
│ cross attn(optional)
│ ↓
┌─└► +
│
│ ↓
│ FFN_NORM
│ ↓
│ MLP
│ ↓
│ FFN_POST_NORM(optional)
│ ↓
│ hidden_state_scale(optional)
│ ↓
└───► +
…↓
OUTPUT_NORM
↓
lm_head_scale(optional)
↓
OUTPUT

Qwen モデルを例as、Qwen モデルfile modeling_qwen.py 内の対応する変number名を、the followingようにcustom設定fileへ記述します。

{
  "BLOCKNAME": "QWenBlock",
  "TOKEN_EMBD": "wte",
  "ATTN_NORM": "ln_1",
  "ATTN_Q_NORM": "",
  "ATTN_K_NORM": "",
  "CROSS_ATTN_NORM": "",
  "CROSS_ATTN_Q": "",
  "ATTN_Q": "",
  "ATTN_K": "",
  "ATTN_V": "",
  "ATTN_QKV": "attn.c_attn",
  "ATTN_KV": "",
  "KV_CONTINUOUS": "true",
  "ATTN_OUT": "attn.c_proj",
  "CROSS_ATTN_OUT": "",
  "ATTN_POST_NORM": "",
  "FFN_NORM": "ln_2",
  "FFN_UP": "mlp.w1",
  "FFN_GATE": "mlp.w2",
  "ACT_TYPE": "silu",
  "FFN_DOWN": "mlp.c_proj",
  "FFN_POST_NORM": "",
  "OUTPUT_NORM": "ln_f",
  "OUTPUT": "lm_head"
}

ACT_TYPE の選択肢は [“silu”, “gelu”, “relu”, “fatrelu”, “squarerelu”, “swiglu”] の 6 種類です。ATTN_NORM と FFN_NORM は RMSNorm のみをsupports。

ATTN_QKV alsoは ATTN_KV を使用するwhen、重みを連続した K|V as分割できるかどうかを確認するis required。連続しているwhenは KV_CONTINUOUS を true にsets。たとえば Qwen モデルの c_attn 重みは連続deploymentであり、Q, K, V のサイズに従って順番に分割can。一方、InternLM2 モデルの wqkv 重みは連続deploymentではなく、Q, K, V が head_dim 単位で交互にdeploymentされています。

Qwen 1.8B モデルの modeling_qwen.py file定義はas follows。

class QWenLMHeadModel(QWenPreTrainedModel):
    def __init__(self, config):
        super().__init__(config)
        self.transformer = QWenModel(config)
        self.lm_head = nn.Linear(config.hidden_size,
config.vocab_size, bias=False)
class QWenModel(QWenPreTrainedModel):
    _keys_to_ignore_on_load_missing = ["attn.masked_bias"]
    def __init__(self, config):
        super().__init__(config)
        self.wte = nn.Embedding(self.vocab_size, self.embed_dim)
        self.ln_f = RMSNorm(self.embed_dim,
eps=config.layer_norm_epsilon)
class QWenBlock(nn.Module):
    def __init__(self, config):
        super().__init__()
        hidden_size = config.hidden_size
        self.bf16 = config.bf16
        self.ln_1 = RMSNorm(hidden_size,
eps=config.layer_norm_epsilon)
        self.attn = QWenAttention(config)
        self.ln_2 = RMSNorm(hidden_size,
eps=config.layer_norm_epsilon)
        self.mlp = QWenMLP(config)
class QWenAttention(nn.Module):
    def __init__(self, config):
        super().__init__()
        self.c_attn = nn.Linear(config.hidden_size, 3 *
self.projection_size)
        self.c_proj = nn.Linear(config.hidden_size,
self.projection_size,
                                bias=not config.no_bias)
class QWenMLP(nn.Module):
    def __init__(self, config):
        super().__init__()
        self.w1 = nn.Linear(config.hidden_size,
config.intermediate_size // 2,
                            bias=not config.no_bias)
        self.w2 = nn.Linear(config.hidden_size,
config.intermediate_size // 2,
                            bias=not config.no_bias)
        ff_dim_in = config.intermediate_size // 2
        self.c_proj = nn.Linear(ff_dim_in, config.hidden_size,
                                bias=not config.no_bias)

cross attention をサポートするモデルを含むcustommodel conversionについては、参考用の Hugging Face モデル構造を提供しています。custom設定fileはas follows。

{
  "BLOCKNAME": "CustomDecoderLayer",
  "TOKEN_EMBD": "embed_tokens",
  "ATTN_NORM": "input_layernorm",
  "ATTN_Q_NORM": "",
  "ATTN_K_NORM": "",
  "CROSS_ATTN_NORM": "cross_layernorm",
  "CROSS_ATTN_Q": "cross_attn.cross_q_proj",
  "ATTN_Q": "",
  "ATTN_K": "",
  "ATTN_V": "",
  "ATTN_QKV": "self_attn.qkv_proj",
  "ATTN_KV": "",
  "KV_CONTINUOUS": "true",
  "ATTN_OUT": "self_attn.o_proj",
  "CROSS_ATTN_OUT": "cross_attn.cross_o_proj",
  "ATTN_POST_NORM": "",
  "FFN_NORM": "post_attention_layernorm",
  "FFN_UP": "mlp.up_proj",
  "FFN_GATE": "mlp.gate_proj",
  "ACT_TYPE": "silu",
  "FFN_DOWN": "mlp.down_proj",
  "FFN_POST_NORM": "",
  "OUTPUT_NORM": "norm",
  "OUTPUT": "lm_head"
}

7. old versionモデル更新

Version 1.0.2 と 1.1 以降のVersionには大きな差分があるin order to、1.0.2 版モデルを最新Versionへ更新するin order toの rkllm.update_rkllm() functionが提供されています。モデル更新時は、前述のモデルloadandbuildprocedureをexecutionする必要はなく、このインターフェースを直接呼び出して更新can。更新後も、モデルのquantization型などのparameterは変更されません。rkllm.update_rkllm() functionのparameter定義はas follows。

表 5 update_rkllm functioninterface specification

function nameupdate_rkllm
descriptionVersion 1.0.2 のモデルを最新Versionへ更新します。
parametermodel: Version 1.0.2 の RKLLM モデルpath。
return value0 はモデル更新成功、-1 はモデル更新失敗をindicates。

sample codeはas follows。

ret = llm.update_rkllm(model = "./model_1.0.2version.rkllm")
if ret != 0:
    print('Load model failed!')
    exit(ret)

8. simulationaccuracyevaluation

rkllm.build() functionで RKLLM モデルをbuildした後、rkllm.get_logits() functionを使用して PC 上でsimulationaccuracyevaluationを行うことがcan。rkllm.get_logits() functionのparameter定義はas follows。

表 6 get_logits functioninterface specification

function nameget_logits
descriptionPC 上でsimulationaccuracyevaluationを行うin order toにis used。
parameterinputs: simulationinput形式は Hugging Face model inferenceと同じです。例：
{“input_ids”:"", “top_k”:1, …}
return valuemodel inferenceで得られた logits valueをreturns。

このfunctionを使用して wikitext dataセットの PPL をevaluationするsample codeはas follows。

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("\n\n".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)}')

9. simulationmodel inference

rkllm.build() functionで RKLLM モデルをbuildした後、rkllm.chat_model() functionを使用して PC 上でsimulationinferenceを行うことがcan。rkllm.chat_model() functionのparameter定義はas follows。

表 7 chat_model functioninterface specification

function namechat_model
descriptionPC 上でsimulationmodel inferenceを行うin order toにis used。
parametermessages: textinputです。対応するプロンプトを付加するis required。
args: inference設定parameterです。例as top_k などのサンプリング戦略parameterを指定します。
return valueモデルのinference結果をreturns。

sample codeはas follows。

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 によるmodel conversionandquantizationの全体procedureを網羅しています。要件や適用シナリオに応じて、異なる設定オプションandquantization方式を選択し、後続のデプロイに向けて柔軟にカスタマイズcan。