[![PRs](https://img.shields.io/badge/AI-Podcast-blue.svg?logo=data:image/svg%2bxml;base64,PHN2ZyBmaWxsPSIjZmZmZmZmIiB2aWV3Qm94PSIwIDAgMjQgMjQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGcgaWQ9IlNWR1JlcG9fYmdDYXJyaWVyIiBzdHJva2Utd2lkdGg9IjAiPjwvZz48ZyBpZD0iU1ZHUmVwb190cmFjZXJDYXJyaWVyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjwvZz48ZyBpZD0iU1ZHUmVwb19pY29uQ2FycmllciI+PHBhdGggZD0iTTEzLDRWMjBhMSwxLDAsMCwxLTIsMFY0YTEsMSwwLDAsMCwxLDIsMFYxOEEtMSwxLDAsMCwwLDAsNyw2VjE4YTEsMSwwLDAsMCwyLDBWNkExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDEsMCwwLDAsMCwyLDBWOEExLDE......

3. 准备 Windows 11 虚拟机

3.1 下载 Windows 11 评估版 .iso 文件：

1. 访问 Microsoft 评估中心，接受服务条款，并下载一个 Windows 11 企业版评估版（90 天试用，英语，美国） ISO 文件 [约 6GB]。
2. 下载完成后，将文件重命名为 setup.iso，并将其复制到目录 WindowsAgentArena/src/win-arena-container/vm/image。

3.2 自动设置 Windows 11 黄金镜像：

在运行 Arena 之前，您需要准备一个新的 WAA 快照（也称为 WAA 黄金镜像）。这个 30GB 的快照代表一个功能齐全的 Windows 11 虚拟机，其中包含运行基准测试所需的所有程序。该虚拟机还托管了一个 Python 服务器，用于接收并执行代理命令。要了解相关组件的更多信息，请参阅我们的 本地 和 云 组件示意图。

要准备黄金快照，请仅运行一次以下命令：

cd ./scripts
./run-local.sh --prepare-image true

您可以在 http://localhost:8006 监控进度。准备过程完全自动化，大约需要 20 分钟。

请勿在虚拟机准备过程中进行任何操作。当配置过程完成时，虚拟机会自动关闭。

最后，您应该会看到名为 winarena 的 Docker 容器按预期正常终止，如下所示的日志所示。

您将在 WindowsAgentArena/src/win-arena-container/vm/storage 中找到 30GB 的 WAA 黄金镜像，它由以下文件组成：

补充说明

• 在开发过程中，如果您希望将 src/win-arena-container 目录中的任何更改包含到 WAA 黄金镜像中，请确保在 run-local.sh 脚本中指定 --skip-build false 标志（默认为 true）。这将确保构建新的容器镜像，而不是使用预构建的 windowsarena/winarena:latest 镜像。
• 如果您之前已经运行过安装流程，并希望从头开始重新进行，请务必删除 storage 目录中的内容。
• 我们建议将此 storage 文件夹复制到仓库外部的安全位置，以防您或代理在某个时刻意外损坏虚拟机，从而避免重新设置。
• 根据您的 Docker 设置，您可能需要使用 sudo 来运行上述命令。
• 如果您正在使用 WSL2？如果遇到 /bin/bash: bad interpreter: No such file or directory 错误，我们建议将 Bash 脚本从 DOS/Windows 格式转换为 Unix 格式：

cd ./scripts
find . -maxdepth 1 -type f -exec dos2unix {} +

4. 在 Arena 中部署代理

4.1 运行基础基准测试

现在您已准备好启动评估。要运行基准代理以完成所有基准任务，请执行以下命令：

cd scripts
./run-local.sh
# 如需查看客户端/代理选项：
# ./run-local.sh --help

打开 http://localhost:8006，您将看到运行代理的 Windows 虚拟机。如果您拥有一台性能强劲的电脑，也可以通过以下命令运行我们论文中最强的代理配置：

./run-local.sh --gpu-enabled true --som-origin mixed-omni --a11y-backend uia

运行结束后，您可以使用以下命令显示结果：

cd src/win-arena-container/client
python show_results.py --result_dir <results_folder_path>

可用配置

以下是我们在研究中使用的 Navi 代理各种超参数组合的比较，您可以通过在运行 run-local.sh 脚本时指定 --som-origin <som_origin> --a11y-backend <a11y_backend> 来覆盖这些配置：

命令	描述	备注
./run-local.sh --som-origin mixed-omni --a11y-backend uia	将 Omniparser 与辅助功能树信息结合	⭐推荐用于最佳效果
./run-local.sh --som-origin omni	使用 Omniparser 进行屏幕理解
./run-local.sh --som-origin oss	使用 webparse、groundingdino 和 OCR（TesseractOCR）	🌲基线
./run-local.sh --som-origin a11y --a11y-backend uia	使用更慢但更准确的辅助功能树
./run-local.sh --som-origin a11y --a11y-backend win32	使用更快但准确性较低的辅助功能树	🐇最快
./run-local.sh --som-origin mixed-oss --a11y-backend uia	将 OSS 检测结果与辅助功能树结合

• --som-origin 决定 Navi 代理如何检测屏幕元素。
• --a11y-backend 指定辅助功能后端类型（在使用 a11y 或混合模式时）。

4.2 本地开发提示

乍一看，在 Docker 容器内运行的代码似乎难以开发和调试。不过，我们提供了一些技巧来简化这一过程。有关更多详细信息，请参阅 开发提示文档，例如：

• 如何将 VSCode 窗口（带调试器）附加到正在运行的容器；
• 如何从本地机器修改代理和 Windows 服务器代码，并实时查看容器中的更改。

🌐 Azure 部署 -> 并行化基准测试

我们提供了一种无缝方式，可在 Azure ML 计算虚拟机上运行 Windows Agent Arena。此选项可显著缩短在所有基准任务中测试您的代理所需的时间，从数小时/数天缩短至几分钟。

1. 设置 Azure 资源组：

• 如果您还没有 Azure 订阅，可以开始免费试用。请记下订阅 ID，我们将在第 3 部分中将其用作 AZURE_SUBSCRIPTION_ID。
• 在 Azure 门户 中，在您选择的区域创建一个新的资源组（例如 agents）。请记下资源组名称，我们将在第 3 部分中将其用作 AZURE_ML_RESOURCE_GROUP。
• 在此资源组中，创建一个 Azure 机器学习资源（例如命名为 agents_ml）。请记下机器学习工作区名称，我们将在第 3 部分中将其用作 AZURE_ML_WORKSPACE_NAME。在创建向导中，请确保勾选自动创建以下内容的选项：
  • 存储账户。注意： 请记下存储账户名称，我们将在第 2 部分中使用它来上传黄金镜像。
  • 密钥保管库。
  • Application Insights。
  • 【可选】容器注册表。您可以使用 Azure 容器注册表私密地存储自定义 Docker 镜像，而无需将其推送到公共的 Docker Hub。

• 创建完成后，导航到 Azure 机器学习门户，并单击您的工作区（agents）。

• 在工作区中，导航到“笔记本”选项卡。在您的用户分配文件夹中（如图所示），创建一个名为 compute-instance-startup.sh 的新 Bash (.sh) 文件。将 scripts/azure_files/compute-instance-startup.sh 文件的内容复制到该文件中并保存。每次在 Azure 中启动新的虚拟机时，都会运行此脚本以应用一些基础配置。请记下您保存文件的路径（格式为 Users/<YOUR_USER>/compute-instance-startup.sh），我们将在第 3 部分中使用该路径来运行此脚本。

• 【可选】根据您的需求，您可能需要为所在区域申请更多的计算配额。您可以通过导航到 Azure 配额页面 来进行申请。作为参考，我们目前在基准测试中使用 Standard_D8_v3 虚拟机规格，该规格属于 Standard Dv3 系列专用 vCPU 类别。每台虚拟机使用 8 个核心。请确保您使用的机器类型支持【嵌套虚拟化】(https://learn.microsoft.com/en-us/answers/questions/813416/how-do-i-know-what-size-azure-vm-supports-nested-v)。

2. 将 Windows 11 和 Docker 镜像上传到 Azure

• 将 Windows 11 存储文件夹上传到与默认数据存储关联的 Blob 容器中。默认情况下，Azure 机器学习工作区的基础数据由存储账户通过一个或多个机器学习数据存储提供支持。名为 workspaceblobstore 的默认数据存储是在设置工作区时创建的，并链接到 Azure 存储账户下的 Blob 容器。您可以通过访问 Azure 机器学习数据存储 来查看数据存储和容器之间的关联。找到后，您可以通过多种方式上传存储文件夹：

  • 下载 Azure 存储资源管理器 程序，登录并选择 Blob 容器。在完成本地设置步骤后，从您的本地计算机上传 WindowsAgentArena/src/win-arena-container/vm/storage 文件夹。
    
  • 或者，您也可以使用 Azure CLI 上传文件夹。要安装 CLI，请按照 此处 提供的步骤操作。安装完成后，可以使用以下命令：

    az login --use-device-code # 仅在提示时需要
    az storage blob upload-batch --account-name <STORAGE_ACCOUNT_NAME> --destination <CONTAINER_NAME> --source <LOCAL_FOLDER>
    # 参数列表请参阅：https://docs.microsoft.com/en-us/cli/azure/storage/blob?view=azure-cli-latest
    

  • 或者，使用 Azure 门户 界面上传文件夹。导航到存储账户，单击“存储浏览器→Blob 容器”，选择您的容器，然后上传文件夹。由于连接可能会不稳定，不建议对大文件使用此方法。

• 【可选】如果您不使用默认的 windowsarena/winarena:latest 镜像，可以将自定义镜像上传到 Azure 容器注册表。您可以按照 Azure 容器注册表文档 操作：

  az login --use-device-code
  # 如果以下命令不起作用，可能需要执行：az acr login --name <ACR_NAME>
  docker login # 系统会提示您输入 ACR 凭据（用户名 + 密码，可在 Azure 门户中找到）
  docker tag <IMAGE_NAME> <ACR_NAME>.azurecr.io/<IMAGE_NAME>:<TAG>
  docker push <ACR_NAME>.azurecr.io/<IMAGE_NAME>:<TAG>
  

3. 环境配置与部署

• 将以下额外的键添加到项目根目录下的 config.json 文件中：

{
    ... // 您之前的配置

    "AZURE_SUBSCRIPTION_ID": "<YOUR_AZURE_SUBSCRIPTION_ID>", 
    "AZURE_ML_RESOURCE_GROUP": "<YOUR_AZURE_ML_RESOURCE_GROUP>",
    "AZURE_ML_WORKSPACE_NAME": "<YOUR_AZURE_ML_WORKSPACE_NAME>"
}

• 创建一个名为 experiments.json 的新文件，用于指定每次实验运行所需的参数，包括要部署的代理和使用的底层 LLM 模型。您可以在 scripts/experiments.json 中找到一个包含多个实验的参考 experiments.json：

{
  "experiment_1": {
    "ci_startup_script_path": "Users/<YOUR_USER>/compute-instance-startup.sh", // 如第 1 节所示
    "agent": "navi",
    "datastore_input_path": "storage",
    "docker_img_name": "windowsarena/winarena:latest",
    "exp_name": "experiment_1",
    "num_workers": 4,
    "use_managed_identity": false,
    "json_name": "evaluation_examples_windows/test_all.json",
    "model_name": "gpt-4-1106-vision-preview",
    "som_origin": "oss", // 或 a11y，或 mixed-oss
    "a11y_backend": "win32" // 或 uia
  }
  // ...
}

• （可选）您也可以使用 run_azure.py 的 --experiments_json 和 --update_json 参数来生成 experiments.json，上述 JSON 等价于以下命令：

cd scripts
python run_azure.py --experiments_json "experiments.json" --update_json --exp_name "experiment_1" --ci_startup_script_path "Users/<YOUR_USER>/compute-instance-startup.sh" --agent "navi" --json_name "evaluation_examples_windows/test_all.json" --num_workers 4 --som_origin oss --a11y_backend win32

• 通过运行以下命令，在 Azure ML Compute 上部署代理：

az login --use-device-code # https://learn.microsoft.com/en-us/cli/azure/install-azure-cli
# 如果有多个租户或订阅，请确保选择正确的租户和订阅：
# az login --use-device-code --tenant "<YOUR_AZURE_AD_TENANT_ID>"
# az account set --subscription "<YOUR_AZURE_AD_TENANT_ID>"

# 确保已在您的 conda 环境中安装 Python 依赖项
# conda activate winarena
# pip install -r requirements.txt

# 在激活的 conda 环境中：
cd scripts
python run_azure.py --experiments_json "experiments.json"

对于 experiments.json 中未完成的实验，脚本将执行以下操作：

1. 创建 <num_workers 个 Azure Compute Instance VM。
2. 每个 VM 运行一个名为 <exp_name> 的 ML 训练作业。
3. 作业完成后销毁这些 VM。

运行日志将保存在您上传 Windows 11 镜像的同一 Blob 容器中的 agent_outputs 文件夹中。您可以将 agent_outputs 文件夹下载到本地，并运行 show_azure.py 脚本，以 Markdown 表格的形式查看每个实验的结果。

cd scripts
python show_azure.py --json_config "experiments.json" --result_dir <path_to_downloaded_agent_outputs_folder>

🤖 BYOA：自带你的代理

想在 Windows Agent Arena 中测试您自己的代理吗？您可以使用我们的默认代理作为模板，在 src/win-arena-container/client/mm_agents 下创建您自己的文件夹。您只需确保您的 agent.py 文件包含 predict() 和 reset() 函数即可。有关代理开发的更多信息，请参阅 BYOA 文档。

👩‍💻 开源贡献

我们欢迎对 Windows Agent Arena 项目的贡献。特别是，我们欢迎：

• 新的开源代理加入基准测试
• 向现有类别添加新任务，或直接创建新的类别

如果您有兴趣参与贡献，请查看我们的 任务开发指南。

❓ 常见问题解答

基准测试的大致运行时间和成本是多少？

组件	成本	时间
Azure Standard_D8_v3 VM	~$8 ($0.38/小时 * 40 * 0.5小时)
GPT-4V	$100	~35分钟，使用 40 个 VM
GPT-4o	$100	~35分钟，使用 40 个 VM
GPT-4o-mini	$15	~30分钟，使用 40 个 VM

如何自定义本地运行的资源分配？

默认情况下，run-local.sh 脚本会尝试创建一个具有 8 GB 内存和 8 个 CPU 核心的 QEMU VM。如果您的系统资源有限，可以通过指定所需的内存和 CPU 分配来覆盖这些默认值：

./run-local.sh --ram-size 4G --cpu-cores 4

如何切换 KVM 加速支持？

如果您的系统不支持 KVM 加速，可以通过指定 --use-kvm false 标志来禁用它：

./run-local.sh --use-kvm false

请注意，由于性能问题，不建议在没有 KVM 加速的情况下在本地运行基准测试。在这种情况下，我们建议您准备黄金镜像，以便稍后在 Azure 上运行基准测试。

👏 致谢

• OS World 提供了原始的基准测试任务框架。
• Dockur 提供了 WAA 底层的 Docker 基础设施。
• GroundingDINO 提供了我们 Navi 代理中的目标检测模块。
• NotebookLM 提供了我们的人工智能生成播客。

🤝 参与贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意一份贡献者许可协议 (CLA)，声明您有权并确实授予我们使用您贡献的权利。有关详细信息，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动确定您是否需要提供 CLA，并相应地为 PR 添加标记（例如状态检查、评论）。请按照机器人提供的说明操作。您只需在整个使用我们 CLA 的仓库中进行一次此操作即可。

本项目已采用 微软开源行为准则。有关更多信息，请参阅 行为准则常见问题解答，或如有任何其他疑问或意见，请联系 opencode@microsoft.com。

🛡️ 商标

本项目可能包含用于项目、产品或服务的商标或标识。微软商标或标识的授权使用须遵守并严格执行微软商标与品牌指南。 在本项目的修改版本中使用微软商标或标识，不得造成混淆或暗示微软的赞助关系。 任何第三方商标或标识的使用均应遵循该第三方的相关政策。

git clone https://github.com/microsoft/WindowsAgentArena.git
cd WindowsAgentArena

# 激活 conda 环境 (如果已创建)
# conda activate winarena

# 安装 Python 依赖
pip install -r requirements.txt

{
    "OPENAI_API_KEY": "<您的_OPENAI_API_KEY>", 
    "AZURE_API_KEY": "<您的_AZURE_API_KEY>",  
    "AZURE_ENDPOINT": "https://<您的端点>.openai.azure.com/" 
}

# 拉取基础镜像
docker pull windowsarena/winarena-base:latest

# 进入脚本目录并构建
cd scripts
./build-container-image.sh

cd ./scripts
./run-local.sh --prepare-image true

cd scripts
./run-local.sh

./run-local.sh --gpu-enabled true --som-origin mixed-omni --a11y-backend uia

cd src/win-arena-container/client
python show_results.py --result_dir <结果文件夹路径>