Midscene + 本地Ollama-Qwen3-VL 部署操作文档（含踩坑指南）

Midscene 本地Ollama-Qwen3-VL 部署操作文档含踩坑指南一、文档说明本文档适用于Windows 环境以暗影精灵11为例i9-14900HX 32G内存 RTX5070 8G完整覆盖从环境安装、模型部署、脚本开发到调试运行的全流程包含实际操作中踩坑点和解决方案最终实现基于 Midscene 的 Web UI 自动化百度搜索“软件测试”案例。二、前置准备硬件要求内存≥16G32G最佳支持8B模型流畅运行显卡NVIDIA 独立显卡支持CUDA≥6G显存RTX5070 8G完全适配硬盘预留≥20G空间Ollama模型项目依赖软件依赖操作系统Windows 10/11 64位浏览器Chrome 最新版Midscene 仅支持Chrome终端CMD/PowerShell或任意支持Node.js的终端三、环境安装步骤1. 安装 Node.js必装操作步骤下载 Node.js访问 Node.js 官网下载LTS 版本推荐20.x.x安装双击安装包勾选“Add to PATH”默认下一步完成安装验证打开终端执行以下命令显示版本号即成功node-v# 输出 v20.x.xnpm-v# 输出 10.x.x注意事项若安装后终端提示“node不是内部命令”需手动将 Node.js 安装目录默认C:\Program Files\nodejs添加到系统环境变量PATH中。2. 安装 Ollama本地模型运行环境操作步骤下载 Ollama访问 Ollama 官网点击“Download for Windows”安装双击安装包默认路径安装自动配置环境变量验证打开终端执行以下命令显示帮助信息即成功ollama--version注意事项安装后需重启终端确保ollama命令可正常调用。3. 下载本地 Qwen3-VL 模型操作步骤打开终端执行以下命令下载模型推荐8B兼顾速度和能力# 下载 qwen3-vl:8b4-bit量化显存占用约4-5GBollama pull qwen3-vl:8b验证模型执行以下命令启动模型显示 Send a message即就绪ollama run qwen3-vl:8b测试模型能力可选在模型终端输入识别百度首页的输入框和搜索按钮并上传百度截图模型能识别即正常。注意事项下载模型需联网速度取决于网络环境8B模型约4-5GB若下载中断重新执行ollama pull qwen3-vl:8b即可断点续传4B模型qwen3-vl:4b适合低配电脑但任务规划准确率和速度不如8B建议优先用8B。4. 配置 Ollama GPU 加速关键提速步骤操作步骤安装 CUDA Toolkit访问 NVIDIA CUDA 官网下载12.x 版本适配RTX5070安装时选择“精简安装”自动配置环境变量。设置 Ollama 环境变量按下WinR输入sysdm.cpl→“高级”→“环境变量”系统变量→“新建”添加变量名OLLAMA_CUDA变量值1启用CUDA加速重启电脑让环境变量和CUDA配置生效验证GPU加速启动模型ollama run qwen3-vl:8b打开“任务管理器”→“性能”→“GPU 0RTX5070”模型推理时GPU利用率上升即成功。注意事项若没有NVIDIA显卡跳过此步骤Ollama自动用CPU推理但速度会慢3-5倍安装CUDA后若GPU未被调用检查显卡驱动是否为最新通过NVIDIA GeForce Experience更新。5. 安装 Midscene 相关依赖操作步骤创建项目目录# 新建项目文件夹mkdirD:\project2025\AI_UI_TEST# 进入目录cdD:\project2025\AI_UI_TEST初始化 npm 项目npminit-y# 生成 package.json 文件安装 Midscene 核心依赖# 安装 Midscene 核心库和桥接模式依赖npminstallmidscene/core midscene/web--save# 安装 TypeScript 及运行工具TS脚本必需npminstalltypescript tsx types/node --save-dev安装 Midscene CLIYAML脚本运行必需npminstall-gmidscene/cli验证 CLI 安装midscene--version# 输出 v1.0.3 及以上注意事项安装 CLI 时出现npm WARN deprecated警告是正常现象不影响功能若midscene命令无法识别手动将 npm 全局目录默认C:\Users\你的用户名\AppData\Roaming\npm添加到系统环境变量PATH。6. 安装 Midscene Chrome 插件操作步骤打开 Chrome 浏览器访问 Chrome 应用商店搜索“Midscene”并安装安装后点击浏览器右上角插件图标启用“Bridge Mode”桥接模式点击“Allow connection”允许连接插件显示“Listening”即就绪。注意事项若无法访问应用商店可通过 Midscene 官网下载离线插件包安装每次运行脚本前需确保插件处于“Bridge Mode”且已允许连接。四、项目配置.env 文件在项目根目录D:\project2025\AI_UI_TEST创建.env文件写入以下配置适配本地 Ollama 模型# .env 文件 - Midscene 模型配置 # 本地 Ollama 服务地址默认端口11434 MIDSCENE_MODEL_BASE_URLhttp://localhost:11434/v1 # 本地模型无需真实 API Key填任意值即可 MIDSCENE_MODEL_API_KEYlocal-deployment # 本地模型名称qwen3-vl:8b 或 qwen3-vl:4b MIDSCENE_MODEL_NAMEqwen3-vl:8b # 模型家族Qwen3-VL 系列必须填 qwen3-vl之前踩坑点 MIDSCENE_MODEL_FAMILYqwen3-vl # 优先使用本地模型 MIDSCENE_AI_PREFER_LOCALtrue注意事项MIDSCENE_MODEL_FAMILY必须填qwen3-vl而非简写qwen否则会报“Invalid MIDSCENE_MODEL_FAMILY”错误之前的核心坑若切换线上模型如 qwen3-vl-32b-thinking需修改MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_API_KEY为线上服务地址和密钥。五、脚本开发与运行1. TypeScript 脚本demo-new-tab.ts脚本内容// demo-new-tab.ts - TS 脚本示例百度搜索“软件测试”importdotenv/config;// 加载 .env 配置必需import{AgentOverChromeBridge}frommidscene/web/bridge-mode;// 睡眠函数等待页面加载constsleep(ms:number)newPromise((r)setTimeout(r,ms));Promise.resolve((async(){constagentnewAgentOverChromeBridge();try{// 连接 Chrome 新建标签页打开百度awaitagent.connectNewTabWithUrl(https://www.baidu.com);// 输入“软件测试”拆分指令降低模型压力之前踩坑点awaitagent.ai(识别页面顶部的搜索输入框输入“软件测试”);awaitsleep(2000);// 点击“百度一下”按钮awaitagent.ai(点击页面中的“百度一下”按钮);awaitsleep(3000);// 断言搜索结果存在awaitagent.aiAssert(页面显示“软件测试”的搜索结果);console.log(脚本执行成功);}catch(error){console.error(脚本执行失败,error);}finally{// 销毁 agent 连接awaitagent.destroy();}})());运行步骤启动本地模型打开终端执行ollama run qwen3-vl:8b保持终端打开运行 TS 脚本在项目目录执行npx tsx demo-new-tab.ts观察结果Chrome 自动打开百度完成输入和点击终端显示“脚本执行成功”即正常。2. YAML 脚本test.yaml脚本内容严格遵循官网语法之前踩坑点# test.yaml - YAML 脚本示例百度搜索“软件测试”web:# 官网要求根字段为 web而非 target之前的坑url:https://www.baidu.combridgeMode:newTabWithUrlcloseNewTabsAfterDisconnect:truetasks:-name:输入搜索关键词flow:# 每个 task 必须包含 flow 数组核心坑之前缺这个-ai:识别页面顶部的搜索输入框输入“软件测试”-name:等待输入完成flow:-sleep:1000-name:点击搜索按钮flow:-ai:点击页面中的“百度一下”按钮-name:等待结果加载flow:-sleep:3000-name:验证搜索结果flow:-aiAssert:页面显示“软件测试”的搜索结果# 断言用 aiAssert而非 assert坑运行步骤确保模型和 Chrome 插件已就绪在项目目录执行# 用 CLI 运行 YAML 脚本--file 参数避免文件识别问题midscene run--filetest.yaml观察结果终端显示步骤执行日志Chrome 自动完成操作生成 HTML 报告。六、常见问题与踩坑总结1. 环境配置类问题现象原因解决方案“Invalid MIDSCENE_MODEL_FAMILY”模型家族配置为qwen改为qwen3-vl官网要求“midscene 不是内部命令”CLI 未添加到环境变量手动添加 npm 全局目录到 PATHOllama 模型无法调用 GPU未配置 CUDA 或环境变量安装 CUDA添加OLLAMA_CUDA1环境变量2. 脚本运行类问题现象原因解决方案“failed to parse json response”模型返回自然语言非 JSON拆分复杂指令明确要求 JSON 格式“failed to call AI model service: empty content”模型推理失败/格式不兼容切换8B模型简化指令描述“No yaml files found in run”CLI 无法识别文件用--file参数或./test.yaml相对路径“missing flow in task”YAML 缺少flow数组每个 task 操作放入flow内3. 性能类问题现象原因解决方案单步操作耗时30秒未启用 GPU 加速配置 CUDA 加速关键模型推理卡顿电脑资源不足关闭无关程序释放内存/显存七、调试与报告查看运行日志终端实时输出执行步骤Plan/Locate/Input/Tap报错时会显示具体原因可视化报告Midscene 自动生成 HTML 报告路径为midscene_run/report/xxx.html用浏览器打开可查看截图、步骤耗时模型调试在 Ollama 终端手动测试指令验证模型是否能识别元素、返回正确格式。八、总结核心流程环境安装→模型部署→配置→脚本开发→运行关键是 GPU 加速和模型家族配置优先选择8B模型速度准确率平衡、YAML脚本简洁、GPU加速大幅提速避坑重点模型家族填qwen3-vl、YAML 包含flow数组、拆分复杂指令、启用 GPU 加速。按以上步骤操作即可稳定实现 Midscene 本地 Ollama 模型的 Web UI 自动化。