#模型策略

本篇文档会重点介绍 Midscene 的模型选用策略。如果你需要进行模型配置，请参考 模型配置。

#背景知识：UI 自动化的技术路线

使用 AI 模型驱动 UI 自动化的有两个关键点：规划合理的操作路径，以及准确找到需要交互的元素。其中“元素定位”能力的强弱，会直接影响到自动化任务的成功率。

为了完成元素定位工作，UI 自动化框架一般有两种技术路线：

• 基于 DOM + 截图标注：提前提取页面的 DOM 结构，结合截图做好标注，请模型“挑选”其中的内容。
• 纯视觉：利用模型的视觉定位能力，基于截图完成所有分析工作，即模型收到的只有图片，没有 DOM，也没有标注信息。

#Midscene 采用纯视觉路线来完成元素定位

Midscene 早期同时兼容「DOM 定位」和「纯视觉」两种技术路线，交由开发者自行选择比对。但在几十个版本迭代、上百个项目的测试后，我们有了一些新的发现。

DOM 定位方案的稳定性不足预期，它常在 Canvas 元素、CSS background-image 绘制的控件、跨域 iframe 中的内容、没有充分被辅助技术标注的元素等情况下出现定位偏差。这些时不时出现的异常情况，会让开发者投入大量时间去排查和修复，甚至陷入奇怪的 Prompt 调优怪圈。

与此同时，我们发现「纯视觉」方案开始体现出它的优越性：

• 效果稳定：这些模型在 UI 操作规划、组件定位、界面理解等领域的综合表现较好，能够帮助开发者更快上手。
• 适用于任意系统：自动化框架不再依赖 UI 渲染的技术栈。无论是 Android、iOS、桌面应用，还是浏览器中的 canvas 标签，只要能获取截图，Midscene 即可完成交互操作。
• 易于编写：抛弃各类 selector 和 DOM 之后，开发者与模型的“磨合”会变得更简单，不熟悉渲染技术的新人也能很快上手。
• token 量显著下降：相较于 DOM 方案，视觉方案的 token 使用量最多可以减少 80%，成本更低，且本地运行速度也变得更快。
• 有开源模型解决方案：开源模型表现渐佳，开发者开始有机会进行私有化部署模型，如 Qwen3-VL 提供的 8B、30B 等版本在不少项目中都有着不错的效果

综合上述情况，从 1.0 版本开始，Midscene 只支持纯视觉方案，不再提供“提取 DOM”的兼容模式。这一限制针对 UI 操作与元素定位；在数据提取或页面理解场景中，仍可按需附带 DOM 信息。

#推荐使用的视觉模型

经过大量项目实测，我们推荐使用这些模型作为使用 Midscene 的默认模型：豆包 Seed，千问 VL，Gemini-3（Pro/Flash），UI-TARS。

这些模型都具备良好的“元素定位”能力，且在任务规划、界面理解等场景上也有不错的表现。

如果你不知道从哪里开始，选用你眼下最容易获得的模型即可，然后在后续迭代中再进行横向比对。

#高阶特性：多模型配合

Midscene 的默认模型策略在很大程度上解决了 UI 自动化项目启动阶段的问题。但随着开发者提交的任务和上下文越加复杂、希望有泛化理解能力时，默认模型的规划能力可能难以应对。我们以这个注册 Github 账号的 Prompt 为例：

完成 github 账号注册的表单填写，确保表单上没有遗漏的字段，选择“美国”作为地区。

确保所有的表单项能够通过校验。

只需要填写表单项即可，不需要发起真实的账号注册。

最终返回表单上实际填写的字段内容。

这个诉求看似简单，但实际要求模型同时理解每个表单项的规则、理解每个控件、操作复杂的地区选择框、主动翻页和触发校验等操作，还要找到对应的元素。使用默认模型时，这些诉求可能难以同时满足，导致成功率较低。

面对此类场景，你可以为 任务规划（Planning）、视觉理解（Insight） 单独配置不同的模型，同时保留默认模型作为基础模型。这并不是“只有 Planning 与 Insight 两种模型”，而是默认模型 +（可选的）Planning/Insight的组合。多模型结合是当前提升 UI 自动化成功率最实用、最有效的手段，耗时和 token 消耗会略有上升。

#模型分工一览

默认策略遵循以下规则（未配置时会自动回落到默认模型）：

• 默认模型：负责元素定位（Locate），以及其他未显式配置到 Planning/Insight 的场景。
• Planning 模型（可选）：负责任务规划（aiAct / ai 里的 Planning）。
• Insight 模型（可选）：负责数据提取、断言与页面理解（aiQuery / aiAsk / aiAssert 等）。

也就是说：配置了 Planning/Insight 后，规划走 Planning，定位走默认模型，数据提取/断言走 Insight。

想快速使用多模型组合配置，参考 多模型配置示例。

#Planning 意图

在使用 aiAct 或 ai 任务规划任务时，你可以追加前缀为 MIDSCENE_PLANNING_MODEL_ 的配置，来为任务规划（Planning）意图使用独立模型。

此处我们推荐使用 gpt-5.1 或其他理解 UI 交互的多模态模型。

#Insight 意图

Midscene 提供了基于页面理解的数据处理接口，如 AI 断言（aiAssert）、数据提取（aiQuery，aiAsk） 等，我们把这类意图归类为 Insight，它的效果取决于模型在视觉问答（VQA）领域的表现。

