企业官网建设流程全解析

如何用 midscene model verify 命令验证模型服务连通性与 Midscene 兼容性

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

当你按 Supported models and setup 配好模型环境变量后，下一个问题是：这套配置到底能不能用？本文解决这个任务——在运行任何 Midscene 自动化任务之前，先用midscene model verify命令确认两件事：模型 API 是否可达，以及所选模型是否满足 Midscene 对多模态 UI 定位的要求。适用环境是按文档要求通过环境变量（或.env文件）配置模型的 SDK/CLI 使用方式。

Midscene 提供两种验证手段，二者解决的问题不同：

• midscene model verify命令：同时检查模型连通性和 Midscene 兼容性，是本文的主路径；
• 直接 curl 请求：只检查模型 API 的基础连通性（Base URL、API Key、模型名是否可用），不检查 Midscene 兼容性，用于在 verify 失败时隔离问题层次。

前置条件：准备.env文件

midscene model verify读取当前工作目录下的.env文件。在准备运行命令的目录中创建（或检查）.env，写入所选模型对应的 4 个变量。各变量的含义与取值规则见 Supported models and setup：

# Replace every value with the configuration for your selected model provider MIDSCENE_MODEL_BASE_URL="https://replace-with-your-model-service-url/v1" MIDSCENE_MODEL_API_KEY="replace-with-your-api-key" MIDSCENE_MODEL_NAME="replace-with-your-model-name" MIDSCENE_MODEL_FAMILY="replace-with-the-family-for-your-model"

注意两点：

• 文件中不要在每行开头加export（CLI 直接解析.env文件，export会造成问题）；
• 文件包含 API Key，文档明确提醒不要将其提交到版本控制。

MIDSCENE_MODEL_FAMILY决定 Midscene 如何适配所选模型，是验证的关键。文档给出的模型系列与 family 取值包括：doubao-seed、qwen3、deepseek、gemini、gpt-5/gpt-6、kimi/kimi3、xiaomi-mimo、glm-v、vlm-ui-tars系列、auto-glm/auto-glm-multilingual。1.0 版本起 Midscene 推荐使用MIDSCENE_MODEL_FAMILY指定多模态模型类型，旧式的MIDSCENE_USE_...配置仍兼容但已弃用。

运行 model verify

两种运行方式（引自 Model debugging and observability）：

# 当前项目已安装 @midscene/cli 时，使用本地 midscene 命令 npx midscene model verify # 当前项目未安装 @midscene/cli，或想使用最新版时 npx @midscene/cli@latest model verify

该命令不接受额外选项，附加选项会直接报错。命令行为（对应实现 model-command.ts、run-connectivity-test.ts）：

• 启动时加载当前目录的.env，且 dotenv 调试日志默认开启（dotenvDebug: true）；
• 并行执行三项检查，全部通过才算整体通过：
  • text check：对文本调用做基本验证，要求响应包含固定令牌CONNECTIVITY_OK；
  • vision check：向 insight 角色模型发送一张内置测试图片，确认视觉调用可完成；
  • AI locate check：对 default 角色模型，用内置的 todo 截图 fixture 做元素定位，定位结果返回有效的元素中心点坐标才算通过。

结果判断

• 通过：终端输出✅ Model verify passed.，命令以退出码 0 结束。
• 失败：命令以退出码 1 结束，并输出Model verify failed with messages:，失败信息按检查项逐行列出，格式为[Text check - 模型名 (intent)]: 详情这样的形式。失败输出末尾还会附一段“Generated curl requests for basic API connectivity”——即根据当前配置生成的 curl 命令，供你手动测试 Base URL、API Key 和模型名。注意文档同时提醒：这些自动生成的 curl 命令中包含你的 API Key，不要公开分享。

另外，midscene model eval目前尚未实现，运行会直接提示 "not implemented yet"，不要把它当作验证手段。

用 curl 直接请求隔离问题层次

当model verify失败时，先用下面的请求确认基础连通性是否成立（变量替换为你自己的值）：

MIDSCENE_MODEL_BASE_URL='replace with your baseUrl' MIDSCENE_MODEL_API_KEY='replace with your API key' MIDSCENE_MODEL_NAME='replace with your model name' curl -X POST "${MIDSCENE_MODEL_BASE_URL%/}/chat/completions" \ -H "Authorization: Bearer ${MIDSCENE_MODEL_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "model": "'"${MIDSCENE_MODEL_NAME}"'", "messages": [ { "role": "user", "content": "What is 1+1?" } ] }'

文档明确这条 curl 请求只验证 Base URL、API Key 和模型名是否可用，属于基础连通性检查，不代表模型满足 Midscene 的兼容性要求。两种结果的组合含义：

• curl 成功、model verify失败 → 模型 API 可达，问题在模型能力或 Midscene 配置一侧，按下一节继续排查；
• curl 也失败 → 先修正 Base URL / API Key / 模型名这类基础配置项。

常见报错与对应检查

Model debugging and observability 给出两类典型失败现象：

1.MIDSCENE_MODEL_FAMILY is not set to a multimodal model with UI localization

看到这条错误，说明MIDSCENE_MODEL_FAMILY没有设置为支持 UI 定位的多模态模型类型。回 Supported models and setup 按你的模型系列核对 family 取值和完整配置示例，再重跑 verify。

2. Base URL 或模型名不正确

• MIDSCENE_MODEL_BASE_URL应指向服务商的 API 端点，通常以/v1之类的版本路径结尾。不要手动拼接/chat/completions——底层 SDK 会自动补全请求路径，多拼会导致端点错误。
• MIDSCENE_MODEL_NAME必须与该端点实际可用的模型名一致。

若需要更多诊断输出，文档给出的选择器包括DEBUG=midscene:ai:call（打印 AI 响应详情）和DEBUG=midscene:*（打印全部 Midscene Debug 日志）。

命令行为要点

• .env覆盖方向：运行 YAML 任务时，当前 Shell 中已存在的同名变量优先于.env；midscene model verify是例外——它使用.env中的值覆盖 Shell 里的同名变量。如果你在验证和正式运行之间切换环境，注意这个差异。
• 不要把密钥外泄：.env文件、verify 失败时生成的 curl 命令都含 API Key，分享失败输出前先检查。

verify 通过后，说明所选模型在连通性和基础多模态能力上满足 Midscene 的要求，可以放心用它跑正式任务。文档给出的后续延伸阅读是查看 Model configuration reference 补全其余参数，以及用 replay report 回放任务、核对时间线（见 model-debugging-observability 的 “Improve model performance” 一节）。

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene