zishuo/kektordb

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

kektordb/README.zh.md

山里人

feat: 性能优化与功能增强（基准测试和 AVO 汇编）

a0efc807

PreviewCode viewBlame

KektorDB

📚 文档 • 🤝 贡献 • 🤖 RAG Open WebUI 指南

English | Italiano | 中文

TIP

Docker 支持： 更喜欢使用容器？根目录中包含 Dockerfile 可用于创建镜像。

KektorDB 是一个用纯 Go 编写的内存型可嵌入的向量 + 图数据库。

它将强大的 HNSW 引擎 与轻量级的 语义图 结合在一起，使你能够将向量相似性与显式关系（如 parent、next、mentions）结合，而无需传统图数据库的复杂性和开销。

基于 SQLite 的哲学构建：无服务器选项、零依赖和易于管理。

KektorDB 图演示

为什么选择 KektorDB？

KektorDB 通过将 数据库、搜索引擎 和 AI 中间件 统一到一个无依赖的二进制文件中，简化了技术栈。

Database First： 一个强大且持久的存储（AOF+Snapshot），支持混合搜索（BM25 + 向量）和元数据过滤。
嵌入式架构： 设计为在应用程序进程旁边运行（如 SQLite），或作为轻量级微服务，消除网络延迟。
轻量级图层： 与"扁平"向量存储不同，KektorDB 理解连接。它提供了一个精简的图引擎，针对 N-Hop 遍历 和 上下文检索 进行了优化，弥合了相似性与结构之间的差距。

使用场景

KektorDB 不是为了替代管理数十亿向量的分布式集群。相反，它在特定且高价值的场景中表现出色：

1. Go 应用的嵌入式搜索

非常适合为构建单体应用或微服务的开发者提供语义搜索，而无需分布式集群的运营开销。

场景： 在 Go 后端实现"相关产品"或"语义搜索"。
解决方案： import "github.com/sanonone/kektordb/pkg/engine" 以在进程内运行数据库。
优势： 零部署复杂性。数据库随应用扩展。

2. 本地 RAG 和知识库

非常适合桌面应用、本地 AI 代理或私有文档搜索，其中数据隐私至关重要。

场景： 需要索引敏感文件（PDF/Markdown/Docx）并使用本地 LLM（Ollama）与它们聊天。
解决方案： 将 KektorDB 指向你的文件夹。它管理整个摄取管道（OCR、分块、链接）。
优势： 设置时间从几天减少到几分钟。没有任何数据离开你的机器。

3. AI 网关和语义缓存

充当智能代理，以优化 LLM 应用的成本和延迟。

场景： 使用 OpenAI/Anthropic API 构建聊天机器人。
解决方案： 使用 KektorDB 作为中间件。语义缓存响应（节省 API 成本）并充当防火墙，在恶意提示到达 LLM 之前阻止它们。
优势： 立即提升性能并降低成本，而无需修改客户端代码。

零代码 RAG（Open WebUI 集成）

KektorDB RAG 演示

KektorDB 可以作为 智能中间件 在你的聊天 UI 和 LLM 之间运行。它拦截请求，执行检索并自动注入上下文。

架构： Open WebUI -> KektorDB 代理 (9092) -> Ollama / LocalAI (11434)

配置方法：

配置 vectorizers.yaml 指向你的文档并启用实体提取。
配置 proxy.yaml 指向你的本地 LLM（Ollama）或 OpenAI。

运行 KektorDB 启用代理：


./kektordb -vectorizers-config='vectorizers.yaml' -enable-proxy -proxy-config='proxy.yaml'

配置 Open WebUI：
- Base URL： http://localhost:9092/v1
- API Key： kektor（或任何字符串）。
聊天： 只需对你的文档提问。KektorDB 处理其余部分。

👉 阅读完整指南：使用 Open WebUI 构建快速 RAG 系统

✨ 主要特性

⚡ 性能与工程

HNSW 引擎： 定制实现，针对高并发读取进行了优化。
混合搜索： 结合向量相似性 + BM25（关键词）+ 元数据过滤。
内存效率： 支持 Int8 量化（节省 75% RAM）并具有零样本自动训练，以及 Float16。
维护与优化：
- Vacuum： 清理已删除节点的后台进程，以回收内存并修复图连接。
- Refine： 持续优化，重新评估图连接以提高搜索质量（召回率）。
AI 网关和中间件： 充当 OpenAI/Ollama 兼容客户端的智能代理。具有 语义缓存 以提供对重复查询的即时响应，以及 语义防火墙 基于向量相似性阻止有害提示，独立于 RAG 管道。
持久化： 混合 AOF + Snapshot 确保持久性。
可观测性： Prometheus 指标（/metrics）和结构化日志。
双模式： 作为独立的 REST 服务器 或 Go 库 运行。

