MindNano Ling3 Compass

MindNano Ling3 Compass 是一个基于 Ling-3.0-tiny 的实验性 C++ 知识库推理方案。建库时保存资料原文、embedding 和 Ling3 原生状态；查询时复用正常问题前向的 hidden 完成检索，读取候选资料状态判断证据，再使用文本或缓存状态生成回答。

仓库提供 Ling3 BF16 GGUF、H1/H2 权重、C++ 引擎、SQLite 知识库接口及测试记录。基础 Ling3 权重未做 LoRA 或全量微调；本次压缩方案不包含历史 H3 训练分支。

目标

• 复用正常 LLM 问题 hidden 检索，减少查询阶段独立 embedding/reranker 模型的常驻开销。
• 复用预先生成的资料状态，减少命中资料的冷文本预填充。
• 支持新增、更新、删除资料，注册新资料无需逐条梯度训练。
• 将资料状态持久化到磁盘，按需恢复，通过有预算的热缓存管理内存。
• 比较完整与压缩状态的存储、质量和延迟，明确各自适用边界。

推理流程

建库：资料原文 → Qwen embedding + Ling3 资料状态 → SQLite
查询：正常问题前向的 hidden → H1 检索 → H2 证据判断 → H3 回答

建库

Qwen3-Embedding-0.6B 生成 1024 维归一化资料向量；Ling3 按固定模板读取资料并保存状态，包括 MLA、KDA 循环状态及卷积状态。一个条目可由多个段落共同注册，生成一个联合资料包。

NoThink 与 Think 的模板和缓存分开。默认只生成 NoThink；Think 需显式启用并注册对应状态。

H1：复用正常 hidden 检索

正常问题前向产生的输入、中间及末层问题区间特征，经池化和 H1 投影映射到资料 embedding 空间，再进行余弦相似度 TopK 检索。H1 不需要额外运行外部问题 embedding 模型。

这是当前正式接口的默认流程，/api/query 与 /v1/chat/completions 共用同一实现。问题前向和公共前缀恢复仍有计算成本，计入请求延迟；读取 hidden 本身不会让这部分计算消失。

h1_variant:"legacy_template" 保留旧独立检索模板作对照，使用同一组 H1 权重。当前服务从单轮请求构造正常问题前向，尚未接入多轮对话中的既有运行上下文。

H2：读取候选并判断证据

引擎按召回顺序恢复候选资料状态，使用 Ling3 读取问题并由 H2 判断证据是否适用，选择首个满足门槛的候选；没有满足条件的证据时拒答。H2 不是独立外部 reranker，其耗时包含状态读取、恢复、模型前向和分类头。

当前结果不能证明 H2 在通用重排任务上优于专用 reranker。

H3：使用选中资料回答

KV 路径恢复选中资料状态，继续输入问题并生成；文本路径将对应资料原文作为 prompt 输入。当前选择一个已联合注册的资料包，不支持把任意独立注册的多个状态无损拼接成联合上下文。

默认 H2 与 H3 保留各自读取流程。接受候选后直接复用 H2 回答条件的 H23 调度选项另行验证，见下文。

查询模式

text_rerank 是额外的标准文本 RAG 对照，需要配置外部 reranker；text_embedding 保留不重排的文本对照。旧 text / kv 名称保留兼容。

完整与压缩模式不会静默互换条目格式。进行配对测试时，应在独立数据库中注册相同资料，避免重复条目影响召回。

当前效果

默认流程回归

2026-10-04，在 RTX 5090、BF16、NoThink、32 个资料包、100 道中英日问题、Top3 条件下，默认正常 hidden 流程：

H23 复用未启用。这是已有回归集，不是未观察盲测。

与改动前已有的正常 hidden 实验路径配对后，候选顺序、分数、H2 概率、选包、答案、输出 token 数与 EOS/结束原因均一致。新默认入口与显式旧模板分别进行了改动前后回归，合计 800 次主要查询。

另在中英日三题 × Think/NoThink 共六组控制实验中，读取 hidden 与普通前向的全词表 logits 最大绝对差为 0，greedy token 相同，保存状态逐字节相同。这验证的是 hidden 提取机制，不是 Think 问答质量。

报告：默认 H1 回归、回归指标、hidden 数值检查。历史 H1 训练结果见 训练记录。

四核 CPU 性能记录

