基于ModelArts训练平台对接SwanLab和WandB

• 方案二：ECS 实时实验监控

  方案说明

  对于需要实时监控训练过程、统一管理实验的场景，可在华为云ECS上部署SwanLab或WandB服务，并与ModelArts训练容器建立网络连接。训练过程中，SDK将实验数据实时上传至部署的服务，用户无需等待训练结束即可通过Web页面查看 Loss、Accuracy、Learning Rate、Reward等训练指标，以及训练日志和实验配置等信息。

  相比实验数据导出方案，本方案支持训练过程实时可视化、多实验统一管理，更适用于长时间训练任务、模型调优及持续迭代开发等场景。

  整体流程如下：

  图7 操作流程
  

  准备ECS资源

  部署SwanLab或WandB服务前，需要准备一台用于运行实验管理服务的ECS实例。

  创建ECS时，建议注意以下配置：

  ●ECS与ModelArts训练任务选择相同Region，以减少网络时延并便于网络配置。

  ● ECS所在VPC建议与ModelArts训练专属资源池使用的VPC保持一致。若ECS与训练资源池不在同一VPC，需要通过VPC对等连接、云连接等方式打通网络，否则训练容器可能无法访问部署在ECS上的实验管理服务。

  ● 根据实验规模选择合适的实例规格。对于个人开发及功能验证场景，普通规格即可满足部署需求；若需支持多人同时访问或管理大量实验，可根据实际情况提升实例规格。

  ● 操作系统建议选择支持Docker和Python环境的Linux Ubuntu发行版，以便后续部署SwanLab或WandB服务。

  ● 为ECS绑定弹性公网IP（EIP），便于通过浏览器访问实验管理页面，以及通过SSH登录ECS进行服务部署和运维。

  ● 配置安全组规则，放行实验管理服务端口。例如SwanLab默认使用8000端口，WandB本地服务端口以实际部署配置为准。同时需要放行SSH端口22，便于登录ECS进行运维。若仅允许训练资源池访问，建议将入方向源地址限制为训练资源池所在网段，避免端口暴露范围过大。

  完成ECS创建后，即可进行网络连通配置，并部署实验管理服务。

  配置网络连通

  完成ECS创建后，需要确保ModelArts训练资源能够访问部署在ECS上的SwanLab或WandB服务。

  开始部署前，建议确认以下网络配置：

  ● ECS与ModelArts专属资源池位于同一VPC；若不在同一VPC，请完成VPC对等连接或其他网络打通配置。

  图8 配置VPC
  

  ●ECS安全组需放行实验管理服务使用的端口（例如SwanLab默认8000，wandb默认8080）以及SSH（22）端口；若部署时修改了端口映射，则需放行实际对外提供服务的端口。

  ● 路由表配置正确，训练资源能够访问ECS私有IP。

  ● 在训练容器中可通过curl或其他网络工具访问实验管理服务地址，确认网络连通正常。

  确认以上配置无误后，即可开始部署SwanLab或WandB服务，并在训练任务中实时上传实验数据。

  部署 SwanLab 服务

  完成网络配置后，可在ECS中部署SwanLab服务，用于接收训练过程中上传的实验数据，并提供实验管理及可视化能力。操作步骤如下：

  1. 准备部署环境。部署SwanLab服务前，需要准备一台可正常运行Docker的Linux ECS，并确保已安装以下基础软件：

     ● Python

     ● pip

     ● Docker

     ● Docker Compose

     ● Git（可选）

     

     若 ECS 无法使用Git，也可以在本地下载SwanLab Self-Hosted部署文件，解压后上传至ECS。

  2. 获取部署文件。推荐通过Git获取SwanLab Self-Hosted官方部署仓库：

     git clone https://github.com/SwanHubX/self-hosted.git
     cd self-hosted/docker

     若ECS无法访问GitHub，可在本地下载仓库压缩包，上传至ECS后解压，并进入self-hosted/docker目录。

  3. 部署 SwanLab 服务。
     • 在线部署

       如果ECS可以访问镜像仓库，可直接执行官方安装脚本：

       ./install.sh

       该脚本会自动拉取 SwanLab 服务所需镜像，并完成初始化配置。

     • 离线部署

       若ECS无法访问镜像仓库，可在能够访问公网的环境中提前拉取镜像，并导入至ECS。

       在本地执行：

       docker pull swanhubx/self-hosted:latest
       docker save swanhubx/self-hosted:latest -o swanlab.tar

       若镜像文件较大，可拆分后上传：

       split -b 500M swanlab.tar swanlab.tar.

       将所有分片上传至ECS后，在ECS中执行：

       cat swanlab.tar.* > swanlab.tar
       docker load -i swanlab.tar

       完成镜像导入后，即可按照正常方式启动服务。

  4. 启动服务。进入部署目录后，执行以下命令启动SwanLab服务：

     docker-compose -f docker-compose.yaml up -d

     启动完成后，可查看容器运行状态：

     docker ps

     当相关容器状态均为Up时，表示SwanLab服务已成功启动。

  5. 验证服务。服务启动成功后，可通过浏览器访问：

     http://<ECS公网IP>:8000

     首次登录，需要输入个人license注册，个人账户的单个license只能拥有一个账号：

     图9 SwanLab Dashboard
     
  6. 修改训练代码。完成SwanLab服务部署后，需要在训练代码中接入SwanLab SDK，使训练任务能够将实验指标上传至ECS中部署的SwanLab服务。
  

  训练镜像准备、依赖安装、代码上传、OBS 挂载及训练启动脚本配置，可参考前文训练任务配置步骤，本节不再重复展开。

  配置SwanLab服务地址

  本实践中，训练容器通过ECS的私有IP访问SwanLab服务，因此需要在训练代码中指定SwanLab服务地址和API Key。

  SWANLAB_API_HOST = "http://<ECS私有IP>:8000"
  SWANLAB_API_KEY = "<Your SwanLab API Key>"

  其中：

  ● <ECS私有IP>：部署SwanLab服务的ECS私有IP。

  ● <Your SwanLab API Key>：在SwanLab页面中获取的API Key。

  为避免在代码中明文写入API Key，实际使用时建议通过环境变量或启动脚本传入。

  图10 设置API Key
  

  ● SWANLAB_API_KEY：用于身份认证，SDK通过该API Key登录并将实验数据上传至SwanLab服务。

  ● SWANLAB_API_HOST：指定SwanLab服务的API地址，SDK通过该地址与部署在ECS上的SwanLab服务进行通信推荐配置为ECS私有IP，训练容器可通过VPC私有网络上传实验数据。

  ● SWANLAB_WEB_HOST：指定SwanLab Web页面访问地址，用于生成实验链接及页面跳转。推荐配置为ECS 弹性公网IP（EIP），便于用户在本地浏览器直接访问实验管理页面。

  接入SwanLab SDK

  完成环境变量配置后，无需在训练代码中显式调用swanlab.login()，SDK会自动读取环境变量中的认证信息并连接部署在ECS上的SwanLab 服务。训练代码可直接参考前文 “集成SwanLab SDK” 章节中的示例，仅需保证调用swanlab.init()、swanlab.log()和swanlab.finish()完成实验初始化、指标记录及实验结束即可。

  提交训练任务

  完成代码修改后，按照前文训练任务提交方式创建自定义训练任务即可。

  本实践中，训练容器通过ECS的私有ip访问SwanLab服务，因此需确保训练任务运行时能够访问：

  http://<ECS私有IP>:8000

  浏览器前往 http://<ECS公网IP>:8000 查看训练过程中的参数：

  图11 查看swanlab数据
  

  部署 WandB 服务

  部署WandB服务步骤如下：

  1. ECS环境要求，同SwanLab部署方案。
  2. 获取WandB镜像。WandB本地部署主要依赖wandb/local镜像。

     如果ECS可以访问Docker Hub，可直接拉取镜像：

     docker pull wandb/local:latest

     当前WandB Local官方Docker镜像仅支持x86_64（AMD64）架构，暂不支持ARM64架构。因此部署WandB Local服务时，建议选择x86架构的ECS。

     如果 ECS 无法访问Docker Hub，可参考SwanLab离线镜像导入方案，先在可访问公网的环境中拉取镜像并导出：

     docker pull wandb/local:latest
     docker save wandb/local:latest -o wandb-local.tar

     若导出的镜像文件较大，可参考SwanLab离线镜像导入方案 对镜像进行拆分、上传、合并后再导入ECS。

     拆分镜像：

     split -b 500M wandb-local.tar wandb-local.tar.

     在ECS上合并镜像：

     cat wandb-local.tar.* > wandb-local.tar

     导入镜像：

     docker load -i wandb-local.tar

  3. 启动WandB服务。

     镜像导入完成后，执行以下命令启动WandB Local服务：

     docker run -d \
       --name wandb-local \
       -p 8080:8080 \
       wandb/local:latest

     启动完成后，可通过以下命令查看容器状态：

     docker ps

     若容器状态显示为Up，则表示WandB服务已成功启动。

  4. 访问服务。WandB默认使用8080端口提供 Web 服务，可通过浏览器访问：

     http://<ECS公网IP>:8080

     访问前需确保：

     ● ECS已绑定弹性公网IP（EIP）。

     ● ECS安全组已放通8080端口。

     ● 操作系统防火墙已允许8080端口访问（如启用了防火墙）。

     完成以上配置后，即可通过浏览器访问WandB管理页面。

     图12 访问WandB
     
  5. 训练代码设计。WandB 的训练代码集成方式与前文SwanLab基本一致，包括SDK安装、训练代码上传、启动脚本配置以及ModelArts训练任务创建等操作，可直接参考SwanLab训练代码设计，本节仅介绍WandB的差异配置。

     为避免在代码中明文写入API Key，建议通过环境变量或启动脚本传入认证信息。WandB SDK启动后会自动读取相关环境变量完成认证，无需在代码中显式调用wandb.login()。其中：

     ● WANDB_API_KEY：用于身份认证，SDK通过该API Key登录部署在ECS上的WandB服务。

     ● WANDB_BASE_URL：指定WandB服务地址，SDK通过该地址连接部署在ECS上的WandB服务。推荐配置为ECS私有IP，训练容器可通过VPC私有网络上传实验数据。

     

     完成环境变量配置后，即可像使用WandB官方云服务一样，在训练过程中记录实验信息和训练指标。

     训练代码运行后，WandB SDK将自动把训练过程中记录的超参数、指标及日志上传至部署在ECS上的WandB服务。训练结束后，可通过浏览器访问http://<ECS公网IP>:8080查看实验运行情况、训练曲线及相关日志。

     图13 在WandB上查看训练指标
     
     

     本文示例截图使用8888端口进行部署，这是由于测试环境中8080端口已被其他服务占用。WandB Local默认使用8080端口，实际部署时可根据环境情况修改为任意未被占用的端口，同时启动命令、访问地址及训练代码中的服务地址保持一致即可。

