🤖 概述

AIOpsLab 是一个整体框架，旨在支持自主 AIOps 代理的设计、开发和评估，同时用于构建可复现、标准化、可互操作且可扩展的基准测试。AIOpsLab 可以部署微服务云环境、注入故障、生成工作负载并导出遥测数据，同时编排这些组件，并提供与代理交互及评估的接口。

此外，AIOpsLab 还内置了一套基准测试套件，包含一系列问题，可在交互式环境中评估 AIOps 代理。该套件可以轻松扩展以满足用户特定需求。有关问题列表，请参阅 此处。

📦 安装

要求

• Python >= 3.11
• Helm
• Poetry（推荐）或 pip
• 其他要求取决于所选的部署选项，将在下一节中说明

第一步：安装 Python 3.11

sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev -y

第二步：安装 Poetry（官方安装程序）

# 使用官方安装程序（不要使用 apt - apt 版本已过时）
curl -sSL https://install.python-poetry.org | python3.11 -
export PATH="$HOME/.local/bin:$PATH"

# 添加到您的 shell 配置文件以保持持久性
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

警告：请勿使用 sudo apt install python3-poetry - 它会安装一个过时的版本，可能无法与锁定文件兼容。

第三步：克隆并安装

git clone --recurse-submodules <CLONE_PATH_TO_THE_REPO>
cd AIOpsLab
poetry env use python3.11
poetry install
eval $(poetry env activate)

故障排除：如果出现“锁定文件不兼容”的错误，请先运行 poetry lock，再运行 poetry install。

使用 pip 的替代安装方法：

pip install -e .

🚀 快速入门

选择 a) 或 b) 来设置您的集群，然后继续执行后续步骤。

a) 本地模拟集群

AIOpsLab 可以在您本地机器上使用 kind 在本地模拟集群上运行。请参阅此 README 以获取先决条件列表。

# 对于 x86 机器
kind create cluster --config kind/kind-config-x86.yaml

# 对于 ARM 机器
kind create cluster --config kind/kind-config-arm.yaml

如果您遇到问题，可以考虑按照此 README 为您的机器构建 Docker 镜像。如有需要，请提交问题。

[提示]

如果您使用代理运行 AIOpsLab，请注意不要将 HTTP 代理地址设置为 172.17.0.1。创建 kind 集群时，集群中的所有节点都会继承主机环境和 Docker 容器的代理设置。

172.17.0.1 地址用于与宿主机通信。更多详情请参阅官方指南：配置 Kind 使用代理。

此外，Docker 不直接支持 SOCKS5 代理。如果您使用 SOCKS5 协议进行代理，可能需要使用 Privoxy 将 SOCKS5 转换为 HTTP。

如果您在本地运行 VLLM 和 LLM 代理，Privoxy 默认会代理 localhost，这会导致错误。为避免此问题，您应设置以下环境变量：

export no_proxy=localhost

完成集群创建后，继续执行下一步“更新 config.yml”。

b) 远程集群（使用 Ansible 手动设置）

AIOpsLab 支持任何您已配置 kubectl 上下文的远程 Kubernetes 集群，无论是来自云提供商的集群，还是您自己搭建的集群。我们提供了一些 Ansible 剧本，可用于在 CloudLab 等云平台以及我们自己的机器上设置集群。请按照此 README 设置您自己的集群，然后继续执行下一步“更新 config.yml”。

c) 使用 Terraform + Ansible 的 Azure VM（推荐用于云端）

只需一条命令即可 provision VM、设置 K8s 并配置 AIOpsLab：

# 模式 B（AIOpsLab 在笔记本电脑上，远程 kubectl）：
python3 scripts/terraform/deploy.py --apply --resource-group <your-rg> --workers 2 --mode B

# 模式 A（AIOpsLab 在控制器 VM 上，完全支持故障注入）：
python3 scripts/terraform/deploy.py --apply --resource-group <your-rg> --workers 2 --mode A

有关所有选项（--allowed-ips、--dev、--setup-only 等），请参阅 Terraform README。

