Lwm

🚀 📡 大型無線模型（LWM）

LWM 是一款強大的預訓練模型，作為無線信道的通用特徵提取器而開發。作為該領域全球首個基礎模型，LWM 利用Transformer架構從模擬數據集（如 DeepMIMO 和 Sionna）以及現實世界的無線數據中提取精細的表示。

🚀 點擊此處嘗試交互式演示！

🚀 點擊此處嘗試 Colab 筆記本！

✨ 主要特性

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。

• Anaconda：包含全面的科學包套件。點擊此處下載。
• Miniconda：是一個輕量級版本，僅包含 Conda 和 Python。點擊此處下載。

安裝完成後，你可以使用 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 許可證。