2. 模型转换

LLM_Converter支持将 Hugging Face 格式的大语言模型转换为 IPU 平台可执行的推理模型。

工作流程说明：

使用converter_hf_to_sim.py将 Hugging Face 模型转换为 IPU 格式的模型，转换过程中converter_hf_to_sim.py通过调用当前工具已支持的模型构建脚本进行模型搭建工作和模型转换工作。

本章将详细介绍如何使用converter_hf_to_sim工具将Hugging Face 格式的预训练模型转换为 IPU 平台支持的推理格式。

1. 模型转换准备

进行模型转换前，请准备以下文件：

Hugging Face 预训练模型下载后主要配置文件：

- 📋核心配置文件：
   config.json (模型架构和参数的完整定义配置文件)

   pytorch_model.bin / model.safetensors (模型权重文件)

   tokenizer.json / tokenizer_config.json (分词器配置文件)

- 📋其他重要文件
    generation_config.json (文本生成参数配置文件)

    vocab.txt / merges.txt / tokenizer.model (分词器词汇文件)

    special_tokens_map.json (特殊token映射文件)

    modelcard.md / README.md (模型卡片文档)

- 📋可选文件
   preprocessor_config.json (多模态模型配置)

   adapter_config.json (适配器模型配置)

---

2. 模型转换工具使用指南

convert_hf_to_sim.py 是 LLM Converter 工具的核心脚本，用于将 Hugging Face 格式的预训练模型转换为 IPU 平台支持的推理格式。本章将详细介绍该脚本的完整使用流程，指导用户完成模型转换的各个步骤, 使用convert_hf_to_sim.py转换模型示意图：

模型转换流程说明：

① Hugging Face模型文件

② Hugging Face模型配置文件

送入模型转换工具LLM_converter，

即可获得IPU 平台支持格式的模型和适配IPU平台推理的配置文件。

下面将详细介绍如何使用convert_hf_to_sim.py脚本转换Hugging Face 格式的模型。

模型转换流程概览

转换工具内部按以下三个阶段依次执行：

阶段	说明	产物
Phase 1: 模型转换	PyTorch → ONNX → Chalk → Float SIM	decoder_model_float.sim 等
Phase 2: 量化校准	仅当指定 --inputs 时执行，通过校准数据推理收集统计信息后进行量化	decoder_model_fixed.sim 等
Phase 3: 离线编译	Fixed → Offline，生成最终可部署模型（默认）	*.sim_sgsimg.img

若仅执行基础转换（不指定 --inputs），将只完成 Phase 1，输出浮点模型；若模型本身已包含权重量化信息（如 AWQ/GPTQ 模型），工具可直接跳过 Phase 2 一步生成离线模型。

转换工具支持以下三种转换模式，所需参数不同：

场景	适用模型	核心参数
原生 AWQ/GPTQ 模型	官方预训练权重量化模型，保留或去除已有量化信息后直接转换	--keep_quantized_weights / --dequantize_weights
SGS 量化模型	浮点模型 + SGS 量化库，配合校准数据量化后转换	--inputs / -q / --quant_config / --quant_level
全 FP16 转换	不执行量化，所有张量统一转为 FP16 格式	--all_fp16

下面将分类详细介绍各参数的用法。

2.1. 基本语法

converter_hf_to_sim.py 是将 Hugging Face 模型转换为 IPU 格式的核心工具。该工具支持浮点、量化及多模态等多种转换模式，并提供丰富的可配置选项，以满足不同场景下的部署需求，下面将详细介绍该脚本的使用方法。

运行以下命令，指定Hugging Face模型目录路径即可完成基础转换：

python3 converter_hf_to_sim.py -d /path/to/hf_model

执行此命令将完成以下操作：

1、读取模型：从 -d 参数指定的目录加载Hugging Face格式模型

2、执行转换：使用工具默认参数进行模型转换与优化

3、输出结果：在输入目录下自动创建 output_models 子目录，保存生成的IPU优化模型文件

2.1.1 output_models文件夹内容说明

转换完成后，输出目录包含：

output_models/
├── *.sim                   # 优化后的模型文件,包含decoder和norm_head模型文件
├── *.ini,*.json,*.npy      # 模型配置文件，包含数据文件和转换配置文件
└── tokenize_template.py    # 分词器模板

💡 (1)decoder_model_float.sim / norm_head_float.sim

说明