你可以追加前缀为 MIDSCENE_INSIGHT_MODEL_ 的配置，来为视觉理解（Insight）意图使用独立模型。

此处我们推荐使用 gpt-5.1 或其他视觉问答（VQA）能力强的模型。

#如何调优执行效果？

如果你在执行过程中遇到了成功率不满足需求的情况，可以尝试以下方法。

0. 查看 Midscene 的回放报告，确保任务执行的时序是正常的，没有进入错误的页面或逻辑分支
1. 使用最优质的、更新的、更大尺寸的模型版本，这会大幅改善 UI 自动化的成功率。比如 Qwen3-VL 的效果会优于 Qwen2.5-VL，同一个模型的 72B 版本准确性会优于 30B 版本
2. 确保模型的 MIDSCENE_MODEL_FAMILY 环境变量配置正确，否则定位结果会出现明显偏移
3. 尝试使用不同的模型，或尝试多模型组合，解决理解能力不足的问题

#更多

#使用视觉模型方案的不足

视觉模型更像是一种具有高度“通用性”的解决方案，它不依赖于具体的 UI 渲染技术栈，能完全基于截图进行分析，它能让开发者快速上手、快速调优，并扩展到任意应用场景。

对应的，它也存在一些不足，主要体现在对模型的要求偏高。

以移动端的 UI 自动化为例，如果界面上有组件树信息 + 完备的 a11y（无障碍）标注，开发者可以使用小尺寸的纯文本模型、基于组件结构推理来完成自动化任务，更有机会把性能做到极致。而纯视觉模型方案则忽略了这些信息，它省下了开发者标注界面的开发成本、更通用，但在运行时需要耗费更多的模型资源。

#模型配置文档

请参考 模型配置。

#关于 aiAct 方法的 deepThink 参数

deepThink 参数用于控制模型在规划时是否启用深度思考。目前支持 qwen3-vl、qwen3.5、doubao-seed-1.6、doubao-seed-2.0、glm-v 等系列模型。

启用后，你可以在报告中看到 Reasoning 栏目。开启后，规划耗时会增加，但结果会更准确。

不同服务商的默认行为：

• qwen3.5 在阿里云：默认开启（更慢，但更准确）
• qwen3-vl 在阿里云：默认关闭（更快，但准确性差）
• doubao-seed-1.6 在火山引擎：默认开启（更慢，但更准确）
• doubao-seed-2.0 在火山引擎：默认开启（更慢，但更准确）
• glm-v 在 Z.AI：默认开启（更慢，但更准确）

你可以通过显式设置 deepThink: true 或 deepThink: false 来覆盖服务商的默认配置。

deepThink 支持 'unset' | true | false，默认值为 'unset'（等同于省略该参数，跟随模型服务商的默认策略）。

提示：deepThink 参数背后的实现方式可能会在未来随着模型提供商的变化而调整。

#模型接口风格

Midscene 要求模型服务商提供兼容 OpenAI 风格的接口（这并不是说只能使用 OpenAI 的模型）。

绝大多数的服务商、部署工具都能满足这个要求。

#如何查看模型的 token 使用情况？

在环境变量中设置 DEBUG=midscene:ai:profile:stats，即可打印模型的用量信息与响应时长。

你也可以在报告文件中查看模型的使用情况。

#"MIDSCENE_MODEL_FAMILY is required" 错误

如果收到了 "No visual language model (VL model) detected" 或 "MIDSCENE_MODEL_FAMILY is required" 错误，请确认已经正确配置 VL 模型的 MIDSCENE_MODEL_FAMILY 环境变量。

从 1.0 版本开始，Midscene 推荐使用 MIDSCENE_MODEL_FAMILY 来指定视觉模型类型。旧的 MIDSCENE_USE_... 配置仍然兼容但已废弃。

详细配置方法请参考 模型配置。

#是否可以为每个 Agent 实例单独配置模型？

可以，你可以为每个 Agent 实例单独配置模型，具体请参考 API 参考 中的 modelConfig 参数。

#希望将浏览器 DOM 信息发送给模型？

Midscene 默认不发送浏览器 DOM 信息给模型，如果你依然希望在进行界面理解时发送（如附加一些截图里不可见的信息），你可以在 aiAsk 或 aiQuery 等界面理解接口的 options 参数中设置 domIncluded 为 true，来发送浏览器 DOM 信息给模型。更多详情请参考 API 参考。

#早期版本兼容

从 1.0 版本开始，Midscene.js 推荐使用以下环境变量名，如：

• MIDSCENE_MODEL_API_KEY
• MIDSCENE_MODEL_BASE_URL

为了保持兼容，我们仍然支持下列 OpenAI 生态中的变量名，但不再推荐使用：

• OPENAI_API_KEY
• OPENAI_BASE_URL

当新变量与 OpenAI 兼容变量同时设置时，Midscene 将优先使用新变量（MIDSCENE_MODEL_*）。

#模型服务连接问题排查

如果你想排查模型服务的连通性问题，可以使用我们示例项目中的 'connectivity-test' 文件夹：https://github.com/web-infra-dev/midscene-example/tree/main/connectivity-test

将你的 .env 文件放在 connectivity-test 文件夹中，然后运行 npm i && npm run test 来进行测试。