# aware

**Repository Path**: chengjiantao/aware

## Basic Information

- **Project Name**: aware
- **Description**: 参考论文实现的RL代码，AWARE: Automate Workload Autoscaling with Reinforcement Learning in Production Cloud Systems
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-01-21
- **Last Updated**: 2026-06-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AWARE 实验代码交接入口

## 项目介绍

这个仓库当前主要包含两条实验线。

1. `rl-controller` 是强化学习控制器实验线，目标是在 NF simulator 中搜索 8 个 batch size 参数。当前主线是 MetaPPO 加 Transition Encoder，并包含轨迹级对比学习、门控时间一致性和熵值控制等实验。

2. `nf_simulator`、`predict/differentiable_proxy` 是代理模型和梯度搜索实验线，目标是用基于 DU List 的吞吐可微代理、Transformer 延迟预测器和随机梯度下降搜索 high reward action。

当前推荐先阅读 `doc` 目录下的四个交接文档。README 只作为入口和环境配置说明，具体实验命令和设计细节以交接文档为准。

## doc 目录下的交接文档

### 交接文档1

`doc/交接文档1.md` 是 rl-controller 主线代码交接文档。

它说明当前 RL 训练入口、环境封装、并行模拟、Transition Encoder、轨迹对比学习、门控时间一致性和熵值控制分别对应哪些代码。阅读这个文档可以理解 rl-controller 的整体结构，以及为什么当前主线是 `main.py` 加 `MetaPPOWithEncoder`。

这个文档适合在修改 RL 算法代码前阅读，尤其是要确认哪些文件是主线、哪些文件是历史分支或对照组。

### 交接文档2

`doc/交接文档2实验执行命令.md` 是 rl-controller 实验命令交接文档。

它记录了基础实验、第二阶段实验、第三阶段实验、优化前后对比实验等命令。第 43 组“优化前后对比实验”已经改成使用 `PYTHON_BIN` 指定 Python 环境，不再依赖旧用户的 `vpp-rl-py311` conda 环境。

这个文档适合在实际启动 rl-controller 实验时阅读。由于其中很多早期历史命令仍保留 `conda activate vpp-rl-py311`，新启动实验时应优先参考文档开头的“运行环境准备”和第 43 组的新写法。

### 交接文档3

`doc/交接文档3已有代码和设计方案的关联.md` 说明已有设计方案和代码文件之间的对应关系。

它重点区分基础 PPO、MetaPPO、MetaPPO 加 Transition Encoder、随机策略对照和 MAML 保留分支。阅读这个文档可以避免把主线方案、对照方案和历史实验分支混在一起。

这个文档适合在做代码清理、方案复盘或解释实验设计时阅读。

### 交接文档4

`doc/交接文档4代理模型与梯度搜索.md` 是代理模型与梯度搜索交接文档。

它说明当前最终方案如何把数据采集、DU List、DU 吞吐可微代理、Transformer 延迟预测模型、残差模型、随机梯度下降搜索和黑盒模拟器复验串起来。当前统一使用 `curve_vpp_confs_v3`，batch size 范围是 1 到 128，延迟口径是 P95，reward 使用归一化吞吐减去 P95 延迟相对 50 微秒阈值的距离惩罚。

这个文档适合在复现实习前最终实验、继续训练代理模型、继续做梯度搜索或分析 reward 搜索结果时阅读。

## 通用环境准备

不要把个人环境名当作可复现依赖。历史命令中的 `vpp-rl-py311` 是旧用户环境名，不会随 git 仓库一起上传。其他人 clone 仓库后，应重新创建自己的 Python 环境。

推荐使用仓库根目录下的本地虚拟环境，并通过 `PYTHON_BIN` 显式指定 Python。

1. 进入仓库根目录：`cd /mnt/disk1/chengjiantao/aware`

2. 创建环境：`python3 -m venv .venv-rl`

3. 升级 pip：`.venv-rl/bin/python -m pip install --upgrade pip`

4. 安装 PyTorch。当前机器验证过 CUDA 12.6 对应的命令是：`.venv-rl/bin/python -m pip install torch --index-url https://download.pytorch.org/whl/cu126`

5. 安装其余依赖：`.venv-rl/bin/python -m pip install -r rl-controller/requirements.txt`

6. 设置 Python 入口：`export PYTHON_BIN=/mnt/disk1/chengjiantao/aware/.venv-rl/bin/python`

7. 检查环境：`$PYTHON_BIN -c "import gymnasium, psutil, matplotlib, torch, numpy, pandas, openpyxl; print('env ok', torch.cuda.is_available())"`

如果是在当前机器继续使用已经验证过的环境，可以直接设置：`export PYTHON_BIN=/mnt/disk1/chengjiantao/aware/.venv-diff-proxy/bin/python`

`.venv-rl`、`.venv-diff-proxy` 这类虚拟环境目录已经被 `.gitignore` 忽略，不应该提交到 git。

## 编译 nf_simulator C 组件

