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

一、文档说明

本文档适用于 Windows 环境（以暗影精灵11为例：i9-14900HX + 32G内存 + RTX5070 8G），完整覆盖从环境安装、模型部署、脚本开发到调试运行的全流程，包含实际操作中踩坑点和解决方案，最终实现基于 Midscene 的 Web UI 自动化（百度搜索“软件测试”案例）。

二、前置准备

硬件要求

• 内存：≥16G（32G最佳，支持8B模型流畅运行）
• 显卡：NVIDIA 独立显卡（支持CUDA，≥6G显存，RTX5070 8G完全适配）
• 硬盘：预留≥20G空间（Ollama模型+项目依赖）

软件依赖

• 操作系统：Windows 10/11 64位
• 浏览器：Chrome 最新版（Midscene 仅支持Chrome）
• 终端：CMD/PowerShell（或任意支持Node.js的终端）

三、环境安装步骤

1. 安装 Node.js（必装）

操作步骤

1. 下载 Node.js：访问 Node.js 官网，下载 LTS 版本（推荐20.x.x）；
2. 安装：双击安装包，勾选“Add to PATH”，默认下一步完成安装；
3. 验证：打开终端，执行以下命令，显示版本号即成功：

   node -v  # 输出 v20.x.x
   npm -v   # 输出 10.x.x
   

注意事项

• 若安装后终端提示“node不是内部命令”，需手动将 Node.js 安装目录（默认C:\Program Files\nodejs）添加到系统环境变量PATH中。

2. 安装 Ollama（本地模型运行环境）

操作步骤

1. 下载 Ollama：访问 Ollama 官网，点击“Download for Windows”；
2. 安装：双击安装包，默认路径安装（自动配置环境变量）；
3. 验证：打开终端，执行以下命令，显示帮助信息即成功：

   ollama --version
   

注意事项

• 安装后需重启终端，确保ollama命令可正常调用。

3. 下载本地 Qwen3-VL 模型

操作步骤

1. 打开终端，执行以下命令下载模型（推荐8B，兼顾速度和能力）：

   # 下载 qwen3-vl:8b（4-bit量化，显存占用约4-5GB）
   ollama pull qwen3-vl:8b
   

2. 验证模型：执行以下命令启动模型，显示>>> Send a message即就绪：

   ollama run qwen3-vl:8b
   

3. 测试模型能力（可选）：在模型终端输入识别百度首页的输入框和搜索按钮，并上传百度截图，模型能识别即正常。

注意事项

• 下载模型需联网，速度取决于网络环境（8B模型约4-5GB）；
• 若下载中断，重新执行ollama pull qwen3-vl:8b即可断点续传；
• 4B模型（qwen3-vl:4b）适合低配电脑，但任务规划准确率和速度不如8B，建议优先用8B。

4. 配置 Ollama GPU 加速（关键提速步骤）

操作步骤

1. 安装 CUDA Toolkit：
   • 访问 NVIDIA CUDA 官网，下载 12.x 版本（适配RTX5070）；
   • 安装时选择“精简安装”，自动配置环境变量。
2. 设置 Ollama 环境变量：
   • 按下Win+R，输入sysdm.cpl→“高级”→“环境变量”；
   • 系统变量→“新建”，添加：
     • 变量名：OLLAMA_CUDA
     • 变量值：1（启用CUDA加速）；
3. 重启电脑：让环境变量和CUDA配置生效；
4. 验证GPU加速：
   • 启动模型：ollama run qwen3-vl:8b；
   • 打开“任务管理器”→“性能”→“GPU 0（RTX5070）”，模型推理时GPU利用率上升即成功。

注意事项

• 若没有NVIDIA显卡，跳过此步骤（Ollama自动用CPU推理，但速度会慢3-5倍）；
• 安装CUDA后若GPU未被调用，检查显卡驱动是否为最新（通过NVIDIA GeForce Experience更新）。

5. 安装 Midscene 相关依赖

操作步骤

1. 创建项目目录：

   # 新建项目文件夹
   mkdir D:\project2025\AI_UI_TEST
   # 进入目录
   cd D:\project2025\AI_UI_TEST
   

2. 初始化 npm 项目：

   npm init -y  # 生成 package.json 文件
   

3. 安装 Midscene 核心依赖：

   # 安装 Midscene 核心库和桥接模式依赖
   npm install @midscene/core @midscene/web --save
   # 安装 TypeScript 及运行工具（TS脚本必需）
   npm install typescript tsx @types/node --save-dev
   

4. 安装 Midscene CLI（YAML脚本运行必需）：

   npm install -g @midscene/cli
   

5. 验证 CLI 安装：

   midscene --version  # 输出 v1.0.3 及以上
   

注意事项

• 安装 CLI 时出现npm WARN deprecated警告是正常现象，不影响功能；
• 若midscene命令无法识别，手动将 npm 全局目录（默认C:\Users\你的用户名\AppData\Roaming\npm）添加到系统环境变量PATH。

6. 安装 Midscene Chrome 插件

操作步骤

1. 打开 Chrome 浏览器，访问 Chrome 应用商店，搜索“Midscene”并安装；
2. 安装后点击浏览器右上角插件图标，启用“Bridge Mode”（桥接模式）；
3. 点击“Allow connection”（允许连接），插件显示“Listening”即就绪。

注意事项

