---
title: miniLLM-vlm
canonical_url: "https://www.modelscope.cn/studios/kayson2026/miniLLM-vlm"
md_url: "https://www.modelscope.cn/studios/kayson2026/miniLLM-vlm.md"
repository: kayson2026/miniLLM-vlm
last_updated: 2026-09-10
sdk_type: gradio
sdk_version: 5.49.1
downloads: 0
stars: 0
---

# miniLLM-vlm

> miniLLM-vlm - kayson2026 在 ModelScope 创建的在线 Demo。从 0 训练一个 VLM 视觉模型

kayson2026/miniLLM-vlm 是 ModelScope 魔搭社区上的在线可交互 Demo（创空间），基于 gradio 5.49.1 构建。

- **Repository**: kayson2026/miniLLM-vlm
- **SDK**: gradio
- **SDK version**: 5.49.1
- **Downloads**: 0
- **Stars**: 0
- **Last updated**: 2026-09-10

Source: https://www.modelscope.cn/studios/kayson2026/miniLLM-vlm

---

# miniLLM-VLM · ModelScope 创空间

独立的单图/纯文本聊天应用。支持中文、英文界面，单图多轮问答、流式输出、停止、重新生成、图片特征缓存和单 GPU 排队。

**不依赖父项目 miniLLM，也不依赖训练代码、原 Base、数据集或训练缓存。** `minillm_vlm/model/` 是从 miniLLM-vlm 固定复制的模型实现，部署时必须携带。不要用原 miniLLM/deploy 的模型文件或 tokenizer 替换这里的运行时。

## 文件职责

| 文件 | 用途 |
| --- | --- |
| `app.py` | 双语界面、会话隔离、事件与请求队列 |
| `inference.py` | 权重校验/加载、SFT ChatML、KV cache、视觉特征缓存、流式解码、模型打包 |
| `style.css` | 浅色/深色、桌面/手机布局 |
| `minillm_vlm/` | 本部署包自带的模型实现，无父目录搜索逻辑 |
| `requirements.txt` | 固定的推理依赖，不包含 torch、datasets、SwanLab |
| `ms_deploy.json` | Gradio 5.49.1、PyTorch 2.3.1 镜像、16 GB xGPU 配置 |
| `tests/test_deployment.py` | 提示词、缓存等价性、会话取消和独立加载回归 |

## 1. 准备环境

推荐在已有 CUDA PyTorch 的 AutoDL 环境先验证。ModelScope 使用 `ms_deploy.json` 指定的镜像。

```bash
cd /root/miniLLM-vlm/deploy/modelscope
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"
python -m pip install -r requirements.txt
```

PyTorch 由平台镜像提供，**不要额外执行不带版本约束的 `pip install -U torch`**。当前方案固定 Transformers 4.55.4，并兼容 tokenizer 文件里的 `TokenizersBackend` 类名；不改写 tokenizer 文件。

`ms_deploy.json` 的 GPU 资源项需要账户具有对应 xGPU 使用资格。请在空间控制台选择已获得的 GPU 资源；创建配置文件不会申请或购买 GPU。

仅使用免费 CPU 时，把 `resource_configuration` 改为 `platform/2v-cpu-16g-mem`。CPU 自动使用 FP32，适合功能验证，不能保证 GPU 方案的响应速度。GPU 自动选用 BF16 或 FP16 autocast；原始权重保留 FP32，避免改变已有模型计算路径，不默认量化。

## 2. 整理模型仓库

模型仓库和创空间代码仓库分开。先生成可移植的模型目录；以下命令只复制文件，不会修改训练产物。

```bash
python inference.py --bundle \
  --checkpoint ../../out/best_sft.pt \
  --vision ../../model/siglips \
  --destination /root/autodl-tmp/miniLLM-VLM-model
```

如果权重仍放在 AutoDL 的 `out/sft/` 中，请将 `--checkpoint` 改为实际 `best_sft.pt` 路径，其旁边必须有 `tokenizer/`。目标目录必须尚不存在，避免覆盖已有文件。

生成的模型仓库根目录：

```text
best_sft.pt
tokenizer/
siglips/
manifest.json
README.md
.gitattributes
```

`best_sft.pt` 已包含完整语言模型和投影层；SigLIP 必须与训练时保持一致。打包器校验 tokenizer 图、tokenizer 全部配套文件和 SigLIP 身份。运行时还会检查模型清单里的 checkpoint SHA-256、参数名称、形状与有限值。