🧠 代理式 RAG 管道

查询重写（CQR）： 基于聊天历史自动重写用户问题（例如："如何安装？" -> "如何安装 KektorDB？"）。解决短期记忆问题。
Grounded HyDe： 生成假设性答案以改善模糊查询的召回率，使用真实数据片段来锚定幻觉。
安全网： 如果高级管道无法找到相关上下文，自动回退到标准向量搜索。

🕸️ 语义图引擎

自动实体提取： 在摄取期间使用本地 LLM 识别概念（人物、项目、技术），并链接相关文档（"连接点"）。
图遍历： 搜索遍历 prev（上一个）、next（下一个）、parent（父级）和 mentions（提及）链接，以提供整体上下文窗口。

知识图谱可视化
通过提取的实体可视化文档之间的语义连接。

🖥️ 集成仪表板

可在 http://localhost:9091/ui/ 访问。

图浏览器： 使用力导向布局可视化你的知识图谱。
搜索调试器： 测试查询并准确查看检索文档的原因。

安装

作为服务器（Docker）


docker run -p 9091:9091 -p 9092:9092 -v $(pwd)/data:/data sanonone/kektordb:latest

作为服务器（二进制）

从发布页面下载预编译的二进制文件。


# Linux/macOS
./kektordb

兼容性说明： 所有开发和测试均在 Linux (x86_64) 上进行。纯 Go 构建应该可以在 Windows/Mac/ARM 上运行。

作为嵌入式 Go 库使用

KektorDB 可以直接导入到你的 Go 应用程序中，无需外部服务或容器。


go get github.com/sanonone/kektordb


package main

import (
	"fmt"
	"github.com/sanonone/kektordb/pkg/core/distance"
	"github.com/sanonone/kektordb/pkg/engine"
)

func main() {
	// 1. 初始化引擎（自动管理持久化）
	opts := engine.DefaultOptions("./kektor_data")
	db, err := engine.Open(opts)
	if err != nil { panic(err) }
	defer db.Close()

	// 2. 创建索引
	db.VCreate("products", distance.Cosine, 16, 200, distance.Float32, "english", nil)

	// 3. 添加数据
	db.VAdd("products", "p1", []float32{0.1, 0.2}, map[string]any{"category": "electronics"})

	// 4. 搜索
	results, _ := db.VSearch("products", []float32{0.1, 0.2}, 10, "category=electronics", 100, 0.5)
	fmt.Println("找到的 ID:", results)
}

🚀 Python 快速入门

此示例演示了完整的工作流程：创建索引、批量插入带有元数据的数据以及执行混合搜索（向量 + 关键词）。

安装客户端和工具：


pip install kektordb-client sentence-transformers

运行脚本：


from kektordb_client import KektorDBClient
from sentence_transformers import SentenceTransformer

# 1. 初始化
client = KektorDBClient(port=9091)
model = SentenceTransformer('all-MiniLM-L6-v2') 
index = "quickstart"

# 2. 创建索引（启用混合搜索）
try: client.delete_index(index)
except: pass
client.vcreate(index, metric="cosine", text_language="english")

# 3. 添加数据（批量）
docs = [
    {"text": "Go is efficient for backend systems.", "type": "code"},
    {"text": "Rust guarantees memory safety.", "type": "code"},
    {"text": "Pizza margherita is classic Italian food.", "type": "food"},
]

batch = []
for i, doc in enumerate(docs):
    batch.append({
        "id": f"doc_{i}",
        "vector": model.encode(doc["text"]).tolist(),
        "metadata": {"content": doc["text"], "category": doc["type"]}
    })

client.vadd_batch(index, batch)
print(f"已索引 {len(batch)} 个文档。")

# 4. 搜索（混合：向量 + 元数据过滤）
# 查找 "fast programming languages" 但仅在 'code' 类别中
query_vec = model.encode("fast programming languages").tolist()

results = client.vsearch(
    index,
    query_vector=query_vec,
    k=2,
    filter_str="category='code'", # 元数据过滤
    alpha=0.7 # 70% 向量相似性，30% 关键词排名
)

print(f"排名最高的结果 ID: {results[0]}")

🦜 LangChain 集成

KektorDB 包含一个用于 LangChain Python 的集成包装器，允许你直接将其连接到现有的 AI 管道。


from kektordb_client.langchain import KektorVectorStore

初步基准测试

基准测试在本地 Linux 机器（消费级硬件，Intel i5-12500）上执行。与 Qdrant 和 ChromaDB（通过 Docker 并使用主机网络）进行比较，以确保公平的基准。

警告： 数据库基准测试很复杂。这些结果反映了在我的开发机器上的特定场景（单节点、重读取、Python 客户端）。它们旨在展示 KektorDB 作为高性能嵌入式引擎的能力，而不是声称在生产分布式场景中的绝对优势。