前置说明

强化学习作业运行时，可通过自定义镜像预装SDK，也可以在训练启动命令中动态安装SDK。

若使用自定义镜像，可提前将SwanLab或WandB SDK安装到镜像中，并将镜像上传至SWR。创建强化学习作业时选择该镜像，即可直接执行训练代码，无需在任务启动阶段重复安装依赖。

若使用未预装SDK的镜像，可在训练任务启动命令中动态安装相应SDK。例如，安装WandB SDK：

python3 -m pip install wandb -i http://<PYPI_MIRROR>/simple/ --trusted-host <PYPI_MIRROR_HOST>

安装SwanLab SDK：

python3 -m pip install swanlab -i http://<PYPI_MIRROR>/simple/ --trusted-host <PYPI_MIRROR_HOST>

其中，<PYPI_MIRROR> 表示训练容器能够访问的PyPI镜像源。若训练容器无法访问公网，应使用企业内部或其他可访问的软件源。

配置训练代码

强化学习作业主要通过OBS挂载方式，将用户上传的训练代码加载至训练容器。

创建强化学习训练作业时，需要将包含训练代码的OBS路径配置为挂载目录，并指定对应的容器挂载路径。训练任务启动后，可通过Python命令直接执行挂载目录中的训练脚本。

例如：

