Metadata-Version: 2.4
Name: srn
Version: 0.1.0
Summary: SRN —— 自研量化·优化·压缩算法集（RL 量化 + Su 优化 + K 优化 + INI 压缩）
Author: REU4-S Project
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/reu4s/srn
Keywords: quantization,llm,compression,inference,rl-quant,srn
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# SRN

**SRN** —— 自研量化 · 优化 · 压缩算法集。

四大算法族，一套零第三方依赖的纯 Python 参考实现：

| 族 | 全称 | 职责 | 模块 |
|---|---|---|---|
| **RL** | Reu4s Level | **有损量化**：把浮点权重压成码字 | `srn.rl` |
| **Su** | — | **推理优化**：显存常驻与流式调度 | `srn.su` |
| **K**  | — | **质量抓手**：尺度 / 码本 / 离群列 | `srn.k`  |
| **INI** | In-place Number Interning | **无损压缩**：位打包 / 行程 / Rice | `srn.ini` |

外加 `srn.core` 提供容器格式与引擎规格（全链路唯一真相源）。

---

## 设计原则

### 1. 零第三方依赖

**核心运行时只用标准库。** 不 import numpy、不 import torch、
不 import 任何推理/量化框架。

理由是实测的，不是洁癖：在目标硬件上（6GB 显存跑 32B 模型），
主流框架**跑不了** —— 它们假设权重能装进显存。

> 本项目对本机（15.4GB RAM + RTX 2060 6GB）实测：
> 裸 fp32 的公式在这里全部不成立，因为它们没有把量化资产算进去。

### 2. 错格式要在加载期炸

量化布局错了**不会抛异常**，只会静默输出乱码（或者在 C 内核里越界）。
所以每个装/卸点都有硬校验：

- `core.spec.check_ioff_bit_offsets` —— 位偏移表校验
- `su.Su1Shape` / `su.Su2Entry.validate` —— 布局自洽
- `core.ContainerReader.validate` —— 全容器校验
- `rl.SpWeights._check` —— 稀疏索引流校验

### 3. 物理账写死在代码里

每个性能数字都带实测出处，且可离线复算：

```python
from srn import su
print(su.Su2Scheduler.predict_sec_per_token(entries, "disk"))  # 6.79 s/token
```

不是「跑跑看」，而是「先算清楚能不能跑」。

---

## 四大算法族

### RL —— 量化

```python
from srn import rl

# 一、块尺度（L1 中心 + Weiszfeld 迭代，抗离群）
scale = rl.rl_scale([0.1, 0.2, 20.0, 0.15])
# → 0.175（均值是 5.11 —— 单个离群值就能毁掉 max/mean 类估计）

# 二、数据驱动码本（生长式 + 热启动 Lloyd-Max）
cb = rl.rl_codebook(samples, bits=4)     # → 16 个升序码值

# 三、整张量量化
q = rl.quantize_tensor(W, bits=4)
W2 = rl.dequantize_tensor(q)             # 往返重建
print(q["sqnr_db"])                      # 本张量实测 SQNR

# 四、稀疏路径（元素级剪枝 + Rice 索引，无 LUT）
ent = rl.sp_quantize(W, keep_p=0.5, bits=4)
w = rl.SpWeights(ent)                    # 推理端只读视图（自带偏移自校验）
```

实测 SQNR（归一化域一维 Lloyd，逼近 Lloyd-Max 理论）：

| bits | SQNR | 体积比（vs fp16） |
|---|---|---|
| 2 | 9.29 dB | 8× |
| 3 | 14.56 dB | 5.3× |
| 4 | 20.11 dB | 4× |
| 6 | 31.88 dB | 2.67× |

### Su —— 优化

```python
from srn import su

# Su1：全模型能不能常驻显存？（离线算账，不需要 GPU）
plan = su.Su1Plan(total_vram_mb=6144, reserve_mb=512)
shapes = plan.shapes_from_meta(metas)
ok, mb = plan.can_resident_all(shapes)   # → (False, 16599)

# Su2：装不下 → 分层调度（显存 / RAM / mmap 流式）
sch = su.Su2Scheduler(vram_budget_mb=4200, ram_budget_mb=0)
p = sch.plan(entries)                    # → 常驻 79 张 / 流式 371 张
print(su.Su2Scheduler.predict_sec_per_token(entries, "disk"))  # 6.79 s/token
```

实测对齐（Qwen2.5-32B + RL3K3 容器）：

| 指标 | SRN 预测 | 引擎实测 |
|---|---|---|
| codes 载荷 | 11.442 GB | 11.96 GB |
| 常驻张量 | 79 张 | 79 张 |
| 每 token 流式 | 7.341 GB | 7.34 GB |
| 走盘 s/token | 6.79 s | ≈8 s |

### K —— 质量

```python
from srn import k

k.k1_group_absmax(x, group=64)           # 组 absmax 尺度
k.k3_codebook(samples, bits=4)           # 数据驱动码本
k.k4_split_outliers(col_absmax)          # 列级离群分离（混合精度）
```

K3 的三根支柱同时命中量化误差的三个主要来源：
① absmax 组尺度限制离群影响范围、② 列尺度解决列间动态范围差异、
③ 数据驱动 Lloyd 码本逼近最优。

### INI —— 无损压缩

```python
from srn import ini

ini.pack_bits(codes, nbits=4)            # 位打包（MSB-first）
ini.encode_runs(zeros)                   # 零游程
d = ini.dq_scales(scales, g2=64)         # 尺度双重量化（int8 + fp16 meta）
ini.rice_encode_sizes(counts, deltas, k=4)   # Rice 增量索引
```

实测（2026-09-21，10 张代表张量）：

- **INI-1 已到熵下限**：打包字节熵 7.838 ~ 7.865（满分 8.0），潜力仅 ~1.02×
  → **不要把 INI 系当主压缩手段**
- **INI-3 有效**：尺度从 4 字节降到 ~1.06 字节（~4×）
- **INI-4 是稀疏路径的命门**：Rice-4 得 5.679 bit/非零（下界 log2K = 12.3），已压 2.2×

---

## ⚠️ 两个必须知道的坑

这两个是实测踩出来的，写在这里是为了让后来人不要重踩。

### 坑一：`ioff` / `voff` 是**位**偏移，不是字节偏移

稀疏索引流的偏移表与 C 内核（`SpBitsR.bitpos = ioff[n]`）严格一致，
单位是 bit。**分块编码时，每块的位偏移必须累加「该块之前已写字节数 × 8」**：

```python
ioff_chunk = local_ioff + bytes_written_before * 8
末尾值     = 整条流的总位数          # 不是字节数
```

漏掉累加 → 第二块起偏移全错 → 内核越界读 → Windows 上直接
`OSError: access violation`。

整张量一次编完**不会**暴露这个问题，只有分块（大张量必须分块）才触发。
用 `core.spec.check_ioff_bit_offsets` 做校验。

### 坑二：`.npy` 载荷长度不能用 `zipfile` 的 `file_size`

`ZipInfo.file_size` 含 `.npy` 头的对齐填充（实测差 128 字节 = 1024 位），
会让位偏移校验**误报**。必须解析头：

```python
_, _, payload = core.decode_npy(blob)
n = len(payload)          # 正确
```

---

## 安装

```bash
pip install srn
```

Python >= 3.9，无任何依赖。

## 自检

```bash
python tests/selftest.py
```

覆盖四大族共 60 项断言，包含与 REU4-S 引擎实测数据的对拍。

## 许可

专有软件。详见 `LICENSE`。
