使用Cpp重写核心，统一实验代码风味，更新构建流

Author: Puiching-Memory

.github/workflows/pypi.yml

@@ -11,61 +11,40 @@ on:
       - published
 
 jobs:
-  build_wheels:
-    name: Build wheels on ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, windows-11-arm, macos-15-intel, macos-latest]
-        
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
 
-      - name: Build wheels
-        uses: pypa/cibuildwheel@v3.2.1
-        env:
-          CIBW_PLATFORM: ${{ matrix.platform || 'auto' }}
-        # Can also be configured directly, using `with:`
-        # with:
-        #   package-dir: .
-        #   output-dir: wheelhouse
-        #   config-file: "{package}/pyproject.toml"
-
-      - uses: actions/upload-artifact@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
-          path: ./wheelhouse/*.whl
+          python-version: "3.10"
 
-  build_sdist:
-    name: Build source distribution
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
+      - name: Install build
+        run: python -m pip install --upgrade build
 
-      - name: Build sdist
-        run: pipx run build --sdist
+      - name: Build sdist and wheel
+        run: python -m build
 
       - uses: actions/upload-artifact@v4
         with:
-          name: cibw-sdist
-          path: dist/*.tar.gz
+          name: python-package-distributions
+          path: dist/
 
   upload_pypi:
-    needs: [build_wheels, build_sdist]
+    needs: [build]
     runs-on: ubuntu-latest
     environment: pypi
     permissions:
       id-token: write
     if: github.event_name == 'release' && github.event.action == 'published'
-    # or, alternatively, upload to PyPI on every tag starting with 'v' (remove on: release above to use this)
-    # if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
     steps:
       - uses: actions/download-artifact@v4
         with:
-          # unpacks all CIBW artifacts into dist/
-          pattern: cibw-*
-          path: dist
-          merge-multiple: true
+          name: python-package-distributions
+          path: dist/
 
       - uses: pypa/gh-action-pypi-publish@release/v1
         # with:

README.md

@@ -46,15 +46,15 @@ from torch.utils.data import DataLoader
 generate_precomputed_file(
     dataset_size=10000,
     total_iterations=100000,
-    persist_path="precomputed/my_experiment.pkl",
+    persist_path="precomputed/my_experiment.safetensors",
     random_seed=0,
     replacement=True,
     maxsize=3000
 )
 
 # Step 2: Create cache decorator at runtime
 decorator = OPTCacheDecorator(
-    precomputed_path="precomputed/my_experiment.pkl",
+    precomputed_path="precomputed/my_experiment.safetensors",
     maxsize=3000, # Must be consistent with maxsize during precomputation
     total_iter=100000
 )
@@ -76,13 +76,13 @@ for batch in dataloader:
 python -m src.OPT4TorchDataSet.cli \
     --dataset-size 10000 \
     --total-iter 100000 \
-    --output precomputed/my_experiment.pkl \
+    --output precomputed/my_experiment.safetensors \
     --seed 0
 ```
 
 - `--dataset-size`: **Required**. Dataset size
 - `--total-iter`: **Required**. Total number of accesses for precomputation
-- `--output`: **Required**. File path to save precomputed results (.pkl format)
+- `--output`: **Required**. File path to save precomputed results (.safetensors format)
 - `--seed`: Random seed to ensure reproducible results (optional)
 - `--no-replacement`: Disable replacement sampling (optional)
 
@@ -96,7 +96,7 @@ If you have not installed the package but are using the source code directly, yo
 # In the project root directory
 python -m src.OPT4TorchDataSet.cli \
     --total-iter 100000 \
-    --output ./precomputed/imagenet_opt.pkl \
+    --output ./precomputed/imagenet_opt.safetensors \
     --seed 42
 ```
 
@@ -121,21 +121,14 @@ uv pip install -r requirements.txt
 uv pip install -U "triton-windows" # Optional for Windows
 ```
 
-**Login to SwanLab** (for experiment tracking)
-```bash
-swanlab login
-```
-https://docs.swanlab.cn/guide_cloud/general/quick-start.html
-
 **Select GPU Device**
 ```bash
-export CUDA_VISIBLE_DEVICES=2
+export CUDA_VISIBLE_DEVICES=0
 ```
 
 **Set Hugging Face Mirror** (improve download speed)
 ```bash
-export HF_ENDPOINT=https://hf-mirror.com
-$env:HF_ENDPOINT = "https://hf-mirror.com" # Or on Windows
+$env:HF_ENDPOINT = "https://hf-mirror.com" # on Windows
 ```
 
 ### Build Python wheel package
@@ -146,8 +139,7 @@ uv python -m build
 ```
 
 ## Experiment
-
-https://swanlab.cn/@Sail2Dream/opt4/overview
+All experiment results are saved as JSON files in the `results/` subdirectory of each experiment.
 
 | Model                        | FIFO Time(s) | LFU Time(s) | LRU Time(s) | OPT Time(s) | RR Time(s) | none Time(s) | warmUp Time(s) |
 | ---------------------------- | ------------ | ----------- | ----------- | ----------- | ---------- | ------------ | -------------- |

README_zh.md

@@ -46,15 +46,15 @@ from torch.utils.data import DataLoader
 generate_precomputed_file(
     dataset_size=10000,
     total_iterations=100000,
-    persist_path="precomputed/my_experiment.pkl",
+    persist_path="precomputed/my_experiment.safetensors",
     random_seed=0,
     replacement=True,
     maxsize=3000
 )
 
 # Step 2: 运行时创建缓存装饰器
 decorator = OPTCacheDecorator(
-    precomputed_path="precomputed/my_experiment.pkl",
+    precomputed_path="precomputed/my_experiment.safetensors",
     maxsize=3000, # 必须与预计算时的maxsize一致
     total_iter=100000
 )
@@ -76,13 +76,13 @@ for batch in dataloader:
 python -m src.OPT4TorchDataSet.cli \
     --dataset-size 10000 \
     --total-iter 100000 \
-    --output precomputed/my_experiment.pkl \
+    --output precomputed/my_experiment.safetensors \
     --seed 0
 ```
 
 - `--dataset-size`: **必需**。数据集大小
 - `--total-iter`: **必需**。预计算的总访问次数
-- `--output`: **必需**。保存预计算结果的文件路径（.pkl格式）
+- `--output`: **必需**。保存预计算结果的文件路径（.safetensors格式）
 - `--seed`: 随机种子，确保结果可重现（可选）
 - `--no-replacement`: 禁用有放回采样（可选）
 
@@ -96,7 +96,7 @@ python -m src.OPT4TorchDataSet.cli \
 # 在项目根目录下
 python -m src.OPT4TorchDataSet.cli \
     --total-iter 100000 \
-    --output ./precomputed/imagenet_opt.pkl \
+    --output ./precomputed/imagenet_opt.safetensors \
     --seed 42
 ```
 
@@ -118,24 +118,17 @@ uv venv --python 3.14
 .venv\Scripts\activate.ps1
 uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
 uv pip install -r requirements.txt
-uv pip install -U "triton-windows" # Optional for Windows
+uv pip install -U "triton-windows" # Windows 系统可选
 ```
 
-**登录 SwanLab**（用于实验追踪）
-```bash
-swanlab login
-```
-https://docs.swanlab.cn/guide_cloud/general/quick-start.html
-
 **选择 GPU 设备**
 ```bash
-export CUDA_VISIBLE_DEVICES=2
+export CUDA_VISIBLE_DEVICES=0
 ```
 
 **设置 Hugging Face 镜像**（提升下载速度）
 ```bash
-export HF_ENDPOINT=https://hf-mirror.com
-$env:HF_ENDPOINT = "https://hf-mirror.com" # 或在 Windows 上
+$env:HF_ENDPOINT = "https://hf-mirror.com" # 在 Windows 上
 ```
 
 ### 构建 Python wheel 包
@@ -145,9 +138,8 @@ uv pip install build
 uv python -m build
 ```
 
-## Experiment
-
-https://swanlab.cn/@Sail2Dream/opt4/overview
+## 实验结果
+所有实验结果均以 JSON 文件形式保存在各个实验目录下的 `results/` 子目录中。
 
 | Model                        | FIFO Time(s) | LFU Time(s) | LRU Time(s) | OPT Time(s) | RR Time(s) | none Time(s) | warmUp Time(s) |
 | ---------------------------- | ------------ | ----------- | ----------- | ----------- | ---------- | ------------ | -------------- |

lab/hit_rate/README.md

@@ -1,32 +1,36 @@
-# 缓存命中率测试
+# 缓存命中率实验 (Cache Hit Rate Experiment)
 
 ## 简介
+该实验旨在评估和比较不同缓存替换策略（LRU, LFU, FIFO, RR 和 OPT）在模拟数据集访问场景下的性能表现。通过测量各种缓存大小配置下的命中率和未命中次数，量化 OPT 算法在减少 I/O 压力方面的理论上限。
 
-该实验旨在评估和比较不同缓存替换策略在模拟数据集访问场景下的性能表现。通过测量各种缓存大小配置下的命中率和未命中次数，我们可以评估OPT（最优页面替换算法）相对于传统缓存策略（如LRU、LFU、FIFO、RR）的优势。
-
-## 结论
-OPT在所有缓存占比下都高于LRU、LFU、FIFO、RR。
-在接近100%下差距逐渐减小。
-20~30%缓存占比下OPT获得最大差距。
-
-## 数据集
-- 使用模拟数据集 HitRateDataset
-- 数据集大小: 10,000 项
-- 访问模式: 随机访问（带放回采样）
-
-## 参数配置
-- 训练轮数: 10轮
-- 批处理大小: 32
-- 缓存大小比例: 10% 到 90% (相对于数据集大小)
-- 预测窗口: 总迭代次数的20%
-
-## 运行实验
+## CLI 使用教程
+你可以通过命令行灵活配置实验参数。使用以下命令运行实验：
 
 ```bash
-cd lab/hit_rate
-python experiment.py
+python experiment.py --dataset-size 10000 --epochs 10 --batch-size 32
 ```
 
-## 输出结果
+**参数说明：**
+- `--dataset-size`: 模拟数据集的大小（默认值：`10000`）。
+- `--epochs`: 模拟训练的轮数，用于产生重复的访问序列（默认值：`10`）。
+- `--batch-size`: 数据加载的批处理大小（默认值：`32`）。
+- `--help`: 查看完整的帮助信息。
+
+## 实验结果格式
+实验结果将保存为 `results/results.json`。
+
+**JSON 结构：**
+```json
+[
+    {
+        "name": "OPT",
+        "cache_size": 1000,
+        "hit_rate": 0.45,
+        "miss_count": 5500,
+        "total_accesses": 10000
+    },
+    ...
+]
+```
 
-实验结果将保存在 `results/results.csv` 文件中
+*注：`name` 代表策略名称，`cache_size` 为实际缓存条目数，`hit_rate` 为 0-1 之间的命中率。*