2026-10-03，AMD 9950X 固定四物理核心、4 线程、GPU 层数 0，BF16、NoThink、Top3、100 道中英日问题，Linux/ext4，资料预注册且热缓存命中：

文本行来自此前测试，KV 行来自后续复用测试，不是本次默认入口更新后的三模式同步重测。H123 推理进程只加载 Ling3 和 H1/H2 头，不包含独立建库服务；RSS 是服务进程内存，不是全系统占用。

这些数据支持在本组短资料、单包选择任务中减少计算与常驻模型开销。压缩仍有质量损失，热缓存内存并未随磁盘体积同比缩小。详细阶段计时、p95 和条件见 端到端对照。

各阶段详细耗时

单位为 ms，每格为 p50 / p95。以下同时列出 H12 + Text 和不重排的 Embedding + Text 对照；两条 H123 为正常 hidden + H23 复用测试，其余三条沿用历史实测，并非五条路线同一轮重测。

H123 两行的“检索前 LLM 前向”是正常问题预填充，H1 直接复用其 hidden；“H1 头”仅计投影耗时，分列是为了拆解成本，不代表再跑一次独立问题编码。H12 + Text 保留历史检索模板的计时。Embedding 路线的问题 LLM 前向包含在 H3 中，表内前置阶段的 0 不代表整条路线没有这项计算。

H2 包含候选状态读取、恢复、模型读取与分类判断；文本重排路线对应外部 Qwen rerank。H123 公共前缀恢复另计入整链：完整 KV 为 2.72/2.93 ms，压缩 KV 为 2.92/3.78 ms。

H3 首 token 的约 0.08 ms 是 H2 已完成回答预填充后的局部耗时，不是整链 TTFT。H3 完整生成包含首 token 阶段，文本路线还包含资料预填充；各列的分位数不能直接相加。整链首 token 和请求完成时间应查看上方汇总表。

KV 存储与压缩

新版压缩：activation960

建库时，对 MLA latent 进行 INT8 量化，保留 RoPE FP16，对卷积状态进行 INT4 量化；KDA 使用冻结的 Q/K 协方差做读取方向感知低秩分解，并将因子保存为 INT4/group32。该过程不修改 LLM 或 H1/H2 权重，不包含额外模型训练。

查询时，H2/H3 按需读取压缩状态，解压、反量化并重建为原生运行状态；命中的资料不再进行文本预填充，document_replay_tokens=0。这保留了资料缓存复用，但仍有状态读取、解码、恢复和问题前向成本，不等于零开销。

48 个全新知识包、288 道中英日问题的配对验收结果：

本组样本的状态文件约缩小 22 倍，减小约 95.4%；不包含共享公共前缀、原文、embedding、数据库页面及索引。压缩方案保留完整 KV 正确字段的 181/188（96.3%），保留完整 KV 严格正确回答的 232/255（91.0%），两者不是同一指标。相对完整 KV，H2 新增 5 次误接受和 6 次误拒绝。全部 1,440 次生成均自然 EOS，无容量失败；仍有字段错误，不能称为无损或等价于 Text。

验收条件为 NoThink、BF16、greedy、4096 上下文、128 输出预算；H3 直接使用已知正确来源包，H2 使用固定候选，不是完整 H123 端到端验收。研究库解码中位为 37.94 ms；本地发布库单条 API 烟测首次解码约 155 ms，热 LRU 命中不重复解码。两者不是相同测试条件，均不能当作整链 TTFT 或端侧速度承诺。原始指标见新版压缩说明及验收记录。

使用时，注册指定 kv_codec:"activation960"，查询指定 mode:"compressed_kv"、think:false。默认仍为 native，旧条目不自动转换；Think 未验收，新格式拒绝注册 Think 缓存。冻结协方差文件 engine/assets/activation960_covariance.bin 约 18 MiB，仅建库压缩时使用，查询无需加载。

压缩文件与条目预留合计预算为 960 KiB，共享公共前缀另计，不能承诺每条总占用低于 1 MiB。无法满足预算时返回 422，不截断资料、不重算替代、不静默回退。

旧版压缩：adaptive768

adaptive768 继续支持，压缩文件与条目预留合计预算为 768 KiB/模式，共享公共前缀另计。以下是旧版 54 道逐字配对题的历史记录，与新版不同数据及条件，不能直接比较准确率。只有精确匹配且自然 EOS 才算正确：

