# faiss-ime

**Repository Path**: eulixos/faiss-ime

## Basic Information

- **Project Name**: faiss-ime
- **Description**: No description available
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-09
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# faiss-ime：K3 A100 IME/RVV 学生论文实验仓

本仓库归档学生论文的完整实验链路：K3 A100 上 signed INT8 inner product 的 Scalar、RVV 与 IME 内核，实现正确性、强 RVV 基线、M/N/K crossover、packing/reuse、tile/tail、PMU 与输出布局归因。

## 范围边界

本仓库只负责学生论文的单 A100、kernel-local 研究，不包含：

- Faiss Flat/IVFFlat 集成；
- INT8 候选生成与 FP32 reranking；
- X100/A100 异构调度；
- Knowhere/Milvus 后端；
- 服务级延迟、在线更新与索引生命周期。

上述内容统一维护在 `sigmod-2027`（CCF A/SIGMOD Paper 1）仓库中。

## 当前结论（冻结于 2026-09-09）

第一轮正式实验、分析与写作交接已经完成：

- 318 个形状的描述性 map：20,988 条 raw、17,490 条 measured；232 个 lifecycle win、86 个 loss；中位加速比 2.383×。
- 18 个代表形状 × 5 个独立进程的 confirmation cohort：34,650 条 raw、29,700 条 measured；10 个 win、8 个 loss；中位加速比 1.042×，范围 0.421×–8.398×。
- map 与 confirmation 的 17 个重叠点中，15 个方向一致；两个翻转点均接近 1× 边界。
- 已完成六张论文图、证据台账、结果章节草稿、数据索引和补充实验清单。

注意：318-shape map 每个形状仅一个进程，因此用于描绘边界；正式统计和论文主结论以 18×5 confirmation cohort 的进程级结果为准。

## 分支与版本

| 分支 | 用途 | 状态/锚点 |
|---|---|---|
| `master` | 当前可读归档：源码、协议、分析结果、论文图和交接材料 | 权威入口 |
| `experiments/formal-matrix-20260909` | 冻结的正式实验源码历史 | commit `7a08593bf3c4924b62ea3a7c2aeab31c97397332` |

`archive/student-formal-matrix-20260909.bundle` 保存上述正式源码分支的完整 Git 历史，便于脱离远端恢复和审计。

## 仓库结构

```text
bench/                 基准程序与环境/PMU守卫
include/vector_ime/    内核 API、packing、prepared/workspace 契约
src/                   Scalar、RVV、IME 与布局实现
scripts/               收集、校验、分析和绘图脚本
tests/                 C++/Python 正确性与数据契约测试
paper/                 证据台账、结果草稿、数据索引、补实验清单
results/analysis/      可提交的小型 CSV/JSON 汇总表
results/figures/       六张论文图（PNG/PDF）
archive/               冻结 Git bundle 与交接 manifest
manifests/             历史实验 checkpoint
```

## 强 RVV 公平基线

每个进程、每个形状取以下实现中的最快值作为 headline RVV 基线：

- `rvv-ref`
- `rvv-accum`
- `rvv-auto`
- `rvv-stock`
- `rvv-batch4`

packed-layout RVV 只用于布局归因，不作为 headline 公平基线。

## 构建与验证

在 K3 A100 环境中使用 CMake 构建。建议始终从干净构建目录开始：

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build --output-on-failure
```

正式实验收集器：

```bash
python3 scripts/collect_formal_matrix.py --help
```

历史 checkpoint 的精确复现入口见：

- `EXPERIMENT_INDEX.md`
- `STRONG_RVV_PROTOCOL.md`
- `M1M4_PROTOCOL.md`
- `paper/DATA_INDEX.md`
- `paper/EVIDENCE_LEDGER.md`

所有正式运行必须使用新输出目录，并保留 CPU affinity、频率、温度、源代码 hash、二进制 hash 和进程级原始记录。

## 数据策略

Git 中提交：

- 源码、协议、测试和分析脚本；
- 汇总 CSV/JSON；
- 六张论文图；
- manifest、证据台账和写作草稿；
- 冻结 Git bundle。

较大的原始 cohort 不在 Git 中重复提交。权威路径、规模、hash 和生成关系记录在 `paper/DATA_INDEX.md` 与 `archive/MANIFEST.json`。本地权威数据根目录为：

```text
E:\学术论文\k3-results\phase31
```

主要原始 cohort：

- `strong-rvv-formal-map-20260909-r1`
- `strong-rvv-formal-confirm-20260909-r1`
- `layout-20260909-r1`
- `strong-rvv-k3-20260909-r1`

## 写作与补实验规则

当前默认进入论文撰写阶段，不再扩张实验矩阵。只有在审稿式检查发现主张缺证据时，才从 `paper/SUPPLEMENT_CHECKLIST.md` 中批准窄范围补实验。任何涉及 Faiss、候选 Recall、FP32 reranking 或异构执行的问题都应转入 `sigmod-2027`，不得写入本学生论文的贡献范围。