Versions
简体中文

选择 AI 模型

选择以下模型之一，获取 API 密钥，完成配置，即可开始使用 Midscene.js。如果你是初学者，请选择最容易获得的模型。

Midscene.js 已适配的模型

Midscene.js 支持两种类型的模型：视觉语言模型和 LLM 模型。

视觉语言模型（VL 模型，✨ 推荐）

Midscene 调用了一些视觉语言模型（VL 模型），无需依赖 DOM 信息就能精确定位页面上目标元素的坐标。

在我们的实践中，这些模型已经能覆盖大部分需求场景，相比 LLM 模型成本也显著更低，因此我们推荐在 UI 自动化中优先使用 VL 模型。此外，借助这些模型，Midscene 不仅可以驱动 Web 自动化，也可以操作 Android、iOS 以及其他任何界面，这种方式更加直观、高效。

以下是已适配的 VL 模型：

LLM 模型（将在下一个大版本移除）

能够理解文本和图像输入的多模态 LLM 模型。GPT-4o 就是这种类型的模型。

多模态 LLM 目前仅可用于 Web 自动化，其中较典型的模型是 GPT-4o。如有需要，你也可以使用其他 LLM 模型。

深入了解模型

豆包系列视觉语言模型（✨ 推荐）

火山引擎提供了多个视觉语言模型，包括：

  • Doubao-seed-1.6-vision（更新且更优秀）
  • Doubao-1.5-thinking-vision-pro

它们在复杂场景的视觉定位和断言方面表现相当出色。在指令清晰的情况下，能满足绝大多数业务场景需求。

配置

从 火山引擎 获取 API 密钥后，可以使用以下配置：

OPENAI_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" 
OPENAI_API_KEY="...."
MIDSCENE_MODEL_NAME="ep-..." # 来自火山引擎的推理接入点 ID 或模型名称
MIDSCENE_USE_DOUBAO_VISION=1

链接

千问 VL（✨ 推荐）

Qwen-VL（千问 VL）是阿里巴巴发布的开源模型系列。它提供视觉定位能力，可以准确返回页面上目标元素的坐标。在用于交互、断言和查询时的综合表现相当出色。你可以在 阿里云 或 OpenRouter 上找到 Qwen 系列的已部署版本。

Midscene.js 支持使用以下版本的模型：

  • Qwen3-VL 系列，包括 qwen3-vl-plus (商业版) 和 qwen3-vl-235b-a22b-instruct (开源版)
  • Qwen2.5-VL 系列

我们推荐使用 Qwen3-VL 系列，因为它的表现明显优于 Qwen2.5-VL。使用 Qwen3-VL 系列的模型要求搭配 Midscene v0.29.3 及以上的版本。

使用 Qwen3-VL 模型的配置

以阿里云 qwen3-vl-plus 模型为例：

OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
OPENAI_API_KEY="......"
MIDSCENE_MODEL_NAME="qwen3-vl-plus"
MIDSCENE_USE_QWEN3_VL=1 # 注意，这个参数与 MIDSCENE_USE_QWEN_VL 不能同时使用

使用 Qwen2.5-VL 模型的配置

以阿里云 qwen-vl-max-latest 模型为例：

OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
OPENAI_API_KEY="......"
MIDSCENE_MODEL_NAME="qwen-vl-max-latest"
MIDSCENE_USE_QWEN_VL=1 # 注意，这个参数与 MIDSCENE_USE_QWEN3_VL 不能同时使用

链接

Gemini-2.5-Pro

从 0.15.1 版本开始，Midscene.js 支持 Gemini-2.5-Pro 模型。Gemini 2.5 Pro 是 Google Cloud 提供的闭源模型。

使用 Gemini-2.5-Pro 时，你应该使用 MIDSCENE_USE_GEMINI=1 配置来开启 Gemini-2.5-Pro 模式。

配置

在 Google Gemini 上申请 API 密钥后，可以使用以下配置：

OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
OPENAI_API_KEY="......"
MIDSCENE_MODEL_NAME="gemini-2.5-pro-preview-05-06"
MIDSCENE_USE_GEMINI=1

链接

UI-TARS

UI-TARS 是基于 VLM 架构的端到端 GUI 代理模型。它仅感知截图作为输入，并执行类似人类的交互（例如键盘和鼠标操作），在 10 多个 GUI 基准测试中实现了最先进的性能。UI-TARS 是一个开源模型，并提供不同大小的版本。

使用 UI-TARS 时，你可以使用目标驱动风格的提示，如"使用用户名 foo 和密码 bar 登录"，它会规划步骤来实现目标。

配置

你可以在 火山引擎 上使用已部署的 doubao-1.5-ui-tars。

OPENAI_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" 
OPENAI_API_KEY="...."
MIDSCENE_MODEL_NAME="ep-2025..." # 来自火山引擎的推理接入点 ID 或模型名称
MIDSCENE_USE_VLM_UI_TARS=DOUBAO

限制

  • 断言表现不佳：它在断言和查询方面可能不如 GPT-4o 和 Qwen 2.5。
  • 操作路径不稳定：它可能会尝试不同的路径来实现目标，因此每次调用的操作路径不稳定。

关于 MIDSCENE_USE_VLM_UI_TARS 配置

MIDSCENE_USE_VLM_UI_TARS 配置用于指定 UI-TARS 版本，使用以下值之一：

  • 1.0 - 用于模型版本 1.0
  • 1.5 - 用于模型版本 1.5
  • DOUBAO - 用于在火山引擎上部署的模型

链接

GPT-4o

GPT-4o 是 OpenAI 的多模态 LLM，支持图像输入。这是 Midscene.js 的默认模型。使用 GPT-4o 时，建议使用逐步提示。

由于 Midscene 需要向模型发送一些 DOM 信息和截图，使用 GPT-4o 的 token 成本较高，并且在复杂场景中不够稳定。

配置

OPENAI_API_KEY="......"
OPENAI_BASE_URL="https://custom-endpoint.com/compatible-mode/v1" # 可选，如果你想要使用不同于 OpenAI 默认的接入点
MIDSCENE_MODEL_NAME="gpt-4o-2024-11-20" # 可选，默认是 "gpt-4o"

选择其他多模态 LLM

Midscene.js 也支持其他模型。对于这些模型，Midscene 将使用与 GPT-4o 相同的提示和策略。如果你想使用其他模型，请按照以下步骤操作：

  1. 需要多模态模型，这意味着它必须支持图像输入。
  2. 模型越大，效果越好。但是，它需要更多的 GPU 或资金。
  3. 找出如何使用与 OpenAI SDK 兼容的接入点调用它。通常你应该设置 OPENAI_BASE_URL、OPENAI_API_KEY 和 MIDSCENE_MODEL_NAME。配置说明请参见配置模型和服务商。
  4. 如果在更换模型后发现效果不佳，可以尝试使用一些简短清晰的提示，或者回滚到之前的模型。更多详情请参见提示技巧。
  5. 请记住遵守每个模型和服务商的使用条款。
  6. 除非你知道自己在做什么，否则不要包含 MIDSCENE_USE_VLM_UI_TARS 和 MIDSCENE_USE_QWEN_VL 配置。

配置

MIDSCENE_MODEL_NAME="....."
OPENAI_BASE_URL="......"
OPENAI_API_KEY="......"

更多详细信息和示例配置，请参见配置模型和服务商。

常见问题

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

通过在环境变量中设置 DEBUG=midscene:ai:profile:stats，你可以打印模型的使用信息和响应时间。

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

收到了 "No visual language model (VL model) detected" 错误

请确保你正确配置了 VL 模型，特别是 MIDSCENE_USE_... 配置是否正确。

更多信息

模型服务连接问题排查

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

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