模型调试与可观测性

本文介绍如何排查模型连接和兼容性问题、观察延迟和 Token 使用量、采集 Trace，以及记录模型调用。

验证模型连接

本节提供两种验证方法。先直接请求模型服务，确认模型 API 可以连接。再运行 Midscene 验证命令，检查模型兼容性。

直接请求模型服务

以下 curl 请求用于检查 Base URL、API Key 和模型名称是否可用。该请求只验证模型 API 的基础连接。它不会检查模型是否满足 Midscene 的兼容性要求。

MIDSCENE_MODEL_BASE_URL='替换为你的 baseUrl'
MIDSCENE_MODEL_API_KEY='替换为你的 API Key'
MIDSCENE_MODEL_NAME='替换为你的 model name'
# MIDSCENE_MODEL_PROTOCOL="openai-responses" # 使用 Responses API 时取消本行注释；默认使用 Chat API。

if [ "$MIDSCENE_MODEL_PROTOCOL" = "openai-responses" ]; then
  model_endpoint="responses"
  model_input_field="input"
else
  model_endpoint="chat/completions"
  model_input_field="messages"
fi

curl -X POST "${MIDSCENE_MODEL_BASE_URL%/}/${model_endpoint}" \
  -H "Authorization: Bearer ${MIDSCENE_MODEL_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "'"${MIDSCENE_MODEL_NAME}"'",
  "'"${model_input_field}"'": [
    {
      "role": "user",
      "content": "What is 1+1?"
    }
  ]
}'

使用 Midscene 验证命令

该命令同时检查模型连接和 Midscene 兼容性。

将模型配置放入 .env 文件，然后运行：

# 如果当前项目已安装 @midscene/test
pnpm exec midscene-test model verify

# 不在项目中安装，直接运行最新版本
pnpm dlx @midscene/test@latest model verify

# 查看命令帮助
pnpm exec midscene-test model verify --help

@midscene/cli 也提供相同的检查：

# 如果当前项目已安装 @midscene/cli，可以使用本地的 midscene 命令
npx midscene model verify

# 如果当前项目未安装 @midscene/cli，或需要使用最新版本
npx @midscene/cli@latest model verify

该命令会读取当前工作目录下的 .env 文件。Dotenv 的 Debug 日志默认开启。.env 中的变量会覆盖已有的 Shell 环境变量。

两条命令都会检查 default、locate、planning 和 insight 模型配置，无需加载 Test 项目或连接浏览器、设备。检查成功时退出码为 0，失败时为 1。

输出会列出各模型名称和 endpoint，并展示文本、图像和 AI 定位检查各自的结果、耗时与实际请求数。最后汇总总请求数及成功、失败的检查数；若某项检查在发送请求前就失败，其请求数为 0。

Model role 列表示被检查的模型配置用途：default 和 planning 分别进行简单文本响应检查，insight 进行图像理解检查，locate 进行 AI 定位检查，共四项检查。文本检查要求回复 CONNECTIVITY_OK，返回内容包含该文本即可通过，不评估任务规划质量。相同的 endpoint 会合并列在表格下方。命令通常在 30 秒内完成。

如果 curl 请求成功，但 Midscene 验证命令失败，说明模型 API 可以连接。请继续检查模型能力和 Midscene 配置。

常见配置错误

`MIDSCENE_MODEL_FAMILY` 未设置为多模态模型

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

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

正确的模型 family 和完整配置示例请参考使用模型 API Key。

Base URL 或模型名称不正确

确认 MIDSCENE_MODEL_BASE_URL 指向服务商的 API 接入地址。该地址通常以 /v1 等版本号结尾。请勿添加 /chat/completions 或 /responses，底层 SDK 会根据所选 API 类型自动添加请求路径。

同时确认 MIDSCENE_MODEL_NAME 与该接入地址提供的模型一致。

模型效果不理想

如果模型可以正常连接，但规划、定位或页面理解不稳定，可以尝试以下方法：

查看回放报告，确认任务执行顺序正确，并且没有进入错误页面或逻辑分支。
优先使用同一系列中较新的正式支持版本。
使用代表性任务对比不同服务商的模型，关注成功率、延迟和成本。
复杂任务可以单独配置 Planning 模型或 Insight 模型。具体分工请参考模型选择指南。

调试能力

Debug 日志

需要额外的诊断信息时，可以设置 DEBUG。常用选择器包括：

DEBUG=midscene:ai:profile:stats：打印模型延迟和 Token 使用量。
DEBUG=midscene:ai:call：打印 AI 响应详情。
DEBUG=midscene:*：打印全部 Midscene Debug 日志。

完整的选择器列表、日志目录和使用注意事项，请参考运行时配置：Debug 日志。

生成的报告文件中也包含模型使用量统计。

记录模型调用

设置 MIDSCENE_RECORD_MODEL_CALL=true，可以将模型请求、响应和流式 Chunk 写入 JSONL 文件：