注意：模式 B 便于开发，但某些故障注入器（例如 VirtualizationFaultInjector）需要在本地机器上运行 Docker。如需完整功能，请使用模式 A。

更新 config.yml

cd aiopslab
cp config.yml.example config.yml

请更新您的 config.yml，使 k8s_host 成为您集群控制平面节点的主机名。将 k8s_user 更新为您在控制平面节点上的用户名。如果您使用的是 kind 集群，您的 k8s_host 应为 kind。如果您在集群上运行 AIOpsLab，您的 k8s_host 应为 localhost。

在本地运行代理

由人类担任代理：

python3 cli.py
(aiopslab) $ start misconfig_app_hotel_res-detection-1 # 或选择您想解决的任何问题
# ... 等待设置 ...
(aiopslab) $ submit("Yes") # 提交解决方案

运行 GPT-4 基线代理：

# 如果项目根目录下没有 .env 文件，则创建一个
echo "OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>" > .env
# 如有需要，可添加更多 API 密钥：
# echo "QWEN_API_KEY=<YOUR_QWEN_API_KEY>" >> .env

# echo "DEEPSEEK_API_KEY=<YOUR_DEEPSEEK_API_KEY>" >> .env

python3 clients/gpt.py # 你也可以在 main() 函数中更改要解决的问题

我们的仓库预集成多种代理，其中包括支持使用基于身份的访问权限对 Azure OpenAI 终端节点进行安全认证的代理。请查看 Clients，以获取所有已实现客户端的完整列表。

客户端会自动从你的 .env 文件中加载 API 密钥。

你可以使用 k9s 或其他集群监控工具方便地检查集群的运行状态。

要在 W&B 应用程序中以表格形式浏览你记录的 session_id 值：

1. 确保你已安装并配置好 W&B。
2. 设置 USE_WANDB 环境变量：

   # 添加到你的 .env 文件
   echo "USE_WANDB=true" >> .env
   

3. 在 W&B Web UI 中，打开任意运行，点击“Tables”→“Add Query Panel”。
4. 在 key 字段中输入 runs.summary 并点击“Run”，你将看到结果以表格形式显示。

⚙️ 使用方法

AIOpsLab 可以通过以下方式使用：

• 将你的代理接入 AIOpsLab
• 向 AIOpsLab 添加新应用
• 向 AIOpsLab 添加新问题

远程运行代理

你可以在具有更大计算资源的远程机器上运行 AIOpsLab。本节将指导你如何在远程设置和使用 AIOpsLab。

1. 在远程机器上启动 AIOpsLab 服务：

   SERVICE_HOST=<YOUR_HOST> SERVICE_PORT=<YOUR_PORT> SERVICE_WORKERS=<YOUR_WORKERS> python service.py
   

2. 从本地机器测试连接： 在你的本地机器上，可以使用 curl 测试与远程 AIOpsLab 服务的连接：

   # 检查服务是否运行
   curl http://<YOUR_HOST>:<YOUR_PORT>/health
   
   # 列出可用问题
   curl http://<YOUR_HOST>:<YOUR_PORT>/problems
   
   # 列出可用代理
   curl http://<YOUR_HOST>:<YOUR_PORT>/agents
   

3. 在远程机器上运行 vLLM（如果使用 vLLM 代理）： 如果你使用的是 vLLM 代理，务必在远程机器上启动 vLLM 服务器：

   # 在远程机器上
   chmod +x ./clients/launch_vllm.sh
   ./clients/launch_vllm.sh
   

   你可以在运行前编辑 launch_vllm.sh 来自定义模型。

4. 运行代理： 在你的本地机器上，可以使用以下命令运行代理：

   curl -X POST http://<YOUR_HOST>:<YOUR_PORT>/simulate \
     -H "Content-Type: application/json" \
     -d '{
       "problem_id": "misconfig_app_hotel_res-mitigation-1",
       "agent_name": "vllm",
       "max_steps": 10,
       "temperature": 0.7,
       "top_p": 0.9
     }'
   

如何将你的代理接入 AIOpsLab？

