LLM_and_VLM Demo 使用说明

---

1. 功能场景介绍

本示例演示如何在开发板上实现同时支持 LLM 文本对话和 VLM 图文理解的 OpenAI API 服务部署。

1.1. 主要特性

• LLM 文本对话：支持通过 OpenAI API 发起文字对话请求
• VLM 图文理解：支持通过 OpenAI API 发起包含图片的图文理解请求
• PCIE 级联：支持通过 PCIE 级联两块开发板的算力进行模型推理
• OpenAI API 兼容：对接标准的 OpenAI API 接口，用户可通过发起 HTTP 请求来调用该 demo 的模型推理功能
  • /v1/models：查询当前支持哪些模型
  • /v1/chat/completions：支持文字对话和图片理解
• 流式响应：支持流式和非流式两种响应模式
• KV 缓存管理：自动管理对话上下文

---

2. 编译环境说明

2.1 编译环境设置

在项目根目录下设置 arm64 编译环境：

export PATH=/tools/toolchain/aarch64-unknown-linux-gcc-12.4.0-glibc-2.37-gnu/bin:$PATH
export CROSS_COMPILE=aarch64-unknown-linux-gnu-12.4.0-
export ARCH=arm64
cd project
make linux-comake_mhera.emmc.glibc-12.4.0-arm64-ext4.d3.4096.fccsp16_lpddr4x_defconfig

如果选用2GB的ddr，defconfig可以使用 linux-comake_mhera.emmc.glibc-12.4.0-arm64-ext4.d3.2048.fccsp16_lpddr4x_defconfig

2.2 编译命令

# 编译整个 project
cd project
make clean;make image -j16

# 编译 LLM_and_VLM demo
cd sdk/verify/sample_code
make llm_and_vlm

# 清理编译产物
make llm_and_vlm_clean

# 编译 IPU service（PCIE 级联场景需要）
cd ../release_feature
make source/ipu/ipu_service

2.3 编译产物

• sgs_demo_llm_and_vlm 可执行文件位于 sample_code/out/arm64/app 目录下
• prog_ipu_ipu_service 可执行文件位于 ../release_feature/out/arm64/app 目录下（PCIE 级联场景需要）

---

3. 运行环境搭建

3.1 软件要求

• Cherry Studio（可选）：用于提供图形化的对话界面，详见"4.2.1 Cherry Studio 说明"章节

3.2 网络环境

运行时需要和发起 HTTP 请求的设备之间可以互相 ping 通。参考以下自会名固定板端IP：

# 使能网口
ifconfig eth0 up

# 设置 MAC 地址（可选，有的板子需要）
ifconfig eth0 hw ether 00:83:16:00:00:01

# 设置 IP 地址和子网掩码
ifconfig eth0 192.168.1.100 netmask 255.255.255.0

# 设置网关
route add default gw 192.168.1.254

# 确认配置
ifconfig eth0

          开发板                                         PC 端
    ┌─────────────────────────┐                   ┌───────────────────────┐
    │  固定IP：192.168.1.100  │◄─────────────────►│  固定IP:192.168.1.200 │
    └─────────────────────────┘    网线直连       └───────────────────────┘

3.3 模型文件

运行时需要模型文件支持，文件需要按照如下目录放置：

sgs_demo_llm_and_vlm        # 板端服务器可执行文件
models                      # 模型存放公共根目录
    LLM                     # LLM 模型存放目录（非 PCIE 级联场景）
    VLM                     # VLM 模型存放目录（非 PCIE 级联场景）
    PCIE_LLM                # PCIE 级联场景的 LLM 模型存放目录

LLM、VLM、PCIE_LLM 模型均可在 models 目录中，包含以下文件：

• ipu.json：模型配置文件，描述模型的输入输出格式、参数等
• generation_config.json：模型生成配置参数
• 模型权重文件和相关配置文件

注意：

• 非 PCIE 级联场景根据使用需求选择 LLM 或 VLM 目录中的模型文件
• PCIE 级联场景使用 PCIE_LLM 目录中的模型文件
• 确保所有模型文件完整且版本匹配

---

3.4 非 PCIE 级联场景环境搭建

3.4.1. 开发板 bootargs 配置

按住回车键后开启开发板电源，进入 uboot 环境，使用 printenv 查看 bootargs 参数，类似如下打印：

bootargs=ubi.mtd=ubia,2048 root=/dev/mtdblock6 rootfstype=squashfs ro init=/linuxrc LX_MEM=0x1000000000,0x100000000 cma=2M mma_heap=mma_heap_name0,miu=0,sz=0x20000000 mma_memblock_remove=1 mtdparts=nand0:1920k@1280k(BOOT),1920k(BOOT_BAK),256k(ENV),256k(ENV1),5m(KERNEL),5m(KERNEL_BACKUP),4m(rootfs),1152k(MISC),109952k(ubia)

