#模型策略

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

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

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

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

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

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

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

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

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

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

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

#推荐使用的多模态模型

经过大量项目实测，我们推荐使用这些模型作为使用 Midscene 的默认模型：豆包 Seed、千问 Qwen3.x、智谱 GLM-V、智谱 AutoGLM、Gemini 3.x 系列。

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

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

此外，Midscene 兼容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.4 或其他理解 UI 交互的多模态模型。

#Insight 意图

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

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

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

#如何调优执行效果？

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

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

#更多

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

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

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

以移动端 UI 自动化为例。如果界面上有组件树信息和完备的 a11y（无障碍）标注，开发者可以使用小尺寸纯文本模型，并基于组件结构推理来完成自动化任务。这样更有机会把性能做到极致。

纯视觉模型方案会忽略这些信息。它省下了开发者标注界面的开发成本，也更加通用，但运行时需要耗费更多模型资源。

#关于 aiAct 方法的 deepThink 参数

deepThink 参数用于控制 Midscene 在 aiAct 执行规划时的具体实现。

• 默认情况下，aiAct 会让模型在同一次规划请求里同时完成下一步规划和目标元素定位。
• 开启 deepThink 后，aiAct 会更注重任务拆解，并将任务 Planning 和 UI 元素定位拆解为不同的模型调用，从而在复杂任务中获得更稳定的效果。

在之前的版本中，deepThink 也会用于控制模型在规划时是否启用模型原生的深度思考。现在这部分由模型原生的思考模式控制。

deepThink 支持 'unset' | true | false。为了兼容旧写法，'unset' 仍然可以传入，并会被按 false 处理。

提示：deepThink 参数背后的实现可能在未来随着 Midscene 的迭代而调整。

#模型原生的思考模式

Midscene 会默认关闭模型原生思考，以获得更好的执行速度和稳定性。如果模型自身不支持关闭原生思考，Midscene 会通过控制思考粒度或限制思考额度的方式，尽可能减少模型的原生思考。

你可以通过下面的 reasoning 配置控制模型的原生思考。

• MIDSCENE_MODEL_REASONING_ENABLED：显式控制是否开启模型原生思考。
  • false：强制关闭模型原生思考（Midscene 默认行为）。
  • true：强制开启模型原生思考。
  • default：遵循模型的默认行为，Midscene 将不会向模型发送任何开启或关闭思考的配置。此时，显式配置的 MIDSCENE_MODEL_REASONING_BUDGET 和 MIDSCENE_MODEL_REASONING_EFFORT 也会被忽略。
• MIDSCENE_MODEL_REASONING_BUDGET：控制模型的思考限额（部分模型支持），具体示例请参考常用模型配置。
• MIDSCENE_MODEL_REASONING_EFFORT：控制模型的思考力度（部分模型支持），具体示例请参考常用模型配置。

注意：不同模型厂商控制模型原生思考方式的参数各不相同。如果某个显式的 reasoning 配置不被当前模型支持，Midscene 会忽略该配置，而不会猜测服务商的私有参数。

#"MIDSCENE_MODEL_FAMILY is not set to a multimodal model" 错误

如果收到 “MIDSCENE_MODEL_FAMILY is not set to a multimodal model with UI localization” 错误，请确认已经正确配置多模态模型的 MIDSCENE_MODEL_FAMILY 环境变量。

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

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

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

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

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

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

#模型服务连接问题排查

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

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