AIOpsLab 使得开发和评估你的代理变得极其简单。你可以通过以下三个简单步骤将你的代理接入 AIOpsLab：

1. 创建你的代理：你可以自由选择任何框架来开发代理。唯一的要求是：

   • 将你的代理封装在一个 Python 类中，例如 Agent。

   • 为该类添加一个异步方法 get_action：

     # 根据当前状态返回代理的动作
     async def get_action(self, state: str) -> str:
         # <你的代理逻辑在这里>
     

2. 将你的代理注册到 AIOpsLab：现在你可以将代理注册到 AIOpsLab 的编排器中。编排器将管理你的代理与环境之间的交互：

   from aiopslab.orchestrator import Orchestrator
   
   agent = Agent()             # 创建你的代理实例
   orch = Orchestrator()       # 获取 AIOpsLab 的编排器
   orch.register_agent(agent)  # 将你的代理注册到 AIOpsLab
   

3. 在某个问题上评估你的代理：

   1. 初始化一个问题：AIOpsLab 提供了一系列你可以用来评估代理的问题。你可以在 这里 或使用 orch.probs.get_problem_ids() 查看可用问题列表。现在根据问题 ID 初始化一个问题：

      problem_desc, instructs, apis = orch.init_problem("k8s_target_port-misconfig-mitigation-1")
      

   2. 设置代理上下文：使用问题描述、指令和可用的 API 为你的代理设置上下文。（这一步取决于你的代理设计，由用户自行决定）

   3. 开始解决问题：调用 start_problem 方法开始解决问题。你还可以指定最大步骤数：

      import asyncio
      asyncio.run(orch.start_problem(max_steps=30))
      

此过程将在编排器中创建一个 Session，代理将在其中解决问题。编排器会评估你的代理解决方案，并提供结果（存储在 data/results/ 下）。你可以利用这些结果来改进你的代理。

如何向 AIOpsLab 添加新应用？

AIOpsLab 提供了一个默认的应用列表，用于评估代理在运维任务中的表现。然而，作为开发者，你也可以向 AIOpsLab 添加新应用，并围绕这些应用设计问题。

注意：对于某些支持 K8S 自动部署的应用，我们集成了 Helm 图表（你也可以使用 kubectl 来安装，例如 HotelRes 应用）。有关 Helm 的更多信息请参见这里。

要通过 Helm 向 AIOpsLab 添加新应用，你需要：

1. 添加应用元数据

   • 应用元数据是一个描述该应用的 JSON 对象。

   • 可以包含任何字段，如应用名称、描述、命名空间等。

   • 我们建议同时包含一个特殊的 Helm Config 字段，如下所示：

     "Helm Config": {
         "release_name": "<用于部署的 Helm 发布名称>",
         "chart_path": "<应用的 Helm 图表路径>",
         "namespace": "<应用应部署的 K8S 命名空间>"
     }
     

     注意：Helm Config 由编排器使用，以便在与该应用相关的问题启动时自动部署你的应用。

     注意：编排器会自动为与该应用相关的所有问题提供上下文信息给代理。

   创建一个包含这些元数据的 JSON 文件，并将其保存在 metadata 目录中。例如，social-network 应用：social-network.json

2. 添加应用类

   在 apps 目录下的新 Python 文件中扩展基类：

   from aiopslab.service.apps.base import Application
   
   class MyApp(Application):
       def __init__(self):
           super().__init__("<应用元数据 JSON 的路径>")
   

   Application 类提供了应用的基础实现。你可以根据需要覆盖方法或添加新方法以满足你的应用需求，但对于大多数应用来说，基类已经足够。

如何向 AIOpsLab 添加新问题？

与应用类似，AIOpsLab 提供了一个默认的问题列表，用于评估代理的表现。然而，作为开发者，你也可以向 AIOpsLab 添加新问题，并围绕你的应用来设计这些问题。

AIOpsLab 中的每个问题包含 5 个组成部分：

