内容
# RAI
[](https://github.com/Classevelabs/rai/releases/latest) [](LICENSE)
**纯Rust实现的仅限CPU的LLM推理引擎。** RAI运行4位量化的语言模型，配备手写的AVX2内核——无需GPU，无需Python运行时，无需PyTorch，无需GGML，无需BLAS。加载一个`.raimodel`文件，在任何现代x86-64笔记本电脑上生成文本。
由 [ClassEve](https://classeve.com) 构建。遵循Apache-2.0许可。
> **官方仓库。** 这是RAI的唯一官方仓库。
> ClassEve的官方账户完整列表请参见 [classeve.com/official](https://classeve.com/official)。
> GitHub账户 `github.com/ClassEve` 是无关的第三方，不隶属于ClassEve。
## 为什么
大多数LLM推理栈假设存在GPU、CUDA工具链或重量级ML框架。RAI采取相反的策略：一个小型、可审计的Rust工作空间，其中每个矩阵乘法都是手写的SIMD内核，整个运行时依赖树都包含在 `Cargo.lock` 中。
- **仅限CPU设计。** AVX2 + FMA + F16C — 自~2013年以来已在每款主流x86 CPU中发货。
- **4位权重，在寄存器中反量化。** 权重在内存中保持打包；解包在GEMM内循环中实时进行。内存中从未存在FP32权重副本。
- **一个扁平的模型文件。** `.raimodel` 格式是一个具有64字节头的单个二进制blob — 可 trivially 解析，零拷贝加载。
- **推测解码。** 草稿模型和自我推测（前N层）模式，具有针对目标模型的数学精确验证。
- **本地服务。** 带有内置Web UI的HTTP聊天服务器，以及REST + MCP服务器，以便代理工具（例如Claude Desktop，Claude Code）可以将RAI用作工具后端。
## 工作空间布局
| Crate | 目的 |
| --- | --- |
| `rai-infer` | 推理引擎：`.raimodel` 加载器，AVX2 W4A8/W4A32 GEMM内核，转换器层（RMSNorm，RoPE，GQA，SwiGLU），KV缓存，采样，推测解码，CLI + HTTP聊天二进制文件 |
| `rai-compress` | 权重量化和压缩：GPTQ，具有Hessian引导的误差补偿，自适应位分配，位打包 |
| `rai-server` | REST + MCP服务器，暴露RAI内存/推理层，供HTTP客户端和MCP客户端使用 |
| `rai-core` | `rai-server`使用的内存，嵌入和推理原语 |
| `rem-nra` | `rai-core`使用的谐振内存后端 |
## 文档
- [安装](./docs/INSTALL.md)
- [架构](./docs/ARCHITECTURE.md)
- [基准测试](./BENCHMARKS.md)
- [发布流程](./docs/RELEASE.md)
- [安全策略](./SECURITY.md)
## 要求
| 要求 | 详情 |
| --- | --- |
| Rust | 稳定工具链，2021版 |
| CPU | x86-64，支持AVX2，FMA和F16C（Intel Haswell 2013+，AMD Zen 2019+） |
| 操作系统 | Linux，Windows或macOS |
| 运行时GPU | **不需要** |
| Python | 仅限可选的模型导出脚本（一次性转换） |
> `.cargo/config.toml` 使用 `target-cpu=native` 进行构建，以便内核使用您的CPU提供的所有功能。如果需要可移植的二进制文件，请删除此标志。
## 构建
```bash
cargo build --workspace --release
```
## 安装
直接从GitHub安装终端用户推理二进制文件（`rai-generate`，`rai-chat`，`profile-fwd`，`gemm-bench`和`bw-bench`）：
```bash
cargo install --git https://github.com/Classevelabs/rai \
--package classeve-rai-infer \
--locked
```
安装本地REST/MCP服务器：
```bash
cargo install --git https://github.com/Classevelabs/rai \
--package classeve-rai-server \
--locked
```
从checkout进行本地开发：
```bash
cargo install --path rai-infer --locked
cargo install --path rai-server --locked
```
开发检查：
```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
```
## 获取模型
RAI在其自己的`.raimodel`格式中运行模型。`rai-infer/scripts/`下的导出脚本转换任何LLaMA/Mistral-family HuggingFace模型（SmolLM，Mistral-7B-Instruct，LLaMA-2/3，...）。它们需要Python，`torch`，`transformers`，`datasets`和`numpy`；CUDA GPU可以加速校准，但不是必需的。
```bash
# GPTQ 4-bit导出（校准，最高质量）
python3 rai-infer/scripts/export_raimodel.py \
--model HuggingFaceTB/SmolLM-135M \
--output smollm-135m-q4.raimodel
# Round-to-nearest导出（无校准，最快，质量略低）
python3 rai-infer/scripts/export_rtn.py \
--model mistralai/Mistral-7B-Instruct-v0.3
```
两者都写入模型文件和`tokenizer.json`。
## 快速入门
### 生成文本
```bash
./target/release/rai-generate \
--model smollm-135m-q4.raimodel \
--tokenizer tokenizer.json \
--prompt "The future of computing is" \
--max-tokens 64 \
--temperature 0.7
```
采样控制： `--temperature`， `--top-k`， `--top-p`， `--repetition-penalty`， `--seed`。测试时计算（“思考”）策略： `--ponder-strategy cfg|ensemble|cfg-ensemble|adaptive`，具有 `--guidance-scale`， `--ensemble-n`， `--noise-sigma`， `--entropy-threshold`。
### 推测解码
```bash
# 草稿模型推测：小型模型提出，大模型验证
./target/release/rai-generate \
--model mistral-7b-q4.raimodel \
--tokenizer tokenizer.json \
--draft mistral-draft-100m-q4.raimodel \
--draft-k 6 \
--prompt "Explain speculative decoding in one paragraph."
# 自我推测：模型自身的首N层作为草稿
./target/release/rai-generate \
--model mistral-7b-q4.raimodel \
--tokenizer tokenizer.json \
--self-spec-layers 8 --self-spec-k 8 \
--prompt "Hello"
```
草稿和目标必须共享一个分词器。验证是精确的：输出质量与标准解码相同，仅更快。
`rai-infer/scripts/train_draft.py` 从任何教师中蒸馏出一个~100M参数的草稿模型。
### 通过HTTP聊天
```bash
./target/release/rai-chat \
--model smollm-135m-q4.raimodel \
--tokenizer tokenizer.json \
--port 8090
```
打开 `http://localhost:8090` 以获取内置的Web UI，或POST到 `/api/chat` （JSON）以获取编程访问。 `--chat-template auto|mistral|llama3|few-shot` 选择提示格式化。
### REST + MCP服务器
`rai-server` 暴露RAI内存/推理层：
```bash
# REST模式（默认端口3000；使用RAI_HOST / RAI_PORT配置）
./target/release/rai-server
# MCP模式在stdio上 — 用于MCP客户端，如Claude Desktop或Claude Code
./target/release/rai-server mcp
```
REST端点： `POST /v1/store`， `/v1/recall`， `/v1/intersect`， `/v1/contradict`， `/v1/surprise`， `/v1/confidence`， `/v1/train`， `/v1/snapshot`，以及 `GET /v1/health`。
在MCP模式下，相同的操作作为工具公开（`rai_store`， `rai_recall`， `rai_intersect`， `rai_contradict`， `rai_surprise`， `rai_explain_confidence`， `rai_memory_health`）。MCP客户端配置示例：
```json
{
"mcpServers": {
"rai": {
"command": "/path/to/rai-server",
"args": ["mcp"]
}
}
}
```
嵌入默认使用内置的模拟提供程序；设置 `RAI_EMBEDDING_PROVIDER=openai` 和 `OPENAI_API_KEY` 以使用兼容OpenAI的嵌入API。
## `.raimodel` 格式
一个单独的扁平、小端二进制文件：
```text
┌─────────────────────────────────────────────┐
│ 头部（64字节） │ 魔法 "RAIM"，版本，
│ │ 架构超参数，
│ │ 量化配置
├─────────────────────────────────────────────┤
│ 节点索引表（每个节点16字节） │ 每个节点的偏移量 + 大小
├─────────────────────────────────────────────┤
│ 节点0：嵌入表（8位） │
│ 节点1..N：转换器层（4位） │ 每个线性：维度，f16
│ 节点N+1：最终RMSNorm（f32） │ 每个组的缩放/零参数，
└─────────────────────────────────────────────┘ 半字节打包代码
```
线性权重被量化为4位代码，具有每组（128列）的f16缩放/零参数，按AVX2内核消耗的确切布局打包成两个代码字节。嵌入表被量化为8位。缩放/零参数在导出时通过f16循环，以便Rust反量化与Python导出器精确匹配。
加载器读取整个文件到堆内存（在操作系统支持的情况下，请求透明大页），并提供零拷贝切片 — 对于带宽受限的解码，测量速度比 `mmap` 快。
## 性能
在4核/8线程笔记本类x86-64 CPU上，SmolLM-135M（83 MB，4位）以 **~195 tokens/s** 解码。量化内核解码受内存带宽限制，内核可维持大量实际DRAM带宽。
参见 [BENCHMARKS.md](./BENCHMARKS.md) 获取方法论、完整数字和压缩质量测量。
## 项目状态
RAI是ClassEve的积极初始公开版本。Rust工作空间、CPU推理路径、量化工具包、REST/MCP服务器、测试、基准测试和CI门控都是公开的，并得到维护。当前的生产准备边界：
- 小型模型（135M级别）经过端到端测试；Mistral-7B系列导出和推理路径可用，并继续得到强化。
- 量化质量通过Hessian加权输出误差针对FP16参考进行测量（参见BENCHMARKS.md）。端到端困惑度扫描仍是计划中的基准测试，而不是声称的结果。
- 优化推理针对具有AVX2、FMA和F16C的x86-64 CPU。标量备用程序存在用于可移植性，而专用ARM NEON内核仍在路线图中。
- 公共API可能会在 `1.0` 之前演变；版本说明将突出重大更改。
欢迎安全报告、问题和拉取请求。参见 [SECURITY.md](./SECURITY.md)、 [SUPPORT.md](./SUPPORT.md) 和 [CONTRIBUTING.md](./CONTRIBUTING.md)。
## 关于
由 [ClassEve](https://classeve.com) 构建和维护 — 面向AI代理和开发者工具的工程。项目页面： [classeve.com/public/rai](https://classeve.com/public/rai)。
## 许可证
Apache License 2.0 — 参见 [LICENSE](./LICENSE)。
版权所有 2025-2026 ClassEve。