将其中的 mma_heap sz 修改为 0x70000000 后保存并重启：

set bootargs ubi.mtd=ubia,2048 root=/dev/mtdblock6 rootfstype=squashfs ro init=/linuxrc LX_MEM=0x1000000000,0x100000000 cma=2M mma_heap=mma_heap_name0,miu=0,sz=0x70000000 mma_memblock_remove=1 mtdparts=nand0:1920k@1280k(BOOT),1920k(BOOT_BAK),256k(ENV),256k(ENV1),5m(KERNEL),5m(KERNEL_BACKUP),4m(rootfs),1152k(MISC),109952k(ubia)

saveenv

reset

3.4.2. 非 PCIE 硬件连接

非 PCIE 级联场景为单板运行，硬件连接要求：

• 开发板：需要一块 MHERA 系列开发板
• 网络连接：通过网线或 Wi-Fi 将开发板连接到局域网，确保与发起 HTTP 请求的设备（如运行 Cherry Studio 的 PC）在同一网段且可互相 ping 通
• 电源：确保开发板正常供电
• 调试串口（可选）：连接串口用于查看启动日志和调试信息

---

3.5 PCIE 级联场景环境搭建

3.5.1. EP 端 bootargs 配置

按住回车键后开启开发板电源，进入 uboot 环境，使用以下命令配置：

setenv bootargs ubi.mtd=ubia,2048 root=/dev/mtdblock6 rootfstype=squashfs ro init=/linuxrc LX_MEM=0x1000000000,0x80000000 cma=2M mma_heap=mma_heap_name0,miu=0,sz=0x60000000 mma_memblock_remove=1 mtdparts=nand0:1920k@1280k(BOOT),1920k(BOOT_BAK),256k(ENV),256k(ENV1),5m(KERNEL),5m(KERNEL_BACKUP),4m(rootfs),1152k(MISC),109952k(ubia) pcie0=ep pci_epf_test.pcie_port=0

saveenv
reset

3.5.2. RC 端 bootargs 配置

setenv bootargs ubi.mtd=ubia,2048 root=/dev/mtdblock6 rootfstype=squashfs ro init=/linuxrc LX_MEM=0x1000000000,0x80000000 cma=2M mma_heap=mma_heap_name0,miu=0,sz=0x60000000 mma_memblock_remove=1 mtdparts=nand0:1920k@1280k(BOOT),1920k(BOOT_BAK),256k(ENV),256k(ENV1),5m(KERNEL),5m(KERNEL_BACKUP),4m(rootfs),1152k(MISC),109952k(ubia) pcie0=rc pciehp.pciehp_poll_mode=1

saveenv
reset

配置说明：

• pcie0=ep：将 PCIE0 配置为 EP 模式
• pcie0=rc：将 PCIE0 配置为 RC 模式
• LX_MEM=0x1000000000,0x80000000：PCIE 级联场景需要更大的内存配置
• mma_heap sz=0x60000000：为模型推理预留足够的内存空间

3.5.3. PCIE 级联硬件连接

PCIE 级联场景需要两块开发板通过 PCIE 总线连接，硬件连接要求：

开发板A (RC端)                     开发板B (EP端)
    ┌─────────────┐                   ┌─────────────┐
    │  PCIE0 接口 │◄─────────────────►│  PCIE0 接口 │
    └─────────────┘    PCIE连接线     └─────────────┘
         │                                  │
         │ 不接电源                         │
         │                            接电源
         ▼                                 ▼
    ┌─────────────┐                   ┌─────────────┐
    │  串口/网络  │                   │  串口/网络   │
    └─────────────┘                   └─────────────┘

• 开发板：需要两块 MHERA 系列开发板
• PCIE 连接线：使用 PCIE 连接线将两块开发板的 PCIE0 接口连接起来
  • RC 端（主控端）PCIE0 接口连接到 EP 端（从端）PCIE0 接口
  • 确保连接线完好，接口牢固
• PCIE0 限速电阻：两块开发板均需要去除 PCIE0 的限速电阻（如存在）
• 电源：
  • EP 端开发板：需要正常供电
  • RC 端开发板：可以不接电源（通过 PCIE 总线从 EP 端获取供电）
  • 建议两块板子均接电源以保证稳定性
• 网络连接：RC 端开发板需要连接到局域网，确保与发起 HTTP 请求的设备可互相 ping 通
• 调试串口（可选）：两块板子均连接串口用于查看启动日志和调试信息

PCIE级联具体连接可参考下图

3.5.4. PCIE 连接验证