1. 应用：问题所基于的应用。
2. 任务：代理需要执行的 AIOps 任务。目前我们支持：检测、定位、分析 和 缓解。
3. 故障：在应用中引入的故障。
4. 工作负载：为应用生成的工作负载。
5. 评估者：用于检查代理表现的评估者。

要向 AIOpsLab 添加新问题，在 problems 目录下创建一个新的 Python 文件，步骤如下：

1. 设置。导入你选择的应用（例如 MyApp）和任务（例如 LocalizationTask）：

   from aiopslab.service.apps.myapp import MyApp
   from aiopslab.orchestrator.tasks.localization import LocalizationTask
   

2. 定义。要定义一个问题，创建一个继承自你所选 Task 的类，并定义 3 个方法：start_workload、inject_fault 和 eval：

   class MyProblem(LocalizationTask):
       def __init__(self):
           self.app = MyApp()
       
       def start_workload(self):
           # <你的工作负载逻辑在这里>
       
       def inject_fault(self)
           # <你的故障注入逻辑在这里>
       
       def eval(self, soln、trace、duration):
           # <你的评估逻辑在这里>
   

3. 注册。最后，将你的问题添加到编排器的注册表中这里。

完整的问题示例请参见这里。

📂 项目结构

  generators - AIOpsLab 的问题生成器
  ├── fault - 按故障注入级别组织的故障生成器
  │   ├── base.py
  │   ├── inject_app.py
  │  ...
  │   └── inject_virtual.py
  └── workload - 按工作负载类型组织的工作负载生成器
      └── wrk.py - wrk 工具接口
  

  orchestrator
  ├── orchestrator.py - 主要的编排引擎
  ├── parser.py - 用于解析智能体响应的解析器
  ├── evaluators - 系统中的评估指标
  │   ├── prompts.py - 用于LLM作为评判者的提示模板
  │   ├── qualitative.py - 定性指标
  │   └── quantitative.py - 定量指标
  ├── problems - aiopslab中的问题定义
  │   ├── k8s_target_port_misconfig - 例如，K8S TargetPort配置错误问题
  │  ...
  │   └── registry.py
  ├── actions - 按照AIOps任务类型组织的智能体可执行动作
  │   ├── base.py
  │   ├── detection.py
  │   ├── localization.py
  │   ├── analysis.py
  │   └── mitigation.py
  └── tasks - 智能体需要解决的单个AIOps任务定义
      ├── base.py
      ├── detection.py
      ├── localization.py
      ├── analysis.py
      └── mitigation.py
  

  service
  ├── apps - 各应用的接口/实现
  ├── helm.py - 与集群交互的Helm接口
  ├── kubectl.py - 与集群交互的kubectl接口
  ├── shell.py - 与集群交互的Shell接口
  ├── metadata - 各应用的元数据和配置
  └── telemetry - 观测性工具（除observer外），例如用于智能体的内存日志观测
  

  observer
  ├── filebeat - Filebeat安装
  ├── logstash - Logstash安装
  ├── prometheus - Prometheus安装
  ├── log_api.py - 用于将日志数据存储到磁盘的API
  ├── metric_api.py - 用于将指标数据存储到磁盘的API
  └── trace_api.py - 用于将追踪数据存储到磁盘的API
  

  ├── config.yml - aiopslab配置文件
  ├── config.py - 配置解析器
  ├── paths.py - 路径和常量
  ├── session.py - aiopslab会话管理器
  └── utils
      ├── actions.py - 智能体可执行动作的帮助函数
      ├── cache.py - 缓存管理器
      └── status.py - aiopslab的状态、错误和警告信息
  

📄 如何引用

