5 分钟跑通 OneJev1.5-27B:从 pip 安装到首次多模态推理的极简快速开始教程
5 分钟跑通 OneJev1.5-27B:从 pip 安装到首次多模态推理的极简快速开始教程
OneJev1.5-27B 是一个 27B 参数的多模态「System One 决策模型」:给它一张截图、照片、视频或纯文本,再配上几个选择题,它能在单次前向推理中为每个选项返回一个经过校准的概率。下面这篇快速开始教程带你从 pip 安装、启动服务到完成首次多模态推理,全程不超过 5 分钟。
📌 一、先认识 OneJev1.5-27B:它和普通多模态大模型有什么不同?
和普通多模态大模型"自由发挥一段话"不同,OneJev1.5-27B 专为决策场景设计:
- 输入:截图、照片、视频或纯文本 + 结构化的选项问题
- 输出:对每个选项给出一个校准概率(单次前向推理,一步到位)
- 底座:基于 Qwen/Qwen3.8-27B 全量微调,训练数据来自约 32 万个真实 agent 运行、视频、图像与公开决策数据集的题目
- 能力:GUI 智能体、视频理解、图文问答等决策任务
| 指标 | 数值 |
|---|---|
| 参数量 | 27.36 B(见 model.safetensors.index.json) |
| 最大上下文长度 | 262,144 tokens |
| 权重原始大小 | 约 54.7 GB(FP32) |
| 精度 | 文本/视觉塔 bfloat16 |
| 许可证 | Apache 2.0 |
🖥️ 二、硬件要求:跑通推理需要什么配置?
| 用途 | 建议配置 |
|---|---|
| FP32 完整精度推理 | 显存 ≥ 60 GB(权重本身约 54.7 GB) |
| BF16 推理 | 24 GB 显存的单卡(如 RTX 4090)即可 |
| 4-bit 量化推理 | 16 GB 显存起步 |
| 磁盘空间 | 预留 60 GB 以上下载空间 |
💡 新手最省心的方案:一块 24 GB 显存的消费级显卡 + BF16 精度,配合官方客户端
qev即可跑通。
📦 三、pip 安装:一条命令装好 qev 客户端
OneJev 的官方 Python 客户端叫 qev,它同时提供模型加载与服务能力。安装只需一条命令:
pip install "qev[torch]"
安装完成后验证:
qev --help
能看到 serve 等子命令说明安装成功。
🚀 四、启动 OneJev1.5-27B 推理服务
在终端执行:
qev serve --model OmniJev/OneJev1.5-27B
首次运行会自动下载模型权重(约 54.7 GB,请耐心等待)。服务默认监听 http://localhost:8000,对外提供 System One API,并通过 media 字段支持图片与视频输入。
如果 8000 端口被占用,可在启动时修改端口参数,并在客户端使用对应地址连接。
🧪 五、首次多模态推理:3 行代码拿到校准概率
服务启动后,用 Python 客户端发起第一次推理:
from qev import Client, Choice, Noul
from qev.media import data_uri
r = Client("http://localhost:8000").system_one(
state={"task": "Pay the open invoice from ACME", "screen": "<image:1>"},
media=[{"type": "image", "data": data_uri("screenshot.png")}],
questions={
"done": Noul("The invoice has been paid"),
"next": Choice("What should the agent do next?",
{"click": "click an element", "stop": "stop"}),
},
)
print(r)
关键参数速览:
| 参数 | 含义 |
|---|---|
state |
当前任务状态,如任务描述 + 屏幕占位符 |
media |
附带的图片或视频(data_uri 可把本地文件转成 data URI) |
questions |
结构化问题;Noul 是"是否成立"型判断,Choice 是"多选一"型选项 |
返回结果中,每个选项都带有一个概率值——这就是"System One 决策"的核心输出,可直接用于智能体自动决策。
📁 六、仓库里有哪些文件值得关注?
| 文件 | 作用 |
|---|---|
| README.md | 项目说明、基准成绩与 Quick Start |
| config.json | 模型架构配置(64 层文本塔 + 27 层视觉塔) |
| generation_config.json | 生成参数:temperature 1.0、top_k 20、top_p 0.95 |
| processor_config.json | 图像/视频处理器配置,视频默认 2 fps 采样 |
| chat_template.jinja | 对话模板,内置思维推理(reasoning_effort 支持 xhigh/medium/low) |
| tokenizer.json / tokenizer_config.json | 分词器与 image / video 等特殊 token 定义 |
| model-00001-of-00002.safetensors / model-00002-of-00002.safetensors | 模型权重分片 |
❓ 七、常见问题排查(FAQ)
- 端口 8000 被占用:修改服务端口,同时把
Client("http://localhost:8000")中的地址改成一致。 - 显存不足(OOM):优先切换 BF16 或 4-bit 量化加载;视频输入时帧数越多越吃显存,可适当降低采样帧率(默认 2 fps,见 processor_config.json)。
- 想关闭推理思考:在对话参数中设置
reasoning_effort为low或medium,模板会自动注入对应指令(见 chat_template.jinja)。 - 下载速度慢:权重约 54.7 GB,建议用带宽稳定的网络或镜像源重试。
✅ 结语
到这里,你已经完成了 OneJev1.5-27B 的完整上手路径:pip 安装 qev → 一行命令启动服务 → 几行代码完成首次多模态推理。接下来可以试试把 screenshot.png 换成你自己的照片或一段视频,体验它在 GUI 决策、视频理解等场景中的能力。
登录后查看全文