Resin

简介

这是对旧版 Resin 搜索引擎/机器学习项目的重启动作，采用了更为合理的架构，但功能尚未完全完善。

Resin 是一款向量空间搜索引擎、向量数据库以及通用键值存储系统。它支持高效的字符串处理、向量运算，并提供专为速度与简洁性设计的自定义存储原语。Resin 可以从字符串中构建大型语言模型，也可以从字节数组中构建大型“任意”模型。

亮点

• 基于页和列的读写器实现的快速键值存储
• 针对字符串、词袋/字符集以及向量的实用文本分析工具
• 用于构建和验证词典以及比较字符串的命令行工具
• 设计简洁、依赖轻量且易于扩展

键值列语义

ColumnWriter

• TryPut(TKey key, ReadOnlySpan value)

  • 仅当键在列范围内的快照中不存在时（包括之前页面中的键）才插入键值对。
  • 如果键已存在，则返回 false；否则将值写入当前页。
  • 当页面满时，会触发页面序列化。

• PutOrAppend(TKey key, ReadOnlySpan value)

  • 如果键在列中的任何位置已经存在，则不会存储新键。相反，值会通过固定大小的节点（LinkedAddressNode）链接到值流中。
  • 尾部追加顺序：原始值保持在最前面，随后按插入顺序依次追加其他值。当链接生效时，该键的地址条目会指向链表头。
  • 如果键在列快照中不存在，则在页面级别操作（在当前页面内插入或追加），并在页面满时可能触发序列化。

ColumnReader

• Get(TKey key)

  • 返回指定键的值。如果该键的地址条目指向一个链表头，则返回所有链接值的拼接字节。
  • 如果键不存在，则返回 ReadOnlySpan<byte>.Empty。

• GetMany(TKey key, out int count)

  • 返回与指定键关联的所有值的拼接 ReadOnlySpan<byte>，并通过 count 输出项数。
  • 如果该键指向单个原始值，则返回该值并设置 count = 1。如果键不存在，则返回空并设置 count = 0。

TKey 对 ColumnWriter/ColumnReader 的限制

在使用 TKey 时，请遵守以下限制以确保正常运行：

• TKey 必须是值类型（struct），并且同时实现 IEquatable<TKey> 和 IComparable<TKey>。
• 排序和相等性必须在不同会话之间保持稳定。列范围内的键快照使用二分查找/排序，因此 CompareTo 必须定义一个与 Equals 一致的严格全序关系。
• 页面级存储使用 long 类型的键。对于原始数值类型的键：
  • double 和 float 通过其 IEEE 位表示形式存储。
  • int 和 long 直接存储。
  • 其他 TKey 类型则通过 GetHashCode() 哈希为 long，以便在页面级别操作。
• 建议：使用数值原语类型（double、float、int、long）以实现确定性的排序和查找。如果使用自定义结构体，请确保：
  • Equals 和 CompareTo 一致且具有确定性。
  • GetHashCode() 稳定且分布均匀；哈希冲突会影响页面级别的操作，因为非原语类型的键会被哈希为 long。
• 键在整个列范围内必须可比较；重复键的检测依赖于列快照和对已排序键的二分查找。

列模型与集合操作

• 每列在其列范围内的快照中最多存储一次给定的 TKey（TryPut 和 PutOrAppend 都会防止重复键）。这使得列实际上成为键的集合，从而可以进行并集、交集和跨列连接等集合操作。通过 PutOrAppend 链接的值会在不引入重复键的情况下为现有键附加额外数据。

存储文件格式：.key、.adr、*.val

• .key（键流）
  • 存储每页/每列的 TKey 表示形式的排序序列。键以固定大小的槽位写入（页面级存储每个条目占用 sizeof(long)），并按页面批次进行序列化。列范围内的快照通过读取并排序此流来构建。
• .adr（地址流）
  • 存储与 .key 条目对齐的 Address 结构体。每个 Address 包含 Offset 和 Length：
    • 对于原始值：直接指向 .val 流（Offset 为值的起始位置，Length 为字节长度）。
    • 对于链接值：指向 .val 流中的 LinkedAddressNode 头（Length 等于节点大小）。通过节点链可以获取单个键的多个值。
• .val（值流）
  • 存储实际的值字节以及用于链接的 LinkedAddressNode 头。值追加写入流的末尾；LinkedAddressNode 也会写入 .val 流，通过绝对偏移形成单向链表。

值文件的不可变性

• .val 流被视为只追加模式：
  • 已有字节绝不会被就地修改。
  • 新值始终写入末尾，保留先前写入的偏移量。
  • 链接操作不会重写现有值；而是追加 LinkedAddressNode 头，并通过更新 .adr 中的指针来修补前一个节点的 NextOffset。
• 优点：
  • 稳定的偏移量使得地址可以安全缓存，读取路径也更加高效。
  • 追加操作呈线性扩展，可最大限度减少碎片并避免就地修改。
  • 历史值得以完整保留；多值链通过节点头表达，而非覆盖数据。

使用方法

• 使用 Resin.KeyValue 实现快速的磁盘结构以及高效的键值读写会话。
• 使用 Resin.TextAnalysis 进行字符串分析、向量运算及相似度计算。
• 使用 Resin.WikipediaCommandLine 提供的命令行工具来构建或验证词典。详细的 CLI 使用方法和设置请参阅 Resin.WikipediaCommandLine/README.md。

贡献

欢迎贡献！请提交带有明确动机的问题或拉取请求，并在适用时附上测试用例和简洁的更改说明。

许可证

本项目采用 MIT 许可证。

获取帮助或报告问题

报告问题

Resin 快速上手指南

