hc/SemanticCommunication
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
SemanticCommunication/code/README.md

11 KiB
Raw Permalink Blame History

Co-MADDPG: 面向语义与传统混合通信的合作竞争多智能体资源分配框架

Co-MADDPG: Cooperative-Competitive Multi-Agent Resource Allocation for Semantic-Traditional Hybrid Wireless Communication

项目简介 / Project Overview

本项目实现了 Co-MADDPG 算法——一种基于 Stackelberg 博弈和动态合作-竞争切换机制的多智能体深度强化学习框架，用于语义通信与传统比特级通信共存场景下的 OFDMA 无线资源分配。

This project implements the Co-MADDPG algorithm — a multi-agent deep reinforcement learning framework based on Stackelberg game dynamics and dynamic cooperation-competition switching for OFDMA wireless resource allocation in semantic-traditional hybrid communication systems.

核心创新 / Key Innovations

  1. 合作竞争博弈建模 / Coopetition Game Modeling: 将语义用户 (Leader) 与传统用户 (Follower) 之间的资源竞争建模为 Stackelberg 博弈
  2. 动态 λ(t) 切换 / Dynamic λ(t) Switching: λ(t) = sigmoid(β·(QoE_sys - Q_th))，根据系统 QoE 在合作与竞争之间自适应切换
  3. 异构 QoE 指标 / Heterogeneous QoE: 语义用户使用 SSim + 压缩率，传统用户使用速率满足度
  4. CTDE 架构 / CTDE Architecture: 集中训练分散执行，联合 Critic 网络

目标期刊 / Target Venue

IEEE Transactions on Communications (TCOM)

环境要求 / Requirements

Python 版本 / Python Version

  • Python 3.8+

依赖库 / Dependencies

pip install numpy torch pyyaml matplotlib
库 / Library 版本 / Version 用途 / Purpose
numpy ≥1.20 数值计算、信道建模 / Numerical computation, channel modeling
torch ≥1.10 (CPU 或 GPU) 神经网络训练 / Neural network training
pyyaml ≥5.0 配置文件加载 / Configuration file loading
matplotlib ≥3.4 IEEE 风格绘图 / IEEE-style plotting

硬件建议 / Hardware Recommendations

场景 / Scenario 配置 / Configuration
功能验证 (Smoke Test) CPU, 2-5 episodes, ~30 秒
短期训练 (Short Training) CPU/GPU, 100-500 episodes, ~10-60 分钟
完整训练 (Full Training) GPU (CUDA), 5000 episodes, ~2-8 小时

快速开始 / Quick Start

1. 克隆项目 / Clone

git clone <repo-url>
cd SemantiCommunication/code

2. 功能验证 (Smoke Test)

# 训练 Co-MADDPG 2 个 episode（验证代码逻辑）
python train.py --algo co_maddpg --episodes 2 --steps 10

# 训练所有 8 个算法各 2 个 episode
python train.py --algo all --episodes 2 --steps 10

3. 正式训练 / Full Training

# 单算法训练（推荐先跑主算法）
python train.py --algo co_maddpg --episodes 5000

# 训练全部 8 个算法
python train.py --algo all --episodes 5000

# 指定配置文件
python train.py --algo co_maddpg --config configs/default.yaml --episodes 5000

4. 评估与绘图 / Evaluation & Plotting

# 运行全部 8 个评估场景，生成 12+ 张图
python evaluate.py

# 指定结果目录
python evaluate.py --results_dir results/

支持的算法 / Supported Algorithms