压缩有 5 题容量失败；成功生成子集为 40/49 正确。全体 43 道 Text 正确题中保住 38 题，不能称为无损。体积来自本组样本，不是任意长度资料的承诺。完整条件与原始数据入口见 KV 压缩实验。

磁盘、内存与缓存命中

未命中的资料状态保存在 SQLite，H2/H3 按需读取；不要求全库 KV 常驻内存。冷命中包含读取、校验、解压/解量化、低秩重建及恢复成本。

热 LRU 保存恢复后的完整状态，由 kv_cache_mb 限制缓存预算；模型运行状态、临时缓冲和系统页缓存仍占用内存。因此按需读取不等于零内存开销，磁盘压缩也不等于运行时 RSS 等比例下降。

成功 KV 路径检查 document_replay_tokens=0，表示没有重新预填充命中的资料文本，不代表没有问题前向或状态恢复计算。

可选 H23 复用

配置 enable_inline_experiments:true，请求指定 experiment:"natural_h23_reuse"，可让 H2 采用回答条件读取，接受候选后直接进入 H3 生成，避免重复回答预填充。

H1 的正常 hidden 复用已是默认行为；H23 是独立的可选调度优化。它改变 H2 的问题模板，目前只验证 NoThink、预注册单资料包和不超过 128 个输出 tokens 的实验条件，默认不开启。详见 H23 报告。

文件目录

README.md                         项目概述和使用入口
LICENSE / NOTICE                  项目许可及署名、来源说明
docs/                             模型卡、验证索引、训练/压缩记录、上传说明
engine/
  compass-server                  示例二进制
  config.json                     服务配置
  src/                            C++ 推理和服务源码
  assets/                         H1/H2、模板与自检样本
  lib/                            示例二进制运行库
  tests/                          机制测试、模型评测与压缩原始结果
models/ling3-compass-bf16.gguf      Ling3 基础模型
adapters/h1/                      独立 H1 权重及配置
reports/                          实验报告与机器可读指标
licenses/                         第三方许可及原始模型卡
external_models.json              外部 embedding/reranker 引用
scripts/hash_release.py           发布哈希生成
SHA256SUMS / UPLOAD_MANIFEST.json  发布文件校验

文档目录 · 模型卡 · 验证记录 · 引擎详细说明

如何使用

以下命令在仓库根目录执行。

外部模型

外部模型不随本仓库分发：

• Qwen3-Embedding-0.6B：建库及文本 embedding 检索。
• Qwen3-Reranker-0.6B：可选标准文本重排对照。

需通过兼容的转换工具生成 GGUF，按各自许可证使用。默认 embedding 路径为 models/external/qwen3-embedding-0.6b-bf16.gguf；可选 reranker 在配置中设置 reranker_model。服务不会自动下载它们。配置内相对路径以配置文件目录为基准。

编译与启动

需要 C++17、CMake、Eigen3、静态 zlib，以及支持 Ling3、与接口兼容的 llama.cpp 动态库：

cmake -S engine -B engine/build -DCMAKE_BUILD_TYPE=Release \
  -DLLAMA_LIB_DIR=/absolute/path/to/compatible/llama/lib
cmake --build engine/build -j4
engine/build/compass-server --config engine/config.json

非标准 Eigen 安装可设置 Eigen3_DIR。仓库也提供 Linux x86_64/CUDA 示例二进制及运行库，可直接使用：

engine/compass-server --config engine/config.json

只使用四个 CPU 线程：

COMPASS_N_GPU_LAYERS=0 COMPASS_THREADS=4 \
  engine/compass-server --config engine/config.json

默认监听 127.0.0.1:8893。线程数本身不绑定四个物理核心；复现固定核心测试还需设置 CPU 亲和性。

建库与查询

初始化：

curl --noproxy '*' http://127.0.0.1:8893/api/init \
  -H 'Content-Type: application/json' \
  -d '{"name":"demo","mode":"kv"}'

注册完整 KV：

curl --noproxy '*' http://127.0.0.1:8893/api/entries \
  -H 'Content-Type: application/json' \
  -d '{"id":"room","text":"星桥会议室的预约编号是 ABC-73921。","kv_codec":"native"}'

查询：