IPU模型采用解耦架构设计，将核心计算（decoder）与输出处理（norm_head）分离，decoder网络执行多层的注意力机制和前馈计算，而norm_head网络负责最终的层归一化和输出投影。

💡 (2)input_config_decoder_model.ini / input_config_norm_head.ini

说明

为了简化部署流程，推理配置所需文件ini由后台自动生成，无需手动设置。

💡 (3)config.json

说明

config.json是基于原始HuggingFace模型配置文件适配IPU的修改版本，新增了SGS_Model_Info键值对。该字段由系统自动填充，用于指定IPU推理时所需的模型文件和ini配置文件路径及数据文件。无需手动维护。如需切换推理模型阶段，可手动修改SGS_Model_Info中的model字段。

SGS_Model_Info键值对内容展示：

"SGS_Model_Info": {
    "decoder_model": [
        "decoder_model_float.sim", # decoder模型文件，修改此处用于切换模型推理阶段
        "input_config_decoder_model.ini" # decoder配置文件
    ],
    "norm_head": [
        "norm_head_float.sim", # norm_head模型文件，修改此处用于切换模型推理阶段
        "input_config_norm_head.ini" # norm_head配置文件
    ],
    "token_embedding_weight": "token_embedding_weight.npy", # 词表数据文件
    "sin_weight": "sin_weight.npy", # 旋转因子数据文件
    "cos_weight": "cos_weight.npy"  # 旋转因子数据文件
},

💡 (4)generation_config.json

说明

基于原始HuggingFace模型配置文件生成，通常无需关注。

💡 (5)sin_weight.npy / cos_weight.npy

说明

旋转因子数据文件。

💡 (6)token_embedding_weight.npy

说明

词表数据文件。

💡 (7)tokenize_template.py

说明

问答模板。LLM_Converter框架提供默认问答模板生成机制，通过各模型对应的*_modeling.py中的tokenize_template接口实现。支持用户自定义：

问答模板生成流程：

1. 框架调用*_modeling.py中的tokenize_template()函数
2. 生成的模板存储于tokenize_template.py
3. 如需定制：修改对应模型的tokenize_template接口
4. 要求：函数必须返回字典格式的模板

2.2 高级语法

执行以下命令可查看所有可配置参数及其说明：

python3 converter_hf_to_sim.py -h

2.2.1 基本参数

💡 (1) -d，--dir:（必选参数）

-- 作用: 指定包含Hugging Face模型和配置文件的目录路径

-- 使用方法:

```
python3 convert_hf_to_sim.py -d /path/to/hf_model
```

使用须知

该目录必须包含：

• config.json（模型配置文件）

• pytorch_model.bin 或 .safetensors（模型权重文件）

• 其他必需的模型相关文件

💡 (2) -o, --output:（可选参数）

-- 作用：指定输出模型的目录路径

-- 使用方法：
```
-o output_dir
```

使用须知

如不指定此参数，工具将在输入模型目录下自动创建 output_models 目录作为默认输出位置。

2.2.2 模型配置参数

💡 (1) -t, --tokenize_dir: （可选参数）

-- 作用：指定包含分词器文件和配置的自定义目录

-- 使用方法：
```
-t /path/to/tokenizer
```

使用须知

默认为 None。仅在需要自定义分词器配置或使用非标准分词器路径时设置。

💡 (2) --n_tokens: （可选参数）

-- 作用：设置预填充阶段LLM模型单次处理的最大token数量

-- 使用方法：
```
--n_tokens 128
```

使用须知

默认为128。

用于精细控制预填充阶段的批处理规模，直接影响内存占用与计算效率

💡 (3) --encoder_tokens: （可选参数）

-- 作用：设置 Marian/Florence2 等 Encoder-Decoder 架构模型中 Encoder 输入的最大 token 数量

-- 使用方法：
```
--encoder_tokens 256
```

使用须知

默认为 None，即使用各模型 modeling 脚本中定义的默认值（Marian: 128, Florence2: 786）。仅在需要覆盖默认 encoder token 数量时设置。

💡 (4) --max_length: （可选参数）

-- 作用：设置LLM模型支持处理的最大token数量。

-- 使用方法：
```
--max_length 2048
```

使用须知

默认为2048。

2.2.3 数据处理参数

💡 (1) --imgsz: （可选参数）