python3 /home/ma-user/modelarts/user-model/code/RL.py

实际脚本路径应根据训练作业配置的OBS挂载目录进行调整。

SwanLab或WandB的服务地址、API Key等信息可以通过训练作业环境变量注入训练容器，避免直接写入训练代码。

修改训练代码

强化学习训练代码的SDK接入方式与前文自定义训练基本一致，只需在原有训练逻辑中增加SDK初始化、指标记录和任务结束处理。

以WandB为例，通常需要调用以下接口：

wandb.login()
wandb.init()
wandb.log()
wandb.finish()

训练过程中，可通过wandb.log()记录Reward、Loss、Episode、Learning Rate、TD Error等指标。

示例初始化代码如下：

import os
import time

import math
import random

import wandb


WANDB_BASE_URL = os.getenv("WANDB_BASE_URL")
WANDB_API_KEY = os.getenv("WANDB_API_KEY")


def run_episode(
    episode: int,
    epsilon: float,
    max_steps: int = 50,
) -> tuple[float, int, float]:

    position = 0
    target = 10
    total_reward = 0.0
    td_errors = []

    for step in range(1, max_steps + 1):
        # epsilon-greedy：随机探索或选择朝目标前进
        if random.random() < epsilon:
            action = random.choice([-1, 1])
        else:
            action = 1 if position < target else -1

        old_distance = abs(target - position)
        position += action
        new_distance = abs(target - position)

        if position == target:
            reward = 10.0
            done = True
        elif new_distance < old_distance:
            reward = 0.5
            done = False
        else:
            reward = -1.0
            done = False

        total_reward += reward

        # 模拟 TD Error，用于生成训练 loss
        predicted_value = random.uniform(-0.5, 0.5)
        target_value = reward + 0.95 * random.uniform(-0.5, 0.5)
        td_error = target_value - predicted_value
        td_errors.append(td_error)

        if done:
            loss = sum(error**2 for error in td_errors) / len(td_errors)
            return total_reward, step, loss

    loss = sum(error**2 for error in td_errors) / len(td_errors)
    return total_reward, max_steps, loss