# 算法 / Algorithm CLI 名称 λ 更新方式 / Update Critic 类型 用途 / Purpose
1 Co-MADDPG co_maddpg 动态 dynamic Stackelberg Joint (CTDE) 本文提出 / Proposed
2 PureCooperative pure_coop 1.0 Simultaneous Joint 消融：去除竞争 / Ablate competition
3 PureCompetitive pure_comp 0.0 Simultaneous Joint 消融：去除合作 / Ablate cooperation
4 FixedLambda fixed_lambda 0.5 Stackelberg Joint 消融：去除动态 λ / Ablate dynamic λ
5 IDDPG iddpg 0.0 Simultaneous Independent 消融：去除 CTDE / Ablate CTDE
6 SingleAgentDQN single_dqn 0.5 N/A Centralized 非 MARL 基线 / Non-MARL baseline
7 EqualAllocation equal_alloc 0.5 N/A None 性能下界 / Lower bound
8 SemanticOnly semantic_only 1.0 N/A Single 消融：去除异构性 / Ablate heterogeneity

项目结构 / Project Structure

SemantiCommunication/code/
│
├── configs/                     # 配置文件 / Configuration
│   ├── __init__.py
│   └── default.yaml             # 主配置（超参数、环境参数）/ Main config
│
├── envs/                        # 环境模块 / Environment modules
│   ├── __init__.py
│   ├── channel_model.py         # 3GPP 信道模型 / 3GPP channel model (Eq.5-8)
│   ├── semantic_module.py       # 语义相似度 SSim / Semantic similarity (SSim)
│   └── wireless_env.py          # Gym 风格无线环境 / Gym-like wireless env
│
├── agents/                      # 核心算法 / Core algorithm
│   ├── __init__.py
│   ├── actor.py                 # Actor 网络 FC→Tanh→[0,1]
│   ├── critic.py                # Critic 网络 (Joint Q-value)
│   ├── noise.py                 # OU 探索噪声 / OU exploration noise
│   ├── replay_buffer.py         # 9-field 经验回放 / 9-field replay buffer
│   └── co_maddpg.py             # Co-MADDPG 主算法 / Main algorithm (★)
│
├── baselines/                   # 7 个基线算法 / 7 baseline algorithms
│   ├── __init__.py
│   ├── pure_coop.py             # λ=1 纯协作
│   ├── pure_comp.py             # λ=0 纯竞争
│   ├── fixed_lambda.py          # λ=0.5 固定
│   ├── iddpg.py                 # 独立 DDPG (无 CTDE)
│   ├── single_dqn.py            # 集中式 DQN
│   ├── equal_alloc.py           # 均分分配
│   └── semantic_only.py         # 仅语义 DDPG
│
├── utils/                       # 工具模块 / Utility modules
│   ├── __init__.py
│   ├── metrics.py               # 评估指标 (Jain fairness, λ, rewards)
│   └── visualization.py         # IEEE 风格绘图 (12 种图)
│
├── train.py                     # 训练入口 / Training entry point (★)
├── evaluate.py                  # 评估入口 / Evaluation entry point (★)
├── README.md                    # 本文件 / This file
├── ARCHITECTURE.md              # 架构设计文档 / Architecture document
├── API.md                       # API 接口文档 / API reference
└── results/                     # 训练结果输出 / Training output directory

配置说明 / Configuration

配置文件位于 configs/default.yaml，主要分为 4 个部分：

env（环境参数）

参数 默认值 说明
num_subcarriers 64 OFDMA 子载波数 N
bandwidth 10.0e+6 系统带宽 (Hz)
subcarrier_spacing 156250.0 子载波间隔 Δf (Hz)
max_power 1.0 最大发射功率 (W)
noise_psd -174 噪声功率谱密度 (dBm/Hz)
carrier_freq 3.5 载波频率 (GHz)
num_semantic_users 3 语义用户数 K_s
num_traditional_users 3 传统用户数 K_b
min_rate_req 5.0e+5 传统用户最低速率需求 (bps)
rho_max / rho_min 1.0 / 0.05 压缩率范围
w1 / w2 0.7 / 0.3 语义 QoE 权重

training（训练参数）

