多智能体资源优化（MARO）平台是面向现实世界资源优化的强化学习即服务（RaaS）实例。它可以应用于许多重要的工业领域，例如物流中的集装箱库存管理、交通领域的共享单车调度、数据中心的虚拟机调度以及金融领域的资产管理等。除了强化学习之外，它还支持其他规划/决策机制，如运筹学。

MARO的主要组件：

• 模拟工具包：提供一些预定义场景，并包含用于构建新场景的可重用模块。
• 强化学习工具包：为强化学习提供全栈抽象，包括智能体管理器、智能体、强化学习算法、学习者、执行者以及各种策略调整器。
• 分布式工具包：提供分布式通信组件、用户自定义函数接口以实现消息自动处理、集群部署和作业编排等功能。

目录

文件/文件夹	描述
maro	MARO源代码。
docs	MARO文档，托管在readthedocs上。
examples	MARO示例展示。
notebooks	MARO快速入门笔记本。

尝试MARO游乐场，快速体验一下吧。

从PyPI安装MARO

注：CLI命令（包括可视化工具）并未包含在pymaro软件包中。若需启用这些功能，需从源码安装。

• Mac OS / Linux

  pip install pymaro
  

• Windows

  # 如果尚未安装，请先安装torch。
  pip install torch===1.6.0 torchvision===0.7.0 -f https://download.pytorch.org/whl/torch_stable.html
  
  pip install pymaro
  

从源代码安装 MARO

注：如果您想使用 CLI 命令（包括可视化工具），请从源代码安装。

• 先决条件

  • C++ 编译器
    • Linux 或 Mac OS X：gcc
    • Windows：适用于 Visual Studio 2017 的构建工具

• 启用虚拟环境

  • Mac OS / Linux

    # 如果您的环境不干净，请先创建一个虚拟环境。
    python -m venv maro_venv
    source ./maro_venv/bin/activate
    

  • Windows

    # 如果您的环境不干净，请先创建一个虚拟环境。
    python -m venv maro_venv
    
    # 在 PowerShell 中可能会遇到 SecurityError，您可能需要执行以下命令。
    Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted
    
    # 激活虚拟环境。
    .\maro_venv\Scripts\activate
    

• 安装 MARO

  # 使用 Git 克隆整个源代码。
  git clone https://github.com/microsoft/maro.git
  

  • Mac OS / Linux

    # 从源代码安装 MARO。
    bash scripts/install_maro.sh;
    pip install -r ./requirements.dev.txt;
    

  • Windows

    # 从源代码安装 MARO。
    .\scripts\install_maro.bat;
    pip install -r ./requirements.dev.txt;
    

• 注：如果找不到您的包，请记得设置 PYTHONPATH

  • Mac OS / Linux

  export PYTHONPATH=MARO路径
  

  • Windows

  $Env:PYTHONPATH=MARO路径
  

快速示例

from maro.simulator import Env

env = Env(scenario="cim", topology="toy.5p_ssddd_l0.0", start_tick=0, durations=100)

metrics, decision_event, is_done = env.step(None)

while not is_done:
    metrics, decision_event, is_done = env.step(None)

print(f"environment metrics: {env.metrics}")

环境可视化

# 在初始化环境实例时启用环境转储功能
env = Env(scenario="cim",
          topology="toy.5p_ssddd_l0.0",
          start_tick=0,
          durations=100,
          options={"enable-dump-snapshot": "./dump_data"})

# 使用转储数据检查环境
maro inspector dashboard --source_path ./dump_data/您的快照转储文件夹

案例展示

• 案例 I - 集装箱库存管理

• 案例 II - Citi Bike

运行 Playground

• 从 Docker Hub 拉取镜像

  # 从 Docker Hub 拉取镜像
  docker pull maro2020/playground
  
  # 运行 Playground 容器。
  # Redis commander（Redis 的 GUI）-> http://127.0.0.1:40009
  # 带有 MARO 的 Jupyter Lab -> http://127.0.0.1:40010
  docker run -p 40009:40009 -p 40010:40010 maro2020/playground
  

• 从源代码构建

  • Mac OS / Linux

    # 构建 Playground 镜像。
    bash ./scripts/build_playground.sh
    
    # 运行 Playground 容器。
    # Redis commander（Redis 的 GUI）-> http://127.0.0.1:40009
    # 带有 MARO 的 Jupyter Lab -> http://127.0.0.1:40010
    docker run -p 40009:40009 -p 40010:40010 maro2020/playground
    

  • Windows

    # 构建 Playground 镜像。
    .\scripts\build_playground.bat
    
    # 运行 Playground 容器。
    # Redis commander（Redis 的 GUI）-> http://127.0.0.1:40009
    # 带有 MARO 的 Jupyter Lab -> http://127.0.0.1:40010
    docker run -p 40009:40009 -p 40010:40010 maro2020/playground
    

贡献

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