• 若无法访问应用商店，可通过 Midscene 官网下载离线插件包安装；
• 每次运行脚本前，需确保插件处于“Bridge Mode”且已允许连接。

四、项目配置（.env 文件）

在项目根目录（D:\project2025\AI_UI_TEST）创建 .env 文件，写入以下配置（适配本地 Ollama 模型）：

# .env 文件 - Midscene 模型配置
# 本地 Ollama 服务地址（默认端口11434）
MIDSCENE_MODEL_BASE_URL=http://localhost:11434/v1
# 本地模型无需真实 API Key，填任意值即可
MIDSCENE_MODEL_API_KEY=local-deployment
# 本地模型名称（qwen3-vl:8b 或 qwen3-vl:4b）
MIDSCENE_MODEL_NAME=qwen3-vl:8b
# 模型家族（Qwen3-VL 系列必须填 qwen3-vl，之前踩坑点！）
MIDSCENE_MODEL_FAMILY=qwen3-vl
# 优先使用本地模型
MIDSCENE_AI_PREFER_LOCAL=true

注意事项

• 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 脚本示例（百度搜索“软件测试”）
import 'dotenv/config';  // 加载 .env 配置（必需）
import { AgentOverChromeBridge } from "@midscene/web/bridge-mode";

// 睡眠函数（等待页面加载）
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

Promise.resolve(
  (async () => {
    const agent = new AgentOverChromeBridge();

    try {
      // 连接 Chrome 新建标签页，打开百度
      await agent.connectNewTabWithUrl("https://www.baidu.com");
      // 输入“软件测试”（拆分指令，降低模型压力，之前踩坑点！）
      await agent.ai('识别页面顶部的搜索输入框，输入“软件测试”');
      await sleep(2000);
      // 点击“百度一下”按钮
      await agent.ai('点击页面中的“百度一下”按钮');
      await sleep(3000);
      // 断言搜索结果存在
      await agent.aiAssert("页面显示“软件测试”的搜索结果");
      console.log("脚本执行成功！");
    } catch (error) {
      console.error("脚本执行失败：", error);
    } finally {
      // 销毁 agent 连接
      await agent.destroy();
    }
  })()
);

运行步骤

1. 启动本地模型：打开终端，执行ollama run qwen3-vl:8b（保持终端打开）；
2. 运行 TS 脚本：在项目目录执行：

   npx tsx demo-new-tab.ts
   

3. 观察结果：Chrome 自动打开百度，完成输入和点击，终端显示“脚本执行成功”即正常。

2. YAML 脚本（test.yaml）

脚本内容（严格遵循官网语法，之前踩坑点！）

# test.yaml - YAML 脚本示例（百度搜索“软件测试”）
web:  # 官网要求根字段为 web，而非 target（之前的坑）
  url: https://www.baidu.com
  bridgeMode: newTabWithUrl
  closeNewTabsAfterDisconnect: true

tasks:
  - name: 输入搜索关键词
    flow:  # 每个 task 必须包含 flow 数组（核心坑！之前缺这个）
      - ai: 识别页面顶部的搜索输入框，输入“软件测试”
  - name: 等待输入完成
    flow:
      - sleep: 1000
  - name: 点击搜索按钮
    flow:
      - ai: 点击页面中的“百度一下”按钮
  - name: 等待结果加载
    flow:
      - sleep: 3000
  - name: 验证搜索结果
    flow:
      - aiAssert: 页面显示“软件测试”的搜索结果  # 断言用 aiAssert，而非 assert（坑！）

运行步骤

1. 确保模型和 Chrome 插件已就绪；
2. 在项目目录执行：

   # 用 CLI 运行 YAML 脚本（--file 参数避免文件识别问题）
   midscene run --file test.yaml
   

3. 观察结果：终端显示步骤执行日志，Chrome 自动完成操作，生成 HTML 报告。

六、常见问题与踩坑总结

1. 环境配置类

问题现象	原因	解决方案
“Invalid MIDSCENE_MODEL_FAMILY”	模型家族配置为qwen	改为qwen3-vl（官网要求）
“midscene 不是内部命令”	CLI 未添加到环境变量	手动添加 npm 全局目录到 PATH
Ollama 模型无法调用 GPU	未配置 CUDA 或环境变量	安装 CUDA，添加OLLAMA_CUDA=1环境变量

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 加速（关键！）
模型推理卡顿	电脑资源不足	关闭无关程序，释放内存/显存

七、调试与报告查看

1. 运行日志：终端实时输出执行步骤（Plan/Locate/Input/Tap），报错时会显示具体原因；
2. 可视化报告：Midscene 自动生成 HTML 报告，路径为midscene_run/report/xxx.html，用浏览器打开可查看截图、步骤耗时；
3. 模型调试：在 Ollama 终端手动测试指令，验证模型是否能识别元素、返回正确格式。

八、总结

1. 核心流程：环境安装→模型部署→配置→脚本开发→运行，关键是 GPU 加速和模型家族配置；
2. 优先选择：8B模型（速度+准确率平衡）、YAML脚本（简洁）、GPU加速（大幅提速）；
3. 避坑重点：模型家族填qwen3-vl、YAML 包含flow数组、拆分复杂指令、启用 GPU 加速。

按以上步骤操作，即可稳定实现 Midscene + 本地 Ollama 模型的 Web UI 自动化。