Resin 是一个高性能的向量空间搜索引擎、向量数据库及通用键值存储系统。它专为速度和简洁性设计，支持高效的字符串处理、向量运算及自定义存储原语，适用于构建大语言模型底层数据或处理大规模字节数组。

环境准备

• 操作系统：支持 Windows、Linux 和 macOS（基于 .NET 运行时）。
• 前置依赖：
  • .NET SDK：版本 6.0 或更高（推荐最新 LTS 版本）。
  • 构建工具：若需从源码编译，请确保安装 Git 和对应的 IDE（如 Visual Studio 2022+ 或 VS Code）。
• 国内加速建议：
  • 安装 .NET SDK 时，推荐使用 .NET 中国镜像站 下载安装包。
  • 若通过命令行安装，可配置国内 NuGet 源以提升包恢复速度：

  dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org --configfile ./NuGet.Config
  # 注：实际使用中建议替换为国内镜像地址，如 https://nuget.cnblogs.com/v3/index.json
  

安装步骤

Resin 主要作为库引用或通过源码编译使用。以下是通过 .NET CLI 集成到项目的步骤：

1. 创建新项目（如已存在项目可跳过）：

   dotnet new console -n ResinDemo
   cd ResinDemo
   

2. 添加 Resin 依赖： 由于该项目处于重构阶段，若 NuGet 包尚未发布最新版，建议直接引用源码或本地编译后的 DLL。若官方包可用，执行：

   dotnet add package Resin
   

   若需从源码构建（推荐获取最新功能）：

   git clone https://github.com/kreeben/resin.git
   cd resin
   dotnet build -c Release
   # 然后在你的项目中引用生成的 dll 或添加项目引用
   dotnet add reference ../resin/src/Resin.KeyValue/Resin.KeyValue.csproj
   dotnet add reference ../resin/src/Resin.TextAnalysis/Resin.TextAnalysis.csproj
   

3. 验证安装： 确保 Program.cs 中可以正常引入命名空间：

   using Resin.KeyValue;
   using Resin.TextAnalysis;
   

基本使用

Resin 的核心功能分为高速键值存储 (Resin.KeyValue) 和文本/向量分析 (Resin.TextAnalysis)。

1. 初始化键值存储 (ColumnWriter/ColumnReader)

Resin 使用列式存储模型，数据保存在 .key (键), .adr (地址), .val (值) 文件中。

using System;
using System.IO;
using Resin.KeyValue;

// 定义键类型，必须是 struct 且实现 IEquatable 和 IComparable
// 推荐使用 int, long, double 等原生数值类型以保证确定性排序
public struct MyKey : IEquatable<MyKey>, IComparable<MyKey>
{
    public long Id;

    public bool Equals(MyKey other) => this.Id == other.Id;
    public int CompareTo(MyKey other) => this.Id.CompareTo(other.Id);
    public override int GetHashCode() => Id.GetHashCode();
}

class Program
{
    static void Main()
    {
        var directory = "./resin_data";
        if (!Directory.Exists(directory)) Directory.CreateDirectory(directory);

        // 1. 写入数据 (ColumnWriter)
        // TryPut: 仅当键不存在时写入
        // PutOrAppend: 若键存在，则将新值链接到旧值之后（形成多值列表）
        using (var writer = new ColumnWriter<MyKey>(directory, "my_column"))
        {
            var key1 = new MyKey { Id = 100 };
            var value1 = System.Text.Encoding.UTF8.GetBytes("Hello Resin");
            
            writer.TryPut(key1, value1);

            // 追加第二个值到同一个键
            var value2 = System.Text.Encoding.UTF8.GetBytes(" Appended Data");
            writer.PutOrAppend(key1, value2);
            
            writer.Dispose(); // 触发页面序列化
        }

        // 2. 读取数据 (ColumnReader)
        using (var reader = new ColumnReader<MyKey>(directory, "my_column"))
        {
            var key1 = new MyKey { Id = 100 };
            
            // Get: 返回所有链接值的拼接字节
            var result = reader.Get(key1);
            if (!result.IsEmpty)
            {
                string content = System.Text.Encoding.UTF8.GetString(result);
                Console.WriteLine($"Read Value: {content}"); 
                // 输出: Hello Resin Appended Data
            }

            // GetMany: 获取拼接值及原始片段数量
            var manyValues = reader.GetMany(key1, out int count);
            Console.WriteLine($"Total segments: {count}");
        }
    }
}

2. 文本分析与向量操作

利用 Resin.TextAnalysis 进行字符串处理和向量计算。

using Resin.TextAnalysis;

// 初始化分析器
var analyzer = new StringAnalyzer();

// 示例：将字符串转换为词袋（Bag of Words）或特征向量
string text = "Resin is a fast vector search engine";
var tokens = analyzer.Tokenize(text); // 分词

// 向量运算示例 (需根据具体 API 版本调整)
// 假设已有两个 float 数组代表向量
float[] vecA = new float[] { 1.0f, 0.5f, 0.2f };
float[] vecB = new float[] { 0.9f, 0.6f, 0.1f };

// 计算余弦相似度或其他向量距离
// float similarity = VectorOperations.CosineSimilarity(vecA, vecB); 
// 注意：具体静态方法名请参考最新源码中的 VectorOperations 类定义

3. 命令行工具 (可选)

若需构建或验证词典，可编译并使用 Resin.WikipediaCommandLine 工具：

# 进入命令行工具目录
cd src/Resin.WikipediaCommandLine

# 运行构建命令 (具体参数参考该目录下的 README)
dotnet run -- build-lexicon --input ./data.txt --output ./lexicon.bin

注意：TKey 的设计至关重要。请确保自定义结构体的 CompareTo 和 Equals 逻辑一致且稳定，否则会导致列快照排序错误或查找失败。优先使用 int 或 long 作为键可获得最佳性能。