• 简体中文

      • 常用模型配置

      配置环境变量的方式

      请将所有模型配置项放置在系统环境变量中，Midscene 会自动读取这些环境变量。

      以下介绍一些常见方法，你也可以使用自己项目中的其他配置方案。

      方法一：在系统中设置环境变量

      在 Midscene Chrome 插件中，你也可以使用这种 export KEY="value" 配置格式

      # 替换为你自己的 API Key
export MIDSCENE_MODEL_BASE_URL="https://.../compatible-mode/v1"
export MIDSCENE_MODEL_API_KEY="sk-abcde..."
export MIDSCENE_MODEL_NAME="qwen3-vl-plus"
export MIDSCENE_MODEL_FAMILY="qwen3-vl"

      方法二：编写 .env 文件（适用于命令行工具）

      在项目的运行路径下创建一个 .env 文件，并添加以下内容，Midscene 的命令行工具默认会读取这个文件。

      MIDSCENE_MODEL_BASE_URL="https://.../compatible-mode/v1"
MIDSCENE_MODEL_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"
MIDSCENE_MODEL_NAME="qwen3-vl-plus"
MIDSCENE_MODEL_FAMILY="qwen3-vl"

      请注意：

      1. 这里不需要在每一行前添加 export
      2. 只有 Midscene 命令行工具会默认读取这个文件，如果是 JavaScript SDK，请参考下一条自行手动加载

      方法三：引用 dotenv 库配置环境变量

      Dotenv 是一个零依赖的 npm 包，用于将环境变量从 .env 文件加载到 node.js 的环境变量参数 process.env 中。

      我们的 demo 项目 使用了这种方式。

      # 安装 dotenv
npm install dotenv --save

      在项目根目录下创建一个 .env 文件，并添加以下内容。注意这里不需要在每一行前添加 export。

      MIDSCENE_MODEL_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"

      在脚本中导入 dotenv 模块，导入后它会自动读取 .env 文件中的环境变量。

      import 'dotenv/config';

      常用模型配置

      这里列出常用模型的配置，如需了解模型区别和选型，可查阅 推荐的视觉模型。

      豆包 Seed 模型

      推荐使用 Doubao-Seed-1.6-Vision。

      从 火山引擎 获取 API 密钥，然后补充以下环境变量：

      MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_API_KEY="...."
MIDSCENE_MODEL_NAME="ep-..." # 来自火山引擎的推理接入点 ID 或模型名称
MIDSCENE_MODEL_FAMILY="doubao-vision"

      千问 Qwen3-VL

      以阿里云 的 qwen3-vl-plus 模型为例，它的环境变量配置如下：

      MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="qwen3-vl-plus"
MIDSCENE_MODEL_FAMILY="qwen3-vl"

      千问 Qwen2.5-VL

      以阿里云 qwen-vl-max-latest 模型为例，它的环境变量配置如下：

      MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="qwen-vl-max-latest"
MIDSCENE_MODEL_FAMILY="qwen2.5-vl"

      智谱 GLM-V

      智谱 GLM-V 是智谱 AI 推出的开源视觉模型。以 GLM-4.6V 为例：

      从 Z.AI（国际）或 BigModel（国内）获取 API 密钥，然后设置：

      MIDSCENE_MODEL_BASE_URL="https://open.bigmodel.cn/api/paas/v4" # 或 https://api.z.ai/api/paas/v4
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="glm-4.6v"
MIDSCENE_MODEL_FAMILY="glm-v"

      了解更多关于智谱 GLM-V

      智谱 AutoGLM

      智谱 AutoGLM 是智谱 AI 推出的开源移动端 UI 自动化模型，模型尺寸为 9B。

      从 Z.AI（国际）或 BigModel（国内）获取 API 密钥后，可以使用以下配置：

      MIDSCENE_MODEL_BASE_URL="https://open.bigmodel.cn/api/paas/v4" # 或 https://api.z.ai/api/paas/v4
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="autoglm-phone" # 模型名以平台实际模型名为准
MIDSCENE_MODEL_FAMILY="auto-glm" # 或 "auto-glm-multilingual"

      关于 MIDSCENE_MODEL_FAMILY 配置

      AutoGLM 提供了两个版本的模型，通过 MIDSCENE_MODEL_FAMILY 区分：

      • auto-glm - 对应 AutoGLM-Phone-9B，针对中文环境优化
      • auto-glm-multilingual - 对应 AutoGLM-Phone-9B-Multilingual，支持英语等其他语言场景

      请根据你的应用语言选择合适的版本。

      Note

      AutoGLM 更适合移动端的交互与操作流程。如果要使用 aiAssert、aiQuery 等需要页面理解/断言的 API，请额外配置一组 MIDSCENE_INSIGHT_MODEL_... 环境变量，让独立的 Insight 模型负责页面理解，具体可参考模型策略 中对于多模型配合的介绍。

      了解更多关于智谱 AutoGLM

      Gemini-3-Pro and Gemini-3-Flash

      在 Google Gemini 上申请 API 密钥后，可以使用以下配置。MIDSCENE_MODEL_NAME 请填写你使用的 Gemini-3-Pro 或 Gemini-3-Flash 具体模型名：

      MIDSCENE_MODEL_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="gemini-3.0-pro" # 或 gemini-3-flash 的具体模型名