启动完成后，在 RC 端执行 lspci 命令验证 PCIE 连接：

01:00.0 Class ff00: 104c:b500
00:00.0 Class 0604: 16c3:abc

如果能看到类似的 PCIE 设备信息，说明连接成功。如果没有返回设备信息，请检查：

1. 板卡的 PCIE 底座是否空焊
2. PCIE 连接线是否可用
3. 两块开发板的 bootargs 配置是否正确

---

4. 运行说明

4.1 板端运行说明

4.1.1. 非 PCIE 级联说明

非 PCIE 级联场景为单板运行，直接启动板端程序即可。

4.1.1.1. 基本用法

./sgs_demo_llm_and_vlm [选项]

4.1.1.2. 命令行参数

参数	说明	默认值
-d <listen_host>	监听的网络地址	0.0.0.0
-p <listen_port>	监听的端口号	8000
-l <model_path>	模型文件路径（ipu.json 所在目录）	./models/LLM
-h	打印帮助信息	-

4.1.1.3. 使用示例

LLM 场景

# 监听网络地址为 192.168.1.100，端口号为 9090，使用默认模型路径
./sgs_demo_llm_and_vlm -d 192.168.1.100 -p 9090

# 指定模型路径为 /models/LLM
./sgs_demo_llm_and_vlm -d 192.168.1.100 -p 9090 -l ./models/LLM

VLM 场景

# 监听网络地址为 192.168.1.100，端口号为 9090，指定模型路径为 /models/VLM
./sgs_demo_llm_and_vlm -d 192.168.1.100 -p 9090 -l ./models/VLM

---

4.1.2. PCIE 级联说明

PCIE 级联场景需要分别启动 EP 端和 RC 端程序。

4.1.2.1. EP 端启动

./prog_ipu_ipu_service

EP 端程序启动后，会等待 RC 端的连接请求。

4.1.2.2. RC 端启动

./sgs_demo_llm_and_vlm [选项]

4.1.2.3. 命令行参数

参数	说明	默认值
-d <listen_host>	监听的网络地址	0.0.0.0
-p <listen_port>	监听的端口号	8000
-l <model_path>	模型文件路径（ipu.json 所在目录）	./models/LLM
-h	打印帮助信息	-

注意：PCIE 级联场景下，-l 参数应指定为 ./models/PCIE_LLM 目录。

4.1.2.4. 使用示例

# EP 端，先于 RC 端执行
./prog_ipu_ipu_service

# RC 端，监听网络地址为 192.168.1.100，端口号为 9090
./sgs_demo_llm_and_vlm -d 192.168.1.100 -p 9090 -l ./models/PCIE_LLM

---

4.2 PC 端验证大语言模型

4.2.1. Cherry Studio 说明

Cherry Studio 是一个可选的图形化界面，可以提供更友好的对话体验。

4.2.1.1. 下载免安装版本

访问 Cherry Studio 官方网站下载免安装版本：

https://www.cherry-ai.com/download

如下图：

在 其他版本中下载 Windows 便携版 Cherry-Studio-1.9.9-x64-portable.exe 文件

下载完成后，直接双击运行 .exe 文件即可使用，无需安装。

4.2.1.2. 配置 OpenAI API 连接

1. 点击界面上的设置按钮打开设置界面

2. 选择"模型服务"选项卡，随后点击"+ 添加"，具体操作看下图：

   

3. 在"添加供应商"下填写供应商名称，如"助手"，供应类型选择"OpenAI"，点击"确定"来创建外部链接模型。参考下图：

   

4. 在 OpenAI 提供商配置中：

   • 将 Base URL 修改为板端模型服务器的地址，格式为：http://<开发板IP>:<端口>/v1
   • 例如：http://192.168.1.100:9090/v1
   • API Key 可填写任意非空字符串（如 sk-test）

5. 待板端出现 Server listening on http://192.168.1.100:9090 log 时，可以点击获取模型列表，链接板端的模型服务。具体操作参考下图：

   

4.2.1.3. 使用 Cherry Studio 进行对话

• 在聊天界面选择配置好的模型
• 输入文字问题或上传图片进行对话
• 查看返回的对话结果

---

4.2.2. PowerShell curl 命令说明

除使用 Cherry Studio 图形界面外，也可以通过 PowerShell 的 curl 命令（实际为 Invoke-WebRequest）直接调用板端 OpenAI API 进行测试。

4.2.2.1. 查询模型列表

curl http://192.168.1.100:9090/v1/models

4.2.2.2. LLM 文本对话

