indexDB/README.md

indexDB

apigo.cc/go/indexDB 提供了统一的混合检索引擎，结合了基于 bleve 的全文检索和基于 chromem-go 的向量检索。

特性

• 全文+向量 混合检索，内置倒数排序融合（RRF）进行评分合并。
• 无状态依赖，支持独立指定全文和向量库路径。
• 高召回率，在应用过滤器时会自动扩大向量检索范围，确保筛选结果的准确性。
• 内容补全，如果向量库命中但全文库未命中，会自动从全文库补全正文内容。
• 游标遍历，提供 ScanDocuments 接口，支持基于 ID 的断点续传遍历，便于外部重建索引。
• 细粒度权限控制，在引擎层进行系统和用户级别的视图隔离。

安装

go get apigo.cc/go/indexDB

使用示例

1. 初始化引擎

package main

import (
	"log"
	"apigo.cc/go/indexDB"
)

func mockEmbedding(text string) ([]float32, error) {
	// ... 请求大模型获取向量
	return []float32{0.1, 0.2, 0.3}, nil
}

func main() {
    // 向量库路径为空或 embedding 函数为 nil，则不启用向量搜索
	dbUnauth, err := indexDB.GetDB("./fulltext", "./vector", mockEmbedding, log.Default())
	if err != nil {
		panic(err)
	}

    // 绑定系统管理员或特定用户权限
	db := dbUnauth.Auth(indexDB.SystemUserID)

    // 2. 添加数据
    db.Add("doc1", "这是一段测试文本", map[string]any{"source": "test"}, []string{"user1"})

    // 3. 混合检索
    filter := []indexDB.Condition{
        {Field: "source", Operator: "eq", Value: "test"},
    }
    results, err := db.Search("", "测试", 10, filter)
    for _, r := range results {
        log.Println("ID:", r.ID, "Score:", r.Score, "Content:", r.Content)
    }

    // 4. 遍历数据（用于外部重建）
    docs, _ := db.ScanDocuments("", 100)
    for _, doc := range docs {
        log.Println("Found:", doc.ID)
    }
}

API 指南

• GetDB(fulltextPath, vectorPath string, embedding func(string) ([]float32, error), logger *log.Logger): 获取引擎实例。
• (*IndexDBUnauthorized) Auth(userId string) *IndexDB: 获得特定用户的授权实例。
• (*IndexDB) Add(id, text string, metadata map[string]any, allowUsers []string) error: 添加数据。
• (*IndexDB) Remove(id string) error: 删除数据。
• (*IndexDB) Search(idPrefix, query string, topK int, filter []Condition) ([]SearchResult, error): 混合检索。
• (*IndexDB) ScanDocuments(lastID string, limit int) ([]RawDocument, error): 基于游标遍历数据。