@inproceedings{
chen2025aiopslab,
title={{AIO}psLab: A Holistic Framework to Evaluate {AI} Agents for Enabling Autonomous Clouds},
author={Yinfang Chen and Manish Shetty and Gagan Somashekar and Minghua Ma and Yogesh Simmhan and Jonathan Mace and Chetan Bansal and Rujia Wang and Saravan Rajmohan},
booktitle={Eighth Conference on Machine Learning and Systems},
year={2025},
url={https://openreview.net/forum?id=3EXBLwGxtq}
}
@inproceedings{shetty2024building,
  title = {Building AI Agents for Autonomous Clouds: Challenges and Design Principles},
  author = {Shetty, Manish and Chen, Yinfang and Somashekar, Gagan and Ma, Minghua and Simmhan, Yogesh and Zhang, Xuchao and Mace, Jonathan and Vandevoorde, Dax and Las-Casas, Pedro and Gupta, Shachee Mishra and Nath, Suman and Bansal, Chetan and Rajmohan, Saravan},
  year = {2024},
  booktitle = {Proceedings of 15th ACM Symposium on Cloud Computing},
}

行为准则

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

许可证

版权所有 © 微软公司。保留所有权利。

根据MIT许可证授权。

商标

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

AIOpsLab 快速上手指南

AIOpsLab 是一个用于设计、开发和评估自主 AIOps 智能体的综合框架。它支持部署微服务云环境、注入故障、生成工作负载并导出遥测数据，同时提供标准化的基准测试套件。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu) 或 macOS
• Python: >= 3.11 (必须)
• 包管理: Poetry (推荐) 或 pip
• 容器编排: Helm
• 集群工具: Kind (用于本地模拟) 或任意远程 Kubernetes 集群

前置依赖安装

请确保已安装 Docker 和 kubectl。

1. 安装 Python 3.11

sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev -y

2. 安装 Poetry (官方安装方式)

⚠️ 注意: 请勿使用 apt 安装 Poetry，版本过旧可能导致兼容性问题。

curl -sSL https://install.python-poetry.org | python3.11 -
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

3. 安装 Helm

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

安装步骤

1. 克隆项目

git clone --recurse-submodules <CLONE_PATH_TO_THE_REPO>
cd AIOpsLab

2. 配置虚拟环境并安装依赖

poetry env use python3.11
poetry install
eval $(poetry env activate)

故障排查: 若遇到 "lock file not compatible" 错误，请先运行 poetry lock，再执行 poetry install。

备选方案 (使用 pip):

pip install -e .

基本使用

第一步：搭建集群

你可以选择在本机运行模拟集群，或使用远程集群。

选项 A：本地模拟集群 (推荐新手) 适用于 x86 架构机器：

kind create cluster --config kind/kind-config-x86.yaml

(ARM 架构机器请使用 kind-config-arm.yaml)

代理提示: 若使用代理，请注意 Kind 节点会继承主机代理设置。若使用 SOCKS5 代理，建议通过 Privoxy 转为 HTTP，并设置 export no_proxy=localhost 以避免本地 LLM 服务出错。

选项 B：远程集群 (Azure/CloudLab 等) 若使用 Azure VM，可通过脚本一键部署：

# Mode B: 本地运行 AIOpsLab，远程运行 K8s
python3 scripts/terraform/deploy.py --apply --resource-group <your-rg> --workers 2 --mode B

第二步：配置文件

复制并编辑配置文件，确保 k8s_host 指向控制平面节点。

• 本地 Kind 集群：设置为 kind
• 在集群内部运行：设置为 localhost

cd aiopslab
cp config.yml.example config.yml
# 使用编辑器修改 config.yml 中的 k8s_host 和 k8s_user

第三步：运行智能体

1. 准备 API Key 在项目根目录创建 .env 文件并填入密钥：

echo "OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>" > .env
# 如需其他模型可追加:
# echo "QWEN_API_KEY=<YOUR_QWEN_API_KEY>" >> .env

2. 启动交互式会话 (人类作为智能体)

python3 cli.py

在交互界面中：

(aiopslab) $ start misconfig_app_hotel_res-detection-1
# ... 等待环境 setup 完成 ...
(aiopslab) $ submit("Yes") 

3. 运行 GPT-4 基准智能体

python3 clients/gpt.py

4. 监控状态 推荐使用 k9s 查看集群实时状态：

k9s

5. (可选) 启用 W&B 实验追踪 在 .env 中添加 USE_WANDB=true，即可在 W&B 面板中以表格形式查看 session_id 和运行结果。