curl -X POST http://192.168.1.100:9090/v1/chat/completions `
  -H 'Content-Type: application/json' `
  -d '{"model":"default-model","messages":[{"role":"user","content":"hello"}]}'

4.2.2.3. VLM 图文理解

方法一：使用 PowerShell here-string（推荐）

$imagePath = "C:\path\to\test.jpg"
$imageBytes = [System.IO.File]::ReadAllBytes($imagePath)
$base64Image = [System.Convert]::ToBase64String($imageBytes)

$jsonPayload = @"
{
  "model":"default-model",
  "messages":[{
    "role":"user",
    "content":[
      {"type":"text","text":"describe this image"},
      {"type":"image_url","image_url":{"url":"data:image/jpeg;base64,$base64Image"}}
    ]
  }]
}
"@

curl -X POST http://192.168.1.100:9090/v1/chat/completions `
  -H 'Content-Type: application/json' `
  -d $jsonPayload

方法二：先构建 JSON 文件

$imagePath = "C:\path\to\test.jpg"
$imageBytes = [System.IO.File]::ReadAllBytes($imagePath)
$base64Image = [System.Convert]::ToBase64String($imageBytes)

$jsonContent = @"
{
  "model":"default-model",
  "messages":[{
    "role":"user",
    "content":[
      {"type":"text","text":"describe this image"},
      {"type":"image_url","image_url":{"url":"data:image/jpeg;base64,$base64Image"}}
    ]
  }]
}
"@

$jsonContent | Out-File -FilePath "C:\temp\vlm_request.json" -Encoding utf8

curl -X POST http://192.168.1.100:9090/v1/chat/completions `
  -H 'Content-Type: application/json' `
  -d @C:\temp\vlm_request.json

---

5. 运行结果说明

5.1 正常启动

程序启动正常会显示初始化完成信息：

llm_and_vlm app initialized on 192.168.1.100:9090

press q then Enter to quit

5.2 运行中日志

• 接受 HTTP 请求并输出响应
• 接收到来自 /v1/models 的请求时，返回当前支持的模型列表

• 接收到来自 /v1/chat/completions 的请求时，根据请求内容完成文字对话或图文理解推理，并返回响应

  llm prompt: who are you?

  [HTTP] POST /v1/chat/completions handled in 4167.039167 ms

  [HTTP] GET /v1/models handled in 0.051834 ms

  llm prompt: write a doc to introduce openclaw

  [HTTP] POST /v1/chat/completions handled in 22684.127836 ms

VLM 图像处理日志：

[llm_and_vlm][vision] ALGO_STS_GetInputAttr begin
[llm_and_vlm][vision] ALGO_STS_GetInputAttr ret=0 width=1024 height=1024 format=1
[llm_and_vlm][vision] ALGO_STS_SetParams begin
the set image pad is <image>
[llm_and_vlm][vision] ALGO_STS_SetParams ret=0
[llm_and_vlm][vision] MI_SYS_MMA_Alloc size=1572864
[llm_and_vlm][vision] MI_SYS_MMA_Alloc ret=0 phy=2109881856
[llm_and_vlm][vision] MI_SYS_Mmap begin
[llm_and_vlm][vision] MI_SYS_Mmap ret=0 vir=0x7f8d479e00
[llm_and_vlm][vision] cv::imread path=/tmp/algo_openai_img_7aFnFb
[llm_and_vlm][vision] copy NV12 bytes=1572864 buffer=1572864
[llm_and_vlm][vision] ALGO_STS_Generate vision stream begin
[llm_and_vlm][vision] ALGO_STS_Generate vision stream ret=0

5.3. 程序退出

在终端输入 q 并按回车退出，程序会：

1. 退出 HTTP 服务器
2. 清理 SGS_STS 资源
3. 等待 HTTP 服务器结束

4. 退出程序

   PCIE 级联场景下，EP 端程序会自动检测到 RC 端断开连接并退出。

---

5.4. 常见问题

5.4.1. 响应较慢

该问题大多是因为开发板和 Cherry Studio 之间使用的网络连接方式有关，若延时较高，建议使用网线直连开发板和运行 Cherry Studio 的 PC 端。

5.4.2. 重复字符问题

单个会话中进行多轮对话后响应出现大量重复字符，LLM/VLM 模型的上下文受限，建议每一个对话在进行 5 次左右后切换新会话来清除上下文。

5.4.3. PCIE 连接问题

若无 PCIE 设备返回，请检查：

1. 板卡的 PCIE 底座是否空焊
2. PCIE 连接线是否可用
3. 两块开发板的 bootargs 配置是否正确

5.4.4. VLM 图像处理失败

若 VLM 图文理解失败，请检查：

1. 图片格式是否支持（JPEG、PNG）
2. 图片大小是否超过限制
3. 模型路径是否正确指向 VLM 模型目录

---