1. NLP 工作负载（GloVe-100d，余弦）

40 万向量，float32 精度。 KektorDB 利用针对余弦相似性优化的 Go Assembly（Gonum）。在此特定设置中，它显示了非常高的吞吐量。

数据库	Recall@10	QPS（查询/秒）	索引时间（秒）
KektorDB	0.9664	1073	102.9s
Qdrant	0.9695	848	32.3s
ChromaDB	0.9519	802	51.5s

2. 计算机视觉工作负载（SIFT-1M，欧几里得）

100 万向量，float32 精度。 KektorDB 使用混合 Go/Rust 引擎（-tags rust）进行此测试。尽管 128d 向量有 CGO 开销，但性能与原生 C++/Rust 引擎相当。

数据库	Recall@10	QPS（查询/秒）	索引时间（秒）
KektorDB	0.9906	881	481.4s
Qdrant	0.998	845	88.5s
ChromaDB	0.9956	735	211.2s

关于索引速度的说明： KektorDB 目前在摄取方面比成熟的引擎更慢。这部分是因为它在插入时立即构建完全可查询的图，但主要是由于当前的单图架构。*优化大规模摄取（bulk）速度是下一个主要版本的绝对优先级。

TIP

性能优化："快速摄取，稍后优化"

如果你需要快速索引大型数据集，请使用较低的 ef_construction（例如 40）创建索引。这显著减少索引时间。然后可以启用具有更高质量目标（例如 200）的 Refine 后台进程。KektorDB 将在后台逐步优化图连接，同时保持可用于查询。

内存效率（压缩与量化）

KektorDB 通过量化和压缩提供显著的内存节省，使你能够将更大的数据集放入 RAM 中，而对性能或召回率的影响最小。

场景	配置	内存影响	QPS	Recall
NLP (GloVe-100d)	Float32	100%（基准）	~1073	0.9664
	Int8	~25%	~858	0.905
Vision (SIFT-1M)	Float32	100%（基准）	~881	0.9906
	Float16	~50%	~834	0.9770

（Rust 加速构建中的"智能分派"逻辑根据向量维度自动为每个操作选择最佳实现——Go、Gonum 或 Rust。纯 Go 版本的 float16 和 int8 作为可移植的回退。)

完整基准测试报告

API 参考（摘要）

有关所有功能和 API 端点的完整指南，请参阅 完整文档。

POST /vector/actions/search：混合向量搜索。
POST /vector/actions/import：高速批量加载。
POST /vector/indexes：创建和管理索引。
POST /graph/actions/link：创建语义关系。
POST /graph/actions/traverse：从特定节点 ID 开始的深度图遍历（N-Hop）。
POST /rag/retrieve：获取 RAG 的文本块。
GET /system/tasks/{id}：监控长时间运行的任务。
POST /system/save：手动快照。

🛣️ 路线图

KektorDB 是一个处于活跃开发中的年轻项目。

即将推出（v0.5.0）- 可扩展性和完整性更新

下一个重要里程碑侧重于突破 RAM 限制并提高数据一致性保证。

磁盘上的混合存储： 实现"可插拔"存储引擎。将 HNSW 图保留在 RAM（或 Int8）中以提高速度，但使用标准 I/O 或内存映射将完整向量数据移动到磁盘。
图事务完整性： 引入 原子批处理 以确保在创建双向链接或更新向量期间的数据一致性（类似于图层的 ACID 行为）。
反向索引： 自动管理入边以允许 O(1) 检索"指向节点 X"，这对于高效的图遍历和清理至关重要。
原生备份/恢复： 简单的 API，用于在不停止服务器的情况下将快照保存到 S3/MinIO/本地。

已规划（短期）

旨在使 KektorDB 为生产做好准备且更快的功能。

图过滤器： 将向量搜索与图拓扑过滤器结合（例如："仅在文档 X 的子节点中搜索"），由 Roaring Bitmaps 增强。
可配置 RAG 关系： 允许用户在 proxy.yaml 中定义自定义图遍历路径，而不是依赖硬编码的默认值。
SIMD/AVX 优化： 将纯 Go Assembly 优化（目前用于余弦）扩展到欧几里得距离和 Float16 操作，以最大化现代 CPU 上的吞吐量。
Roaring Bitmaps： 用 Roaring Bitmaps 替换当前基于地图的过滤器，以实现超快的元数据过滤器（例如 WHERE user_id = X）。
RBAC 和安全性： 实现基于角色的访问控制（Admin 与 Read-Only）以及针对多租户应用的更精细的粒度。
官方 TypeScript 客户端： 以更好地支持 AI JS/Node.js 生态系统。