在 ModelScope 创建自己的模型仓库后，将**上述目录内容**上传到仓库根目录。`.pt` 和 `.safetensors` 已通过 `.gitattributes` 声明 Git LFS。不要上传两个 SFT 权重、训练数据或 cache。也不要把整个模型目录多嵌套一层。

## 3. 发布创空间

1. 新建 Gradio 创空间。
2. 把本目录的代码文件放到创空间仓库根目录，保证根目录有 `app.py` 和 `ms_deploy.json`，并携带 `minillm_vlm/`。不上传本地 `weights/`、虚拟环境、测试缓存或日志。
3. 在创空间环境变量中设置 `MINILLM_VLM_MODEL_ID=你的用户名/模型仓库名`。推荐同时设置 `MINILLM_VLM_REVISION` 为经过验收的模型版本。
4. 使用已经开通的 GPU 资源启动。启动阶段下载、校验、加载和预热一次，页面显示“已就绪”后即可提问。

私有模型需要给运行环境配置 ModelScope 的读取凭据，使用平台的秘密变量或登录机制；不要把访问令牌写进 Git 仓库或网页代码。

## 配置项

| 环境变量 | 默认 | 含义 |
| --- | --- | --- |
| `MINILLM_VLM_MODEL_ID` | 未设置 | ModelScope 模型仓库 ID |
| `MINILLM_VLM_REVISION` | `master` | 模型版本；上线推荐固定版本 |
| `MINILLM_VLM_MODEL_DIR` | 未设置 | 优先使用指定的本地模型目录 |
| `MINILLM_VLM_VISION_DIR` | 模型目录下 `siglips` | 仅用于本地调试的视觉模型路径覆盖 |
| `MODELSCOPE_CACHE` | ModelScope 默认缓存 | 模型下载缓存目录，请选择空间允许写入且容量足够的位置 |
| `MINILLM_VLM_DEVICE` | `auto` | `auto`、`cuda`、`cpu` |
| `MINILLM_VLM_DTYPE` | `auto` | `auto`、`float32`、`bfloat16`、`float16`；CPU 仅 FP32 |
| `MINILLM_VLM_ATTENTION` | `auto` | `auto`、`math`、`eager`；排查数值差异可选 `math` |
| `MINILLM_VLM_CPU_THREADS` | `2` | CPU 计算线程数 |
| `MINILLM_VLM_TIMEOUT` | `120` | 每次推理的时间上限（秒）；不能强制打断正在执行的单个算子 |
| `PORT` | `7860` | 本地运行端口；ModelScope 保持 7860 |

资源定位顺序：显式本地目录 → 本部署目录下 `weights/` → ModelScope 模型仓库。不会搜索原 miniLLM 或训练项目父目录。`out` 中记录的 AutoDL 绝对路径不会用于部署加载。

## 交互与性能约定

- 右上角切换简体中文/English，保留当前图片和历史。界面语言不改写模型提示词，不翻译历史；使用英文问题可以引导模型用英文回答。
- 手机端默认折叠“图片与设置”，点击即可展开上传区域和回答参数，给对话留出更多空间。
- 每个会话只使用一张图片。更换/移除图片会取消该会话任务、清空历史与特征缓存。新对话同时清空图片。
- 默认确定性解码（多样性为 0），默认最多 **512 tokens**，可改为 **32～1024**（步长 32）。超过 512 为按需选择的实验长回答档，双语界面会提示可能增加耗时和重复。模型仍可遇到 EOS 提前结束；达到长度上限会明确显示，不伪装成正常 EOS 结束。
- 提示词沿用 SFT 的 ChatML 格式，不增加父项目中的默认 system prompt 或思考标签。
- 回答上限不超过 512 时，总上下文预算保持 **768 tokens**；选择超过 512（最多 1024）时，仅为该请求启用 **2048 tokens** 总预算。两者均受模型位置上限约束，不改变其他会话的设置。默认预留 512 tokens 回答，剩余 256 用于图片标记、问题和历史；1024 档预留 1024 用于输入。
- 总预算包含视觉标记和预留回答。超长时丢弃最旧完整问答轮次，把同一图片保留在剩余上下文中；当前问题过长则提示用户修改。实验档超过本轮 SFT 的 768-token 训练长度，尚不能保证相同回答质量。
- 单次生成使用 KV cache；同图追问复用投影后的视觉特征。每轮文字 prefill 重新构造，避免跨轮缓存与裁剪、重生成发生错位。
- 整个推理生成器在同一个后台线程中执行，避免 Gradio 在线程池间恢复生成器时破坏 PyTorch 的 autocast/inference_mode 上下文。
- 全局同时执行一个推理任务，Gradio 队列最多 16 个。停止、图片、历史和缓存按会话隔离，取消事件会传递给实际计算线程。
- 空闲会话缓存按 30 分钟过期清理，最多 64 个会话；GPU 上不保留空闲会话的视觉缓存。关闭页面会触发会话清理，Gradio 临时文件定期清理。不会主动将聊天内容或图片写入训练日志。
- 上传限制 10 MB、1600 万像素；解码保持训练时 EXIF 方向修正、RGB 转换和原 SigLIP processor。浏览器图片组件可能重新编码上传图片；需要像素级回归时使用同一解码后的 RGB 图片。