def main() -> None:
    if not WANDB_API_KEY:
        raise RuntimeError()

    # 显式指定自建 W&B 服务
    os.environ["WANDB_BASE_URL"] = WANDB_BASE_URL
    os.environ["WANDB_API_KEY"] = WANDB_API_KEY

    print(f"W&B server: {WANDB_BASE_URL}")
    print("正在登录 W&B 服务……")

    wandb.login(
        key=WANDB_API_KEY,
        host=WANDB_BASE_URL,
        relogin=True,
    )

    run = wandb.init(
        project="modelarts-rl-test",
        name=f"ecs-wandb-test-{int(time.time())}",
        job_type="reinforcement-learning",
        config={
            "algorithm": "epsilon-greedy",
            "environment": "simple-line-world",
            "episodes": 30,
            "max_steps": 50,
            "initial_epsilon": 1.0,
            "minimum_epsilon": 0.05,
            "epsilon_decay": 0.90,
            "discount_factor": 0.95,
            "learning_rate": 0.01,
            "wandb_server": WANDB_BASE_URL,
        },
    )

    epsilon = 1.0
    rewards = []

    try:
        for episode in range(1, run.config.episodes + 1):
            reward, episode_length, loss = run_episode(
                episode=episode,
                epsilon=epsilon,
                max_steps=run.config.max_steps,
            )

            rewards.append(reward)
            average_reward = sum(rewards[-5:]) / min(len(rewards), 5)

            learning_rate = (
                run.config.learning_rate
                * math.exp(-0.02 * episode)
            )

            run.log(
                {
                    "episode": episode,
                    "train/reward": reward,
                    "train/average_reward_5": average_reward,
                    "train/episode_length": episode_length,
                    "train/loss": loss,
                    "train/epsilon": epsilon,
                    "train/learning_rate": learning_rate,
                },
                step=episode,
            )

            print(
                f"episode={episode:02d}, "
                f"reward={reward:6.2f}, "
                f"average_reward={average_reward:6.2f}, "
                f"steps={episode_length:02d}, "
                f"loss={loss:.4f}, "
                f"epsilon={epsilon:.4f}"
            )

            epsilon = max(
                run.config.minimum_epsilon,
                epsilon * run.config.epsilon_decay,
            )

            time.sleep(0.2)

        run.summary["final_reward"] = rewards[-1]
        run.summary["best_reward"] = max(rewards)
        run.summary["average_reward"] = sum(rewards) / len(rewards)
        run.summary["training_status"] = "success"

        print("强化学习模拟训练完成，指标已发送到 W&B。")

    except Exception:
        run.summary["training_status"] = "failed"
        raise

    finally:
        run.finish()