参数 默认值 说明
max_episodes 5000 最大训练轮数
max_steps 200 每轮最大步数
batch_size 256 批量大小
buffer_capacity 100000 经验回放容量
actor_lr / critic_lr 1e-4 / 3e-4 学习率
gamma 0.95 折扣因子
tau 0.01 软更新系数
beta 5.0 λ(t) sigmoid 的陡度
q_threshold 0.6 λ(t) 切换阈值 Q_th

network（网络结构）

参数 默认值 说明
actor_hidden [256, 256, 128] Actor 隐藏层
critic_hidden [512, 512, 256] Critic 隐藏层

reward（奖励权重）

参数 默认值 说明
coop_self / coop_other / coop_sys 0.5 / 0.3 / 0.2 合作奖励权重
comp_self / comp_sys 0.8 / 0.2 竞争奖励权重

关键公式 / Key Formulas

公式 表达式 论文编号
路径损耗 / Path Loss PL(d) = 36.7·log₁₀(d) + 22.7 + 26·log₁₀(fc) Eq.(5)
信道增益 / Channel Gain h_{k,n} ~ CN(0, 10^{-PL/10}) Eq.(6)
噪声功率 / Noise Power σ² = 10^{(N₀_dBm-30)/10} · Δf Eq.(7)
信噪比 / SNR γ_{k,n} = p_{k,n} · |h_{k,n}|² / σ² Eq.(8)
语义相似度 / SSim φ(γ̄,ρ) = 1 - exp(-a(ρ)·γ̄^{b(ρ)}) —
语义 QoE QoE_s = 0.7·SSim + 0.3·(1-ρ/ρ_max) —
传统 QoE QoE_b = min(R_k/R_req, 1) —
动态 λ λ(t) = sigmoid(β·(QoE_sys - Q_th)) —
混合奖励 r_i = λ·r_coop + (1-λ)·r_comp —

评估场景 / Evaluation Scenarios

evaluate.py 包含 8 个评估场景，对应论文 Section VII 的 12 张图：

# 场景 对应图表 说明
1 Convergence Fig.2 收敛曲线对比
2 QoE vs SNR Fig.3 不同 SNR 下的系统 QoE
3 Fairness vs SNR Fig.4 不同 SNR 下的 Jain 公平性
4 QoE vs Users Fig.5 用户数量扩展性
5 Rate Satisfaction vs Users Fig.6 速率满足度
6 Lambda Trajectory Fig.7-8 λ(t) 演化轨迹和散点图
7 Ablation Study Fig.10 消融实验柱状图
8 Sensitivity Fig.11-12 β 和 Q_th 敏感性分析

输出文件 / Output Files

训练和评估产生的文件保存在 results/ 目录：

results/
├── <algo_name>/
│   ├── model_s.pth              # 语义智能体模型权重
│   ├── model_b.pth              # 传统智能体模型权重
│   ├── training_log.json        # 训练指标日志
│   └── config_snapshot.yaml     # 训练时的配置快照
├── figures/
│   ├── fig02_convergence.png
│   ├── fig03_qoe_vs_snr.png
│   ├── ...
│   └── fig12_qth_sensitivity.png
└── evaluation_results.json      # 评估汇总数据

已知问题与注意事项 / Known Issues & Notes

  1. YAML 科学记数法: 使用 5.0e+5 格式（非 500.0e3），否则 yaml.safe_load() 会将其解析为字符串
  2. Smoke Test QoE 值: 2 episode 的 smoke test 中所有算法的 QoE 值相近（~0.7-0.9），这是因为网络尚未充分训练。需完整训练（5000 episodes）才能看到显著差异
  3. GPU 加速: 默认自动检测 CUDA。CPU 训练较慢但功能完整
  4. 随机种子: 默认 seed=42，可在配置中修改

论文引用 / Citation

如引用本工作，请参考论文：

Co-MADDPG: 面向语义与传统混合通信的合作竞争多智能体资源分配框架

论文文件位于 ../paper/ 目录。

License

MIT License