## 验证

```bash
python -m unittest discover -s tests -v
```

自动测试使用极小的随机模型验证算法，不把随机模型当作训练质量证据。真实模型还需要在目标 GPU 上进行数值/生成对照、显存测试和多用户浏览器测试。

后台每次完成推理记录 token 数、首 token 延迟、解码速度、总时间，不记录问题正文。首 token 时间从请求开始实际计算计时，含图像处理和文字 prefill，不含 Gradio 外层排队或首次下载；浏览器用户感知延迟还包含网络和队列。

GPU 验收目标为：预热后无排队的首段文字约 1～2 秒、解码至少 20 tokens/s。这是目标，**不是未经实测的保证**。CPU 模式单独报告；保持模型的重复/幻觉等已知能力限制说明，不把页面优化当作模型能力提升。

### 本次本地验证（2026-09-09）

- 10 项回归通过，涵盖提示词、整轮裁剪、缓存/无缓存解码一致、视觉缓存、停止隔离、缓存失效、可移植加载、篡改拒绝、双语事件及 512/1024 长度与上下文边界。
- 使用实际 `best_sft.pt`（step 44612），纯文本与合成图片各进行 32-token 贪心对照，部署端和原模型 `generate_caption` 接口得到相同 token 序列。
- 长度调整后，用实际权重测试 Python 入门指南：默认档生成 512 tokens 后达到长度上限；选择 1024 档后生成 583 tokens 并遇 EOS 正常结束，两次生成的前 512 tokens 一致。该检查验证长度控制，不代表长回答质量已达标。
- 已在浏览器检查中文/英文、浅色/深色界面、实际文字回答和 390 px 手机视口。
- 本地验证环境为 CPU / PyTorch 2.14.0 / Transformers 4.55.4 / Gradio 5.49.1；平台配置仍为已用于本项目训练的 PyTorch 2.3 系列兼容镜像。**尚未在 ModelScope GPU 容器中实测速度或完成发布。**

---

## English quick start

This is a standalone bilingual Gradio studio for the exported miniLLM-VLM SFT model. It needs `best_sft.pt`, its exact `tokenizer/`, and the matching `siglips/`. No training code or original Base checkpoint is required.

Install `requirements.txt` in an environment with compatible PyTorch already installed. Set `MINILLM_VLM_MODEL_DIR` to the prepared model folder, or set `MINILLM_VLM_MODEL_ID` to a ModelScope model repository. Run `python app.py`; the server listens on port 7860. Use `python app.py --ui-only` for an explicitly labelled interface preview.

Upload the contents of this deployment directory to the studio repository root, including `minillm_vlm/`, excluding local weights and caches. Upload model assets to a separate model repository. The supplied studio configuration targets an eligible 16 GB xGPU; CPU fallback uses `platform/2v-cpu-16g-mem` and is slower.

The language toggle changes interface labels and example questions, not existing conversations or the trained prompt format. Generation uses per-request KV cache, per-session visual features, streaming output, and cancellable single-model execution. Changing the image starts a new conversation. The model is experimental; deployment does not repair its known reasoning, translation, or repetition limitations.

The default output limit is **512 tokens**, adjustable up to **1024**. Limits above 512 opt into experimental long answers with a **2048-token total context budget**; other requests retain the **768-token budget**. Generation still stops at EOS or the time limit. Longer answers may be slower and more repetitive.