当您提交拉取请求时，CLA 机器人会自动确定您是否需要提供 CLA，并相应地标记 PR（例如状态检查、评论）。只需按照机器人提供的指示操作即可。对于使用我们 CLA 的所有仓库，您只需执行一次此操作。

该项目已采用 微软开源行为准则。 更多信息请参阅 行为准则常见问题解答 或发送电子邮件至 opencode@microsoft.com 以获取更多问题或意见。

相关论文

集装箱库存管理

Wenlei Shi, Xinran Wei, Jia Zhang, Xiaoyuan Ni, Arthur Jiang, Jiang Bian, Tie-Yan Liu. “具有预训练异构观测表示的协作策略学习”。AAMAS 2021

Xihan Li, Jia Zhang, Jiang Bian, Yunhai Tong, Tie-Yan Liu. “用于复杂物流网络中资源平衡的协作式多智能体强化学习框架”。AAMAS 2019

相关新闻

MSRA 2021 年十大黑客技术

开源平台 MARO：资源优化的任意门

AI 从“点”到“面”

引用我们

许可证

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

根据 MIT 许可证授权。

MARO 快速上手指南

MARO (Multi-Agent Resource Optimization) 是微软开源的多智能体资源优化平台，旨在为现实世界的资源优化问题提供“强化学习即服务”（RaaS）。它广泛应用于物流（集装箱库存管理）、交通（共享单车调度）、数据中心（虚拟机调度）及金融资产管理等领域。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python 版本: 支持 Python 3.x (具体版本请参考 PyPI 文件列表)
• 编译器依赖 (仅当从源码安装以使用 CLI 和可视化工具时需要):
  • Linux / macOS: gcc
  • Windows: Visual Studio 2017 Build Tools

注意: 如果仅需使用 Python SDK 进行算法开发，可直接通过 pip 安装，无需编译器。若需使用命令行工具（如可视化仪表盘），建议从源码安装。

2. 安装步骤

方式一：通过 PyPI 安装（推荐用于快速开发）

此方式安装核心 Python 包 pymaro，不包含 CLI 命令和可视化工具。

macOS / Linux:

pip install pymaro

Windows: Windows 用户需先安装特定版本的 PyTorch，再安装 MARO：

# 1. 安装 PyTorch (如未安装)
pip install torch===1.6.0 torchvision===0.7.0 -f https://download.pytorch.org/whl/torch_stable.html

# 2. 安装 MARO
pip install pymaro

方式二：从源码安装（包含 CLI 和可视化工具）

如需使用 maro 命令行工具及可视化功能，请按以下步骤操作：

1. 创建并激活虚拟环境

macOS / Linux:

python -m venv maro_venv
source ./maro_venv/bin/activate

Windows (PowerShell):

python -m venv maro_venv
# 若遇到执行策略错误，运行以下命令解锁
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted
.\maro_venv\Scripts\activate

2. 克隆代码并安装

# 克隆仓库
git clone https://github.com/microsoft/maro.git
cd maro

macOS / Linux:

bash scripts/install_maro.sh
pip install -r ./requirements.dev.txt

Windows:

.\scripts\install_maro.bat
pip install -r ./requirements.dev.txt

3. 配置环境变量

如果导入包时提示找不到模块，请设置 PYTHONPATH：

macOS / Linux:

export PYTHONPATH=/path/to/maro

Windows:

$Env:PYTHONPATH="C:\path\to\maro"

3. 基本使用

以下是一个最简单的示例，展示如何初始化一个集装箱库存管理（CIM）场景并运行仿真。

代码示例

from maro.simulator import Env

# 初始化环境
# scenario: 场景名称 (cim = 集装箱库存管理)
# topology: 拓扑结构
# start_tick: 开始时间步
# durations: 持续时长
env = Env(scenario="cim", topology="toy.5p_ssddd_l0.0", start_tick=0, durations=100)

# 执行第一步
metrics, decision_event, is_done = env.step(None)

# 运行直到结束
while not is_done:
    metrics, decision_event, is_done = env.step(None)

# 输出最终指标
print(f"environment metrics: {env.metrics}")

可视化体验

若已从源码安装，可开启数据快照并使用仪表盘查看仿真过程：

1. 启用数据导出：在初始化 Env 时添加 options 参数。

   env = Env(scenario="cim",
             topology="toy.5p_ssddd_l0.0",
             start_tick=0,
             durations=100,
             options={"enable-dump-snapshot": "./dump_data"})
   # ... 运行 env.step() 逻辑 ...
   

2. 启动可视化仪表盘：

   maro inspector dashboard --source_path ./dump_data/YOUR_SNAPSHOT_DUMP_FOLDER
   

快速体验 Playground

如果您希望立即体验完整环境（包含 Jupyter Lab 和 Redis 监控），可以使用 Docker：

# 拉取镜像
docker pull maro2020/playground

# 运行容器
# 访问 http://127.0.0.1:40010 使用 Jupyter Lab
# 访问 http://127.0.0.1:40009 使用 Redis Commander
docker run -p 40009:40009 -p 40010:40010 maro2020/playground