模型简介
模型特点
模型能力
使用案例
🚀 📡 大型无线模型(LWM)
LWM 是一款强大的预训练模型,作为无线信道的通用特征提取器而开发。作为该领域全球首个基础模型,LWM 利用Transformer架构从模拟数据集(如 DeepMIMO 和 Sionna)以及现实世界的无线数据中提取精细的表示。
✨ 主要特性
LWM 的构建方式
LWM 模型的结构基于 Transformer,使其能够捕捉信道数据中的细粒度和全局依赖关系。与局限于特定任务的传统模型不同,LWM 通过我们提出的掩码信道建模(Masked Channel Modeling,MCM)技术采用自监督方法。该方法通过预测掩码信道段对未标记数据上的模型进行训练,使模型能够学习天线和子载波之间的复杂关系。利用双向注意力机制,LWM 通过关注前后信道段来解释完整上下文,从而得到能够编码全面空间信息的嵌入,适用于各种场景。
LWM 提供了什么
LWM 提供了一个通用的特征提取框架,可应用于各种无线通信和传感任务。它旨在处理复杂的无线环境,以一种有助于在不同场景和条件下实现稳健性能的方式捕捉信道特征。
LWM 在数十万个无线信道样本上进行训练,旨在能够在各种环境(从密集城市区域到合成设置)中实现泛化,确保其在广泛的无线任务中的适应性和一致性。
LWM 的使用方式
LWM 旨在作为高质量嵌入的来源,轻松集成到下游应用中,这些嵌入封装了复杂的信道特征。通过将原始无线信道数据输入到预训练模型中,用户可以获得捕捉信道环境中基本空间关系和交互的嵌入。
这些嵌入提供了无线数据的通用和上下文表示,可在不同应用中加以利用。通过这种方式使用预训练模型,用户可以减少对大量标记数据的需求,同时受益于保留原始信道关键属性的嵌入。
使用 LWM 的优势
- 多任务适用性:LWM 采用自监督和无标签预训练,在广泛的无线任务中表现出色,提供了灵活性和高性能。
- 小数据高效性:使用 LWM 嵌入,下游任务可以用更少的数据实现高精度,减少对大型数据集的依赖。
- 多环境适应性:在多样化数据上进行预训练,LWM 在从城市到农村的各种环境中都表现出色,确保可靠的性能。
加入越来越多使用 LWM 进行无线通信和传感研究的研究人员社区,为你的模型解锁新的性能和洞察力水平!
📦 安装指南
1. 安装 Conda
首先,确保你安装了像 Conda 这样的包管理器,以管理你的 Python 环境和包。你可以通过 Anaconda 或 Miniconda 安装 Conda。
安装完成后,你可以使用 Conda 管理环境。
2. 创建新环境
安装 Conda 后,按照以下步骤创建新环境并安装所需的包。
步骤 1:创建新环境
打开 Anaconda PowerShell Prompt,创建一个名为 lwm_env
的新 Conda 环境:
conda create -n lwm_env
步骤 2:激活环境
激活环境:
conda activate lwm_env
3. 安装所需的包
环境激活后,安装必要的包。
安装支持 CUDA 的 PyTorch
虽然推理可以在 CPU 上高效运行,但训练资源密集型的下游任务可能需要 GPU。访问 此页面,根据你的系统规格选择适当的选项。该网站将生成定制的安装命令。
例如,在 NVIDIA 系统上,你可以使用以下命令,并根据你的系统选择适当的 CUDA 版本:
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia
此命令安装支持 CUDA 的 PyTorch,用于 GPU 加速训练。确保指定的 CUDA 版本与你的系统兼容,必要时进行调整。
⚠️ 重要提示
如果在安装支持 CUDA 的 PyTorch 时遇到问题,请验证你的 CUDA 版本兼容性。这也可能是由于冲突的安装尝试导致的,尝试使用新环境。
通过 Conda Forge 安装其他所需的包
conda install python numpy pandas matplotlib tqdm -c conda-forge
使用 pip 安装 DeepMIMOv3
pip install DeepMIMOv3
4. 克隆数据集场景
以下函数将帮助你从存储库中克隆特定的数据集场景:
import subprocess
import os
import shutil
def clone_dataset_scenario(repo_url, model_repo_dir="./LWM", scenarios_dir="scenarios"):
"""
Clones all scenarios from a repository, ensuring all files (small and large) are downloaded.
Args:
repo_url (str): URL of the Git repository
model_repo_dir (str): Path to the model repository
scenarios_dir (str): Directory name for storing scenarios
"""
# Ensure we're in the correct directory structure
current_dir = os.path.basename(os.getcwd())
if current_dir == "LWM":
model_repo_dir = "."
# Create the scenarios directory if it doesn't exist
scenarios_path = os.path.join(model_repo_dir, scenarios_dir)
os.makedirs(scenarios_path, exist_ok=True)
# Store the original working directory
original_dir = os.getcwd()
try:
# Clean up any existing temp directory
if os.path.exists(scenarios_path):
shutil.rmtree(scenarios_path)
# Clone the entire repository (including all files)
print(f"Cloning entire repository into temporary directory...")
subprocess.run([
"git", "clone",
repo_url,
scenarios_path
], check=True)
# Navigate to the temporary clone directory
os.chdir(scenarios_path)
# Pull all files using Git LFS
print(f"Pulling all files using Git LFS...")
subprocess.run(["git", "lfs", "install"], check=True) # Ensure LFS is installed
subprocess.run(["git", "lfs", "pull"], check=True) # Pull all LFS files
print(f"Successfully cloned all scenarios into {scenarios_path}")
except subprocess.CalledProcessError as e:
print(f"Error cloning scenarios: {str(e)}")
finally:
# Clean up temporary directory
if os.path.exists(scenarios_path):
shutil.rmtree(scenarios_path)
# Return to original directory
os.chdir(original_dir)
5. 克隆模型存储库
现在,将 LWM 模型存储库克隆到你的本地系统。
# Step 1: Clone the model repository (if not already cloned)
model_repo_url = "https://huggingface.co/wi-lab/lwm"
model_repo_dir = "./LWM"
if not os.path.exists(model_repo_dir):
print(f"Cloning model repository from {model_repo_url}...")
subprocess.run(["git", "clone", model_repo_url, model_repo_dir], check=True)
6. 克隆所需的数据集场景
你现在可以从 DeepMIMO 数据集中克隆特定场景,如下表所示:
📊 数据集概述
属性 | 详情 |
---|---|
数据集 0 | 城市:丹佛;用户数量:1354;DeepMIMO 城市场景 18 |
数据集 1 | 城市:印第安纳波利斯;用户数量:3248;DeepMIMO 城市场景 15 |
数据集 2 | 城市:俄克拉荷马;用户数量:3455;DeepMIMO 城市场景 19 |
数据集 3 | 城市:沃思堡;用户数量:1902;DeepMIMO 城市场景 12 |
数据集 4 | 城市:圣克拉拉;用户数量:2689;DeepMIMO 城市场景 11 |
数据集 5 | 城市:圣地亚哥;用户数量:2192;DeepMIMO 城市场景 7 |
需要注意的是,这六个数据集在 LWM 模型的预训练过程中并未使用,所产生的高质量嵌入证明了 LWM 的强大泛化能力,而非过拟合。
以下操作设置用于生成 LWM 预训练和下游任务的数据集。如果你打算使用自定义数据集,请确保它们符合这些配置:
操作设置:
- 基站天线数:32
- 用户设备天线数:1
- 子载波数:32
- 路径数:20
- 频率:3.5GHz(顺便说一下,我们的结果在不同频率范围内是一致的)
克隆场景:
import numpy as np
dataset_repo_url = "https://huggingface.co/datasets/wi-lab/lwm" # Base URL for dataset repo
# Clone the requested scenarios
clone_dataset_scenario(dataset_repo_url, model_repo_dir)
7. 将工作目录更改为 LWM
if os.path.exists(model_repo_dir):
os.chdir(model_repo_dir)
print(f"Changed working directory to {os.getcwd()}")
else:
print(f"Directory {model_repo_dir} does not exist. Please check if the repository is cloned properly.")
💻 使用示例
基础用法
# 以下代码展示了如何克隆数据集场景
import subprocess
import os
import shutil
def clone_dataset_scenario(repo_url, model_repo_dir="./LWM", scenarios_dir="scenarios"):
"""
Clones all scenarios from a repository, ensuring all files (small and large) are downloaded.
Args:
repo_url (str): URL of the Git repository
model_repo_dir (str): Path to the model repository
scenarios_dir (str): Directory name for storing scenarios
"""
# Ensure we're in the correct directory structure
current_dir = os.path.basename(os.getcwd())
if current_dir == "LWM":
model_repo_dir = "."
# Create the scenarios directory if it doesn't exist
scenarios_path = os.path.join(model_repo_dir, scenarios_dir)
os.makedirs(scenarios_path, exist_ok=True)
# Store the original working directory
original_dir = os.getcwd()
try:
# Clean up any existing temp directory
if os.path.exists(scenarios_path):
shutil.rmtree(scenarios_path)
# Clone the entire repository (including all files)
print(f"Cloning entire repository into temporary directory...")
subprocess.run([
"git", "clone",
repo_url,
scenarios_path
], check=True)
# Navigate to the temporary clone directory
os.chdir(scenarios_path)
# Pull all files using Git LFS
print(f"Pulling all files using Git LFS...")
subprocess.run(["git", "lfs", "install"], check=True) # Ensure LFS is installed
subprocess.run(["git", "lfs", "pull"], check=True) # Pull all LFS files
print(f"Successfully cloned all scenarios into {scenarios_path}")
except subprocess.CalledProcessError as e:
print(f"Error cloning scenarios: {str(e)}")
finally:
# Clean up temporary directory
if os.path.exists(scenarios_path):
shutil.rmtree(scenarios_path)
# Return to original directory
os.chdir(original_dir)
高级用法
# 以下代码展示了如何进行推理并生成标签
from input_preprocess import tokenizer, create_labels
from lwm_model import lwm
import torch
import numpy as np
scenario_names = np.array([
"city_18_denver", "city_15_indianapolis", "city_19_oklahoma",
"city_12_fortworth", "city_11_santaclara", "city_7_sandiego"
])
scenario_idxs = np.array([0, 1, 2, 3, 4, 5]) # Select the scenario indexes
selected_scenario_names = scenario_names[scenario_idxs]
preprocessed_chs = tokenizer(
selected_scenario_names=selected_scenario_names, # Selects predefined DeepMIMOv3 scenarios. Set to None to load your own dataset.
manual_data=None, # If using a custom dataset, ensure it is a wireless channel dataset of size (N,32,32) based on the settings provided above.
gen_raw=True # Set gen_raw=False to apply masked channel modeling (MCM), as used in LWM pre-training. For inference, masking isn't necessary unless you want to test LWM's robustness to noisy inputs.
)
device = 'cuda' if torch.cuda.is_available() else 'cpu'
print(f"Loading the LWM model on {device}...")
model = lwm.from_pretrained(device=device)
from inference import lwm_inference, create_raw_dataset
input_types = ['cls_emb', 'channel_emb', 'raw']
selected_input_type = input_types[1] # Change the index to select LWM CLS embeddings, LWM channel embeddings, or the original input channels.
if selected_input_type in ['cls_emb', 'channel_emb']:
dataset = lwm_inference(preprocessed_chs, selected_input_type, model, device)
else:
dataset = create_raw_dataset(preprocessed_chs, device)
tasks = ['LoS/NLoS Classification', 'Beam Prediction']
task = tasks[1] # Choose 0 for LoS/NLoS labels or 1 for beam prediction labels.
labels = create_labels(task, selected_scenario_names, n_beams=64) # For beam prediction, n_beams specifies the number of beams in the codebook. If you're generating labels for LoS/NLoS classification, you can leave this value unchanged as it doesn't impact the label generation.
8. 对数据集进行分词并加载模型
在深入研究数据集分词和加载模型之前,让我们了解一下分词过程如何适应无线通信环境。在这种情况下,分词是指将每个无线信道分割成块,类似于视觉Transformer(ViTs)处理图像的方式。每个无线信道被构造为一个 32x32 的矩阵,其中行代表天线,列代表子载波。
分词过程包括将信道矩阵划分为块,每个块包含 16 个连续子载波的信息。然后将这些块嵌入到 64 维空间中,为 Transformer 提供每个块更丰富的上下文。在这个过程中,添加位置编码以保留信道内的结构关系,确保 Transformer 能够捕捉空间和频率依赖关系。
如果你选择在推理期间应用掩码信道建模(MCM)(通过设置 gen_raw=False
),LWM 将像在预训练期间一样掩码某些块。然而,对于标准推理,除非你想测试 LWM 对噪声输入的鲁棒性,否则不需要进行掩码!推理后打印的 LWM 损失可以显示它对掩码块的预测效果。
现在,让我们对数据集进行分词并加载预训练的 LWM 模型。
from input_preprocess import tokenizer
from lwm_model import lwm
import torch
scenario_names = np.array([
"city_18_denver", "city_15_indianapolis", "city_19_oklahoma",
"city_12_fortworth", "city_11_santaclara", "city_7_sandiego"
])
scenario_idxs = np.array([0, 1, 2, 3, 4, 5]) # Select the scenario indexes
selected_scenario_names = scenario_names[scenario_idxs]
preprocessed_chs = tokenizer(
selected_scenario_names=selected_scenario_names, # Selects predefined DeepMIMOv3 scenarios. Set to None to load your own dataset.
manual_data=None, # If using a custom dataset, ensure it is a wireless channel dataset of size (N,32,32) based on the settings provided above.
gen_raw=True # Set gen_raw=False to apply masked channel modeling (MCM), as used in LWM pre-training. For inference, masking isn't necessary unless you want to test LWM's robustness to noisy inputs!
)
device = 'cuda' if torch.cuda.is_available() else 'cpu'
print(f"Loading the LWM model on {device}...")
model = lwm.from_pretrained(device=device)
9. 进行推理
在运行推理之前,了解不同嵌入类型的好处很重要。CLS 嵌入(cls_emb) 提供了整个无线信道的高度压缩、整体视图,使其非常适合需要一般理解的任务,如分类或高级决策。另一方面,信道嵌入(channel_emb) 捕捉无线信道的详细空间和频率信息,更适合复杂任务,如波束成形或信道预测。
你现在可以使用 LWM 模型对预处理数据进行推理。
from inference import lwm_inference, create_raw_dataset
input_types = ['cls_emb', 'channel_emb', 'raw']
selected_input_type = input_types[1] # Change the index to select LWM CLS embeddings, LWM channel embeddings, or the original input channels.
if selected_input_type in ['cls_emb', 'channel_emb']:
dataset = lwm_inference(preprocessed_chs, selected_input_type, model, device)
else:
dataset = create_raw_dataset(preprocessed_chs, device)
通过选择 cls_emb
或 channel_emb
,你可以利用预训练模型丰富的特征提取能力,将原始信道转换为高度信息丰富的嵌入。如果你更喜欢使用原始数据,可以选择 raw
输入类型。
10. 必要时生成标签
如果你的数据集需要标签,你可以使用 DeepMIMO 数据轻松生成它们。以下是一个根据所选场景为视距(LoS)/非视距(NLoS)分类或波束预测创建标签的示例:
from input_preprocess import create_labels
tasks = ['LoS/NLoS Classification', 'Beam Prediction']
task = tasks[1] # Choose 0 for LoS/NLoS labels or 1 for beam prediction labels.
labels = create_labels(task, selected_scenario_names, n_beams=64) # For beam prediction, n_beams specifies the number of beams in the codebook. If you're generating labels for LoS/NLoS classification, you can leave this value unchanged as it doesn't impact the label generation.
11. 利用数据集进行下游任务
LWM 使用自监督学习在庞大且多样化的数据集上进行预训练,不依赖于标记数据。在推理过程中,它实时将原始信道转换为丰富的嵌入,捕捉无线信道中的一般和复杂模式。这些嵌入可以直接应用于各种下游任务,提供了比使用原始信道数据更强大的替代方案。
12. 探索交互式演示
要交互式体验 LWM,请访问我们托管在 Hugging Face Spaces 上的演示:
现在你已经准备好探索 LWM 在无线通信中的强大功能!开始处理数据集并生成高质量的嵌入,以推进你的研究或应用。
如果你有问题或需要帮助,请随时:
- 访问 Hugging Face 讨论区 获取社区支持。
- 查看 LWM 网站常见问题解答。
- 通过电子邮件 lwmwireless@gmail.com 直接联系我们。
请在使用 LWM 模型或其任何修改部分时引用以下论文:
@misc{alikhani2024largewirelessmodellwm,
title={Large Wireless Model (LWM): A Foundation Model for Wireless Channels},
author={Sadjad Alikhani and Gouranga Charan and Ahmed Alkhateeb},
year={2024},
eprint={2411.08872},
archivePrefix={arXiv},
primaryClass={cs.IT},
url={https://arxiv.org/abs/2411.08872},
}
📄 许可证
本项目采用 MIT 许可证。






