SemaxStore — 高性能知识库存储引擎

📦 项目概述

SemaxStore 是一个零依赖的纯 TypeScript 知识库引擎，支持：

| 功能 | 实现方式 | |------|----------| | 语义检索 | HNSW + int8 量化 (99% recall, O(log N)) | | 关键词检索 | BM25 倒排索引 (磁盘存储 + 热缓存) | | 精准查找 | 符号索引 (O(1) 函数/类/表名查找) | | 多维过滤 | 标签索引 + 路径索引 + Glob 模式 | | 多路融合 | RRF 合并 + float32 重排 | | 文件切分 | Markdown/TypeScript/SQL 智能切分 |

🏗️ 核心架构

┌─────────────────────────────────────────────────────────────┐
│                     KnowledgeEngine                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ ChunkingEngine│ │MultiDimension│ │ QueryIntent  │       │
│  │ (文件切分)    │ │ Index (索引) │ │ Parser (意图)│       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     SemaxStore                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  HNSWIndex   │ │ BM25DiskIndex│ │   RRF Fusion │       │
│  │  (向量索引)   │ │  (倒排索引)  │ │   (结果合并) │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Storage Layer                              │
│  graph.semax  vectors.q8  vectors.f32  chunks.semax  bm25    │
└─────────────────────────────────────────────────────────────┘

📂 目录结构

packages/semax-store/
├── src/
│   ├── core/               # 核心算法
│   │   ├── hnsw.ts         # HNSW 图索引
│   │   ├── quantizer.ts    # int8 量化
│   │   ├── distance.ts     # 距离计算
│   │   └── min-heap.ts     # 堆结构
│   │
│   ├── bm25/               # BM25 倒排
│   │   └── bm25-disk.ts    # 磁盘存储 + 热缓存
│   │
│   ├── fusion/             # 结果融合
│   │   └── rrf.ts          # RRF 合并算法
│   │
│   ├── storage/            # 二进制存储
│   │   ├── graph-store.ts  # HNSW 图
│   │   ├── vector-store.ts # 向量 (Q8/F32)
│   │   ├── chunk-store.ts  # 内容
│   │   └── id-map.ts       # ID 映射
│   │
│   ├── chunking/           # 文件切分
│   │   ├── file-type.ts    # 类型检测
│   │   ├── markdown-chunker.ts
│   │   ├── ts-chunker.ts   # TypeScript + 符号提取
│   │   └── sql-chunker.ts  # SQL + schema 提取
│   │
│   ├── indexing/           # 多维度索引
│   │   ├── symbol-index.ts # 符号精准索引
│   │   └── multi-dimension-index.ts # 标签 + 路径
│   │
│   ├── search/             # 查询引擎
│   │   ├── engine.ts       # 搜索引擎
│   │   └── query-intent.ts # 意图识别
│   │
│   ├── knowledge/          # 知识库入口
│   │   └── engine.ts       # KnowledgeEngine
│   │
│   ├── index.ts            # SemaxStore 入口
│   └── types.ts            # 类型定义
│
├── test/
│   ├── verify.ts           # 验证脚本
│   ├── knowledge-demo.ts   # 知识库演示
│   └── mock-encoder.ts     # Mock 编码器
│
├── docs/
│   └── knowledge-base-design.md  # 设计文档
│
└── package.json

🔬 文件类型支持

代码类 (ts, tsx, js, go, py, sql)

// 智能切分策略
Function → chunk  // 每个函数独立 chunk
Class    → chunk  // 类定义 + 方法合并
Interface → chunk // 接口定义

// 符号提取
symbols: {
  functions: [{ name, signature, isAsync, description }],
  classes: [{ name, extends, methods, properties }],
  interfaces: [{ name, properties, methods }],
}

// 精准查找
"getUserById" → O(1) 符号索引 → chunk
"User 类"     → 符号 + 关键词 → 混合查询

文档类 (md, mdx, txt, log)

// 标题层级切分
H1 "项目概述"
  └─ H2 "架构"
      └─ H3 "存储层" → chunk
      └─ H3 "索引层" → chunk

// 结构提取
headingPath: "项目/架构/存储层"
codeBlocks: [{ lang, content }]
links: ["https://..."]

SQL 类

// Schema 切分
CREATE TABLE users → chunk
CREATE INDEX idx_  → chunk
SELECT ... FROM    → chunk

// Schema 提取
schema: {
  tableName: "users",
  columns: [{ name, type, nullable, foreignKey }],
  indexes: [{ name, columns }],
  relations: [{ table, type }]
}

// 精准查找
"users 表结构" → 表名索引 → schema chunk

🚀 查询示例

const engine = new KnowledgeEngine(config);
await engine.build();

// 1. 符号精准查询 (O(1))
engine.search("trainQuantizer");
// → 意图: symbol → 符号索引精准匹配

// 2. 标签过滤
engine.search("tech:typescript chunk:function");
// → 意图: tag → 标签索引过滤

// 3. 路径定位
engine.search("src/core/");
// → 意图: path → 路径索引查找

// 4. 语义查询
engine.search("如何实现向量量化");
// → 意图: semantic → BM25 + HNSW + RRF

// 5. 混合查询
engine.search("getUserById 函数");
// → 意图: hybrid → 符号 + BM25 融合

// 6. 自动补全
engine.autoComplete("HNSW");
// → ["HNSWIndex (class)", "HNSW.search (function)", ...]

📊 性能验证

| 指标 | Small (1K) | Medium (10K) | Large (50K) | |------|------------|---------------|-------------| | HNSW recall@10 | 99.0% | 99.0% | 99.0% | | HNSW 延迟 | 0.1ms | 0.5ms | 1.3ms | | BM25 精确率 | 100% | 100% | 100% | | BM25 延迟 | 0.1ms | 0.8ms | 3.5ms | | 融合延迟 | 0.6ms | 1.5ms | 3.3ms | | 构建速度 | 3650 docs/s | 893 docs/s | 653 docs/s | | 存储大小 | 0.86 MB | 15.2 MB | 76.1 MB |

🔗 与现有系统集成

knowledge-models (bge-base-zh-v1.5)

// 编码函数接入
import { BGEEncoder } from 'specflow-knowledge-models';

const config = {
  encodeFn: async (text: string) => {
    return bgeEncoder.encode(text); // 768d
  },
  dim: 768,
};

cognitive-engine

// L1 知识库层
import { KnowledgeEngine } from 'semax-store';

// 替换现有存储层
class CognitiveStorage {
  private knowledgeEngine: KnowledgeEngine;

  async storeKnowledge(docs) {
    await this.knowledgeEngine.build();
  }

  async searchKnowledge(query) {
    return this.knowledgeEngine.search(query);
  }
}

🛠️ 使用方式

# 构建
cd packages/semax-store

# 运行验证
node --experimental-strip-types test/verify.ts --scale medium

# 运行知识库演示
node --experimental-strip-types test/knowledge-demo.ts

📖 设计文档

完整设计文档: docs/knowledge-base-design.md

包含：

• 五层架构详解
• 文件切分策略
• 多维度索引设计
• 查询意图识别
• 与 bge 编码器集成
• 扩展方案（设计资产、动画等）