if __name__ == "__main__":
    main()

使用SwanLab时，可在训练代码中调用对应接口：

swanlab.login()
swanlab.init()
swanlab.log()
swanlab.finish()

具体初始化参数、服务地址配置及指标记录方式可参考前文SwanLab相关章节。

查看实验结果

强化学习作业的实验结果查看方式与自定义训练一致，可根据使用场景选择离线查看或实时监控。

离线查看

训练过程中，将SwanLab或WandB生成的实验文件保存至训练任务配置的OBS输出挂载目录。训练结束后，实验文件将同步至对应OBS路径。

用户可将实验文件下载至本地，并通过SwanLab或WandB提供的本地工具查看和分析实验结果。具体配置方式可参考前文实验文件导出与本地查看章节。

实时监控

若在ECS上部署SwanLab或WandB服务，并在训练代码中配置对应的服务地址和API Key，训练过程中的实验数据可实时上传至ECS上部署的服务。

用户可通过Web页面查看训练任务状态、实验指标变化以及不同训练任务之间的对比结果。

使用实时监控模式时，应确保训练容器能够正常访问ECS服务。

网络配置说明

若采用ECS部署SwanLab或WandB服务进行实时监控，建议强化学习作业使用专属资源池运行。

同时，应确保专属资源池与ECS之间网络互通，可采用以下方式：

● 专属资源池与ECS使用同一个VPC。

● 专属资源池与ECS位于不同VPC，并在两个VPC之间建立对等连接，同时配置相应路由和安全组规则。

还需要在ECS安全组中放通SwanLab或WandB服务使用的端口，并确保训练容器能够访问对应的服务地址。

网络连通配置方式与前文自定义训练实时监控方案一致，此处不再重复介绍。

验证结果

强化学习平台接入SwanLab或WandB的基本原理与ModelArts自定义训练一致。

完成SDK安装、OBS代码挂载、环境变量配置和网络连通配置后，强化学习作业即可记录Reward、Loss、Episode、Learning Rate等训练指标，并支持指标可视化、历史实验管理和多次实验对比。

本节以WandB为例展示强化学习作业的接入方式。SwanLab的整体使用流程与WandB基本一致，具体接口和配置方式可参考前文SwanLab相关章节。