-- 作用：设置输入图像的尺寸（宽度, 高度），在多模态模型转换过程中，用于指定图像预处理的目标分辨率

-- 使用方法：
```
--imgsz 224 224
```

💡 (2) --videosz: （可选参数）

-- 作用：设置输入视频的尺寸格式（时长, 通道数, 高度, 宽度），用于视频类多模态模型的转换与处理

-- 使用方法：
```
--videosz 10 3 224 224
```

💡 (3) --visual_input_formats: （可选参数）

-- 作用：指定多模态视觉模型的输入数据格式，用于适配不同图像预处理管线

-- 使用方法：
```
--visual_input_formats YUV_NV12
```

使用须知

可选值：YUV_NV12 / RGBA / BGRA / BGR / RGB / GRAY。请根据模型预处理要求与输入数据格式选择匹配的类型。

2.2.4 量化参数

💡 (1) --inputs: （可选参数）

-- 作用：这个参数仅对于转换SGS量化模型使用，指定量化校准数据 JSON 文件路径，用于 SGS 量化库的模型转换。
        如果是Qwen3-0.6b的纯文本模型，格式为 `[{"prompt": "文本"}, ...]`
        如果是Qwen2.5-VL的VLM模型，格式为 `[{"image": "图像路径", "prompt": "文本"}, ...]`

每种类型的模型的量化校准数据 JSON 文件构造方法不一样，具体参加详见已支持模型中支持SGS 量化的模型量化校准数据 JSON 构造方法。

-- 使用方法：
```
--inputs inputs_text.json
```

使用须知

如果是纯文本的LLM模型，每条 prompt 长度应尽可能长，建议 100 字以上，过短的文本会导致量化统计信息不足。详见快速上手中的 SGS 量化模型转换章节。如果是VLM的多模态模型，因为图像token数量相对较大，所以对 prompt 的长度没有严格要求。

💡 (2) -q, --q_mode: （可选参数）

-- 作用：这个参数仅对于转换SGS量化模型使用，设置模型量化模式，这个参数是可选参数，默认可以不传，

-- 使用方法：
```
-q q_mode1 q_mode2 q_mode3 ...
```

q_mode 说明见模型转换 4.2.3 torch_calibrator工具详解 torch_calibrator量化参数 -q / --q_mode 详解。

默认LLM的decoder是用Q16量化，norm_head是用Q10量化，其余模型是用Q25量化。

需要注意的是，q_mode 设置的顺序要和模型的顺序一一对应，工具链会打印出模型和对应设置的q_mode，用户可以自行调整。

💡 (3) --quant_config: （可选参数）

-- 作用：这个参数仅对于转换SGS量化模型使用，指定量化配置 YAML 文件路径，用于自定义量化参数

-- 使用方法：
```
--quant_config /path/to/quant_config1.yaml /path/to/quant_config2.yaml /path/to/quant_config3.yaml ...
```

quant_config 说明见模型转换 4.2.3 torch_calibrator工具详解 torch_calibrator配置文件 quant_config.yaml 详解。

默认情况下工具链会配置好LLM decoder模型的quant_config.yaml，并生成在当前执行目录下。

需要注意的是，quant_config 设置的顺序要和模型的顺序一一对应，工具链会打印出模型和对应设置的quant_config，用户可以自行调整。

💡 (4) --quant_level: （可选参数）

-- 作用：这个参数仅对于转换SGS量化模型使用，设置量化等级，控制量化精度与性能的平衡

-- 使用方法：
```
--quant_level L6
```
工具链默认使用torch_calibrator量化，所以quant_level默认是None

使用须知

不同芯片支持的量化等级不同，请根据目标芯片选择合适的等级。若 --quant_level 与 --q_mode 同时指定，工具将报错。 并且对于支持fp16的soc,quant_level只支持设置L6,L6-1

💡 (5) --quant_maxlength: （可选参数）

-- 作用：这个参数仅对于转换SGS量化模型使用，设置用作量化的decoder模型的maxlength，默认值为 2048

-- 使用方法：
```
--quant_maxlength 2048
```

💡 (6) --save_quant_info: （可选参数）

-- 作用：这个参数仅对于转换SGS量化模型使用，保存模型量化信息，便于后续调试与分析，默认 False

-- 使用方法：
```
--save_quant_info
```

💡 (7) --gen_quant_data_only: （可选参数）