`nf_simulator` 依赖 C dispatcher。`libdispatcher.so` 和 `ngsim_dispatch` 是本地构建产物，不一定会随 git 仓库上传。clone 后如果运行模拟器时报找不到 dispatcher 或 shared library，应重新编译。

1. 进入目录：`cd /mnt/disk1/chengjiantao/aware/nf_simulator/lib`

2. 编译：`SCHEDULE_TYPE=SCHE_PRIO USE_RUNTIME_SUPPORT=1 ./build.sh`

3. 回到仓库根目录：`cd /mnt/disk1/chengjiantao/aware`

4. 做最小检查：`$PYTHON_BIN -m nf_simulator.du_batch_experiment --help`

## 运行交接文档2中的 rl-controller 实验

交接文档2对应 `rl-controller` 训练实验。运行前应完成通用环境准备，并确认 `PYTHON_BIN` 已设置。

第 43 组优化后第三阶段实验的启动方式如下。

1. 进入目录：`cd /mnt/disk1/chengjiantao/aware/rl-controller`

2. 创建 tmux：`tmux new -s 43_exp_optimized_stage3_comparison`

3. 设置 GPU 和 matplotlib 缓存目录：`export CUDA_VISIBLE_DEVICES=0`，`export MPLCONFIGDIR=/tmp/matplotlib-cache`

4. 如果没有设置过 `PYTHON_BIN`，在当前目录下设置：`export PYTHON_BIN=${PYTHON_BIN:-../.venv-rl/bin/python}`

5. 运行完整命令请看 `doc/交接文档2实验执行命令.md` 的第 43 组。不要再使用 `conda activate vpp-rl-py311`。

6. 运行一个最小启动测试可以使用：`$PYTHON_BIN ./main.py --app_name smoke_rl_controller_stage3_len5 --traffic_mode 0 --use_parallel_env --max_parallel_workers 1 --use_encoder --encoder_type mlp --total_iterations 1 --episodes_per_iteration 1 --episode_length 5 --steps_per_mode 5000 --enable_trajectory_contrastive --trajectory_contrastive_weight 0.05 --trajectory_length 5 --enable_gated_temporal --gated_temporal_weight 0.03 --action_change_threshold 0.3 --reward_change_threshold 0.5 --entropy_floor 2.5 --entropy_floor_weight 0.01 --enable_adaptive_entropy_floor --action_top_ratio_threshold 0.5 --adaptive_entropy_increase 1.5 --max_entropy_coef 0.15 --entropy_recovery_patience 3 --seed 20260627`

实验输出主要保存在 `rl-controller/logs` 和 `rl-controller/checkpoints`。这些目录通常不提交到 git。

## 运行交接文档4中的代理模型和梯度搜索实验

交接文档4对应代理模型、Transformer 延迟预测和混合 reward 梯度搜索。运行前应完成通用环境准备，并重新编译 nf_simulator C 组件。

需要注意，`predict/data/` 和 `nf_simulator/log/` 是实验输出目录，通常不会随 git 仓库上传。因此 clone 后不会自动拥有 `predict/data/最终实验/20260626_175334_curve_vpp_confs_v3_batch128_p95_reward50us` 这个完整实验目录。要复现实验有两种方式。

1. 按 `doc/交接文档4代理模型与梯度搜索.md` 中的命令重新采集数据、训练模型并搜索。

2. 从已有机器手动拷贝完整实验目录，再运行分析或继续搜索。

从零复现实验时，建议按以下顺序执行。

1. 运行 DU 灰盒和残差大规模实验，生成可微代理数据和残差模型。命令见交接文档4的“运行 DU 灰盒和残差大规模实验”。

2. 运行 DU Transformer 数据采集、训练、评估和搜索。命令见交接文档4的“运行 DU Transformer 数据采集、训练、评估和搜索”。

3. 运行最终混合 reward 搜索。命令见交接文档4的“运行最终混合 reward 搜索”。

4. 如果只想检查入口是否正常，可以运行：`$PYTHON_BIN -m predict.differentiable_proxy.search.hybrid_du_transformer_reward_search --help`

交接文档4的当前实验约定是 `curve_vpp_confs_v3`、`max_batch=128`、P95 延迟、50 微秒 reward 阈值。修改这些设置后，旧训练样本中的 reward 和延迟口径可能不再一致，应重新采集或重新回放计算。

## 上传 git 前检查

上传前应确认提交的是代码、文档和依赖说明，而不是本地环境和大规模实验输出。

1. 检查状态：`git status --short`

2. 应提交的环境相关文件包括 `.gitignore`、`rl-controller/requirements.txt`、`README.md` 和更新后的交接文档。

3. 不应提交 `.venv-rl`、`.venv-diff-proxy`、`predict/data/`、`nf_simulator/log/`、`rl-controller/logs` 和 `rl-controller/checkpoints`。

4. 如果希望别人直接复用某次大规模实验结果，应单独说明实验目录如何拷贝，而不是依赖 git 自动包含这些输出。