MIDSCENE_MODEL_FAMILY="gemini"

      UI-TARS

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

      MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_API_KEY="...."
MIDSCENE_MODEL_NAME="ep-2025..." # 来自火山引擎的推理接入点 ID 或模型名称
MIDSCENE_MODEL_FAMILY="vlm-ui-tars-doubao-1.5"

      关于 MIDSCENE_MODEL_FAMILY 配置

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

      • vlm-ui-tars - 用于模型版本 1.0
      • vlm-ui-tars-doubao - 用于在火山引擎上部署的模型版本 1.5（与 vlm-ui-tars-doubao-1.5 等效）
      • vlm-ui-tars-doubao-1.5 - 用于在火山引擎上部署的模型版本 1.5
      Tip

      旧版本使用 MIDSCENE_USE_VLM_UI_TARS=DOUBAO 或 MIDSCENE_USE_VLM_UI_TARS=1.5 配置，该配置仍然兼容但已废弃，建议迁移到 MIDSCENE_MODEL_FAMILY。

      迁移对应关系：

      • MIDSCENE_USE_VLM_UI_TARS=1.0 → MIDSCENE_MODEL_FAMILY="vlm-ui-tars"
      • MIDSCENE_USE_VLM_UI_TARS=1.5 → MIDSCENE_MODEL_FAMILY="vlm-ui-tars-doubao-1.5"
      • MIDSCENE_USE_VLM_UI_TARS=DOUBAO → MIDSCENE_MODEL_FAMILY="vlm-ui-tars-doubao"

      GPT-4o

      从 1.0 版本开始，Midscene 不再支持使用 GPT-4o 作为 UI 操作的规划模型。详见：模型策略。

      多模型示例：GPT-5.1 用于 Planning/Insight，Qwen3-VL 负责视觉

      关于组合多个模型的更多信息，可查阅 进阶：组合多个模型。

      下面以 GPT-5.1 用于 Planning/Insight、Qwen3-VL 负责视觉为例。使用 GPT-5.1 处理重度推理（Planning 和/或 Insight），让 Qwen3-VL 专注视觉定位。独立的 Planning 和 Insight 模型可按需启用，不需要同时开启。

      # 默认视觉模型：Qwen3-VL
export MIDSCENE_MODEL_BASE_URL="https://..."       # Qwen3-VL 接口地址
export MIDSCENE_MODEL_API_KEY="..."                # 你的 Qwen3-VL API Key
export MIDSCENE_MODEL_NAME="qwen3-vl-plus"
export MIDSCENE_MODEL_FAMILY="qwen3-vl"

# Planning 模型：GPT-5.1
export MIDSCENE_PLANNING_MODEL_API_KEY="sk-..."    # 你的 GPT-5.1 API Key
export MIDSCENE_PLANNING_MODEL_BASE_URL="https://..."
export MIDSCENE_PLANNING_MODEL_NAME="gpt-5.1"

# Insight 模型：GPT-5.1
export MIDSCENE_INSIGHT_MODEL_API_KEY="sk-..."     # 你的 GPT-5.1 API Key
export MIDSCENE_INSIGHT_MODEL_BASE_URL="https://..."
export MIDSCENE_INSIGHT_MODEL_NAME="gpt-5.1"

      更多

      更多高阶配置请查看 模型配置 文档。

      模型服务连接问题排查

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

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