# webui

**Repository Path**: zzuos/webui

## Basic Information

- **Project Name**: webui
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Qwen3-VL (iuxray) RK3588 推理

基于 Rockchip RKLLM 1.3.0 多模态示例改写,适配:
- 视觉编码器: `.rknn` 格式 (RKNN)
- 大模型:     `.rkllm` 格式 (RKLLM, w8a8)

## 模型文件说明(重要)

**模型文件不在此仓库中**(体积超过 Gitee 限制),部署时需自行准备并放置:
1. 把视觉模型和 LLM 模型放到板子上任意目录(例如 `/home/lemon/`);
2. 复制 `models.conf.example` 为 `models.conf`(位于 install 目录或工程根目录),
   修改 `VISION=`/`LLM=` 为实际路径,`SYSTEM=` 按需调整;
3. 或者在运行时用 `webui swap <llm路径> [vision路径]` 指定;
4. 换模型详见下文"更换模型"一节。

## 编译(板上原生编译,无需交叉工具链)

```bash
cd /home/lemon/qwen3vl_iuxray_infer
make -j4 && make install
```

产物在 `install/demo_Linux_aarch64/`:
```
qwen3vl_infer              # 可执行文件
lib/librknnrt.so           # NPU 运行时
lib/librkllmrt.so          # RKLLM 运行时
run.sh                     # 启动脚本
```

## 运行

### 方式一: 网页界面(推荐)

```bash
cd /home/lemon/qwen3vl_iuxray_infer/install/demo_Linux_aarch64
./run_web.sh                    # 本机访问 http://127.0.0.1:8080
./run_web.sh 9000               # 换端口
./run_web.sh 8080 0.0.0.0       # 允许局域网其他设备访问(无鉴权,注意安全)
```

浏览器打开后:上传胸片(或填服务器上的图片路径)→ 提问 → 流式输出。
带图提问后可不带图追问;"清空对话"按钮重置上下文;换图自动重编码。
后端为常驻进程,模型只加载一次;推理日志见 `web/backend.log`,
上传的图片存在 `web/uploads/`。
注意:只有上传的图片能预览(预览接口仅限 uploads 目录);
填服务器路径的图片可正常推理但无预览。

### 方式二: 命令行

```bash
cd /home/lemon/qwen3vl_iuxray_infer/install/demo_Linux_aarch64
./run.sh [胸片图片路径]
```

启动后交互命令:
- 输入带 `<image>` 的问题 → 多模态推理(图像 embedding 进入上下文),例如:
  `<image>这张胸片有什么异常发现?请给出诊断印象。`
- 输入不带 `<image>` 的问题 → 纯文本追问(保留上文)
- `load <图片路径>` → 更换图片并清空对话
- `clear` → 清空对话历史
- `exit` → 退出

可选参数(加在 run.sh 的 qwen3vl_infer 命令行后):
```
--system "你是一名放射科医生..."   # 自定义 system prompt
--thinking                        # 开启 Qwen3 thinking 模式(需训练时启用过)
--template auto                   # 不设模板,用 runtime 内部解析(thinking 需配合此项)
--template raw                    # 不使用 chat template(裸 prompt)
--temp 0.7 --top-p 0.8 --top-k 40 # 随机采样(默认贪心 top_k=1,医学问答推荐贪心)
--no-history                      # 每轮独立、不保留历史
--img-start/--img-end/--img-content # 自定义图像特殊 token(默认 Qwen3-VL 标准)
```

## 说明

1. **图像预处理**:读图 → BGR2RGB → 补边成正方形(灰 127.5)→ 双线性缩放到
   448x448 → uint8 NHWC 送入 RKNN(归一化 mean/std 已内置于 RKNN 模型)。
   该约定与 Rockchip 导出脚本一致;若你的模型训练时用 HuggingFace processor
   的默认处理(按 28 网格缩放 + 0 填充),对非正方形图像会有轻微差异,
   胸片通常接近正方形,影响很小。
2. **图像 token 数**由 RKNN 输出维度自动读取,启动时会打印。
3. **特殊 token** 默认 `<|vision_start|> / <|vision_end|> / <|image_pad|>`,
   与 Qwen3-VL 一致;若微调时改过词表,需用 `--img-*` 覆盖。
4. **chat template** 默认 Qwen3 标准(`<|im_start|>system/user/assistant`);
   若微调时用了别的模板,请用 `--template raw` 自行拼 prompt,或改 main.cpp
   中的模板字符串。
5. `img_vec.bin` 为当前图片的视觉 embedding(调试用)。
6. 每次运行会打印 prefill/decode 耗时与 token 速度。

## 更换模型

模型路径配置在 `install/demo_Linux_aarch64/models.conf`(VISION=/LLM= 两行),
网页后端每次启动时读取。三种换模型方式:

1. **文件同名覆盖**(最简单): 新模型直接覆盖旧文件(路径不变),然后
   `webui restart`(网页里点"重启后端"按钮也行)。
2. **命令行换**:
   ```bash
   webui swap /path/新llm.rkllm /path/新vision.rknn   # 两个都换
   webui swap /path/新llm.rkllm                       # 只换 LLM, 视觉保持不变
   ```
   会自动停服务 → 更新 models.conf → 重启并加载新模型。
3. **网页上传换**: 打开网页左侧"模型管理",点"上传新 LLM (.rkllm)"或
   "上传新视觉 (.rknn)",选文件后自动上传、切换、重载,约 10 秒后可用。
   上传的模型存在 `web/models/`,重复上传会占用磁盘,记得清理旧文件。

查看当前配置: `webui models`。注意网页后端只加载内存中的旧模型,换文件后必须重启(方式 1/3 已自动处理)。

**System prompt(控制回答语言/风格)**: 默认已配置中文放射科提示词(见 models.conf 的 SYSTEM 行)。
- 网页"模型管理"里直接编辑并点"应用 System prompt";
- 或命令行: `webui system "你是一名专业放射科医生,请始终用中文回答。"`;
- 或直接改 models.conf 后 `webui restart`。
微调数据若是英文报告(iu-xray),图文混合输入时模型仍可能偶发英文,
中文 system prompt 能大幅缓解;根治需在微调数据中加入中文指令样本。

## 故障排查

- `rknn_init fail` → 检查 NPU 驱动: `ls /dev/dri/renderD128`,或 `dmesg | grep -i rknpu`。
- `rkllm_init failed` → 确认模型路径、内存足够(w8a8 2B 约需 3GB+,板子 15GB 足够);换模型后确认文件完整(上传中断会报"文件不完整")。
- 输出乱码/答非所问 → 检查 chat template 与特殊 token 是否和微调时一致。
- 网页打不开 → 确认 `run_web.sh` 的监听地址:本机用 127.0.0.1,局域网用 `./run_web.sh 8080 0.0.0.0`。