curl --noproxy '*' http://127.0.0.1:8893/api/query \
  -H 'Content-Type: application/json' \
  -d '{"question":"星桥会议室的预约编号是什么？","mode":"full_kv","think":false,"top_k":3,"max_tokens":128}'

使用新压缩候选时，将注册参数改为 kv_codec:"activation960"，查询改为 mode:"compressed_kv"，保持 think:false；建议另设数据库进行比较。旧 adaptive768 继续支持。旧模板对照可在查询中指定 h1_variant:"legacy_template"。

OpenAI Chat Completions 格式入口使用同一推理流程：

curl --noproxy '*' http://127.0.0.1:8893/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"mindnano-ling3-compass","messages":[{"role":"user","content":"星桥会议室的预约编号是什么？"}],"mode":"full_kv","think":false,"top_k":3,"max_tokens":128,"stream":false}'

当前只支持一个 user 消息和 stream:false，并非完整 OpenAI API 功能实现。扩展指标保存在响应的 compass 字段。

仅推理部署

建库完成后，可以使用 inference_only:true 启动只加载 Ling3 与 H1/H2 的服务，不加载外部 embedding/reranker。该服务可使用 H123 和 H12 Text，不支持注册/更新条目、外部 embedding 检索或 Qwen 重排。

目前 embedding 文件仍须存在，以进行数据库 ABI 身份校验；这不等于将其作为运行模型加载。独立建库进程更新后，应重启只读推理进程使缓存一致；当前没有跨进程热缓存失效协议。

API

同一服务内更新、删除会使对应热缓存失效。更详细的参数、错误及实验接口见 引擎说明。

如何读取性能指标

timing_ms.ttft 是服务端从请求进入推理链到首个生成 token 的时间；timing_ms.request_total 是引擎处理完整请求的时间。客户端完整 HTTP 耗时还包含传输、序列化等开销。

阶段字段包括 query_encode、shared_head、h1_projection、embedding、search 和 h2。H1 的问题前向属于在线请求成本；离线资料 embedding 与状态生成属于建库成本。

generation.ttft_ms 只计 H3 阶段，不能代替整链 TTFT。还应一起检查输出 token 数、finish_reason、EOS、document_replay_tokens、缓存命中与 h1_variant。拒答和真实生成应分开解释；不同阶段分位数不能直接相加。非流式接口的服务端 TTFT 不是客户端收到首字的时间。

当前边界

• 默认 NoThink；Think 需独立缓存，质量和输出长度仍属实验。
• 单 worker、单轮、非流式；尚无并发推理和完整会话管理。
• 向量检索为线性扫描，未验证大规模 ANN。
• 一次选择一个已联合注册的资料包，未实现通用跨包 KV 合并。
• 压缩存在逐字精度损失和容量失败；H2 也可能受状态压缩影响。
• 已有短资料及开发集结果不能代表任意真实文档或领域。
• 状态依赖模型、模板、头权重、上下文和运行库 ABI；不兼容时应在新数据库重新注册。
• 默认上下文 4096；当前接口问题上限 512 tokens、输出上限 1024 tokens、条目 Ling3 前缀上限 1536 tokens、embedding 输入上限 2048 tokens。这些是当前实现限制，不是模型理论上限。

验证

engine/compass-server --self-test --config engine/config.json
ctest --test-dir engine/build --output-on-failure
engine/build/hidden-capture-test models/ling3-compass-bf16.gguf engine/assets
sha256sum -c SHA256SUMS

小头自检、无模型机制测试和真实模型 hidden 检查分别覆盖不同范围。实际模型评测与历史结果入口见 发布验证；发布操作见 上传维护。

许可证与署名

本项目原创代码、文档、H1/H2 权重及原创配套资产采用 Apache License 2.0。署名为 Sariel00 / MindNano，项目地址为 Sariel00/mindnano-ling3-compass。许可全文和归属说明见 LICENSE 与 NOTICE。

再分发时应保留适用的版权、许可和 NOTICE 归属信息，对修改的文件标明修改。Apache-2.0 允许商业使用和修改，不要求额外强制界面署名，也不授予商标背书权。此前已按 MIT 发布版本的既有授权不被撤销。

直接引入的第三方模型、代码和运行库继续沿用原许可证，包括 Ling3 基础模型及其 GGUF 格式转换、llama.cpp、Qwen embedding/reranker 和随附依赖；不因放入本仓库而改为项目许可。详情见 第三方说明 及 licenses/。