midscene_run/model-requests/<启动时间>-<pid>.jsonl

每个进程生成一个文件，每行对应一个 JSON 事件。只有 Node.js 和 Electron 支持写入本地文件。浏览器和 Worker 不会写入本地文件。使用 Codex App Server 时，记录还会包含可获取的协议元数据。

每个事件的 type 为 request、chunk、response 或 error。事件还包含 executionId，用于关联同一个 execution ID 下的调用及其重试。对于 HTTP 模型请求，这个值也会通过 x-midscene-execution-id Header 发送。不属于报告 execution 的调用（例如连接检查）会使用带 unscoped- 前缀的生成 ID。

注意事项

文件包含请求 Body（包括自定义 extraBody）、响应 Header 和 Body、流式响应，以及可能采用 Base64 编码的截图。请求 Header 不会被记录。

这些文件可能包含敏感信息，且体积较大。请仅在排查问题时启用记录，并在使用后妥善保管或删除文件。记录格式不保证跨版本兼容。

Midscene 会自动为 OpenAI-compatible HTTP 模型请求添加以下 Header：

Header	值	用途
`x-midscene-version`	当前 `@midscene/core` 版本	标识发起请求的 Midscene 版本
`x-midscene-execution-id`	当前 execution ID	关联同一个 execution ID 下的全部模型请求及其重试，例如一次 `aiAct` 调用

不属于报告 execution 的调用（例如连接检查）会使用带 unscoped- 前缀的生成 execution ID。这两个 Header 会被默认发送，如果 MIDSCENE_*_INIT_CONFIG_JSON 中自定义了同名 Header，则会被 Midscene 覆盖。

可观测性平台

LangSmith

LangSmith 是用于调试大语言模型的平台。安装依赖并设置环境变量后，Midscene 可以自动接入 LangSmith。

安装依赖

npm install langsmith

设置环境变量

# 启用 Midscene 的 LangSmith 自动集成
export MIDSCENE_LANGSMITH_DEBUG=1

# LangSmith 配置
export LANGCHAIN_API_KEY="your-langchain-api-key-here"
export LANGCHAIN_TRACING=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
# export LANGCHAIN_ENDPOINT="https://eu.api.smith.langchain.com" # 如果在欧洲区域注册

启动 Midscene 后，应该会看到类似以下内容的日志：

DEBUGGING MODE: langsmith wrapper enabled

注意事项：

LangSmith 和 Langfuse 可以同时启用。
该集成仅支持 Node.js。浏览器环境会抛出错误。
如果使用 createOpenAIClient，它会覆盖通过环境变量启用的自动集成。

如需进行更细粒度的控制，例如只对特定任务启用 LangSmith，请使用 createOpenAIClient 手动包装客户端。

Langfuse

Langfuse 是一个 LLM 可观测性平台。Midscene 集成了 Langfuse 的 observeOpenAI wrapper，可以自动追踪 OpenAI API 调用。

Langfuse 的追踪基于 OpenTelemetry，因此需要在应用启动时初始化 OpenTelemetry SDK。

安装依赖

npm install @langfuse/openai @langfuse/otel @opentelemetry/sdk-node

初始化 OpenTelemetry

在应用入口文件的最顶部添加以下代码：

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";

const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});
sdk.start();

设置环境变量

# 启用 Midscene 的 Langfuse 自动集成
export MIDSCENE_LANGFUSE_DEBUG=1

# Langfuse 配置
export LANGFUSE_PUBLIC_KEY="your-langfuse-public-key-here"
export LANGFUSE_SECRET_KEY="your-langfuse-secret-key-here"
export LANGFUSE_BASE_URL="https://cloud.langfuse.com" # 🇪🇺 欧洲区域
# export LANGFUSE_BASE_URL="https://us.cloud.langfuse.com" # 🇺🇸 美国区域

启动 Midscene 后，应该会看到类似以下内容的日志：

OpenTelemetry SDK initialized for Langfuse tracing
DEBUGGING MODE: langfuse wrapper enabled

更多配置和最佳实践请参考 Langfuse OpenAI 集成文档。

注意事项：

LangSmith 和 Langfuse 可以同时启用。
该集成仅支持 Node.js。浏览器环境会抛出错误。
如果使用 createOpenAIClient，它会覆盖通过环境变量启用的自动集成。

安全注意事项

不要将 .env 文件、Trace、Debug 日志或模型调用记录提交到源码仓库。
日志和 Trace 可能包含模型输入、输出或截图，分享前请先检查内容。

#模型调试与可观测性

#验证模型连接

#直接请求模型服务

#使用 Midscene 验证命令

#常见配置错误

#MIDSCENE_MODEL_FAMILY 未设置为多模态模型

#Base URL 或模型名称不正确

#模型效果不理想

#调试能力

#Debug 日志

#记录模型调用

#请求追踪 Header

#可观测性平台

#LangSmith

#Langfuse

#安全注意事项