3. 模型推理

LLM Converter 提供 run_llm 与 run_serve 两种推理工具，分别面向功能验证和生产部署两个关键阶段。以下是两者的详细对比：

工具	run_llm.py	run_serve.py
用途定位	模型转换后的功能验证与单次推理测试	生产环境部署
调用接口	命令行（CLI）调用	HTTP API（兼容 OpenAI 格式）
并发支持	单次顺序执行	支持多客户端并发请求
运行模式	单线程顺序执行	支持多客户端并发请求与队列管理
任务管理	手动执行，无内置调度	内置请求队列与自动调度
适用场景	模型功能验证、转换测试、调试分析	在线推理服务、多模态集成、云服务部署

下面将分别针对上述两种工具的使用进行介绍。

1. run_llm推理模型

在 LLM Converter 框架中，run_llm 作为大语言模型的直接推理接口，用于执行一次完整的推理任务并输出模型运行结果。该模块主要用于验证模型转换后的功能完整性，检测模型加载、分词器配置及推理流程的正确性，帮助开发者在部署前及时发现并定位问题。

支持文本、图像、视频、音频等多种输入类型。

1.1 使用方法

简单使用示例：

python3 Tool/Scripts/LLM_Converter/run_llm.py \
-d=SGS_LLM_Models/Qwen/Qwen1.5-0.5B/output_models \
--prompt "Give me a short introduction to large language model."

可支持配置的参数说明：

1.1.1 基本参数

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

-- 作用: 指定包含 SGS LLM 模型和配置文件的目录。

-- 使用方法:

```
python3 run_llm.py -d /path/to/output_model
```

使用须知

即执行convert_hf_to_sim.py时-o / --output指定的文件夹路径。

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

-- 作用: 指定包含 tokenizer 文件和配置的目录。

-- 使用方法:

```
python3 run_llm.py -t /path/to/tokenizer
```

使用须知

当且仅当output_models目录中没有产生tokenizer相关文件时才需手动指定。

执行convert_hf_to_sim.py时如果没有产生tokenizer相关文件会出现以下提示语句：

Please use the -t parameter when running run_llm to specify the tokenizer directory.

此时执行运行指令就需要配置-t参数

1.1.2 数据处理参数

以下参数主要为问答模板tokenize_template.py服务：

💡 (1) --prompt:

-- 作用: 指定文本输入，支持中文、英文等各种文本, 默认为 Hello

-- 使用方法:
```
python3 run_llm.py --prompt "Hello"
```

💡 (2) --image:

-- 作用: 指定图像输入，JPG、PNG等常见图像格式

-- 使用方法:
```
python3 run_llm.py  --image /path/to/image.jpg
```

💡 (3) --video:

-- 作用: 指定视频输入

-- 使用方法:
```
python3 run_llm.py --video /path/to/video.mp4
```

💡 (4) --wav_file:

-- 作用: 指定音频输入

-- 使用方法:
```
python3 run_llm.py  --wav_file audio1.wav audio2.wav
```

💡 (5) --use_audio_in_video:

-- 作用: 视频输入配合参数，指定是否处理视频中的音频信息，默认False

-- 使用方法:
```
python3 run_llm.py  --use_audio_in_video
```

💡 (6) --max_num:

-- 作用: 图像预处理时的最大数量限制，默认为1

-- 使用方法:
```
python3 run_llm.py  --max_num 1
```

1.1.3 模型配置参数

💡 (1) --no_streamer:

-- 作用: 是否禁用流式输出，默认为False

-- 使用方法:
```
python3 run_llm.py  --no_streamer
```

💡 (2) --processor_decode:

-- 作用: 是否使用处理器解码，默认为False

-- 使用方法:
```
python3 run_llm.py  --processor_decode
```

1.1.4 系统参数

💡 (1) --soc_version:

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

-- 使用方法：
```
python3 run_llm.py  --soc_version CHIP
```

💡 (2) --show_log:

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

-- 使用方法：
```
python3 run_llm.py  --show_log
```

1.1.5 RPC配置参数

💡 (1) --host:

-- 作用：设置IPU 服务器主机地址

-- 使用方法：
```
python3 run_llm.py  --host 192.168.1.100
```

💡 (2) --port:

-- 作用：设置IPU 服务器端口

-- 使用方法：
```
python3 run_llm.py  --port 8080
```

💡 (3) --model_onboard_dir:

-- 作用：指定 模型在IPU上的加载目录