-- 作用：这个参数仅对于转换SGS量化模型使用，仅生成量化校准数据而不执行完整转换，用于预先生成量化输入数据供后续复用，默认 False

-- 使用方法：
```
--gen_quant_data_only
```

💡 (8) --dequantize_weights: （可选参数）

-- 作用：这个参数仅对于转换原始AWQ模型使用，将已量化的LLM模型权重转换回浮点格式,适用于需要还原模型至浮点精度进行调试、分析或后续处理的场景，默认False

-- 使用方法：
```
--dequantize_weights
```

💡 (9) --keep_quantized_weights: （可选参数）

-- 作用：这个参数仅对于转换原始AWQ模型使用，在转换过程中保留量化LLM的权重及量化参数,适用于需要在保留量化信息的同时进行模型格式转换或调试的场景，默认True

-- 使用方法：
```
--keep_quantized_weights
```

使用须知

⚠️--dequantize_weights和--keep_quantized_weights是互斥开关，两者均无需配置具体数值，仅需在命令中指定参数本身即可生效。同一命令中不可同时使用，请在运行时根据需求选择其一

错误示范1：
python3 convert_hf_to_sim.py -d /path/to/hf_model --keep_quantized_weights --dequantize_weights

错误示范2：
python3 convert_hf_to_sim.py -d /path/to/hf_model --keep_quantized_weights False

错误示范3：
python3 convert_hf_to_sim.py -d /path/to/hf_model --dequantize_weights True

正确示范：
python3 convert_hf_to_sim.py -d /path/to/hf_model --keep_quantized_weights
或
python3 convert_hf_to_sim.py -d /path/to/hf_model --dequantize_weights

2.2.5 模型状态参数

💡 (1) -p: （可选参数）

-- 作用：指定 Hugging Face 模型转换至目标平台框架时所输出的具体阶段模型。

-- 使用方法：
```
-p Float 或 -p Fixed
```

使用须知

可选值

• Float: 浮点转换

• Fixed: 定点转换

• Fixed_without_ipu_ctrl: 不含 IPU 控制的定点转换

• Offline: 离线转换(默认)

说明：如需导出包含中间阶段的模型，可在执行转换前于终端中配置环境变量：

export LLM_DEBUG=1

启用后，工具生成的模型将保留各中间阶段的模型信息，便于调试与分析。

2.2.6 性能优化参数

💡 (1) --all_fp16: （可选参数）

-- 作用：将模型中所有可转换张量统一转换为FP16浮点格式，适用于对精度要求相对宽松的部署场景

-- 使用方法：
```
--all_fp16
```

重要提示

⚠️用 --all_fp16 参数转换的模型，其运行速度较低、体积较大、效率较差，如对性能有较高要求，请谨慎选用。

💡 (2) --num_process: （可选参数）

-- 作用：设置并行转换的进程数，用于加速大规模模型的转换过程，默认值为 1, 因为LLM参数量大，转换过程中占用内存较大，请谨慎开启多进程

-- 使用方法：
```
--num_process 4
```

2.2.7 系统参数

💡 (1) --soc_version: （必选参数）

-- 作用：设置IPU的SoC版本

-- 使用方法：
```
--soc_version CHIP
```

💡 (2) --show_log: （可选参数）

-- 作用：实时输出详细的转换过程日志信息，便于开发者在转换过程中进行实时调试、状态监控与问题排查

-- 使用方法：
```
--show_log
```

💡 (3) --num_soc: （可选参数）

-- 作用：设置目标 SoC 芯片数量，用于级联部署场景。默认为 1（非级联模式），设为 2 表示使用两块 SoC 芯片级联推理， 目前只支持2块soc芯片级联

-- 使用方法：
```
--num_soc 2
```

使用须知

目前仅支持两块 SoC 芯片级联。级联模式下的转换与运行请参考快速上手中的级联模型章节。

💡 (4) --work_mode: （可选参数）

-- 作用：设置校准器工作模式，根据目标芯片支持的模式选择

-- 使用方法：
```
--work_mode mode_name
```

使用须知

可选值由当前 SDK 版本自动检测，可通过执行 python3 -c "import calibrator_custom; print(calibrator_custom.get_supported_work_mode())" 查看支持的选项。

💡 (5) --tts: （可选参数）

-- 作用：启用 TTS（Text-to-Speech）文本转语音转换功能，适用于语音合成类模型，默认 False

-- 使用方法：
```
--tts
```