-- 使用方法：
```
python3 run_llm.py  --model_onboard_dir /path/to/model
```

💡 (4) --timeout:

-- 作用：设置IPU服务器超时时间（秒），默认60

-- 使用方法：
```
python3 run_llm.py  --timeout 120
```

📋 参数依赖关系说明：

1. 基础必需：-d 为必须参数

2. • --image 用于图像理解
   • --video + --use_audio_in_video 用于视频理解
   • --wav_file 用于音频处理

3. 输出控制：--no_streamer 用于非流式输出，--processor_decode 用于特殊解码（如Florence-2-base二次解码）

2. run_serve推理模型

在 LLM Converter 框架中，run_serve 是将大语言模型部署为生产级 HTTP API 服务的核心工具。该服务器将转换后的模型封装为高性能、可扩展的 API 端点，并提供以下能力：

- 统一推理服务：支持文本与多模态模型的集成处理，实现单一服务端对多种输入类型的兼容。

- 标准化接口：采用 OpenAI 兼容的 API 设计，便于集成现有工具与客户端应用。

- 生产级部署：内置并发处理、资源管理与服务监控能力，满足高可用和高性能的生产环境需求。

通过 run_serve，开发者可将优化后的模型快速部署为稳定、可扩展的云服务。

2.1 使用方法

1、终端运行示例：

python3 Tool/Scripts/LLM_Converter/run_serve.py \
-d=SGS_LLM_Models/Qwen/Qwen1.5-0.5B/output_models \
--port 8013

2、远程到开发板推理:

Linux SDK-alkaid已提供sdk/verify/release_feature/source/dla/ipu_server的app。

使用过程如下：

(1) 首先，板端运行ipu_server开启RPC服务（PORT为设定的port号）

./prog_dla_ipu_server -p PORT

(2) 其次，PC端运行run_serve.py

python3 Tool/Scripts/LLM_Converter/run_serve.py \
-d=SGS_LLM_Models/Qwen/Qwen1.5-0.5B/output_models \
--port 8013
--ipu_host 10.44.16.3
--ipu_port 3333
--model_onboard_dir /path/to/model/on/borad/

可支持配置的参数说明：

2.1.1 基本参数

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

-- 作用: 指定包含 SGS LLM 模型和配置文件的目录。

-- 使用方法:

```
python3 run_llm.py -d /path/to/output_model
```

使用须知

即执行convert_hf_to_sim.py时-o / --output指定的文件夹路径。

💡 (2) -t, --tokenize:（可选参数）

-- 作用: 指定包含 tokenizer 文件和配置的目录。

-- 使用方法:

```
python3 run_llm.py -t /path/to/tokenizer
```

使用须知

当且仅当output_models目录中没有产生tokenizer相关文件时才需手动指定。

执行convert_hf_to_sim.py时如果没有产生tokenizer相关文件会出现以下提示语句：

Please use the -t parameter when running run_llm to specify the tokenizer directory.

此时执行运行指令就需要配置-t参数

2.1.2 硬件参数

💡 (1) --host:

-- 作用：设置IPU 服务器主机地址

-- 使用方法：
```
--host 192.168.1.100
```

💡 (2) --port:

-- 作用：设置IPU 服务器端口

-- 使用方法：
```
--port 8080
```

💡 (3) --model_onboard_dir:

-- 作用：指定 模型在IPU上的加载目录

-- 使用方法：
```
--model_onboard_dir /path/to/model
```

💡 (4) --timeout:

-- 作用：设置IPU服务器超时时间（秒），默认60

-- 使用方法：
```
--timeout 60
```

💡 (5) --ipu_host:

-- 作用：设置IPU 硬件服务器主机地址

-- 使用方法：
```
--ipu_host 192.168.1.100
```

💡 (6) --ipu_port:

-- 作用：设置IPU 硬件服务器端口

-- 使用方法：
```
--ipu_port 8080
```

2.1.3 系统参数

💡 (1) --soc_version:

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

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

💡 (2) --show_log:

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

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

💡 (3) --log_level:

-- 作用：设置输出详细的转换过程日志信息类型

-- 使用方法：
```
--log_level 'info'
```

使用须知

可选值

• debug: 调试信息（最详细）

• info: 一般信息（默认）

• warning: 警告信息

• error: 错误信息（最少）

💡 (4) --verbose_logs:

-- 作用：是否启用详细日志，默认False

-- 使用方法：
```
--verbose_logs
```

💡 (5) --max_history_tokens:

-- 作用：设置最大历史 token 数量，默认值2048

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

2.1.4 性能参数

💡 (1) --smart_processing_mode:

-- 作用：设置智能处理模式

-- 使用方法：
```
--smart_processing_mode balanced
```

使用须知

可选值

• conservative: 保守模式 - 优先稳定性，适合关键任务

• balanced: 平衡模式（默认）- 性能与稳定性平衡

• aggressive: 激进模式 - 优先性能，适合高并发场景

💡 (2) --max_queue_size:

-- 作用：设置请求队列最大长度，默认50

-- 使用方法：
```
--max_queue_size 50
```

💡 (3) --max_concurrent:

-- 作用：设置最大并发处理数，默认1
-- 使用方法：
```
--max_concurrent 1
```

2.2 多轮对话运行方法参考

运行方法示例：

step1:开启终端运行：

python3 run_serve.py
-d Qwen2.5/output_models/
--port 8013

step2:开启另一个终端运行：

curl -X POST http://localhost:8013/v1/chat/completions
 -d '{
      "messages": [
        {"role": "user", "content": "你好，请介绍一下你自己"}
      ],
      "stream": true
    }'

如需开启下一轮对话再通过curl提问即可，无需重复启动run_serve功能。

---

3. 开发板python环境部署与LLM推理

本节仅适用于安装了 Ubuntu 系统的 IPU 开发板。开发板内存空间有限，加之 Python 运行环境及依赖库本身需占用较多内存，仅适合运行参数量较小的 LLM 模型。大参数模型请参照前两节通过 PC 端执行推理。

在 Ubuntu 开发板上直接搭建 Python 运行环境后，无需依赖 PC 端即可在板端独立完成模型推理。

板端推理的底层调用链路如下：run_llm.py / run_serve.py 在导入 calibrator_custom 时，通过 platform.machine() 检测到当前为 aarch64 架构，自动加载 py_ipu_adapter 以替代 x86_64 平台使用的 py_wrapper 等本地库。其中 py_ipu_adapter 的核心组件包括：

• py_ipu：已编译为 aarch64 原生共享库的推理引擎，其 IPUModel 类直接调用板端 IPU 驱动，提供 alloc_buffer、set_input、invoke、get_output 等底层接口，负责模型加载与算子执行；
• stubs：为 sgs_chalk（计算图构建）、compile_offline（离线编译）、calibrator（量化校准）等仅 x86_64 可用的模块提供空实现占位，保证推理代码能正常 import 而不触发链接错误。

上层推理脚本无需感知平台差异，同一份 run_llm.py / run_serve.py 代码在 PC 端和板端均可直接运行。

3.1 环境搭建

1. 安装系统依赖

sudo apt install python3-pip libgl1

2. 安装 IPU Python 包

py_ipu 离线 wheel 包一般位于 /usr/local/share 目录下，请根据 Python 版本选择对应的 .whl 文件：

python3 -m pip install py_ipu-1.0.0-py3-none-linux_aarch64.whl

3. 安装 Python 依赖库

# PyTorch（CPU 版本）
python3 -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# 其他依赖
python3 -m pip install \
    opencv_python==4.11.0.86 \
    transformers==4.57.3 \
    Pillow==11.2.1 \
    onnx==1.17.0 \
    joblib==1.4.2 \
    accelerate==1.3.0 \
    flatbuffers==25.2.10 \
    attrdict \
    einops==0.8.1 \
    timm==1.0.15 \
    draccus==0.11.5 \
    imageio==2.37.0 \
    uvicorn==0.38.0 \
    fastapi==0.124.4 \
    aiohttp==3.13.2 \
    -i https://mirrors.aliyun.com/pypi/simple

4. 配置 bootargs

确保内核启动参数中包含以下关键项,并且MMA建议预留1.5GB：

mma_heap=mma_heap_name0,miu=0,sz=0x60000000

3.2 模型推理

环境搭建完成后，将转换好的模型目录（output_models/）拷贝至板端，即可直接运行推理。

run_llm 单次推理：

python3 run_llm.py -d=./Qwen3-0.6B/ --prompt "Hello"

run_serve 服务模式：

python3 run_serve.py -d=./Qwen3-0.6B/ --port 8888

服务启动后，可使用 Cherry Studio 或其他兼容 OpenAI API 的前端工具，通过 http://<板端IP>:8888 连接进行多轮对话。