内容
<p align="center">
<img src="velesdb_icon_pack/favicon/android-chrome-512x512.png" alt="VelesDB Logo" width="200"/>
</p>
<h1 align="center">
<img src="velesdb_icon_pack/favicon/favicon-32x32.png" alt="VelesDB" width="32" height="32" style="vertical-align: middle;"/>
</h1>
<h3 align="center">
您的AI代理会忘记一切。VelesDB解决了这个问题。
</h3>
<p align="center">
<strong>一个约9 MB的二进制文件。三个引擎。一个查询语言。零云依赖。</strong><br/>
<em>向量 + 图 + 列存储 — 在 <a href="docs/VELESQL_SPEC.md">VelesQL</a> 下统一</em>
</p>
<p align="center">
<a href="https://github.com/cyberlife-coder/VelesDB/actions/workflows/ci.yml"><img src="https://github.com/cyberlife-coder/VelesDB/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://app.codacy.com/gh/cyberlife-coder/VelesDB/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://img.shields.io/codacy/grade/58c73832dd294ba38144856ae69e9cf2?branch=main&label=code%20quality" alt="Codacy code quality"></a>
<a href="https://crates.io/crates/velesdb-core"><img src="https://img.shields.io/crates/v/velesdb-core.svg?cacheSeconds=3600" alt="Crates.io"></a>
<a href="https://crates.io/crates/velesdb-core"><img src="https://img.shields.io/crates/d/velesdb-core.svg" alt="Crates.io Downloads"></a>
<a href="https://pypi.org/project/velesdb/"><img src="https://img.shields.io/pypi/v/velesdb.svg?cacheSeconds=3600" alt="PyPI"></a>
<a href="https://www.npmjs.com/package/@wiscale/velesdb-sdk"><img src="https://img.shields.io/npm/v/@wiscale/velesdb-sdk.svg?cacheSeconds=3600" alt="npm"></a>
<a href="https://app.codacy.com/gh/cyberlife-coder/VelesDB/dashboard"><img src="https://img.shields.io/codacy/coverage/58c73832dd294ba38144856ae69e9cf2?branch=main" alt="Codacy coverage"></a>
<img src="https://img.shields.io/badge/tests-9k%2B_(Rust%2BTS%2BPy)-brightgreen" alt="Tests">
<a href="https://github.com/cyberlife-coder/VelesDB/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-VelesDB_Core_1.0-blue" alt="License"></a>
<a href="https://github.com/cyberlife-coder/VelesDB"><img src="https://img.shields.io/github/stars/cyberlife-coder/VelesDB?style=flat-square" alt="Stars"></a>
<a href="https://img.shields.io/badge/contributors-welcome-brightgreen"><img src="https://img.shields.io/badge/contributors-welcome-brightgreen" alt="Contributors Welcome"></a>
</p>
<p align="center">
<a href="https://github.com/cyberlife-coder/VelesDB/releases/latest">下载最新版本</a> •
<a href="#getting-started-in-60-seconds">快速开始</a> •
<a href="ARCHITECTURE.md">架构</a> •
<a href="ROADMAP.md">路线图</a> •
<a href="QUALITY_BAR.md">质量标准</a> •
<a href="https://velesdb.com/en/">文档</a> •
<a href="https://deepwiki.com/cyberlife-coder/VelesDB">DeepWiki</a>
</p>
---
> **当今每个AI代理都组合了三个数据库来存储记忆 — 向量用于“什么感觉相似”，图用于“什么有关联”，SQL用于“我确切知道什么”。这需要三个部署、三个配置、三种查询语言和一大堆胶水代码。**
>
> **VelesDB用单个Rust二进制文件取代了所有这些 — 比单个智能手机照片还小。**
---
## VelesDB背后的故事
VelesDB诞生于法国，源于一个简单的观察：**欧盟的数据主权是一个架构问题，而不是法律问题。**
美国云法案、FISA 702和爱国者法案为美国当局提供了多种法律途径，以获取任何美国公司持有的数据 — 无论服务器位于哪里。在`eu-west-1`上托管服务是一个延迟决策，而不是主权决策。欧盟的数据保护框架已被两次无效化（Schrems I，Schrems II），第三次挑战正在进行中。
对于在欧洲开发处理健康数据、法律文件或财务记录的AI代理的开发人员来说，典型的2026年堆栈会将嵌入发送到Pinecone（美国）、图发送到Neo4j Aura（美国）和元数据发送到AWS上的PostgreSQL（美国提供商）。所有这些都可以通过FISA令牌访问。
VelesDB完全消除了美国提供商在链条中的存在。一个Rust二进制文件，设计为本地优先。无需API密钥，无需云账户，无需数据处理器。您的数据存储在您控制的目录中 — 在您的笔记本电脑上，在您的服务器上，在您的司法管辖区内。
> [阅读完整故事：“我在一个法国数据库，因为云法案使得欧盟数据主权无法实现”](https://dev.to/wiscale-fr/i-built-a-database-in-france-because-the-cloud-act-makes-eu-data-sovereignty-impossible-5325)
---
## 为什么选择VelesDB？
| 今天（需要维护3个系统） | 使用VelesDB（1个二进制文件） |
|-------------------------------|------------------------|
| pgvector用于嵌入 | **向量引擎** — 450us p50端到端（10K/384D，WAL ON，召回率>=96%） |
| Neo4j用于知识图谱 | **图引擎** — MATCH子句，BFS/DFS |
| PostgreSQL/DuckDB用于元数据 | **类型化列存储 + 二级索引** — 过滤API比JSON扫描快130倍（100K行*¹） |
| 自定义胶水代码 + 3种查询语言 | **VelesQL** — 所有功能的一种语言 |
| 3个部署，3个配置，3个备份 | **约9 MB二进制文件** — 离线运行，支持空气隔离 |
> *¹ 列存储过滤API微基准测试，整数相等性：100K行比JSON扫描快130倍，10K行比JSON扫描快55倍 — 参见 [docs/BENCHMARKS.md § 6](docs/BENCHMARKS.md)。`SELECT ... WHERE`元数据过滤使用二级索引（如果可用），并使用自适应列存储有效载荷镜像进行扫描繁重的过滤（参见下面的[2]）。*
---
## 什么是VelesDB？
VelesDB是一个**本地优先的AI代理数据库**，它将三个引擎融合到一个约9 MB的二进制文件中：
| 引擎 | 功能 | 性能 |
|--------|-------------|-------------|
| **向量** | 语义相似性搜索（HNSW + AVX2/NEON SIMD） | **450us** p50端到端（384D，WAL ON，召回率>=96%） [1] |
| **图** | 知识关系（BFS/DFS，边属性） | 原生 **MATCH** 子句 |
| **列存储** | 结构化元数据过滤（类型化列） | **130倍** 比JSON扫描快 [2] |
> [1] 重现：`python benchmarks/velesdb_benchmark.py --recall` （Python SDK路径，10K/384D，WAL fsync开启，i9-14900KF参考机器）。参见 [docs/BENCHMARKS.md](docs/BENCHMARKS.md) 和 [CHANGELOG v1.13.0](CHANGELOG.md)。在v3.3.0上重新验证（2026-06-24）：p50 ≈ 360 µs（356–366 µs，跨两个干净的隔离运行），召回率@10 0.986–0.989 在Apple Silicon上 — [报告](benchmarks/results/report_3.3.0_apple-silicon_2026-06-24.json)（延迟是硬件特定的；规范的450 µs是i9-14900KF数字）。
> [2] 重现：`cargo bench -p velesdb-core --bench column_filter_benchmark`。参见 [docs/BENCHMARKS.md § 6](docs/BENCHMARKS.md) — 在100K行：列存储29.5 us vs JSON扫描3.84 ms（整数相等过滤）。列存储过滤API的微基准测试，现在通过每集合的有效载荷镜像提供`SELECT ... WHERE`元数据过滤，并支持JOIN执行；当可用时使用二级索引。
所有三个引擎都通过 **VelesQL** 查询 — 一种具有向量、图和列扩展的类似SQL的语言：
```sql
MATCH (doc:Document)-[:AUTHORED_BY]->(author:Person)
WHERE similarity(doc.embedding, $question) > 0.8
AND author.department = 'Engineering'
RETURN author.name, doc.title
ORDER BY similarity() DESC LIMIT 5
```
**内置代理内存SDK** 为AI代理提供语义、情景和过程内存 — 无需外部服务。
> **一个二进制文件。无云。无胶水代码。在服务器、浏览器、移动设备和桌面上运行。**
---
## 代理内存SDK
AI代理的内置内存 — 语义、情景和过程。无需外部服务。
### 楔形：`why()` — 连接的内存可以在重启后存活
大多数“代理内存”都是向量召回：它找到文本的相似之处。 VelesDB的高级`MemoryService`添加了缺失的部分 — 它通过连接内存与类型化的链接来回答为什么某件事情发生，从而可以访问与问题**没有共同点**的上下文。存储位于磁盘上，因此它跨会话工作。离线运行，无需API密钥，无需模型下载：
哪里 Mem0 和 Zep 是云耦合的协调器（Qdrant + Postgres上的服务网格，带有云LLM环），这是 **一个本地二进制文件** — 与LoCoMo QA上的Mem0处于同一层级（~57-58％ vs ~55％，中立基准），领先于Zep，但完全离线且具有可审计的`why()`证据路径。选择它是因为您的数据不能离开盒子。
```python
from velesdb import MemoryService # pip install velesdb
mem = MemoryService("./agent_memory") # 真正的磁盘存储；存活重启
reason = mem.remember("Robert is recovering from knee surgery")
mem.remember("Booked the aisle seat on Robert's flight", links=[(reason, "because")])
# 一个**新**进程，几周后，重新打开同一个存储并提问：
mem.why("why the aisle seat on Robert's flight?") # 遍历预订 → 原因 — recall()无法做到
```
记忆默认情况下是永久的；`forget(id)` 删除一个，`remember(…, ttl_seconds=…)` （或服务器范围的`VELESDB_MEMORY_DEFAULT_TTL`）使一个事实具有可持续的、存活重启的过期时间。
相同的楔形功能在 **Python** (`pip install velesdb`)、**Node** (`npm i @wiscale/velesdb-memory-node`) 和作为本地 **[MCP服务器](crates/velesdb-memory)** 中提供。
**四种可运行的方式来查看它** — 每种方式都展示了纯向量召回遗忘的部分以及`why()`恢复的部分：
| 演示 | 它显示什么 |
|---|---|
| [`why_across_sessions.py`](examples/agent_memory/why_across_sessions.py) | 原因在进程重启后存活 — 召回16个记忆的前5个，`why()`到达它 |
| [`why_magic_constant.py`](examples/agent_memory/why_magic_constant.py) | *为什么* 魔法常量具有它的值 — 一个商业原因与代码共享**没有字** |
| [`memory_builds_its_own_graph.py`](examples/agent_memory/memory_builds_its_own_graph.py) | 粘贴原始散文 → 本地模型自动连接图（无`relate()`），`why()`遍历到根本原因 |
| [`why_magic_constant.mjs`](crates/velesdb-node/examples/why_magic_constant.mjs) | 相同的引擎和楔形在 **Node** 绑定中 |
> **不是弱嵌入器技巧。** 在每个检索演示中，召回对原因**甚至在真正的语义嵌入器** （`ollama` / `all-minilm`）下保持盲目 — 原因由决策连接，而不是通过表面相似性，这正是向量存储无法遵循的。
---
对于底层构建块（情景、过程、TTL、快照）：
```python
from velesdb import Database, AgentMemory
db = Database("./agent_data")
memory = AgentMemory(db, dimension=384)
memory.semantic.store(1, "巴黎是法国的首都", embedding)
memory.episodic.record(1, "用户询问地理信息", timestamp, embedding)
memory.procedural.learn(1, "answer_geography", steps, embedding, confidence=0.8)
```
| 功能 | API |
|---------|-----|
| TTL / 自动过期 | `store_with_ttl()`, `auto_expire()` |
| 快照 / 回滚 | `snapshot()`, `load_latest_snapshot()` |
| 强化 | `reinforce(success=True)` — 6种策略（策略选择通过Rust API；Python使用`FixedRate`默认值） |
并且由于内存存储在与图和列存储相同的引擎中，因此一个VelesQL语句通过相似性、图上下文和会话回忆 — 在单个查询中测试端到端（[end-to-end tested](crates/velesdb-core/tests/bdd/graph_vector_hybrid.rs))：
```sql
SELECT memory.*, similarity() FROM agent_memory AS memory
WHERE vector NEAR $embedding
AND MATCH (ctx)-[:RELATES_TO]->(fact)
AND session_id = $current_session
ORDER BY similarity() DESC LIMIT 10
```
> **完整指南：** [docs/guides/AGENT_MEMORY.md](docs/guides/AGENT_MEMORY.md) | [源代码](crates/velesdb-core/src/agent/)
---
## 快速比较
| | **VelesDB** | Chroma | Qdrant | pgvector |
|---|---|---|---|---|
| **架构** | 统一向量 + 图 + 列存储 | 仅向量 | 向量 + 有效载荷 | PostgreSQL的向量扩展 |
| **元数据过滤** | **类型化列存储 [2] + 二级索引** | JSON 扫描 | JSON 有效载荷 | SQL（PostgreSQL） |
| **部署** | 嵌入式 / 服务器 / WASM / 移动端 | 服务器（Python） | 服务器（Rust） | 需要PostgreSQL |
| **二进制大小** | ~9 MB | ~500 MB（带依赖项） | ~50 MB | N/A（PG扩展） |
| **搜索延迟** | **450us** p50（10K/384D，WAL ON，召回率>=96%） | ~1-5ms | ~1-5毫秒 | ~5-20毫秒 |
| **图支持** | 原生（MATCH子句） | 无 | 无 | 无 |
| **查询语言** | VelesQL（SQL + NEAR + MATCH） | Python API | JSON API / gRPC | SQL + 运算符 |
| **浏览器（WASM）** | 是 | 否 | 否 | 否 |
| **移动端（iOS/Android）** | 是 | 否 | 否 | 否 |
| **离线 / 本地优先** | 是 | 部分 | 否 | 否 |
> *竞争对手延迟是公开基准和供应商文档中的典型范围。直接比较是近似的 — 架构不同（嵌入式与客户端-服务器，可持续与内存，召回级别）。运行您自己的基准测试以进行准确比较。*
> **VelesDB的甜点：** 当您需要在单个引擎中需要向量 + 图 + 结构化过滤，本地部署，或一个可以在任何地方运行的轻量级二进制文件。
>
> **不是最佳选择（尚不成熟）：** 如果您需要具有多节点分布式集群的托管云服务。
## 快速入门（60秒）
**最快的路径是 Python — 中位数小于 5 秒。** （[时间测量方法](docs/quickstart/timing-results.md)）
```bash
pip install velesdb
curl -O https://raw.githubusercontent.com/cyberlife-coder/VelesDB/main/examples/python/hello_velesdb.py
python hello_velesdb.py
```
预期输出：
```
Query: "tech"
score=1.000 Rust 1.89 发布说明
score=0.600 AI 生成的爵士乐：新浪潮
score=0.000 东京最好的拉面
Query: "tech + music"
score=0.990 AI 生成的爵士乐：新浪潮
score=0.707 Rust 1.89 发布说明
score=0.707 Miles Davis 唱片集
```
就这样 — 没有服务器，没有 JSON，没有嵌入模型。阅读 [25 行脚本](examples/python/hello_velesdb.py) 以了解发生了什么。从这里开始， [Agent Memory 指南](docs/guides/AGENT_MEMORY.md) 和 [VelesQL 规范](docs/VELESQL_SPEC.md) 是自然的下一步骤。
<details>
<summary><strong>其他安装路径 — Rust、Docker、WASM、REST 服务器</strong></summary>
**Cargo（Rust + REST 服务器）：**
```bash
cargo install velesdb-server velesdb-cli
```
**Docker（REST 服务器）：**
```bash
# 在本地构建镜像
git clone https://github.com/cyberlife-coder/VelesDB.git && cd VelesDB
docker build -t velesdb .
# 运行并持久化数据（命名卷）
docker run -d -p 8080:8080 -v velesdb_data:/data --name velesdb velesdb
# 验证是否正在运行
curl http://localhost:8080/health
```
容器内数据存储在 `/data` 目录中；命名卷 `velesdb_data` 在重启时保持持久。
**Docker Compose：**
```bash
git clone https://github.com/cyberlife-coder/VelesDB.git && cd VelesDB
docker-compose up -d
```
| 环境变量 | 默认值 | 描述 |
|---|---|---|
| `VELESDB_DATA_DIR` | `/data` | 数据存储目录 |
| `VELESDB_HOST` | `0.0.0.0` | 绑定地址 |
| `VELESDB_PORT` | `8080` | HTTP 端口 |
| `RUST_LOG` | `info` | 日志级别（`debug`、`info`、`warn`、`error`） |
**WASM（浏览器）：**
```bash
npm install @wiscale/velesdb-wasm
```
**安装脚本（Linux/macOS）：**
```bash
curl -fsSL https://raw.githubusercontent.com/cyberlife-coder/VelesDB/main/scripts/install.sh | bash
```
**安装脚本（Windows PowerShell）：**
```powershell
irm https://raw.githubusercontent.com/cyberlife-coder/VelesDB/main/scripts/install.ps1 | iex
```
**首次针对 REST 服务器的搜索（当 `velesdb-server` 在 :8080 上运行时）：**
```bash
curl -X POST http://localhost:8080/collections \
-d '{"name": "docs", "dimension": 4, "metric": "cosine"}' -H "Content-Type: application/json"
curl -X POST http://localhost:8080/collections/docs/points \
-d '{"points": [
{"id": 1, "vector": [1.0, 0.0, 0.0, 0.0], "payload": {"title": "AI Intro", "category": "tech"}},
{"id": 2, "vector": [0.0, 1.0, 0.0, 0.0], "payload": {"title": "ML Basics", "category": "tech"}},
{"id": 3, "vector": [0.0, 0.0, 1.0, 0.0], "payload": {"title": "History of Computing", "category": "history"}}
]}' -H "Content-Type: application/json"
curl -X POST http://localhost:8080/collections/docs/search \
-d '{"vector": [0.9, 0.1, 0.0, 0.0], "top_k": 2}' -H "Content-Type: application/json"
# {"results":[{"id":"1","score":0.994,"payload":{"title":"AI Intro","category":"tech"}}, ...]}
# 结果包装在 {"results":[...]} 中，点 ID 序列化为字符串。
# （统一的 POST /query 端点返回投影行，整数 ID。）
```
</details>
> 完整的安装指南：[docs/guides/INSTALLATION.md](docs/guides/INSTALLATION.md)
---
## 矢量引擎
本地 HNSW 索引，带有 SIMD 加速的距离内核。现代 x86_64 硬件上的毫秒级搜索。
### 端到端搜索延迟（规范）
| 指标 | 值 |
|--------|-------|
| 搜索 p50（10K，384D，WAL 开启） | **450 微秒** |
| SIMD 点积（768D，AVX2） | **21.7 纳秒** |
| Recall@10（平衡） | **98.8%** |
| 量化 | PQ（8–32 倍，取决于配置）、RaBitQ（32 倍）、SQ8（4 倍）\*³、二进制（32 倍）\*³ |
> \*³ 查询路径压缩来自 **PQ** 和 **RaBitQ** — 两者都集成到集合搜索路径中，包括重启。集合级 SQ8/二进制模式维护缓存，尚未有搜索路径读取它们（搜索保持全精度 f32 — 因此 SQ8 作为集合模式会 **增加** 内存）；它们的量化基元可编程使用。参见 [docs/guides/QUANTIZATION.md](docs/guides/QUANTIZATION.md)。
> **上述规范的出处：** 英特尔 Core **i9-14900KF** （x86_64，AVX2），`velesdb_benchmark.py`。 “端到端 / p50” = 完整生产路径（VelesQL → HNSW → **WAL 开启** → 有效载荷补水），查询集的中位数。 “索引仅”数据（下面的详细信息）排除 WAL 和有效载荷，在热缓存上运行 — 它们与端到端数字不可比较。每台机器的数字各不相同；新的 Apple-Silicon 测量值如下。
5 种搜索质量模式（快速 → 完美），自适应两阶段 ef，自动调谐。
<details>
<summary>详细基准和搜索模式</summary>
### HNSW 索引仅微基准（实验室级别）
> 下面的数字是 **索引仅** 微基准（无 WAL，无元数据获取，热缓存）。对于生产路径数字，请参见上面的“端到端搜索延迟（规范）” — **450µs p50** 在 10K/384D，召回率 ≥ 96%。
| 组件微基准 | 结果 | 如何重现 |
|-----------|--------|------------------|
| HNSW 搜索索引仅（5K/768D，k=10） | **55 微秒** | `cargo bench -p velesdb-core --bench hnsw_benchmark -- hnsw_search_latency` |
| SIMD 点积内核（768D，AVX2） | **21.7 纳秒** | `cargo bench -p velesdb-core --bench simd_benchmark` |
| Recall@10（准确模式） | **100%** | `cargo bench -p velesdb-core --bench recall_benchmark` |
| BM25 稀疏搜索索引仅（10K 文档，top-10） | **57.6 微秒** （16 倍于 v1.12 中的 956 微秒） | `cargo bench -p velesdb-core --bench sparse_benchmark -- top10_10k_corpus` |
#### 在 Apple M5 Pro 上交叉检查（ARM64 / NEON，18 核）- 2026-05-31 测量，v1.16.0
新鲜的 Apple Silicon 上的数字（单线程，隔离运行）。它们确认了引擎配置文件，并使每个数字的范围明确；它们不能代替上面的 x86_64/AVX2 参考数字。
| 实际测量内容 | 结果 | 基准 |
|---|---|---|
| HNSW 搜索，**索引仅** （10K/768D，k=10；无 WAL/有效载荷，热缓存） | 55 µs | `hnsw_benchmark -- hnsw_search_latency` |
| HNSW 搜索 **缩放** （top-10，索引仅） | 116 µs @100K · 128 µs @500K · 129 µs @1M | `scalability_benchmark` |
| **VelesQL 引擎** （解析→规划→执行→投影，10K） | 41 µs | `velesql_execution_benchmark` |
| **端到端 via PyO3/NumPy** （10K/384D，p50；Python 生产路径） | 55 µs（p99 99 µs） | `python benchmarks/velesdb_benchmark.py` |
| SIMD 距离，**NEON** （768D）：点积 / 欧几里得距离 / 余弦距离 | 31 / 35 / 47 纳秒 | `simd_benchmark` |
| BM25 全文搜索（10K，单/多词） | 23.5 / 71 µs | `bm25_benchmark` |
| 稀疏搜索（top-10，10K 语料库） | 29.8 µs | `sparse_benchmark -- top10_10k_corpus` |
| **Recall@10** （n=10K/128D，精确 kNN 基线；ef 扫描） | ef=96 → 97.4% · ef=160 → 99.8% · ef=512 → 100% | `recall_benchmark` |
> 上述召回率数字是 `recall_benchmark` 的内部 ef 扫描（96/160/512）— **与下面的产品“模式”表（快速/平衡/准确）** 区分开来。在此机器上，PyO3/NumPy 绑定开销可忽略：端到端 ≈ 索引仅 ≈ 55 µs。 **450 µs** 规范数字是 i9-14900KF 基准下的 WAL 开启生产条件；每台机器的结果不同。召回率使用真正的精确 kNN 地面实况，而不是近似自比较。
| 模式 | ef_search | Recall@10 | 用例 |
|------|-----------|-----------|----------|
| 快速 | 64 | 92.2% | 实时建议，类型提示 |
| 平衡（默认） | 128 | 98.8% | 生产搜索，RAG 管道 |
| 准确 | 512 | 100% | 评估，地面实况比较 |
*测量值来源于 `benchmarks/results/pr363_365_comparison.md`（i9-14900KF，64 GB DDR5，Windows 11，`--release`，`target-cpu=native`）。Windows 微基准有 5-10% 的噪声 — 预期一个范围，而不是一个点。*
</details>
### 距离度量
5 种具有 SIMD 加速的度量（AVX-512，AVX2，NEON；WASM 目前使用标量回退 — 计划使用 SIMD128 内核）：
| 度量 | 测量内容 | 用例 | SIMD 性能（768D）\*² |
|--------|-----------------|----------|------------------|
| **余弦** | 向量之间的角度（方向相似性） | 文本嵌入（BERT，OpenAI，Cohere），标准化向量 | 33 纳秒 |
| **欧几里得距离** | 直线距离（L2 范数） | 图像特征，空间数据，当幅度重要时 | 20 纳秒 |
| **点积** | 内积（投影） | 预标准化向量，最大内积搜索（MIPS） | 22 纳秒 |
| **汉明距离** | 二进制向量中的位差异 | 二进制嵌入，局部敏感哈希（LSH），指纹 | 36 纳秒 |
| **Jaccard** | 集重叠（交集 / 并集） | 稀疏向量，标签相似性，集合成员资格 | 35 纳秒 |
> \*² 768D 向量，AVX2 热缓存（与表格列标题匹配），参见 promise-contract.json 中的策略声明
```sql
-- 在集合创建时选择度量
CREATE COLLECTION docs (dimension = 768, metric = 'cosine');
CREATE COLLECTION images (dimension = 512, metric = 'euclidean');
CREATE COLLECTION fingerprints (dimension = 256, metric = 'hamming');
```
```sql
SELECT * FROM docs WHERE vector NEAR $v AND category = 'tech' LIMIT 5
```
- **SIFT1M 标准化 ANN 基准** - 在事实上标准的 INRIA TEXMEX 数据集上测量（1M × 128D 向量，L2 度量）。参见 [docs/BENCHMARKS.md § 11](docs/BENCHMARKS.md#11-sift1m--standard-ann-benchmark) 以了解方法论，数据集来源以及如何重现。
> **完整基准和方法论：** [docs/BENCHMARKS.md](docs/BENCHMARKS.md) | [velesdb-benchmarks 仓库](https://github.com/cyberlife-coder/velesdb-benchmarks) | **量化指南：** [docs/guides/QUANTIZATION.md](docs/guides/QUANTIZATION.md)
---
## 图引擎
带有 BFS/DFS 遍历、边标签和 Cypher 启发的 MATCH 查询的 属性图 - 与向量搜索集成。
```sql
-- 在一个语句中融合向量 + 图
MATCH (doc:Document)-[:AUTHORED_BY]->(author:Person)
WHERE similarity(doc.embedding, $question) > 0.8
RETURN author.name, doc.title
ORDER BY similarity() DESC LIMIT 5
```
跨集合 MATCH 带有 `@collection` 注解 - 遍历在主集合的边商店上运行；`@collection` 丰富了匹配节点的有效载荷来自另一个集合（它不是分布式跨图遍历）：
```sql
MATCH (p:Product@products)-[:STORED_IN]->(inv:Inventory@inventory)
RETURN p.name, inv.price, inv.stock
LIMIT 20
```
> **图模式指南：** [docs/guides/GRAPH_PATTERNS.md](docs/guides/GRAPH_PATTERNS.md)
---
## 列式存储引擎
类型化的列式存储 - DuckDB 和 ClickHouse 使用的方法。它的过滤 API **比 JSON 扫描快 130 倍**，在 100K 行（微基准：`cargo bench -p velesdb-core --bench column_filter_benchmark`）。
```
JSON 扫描：3.84 毫秒 @ 100K → 列式存储：29.5 微秒 @ 100K（快 130 倍）
```
列式存储引擎支持 `JOIN` 执行，并通过每个集合的有效载荷镜像提供 `SELECT ... WHERE` 元数据过滤 - 顶级标量有效载荷字段镜像到类型化的列中，过滤器编译为 RoaringBitmap 扫描。镜像自适应构建 - 仅在顺序扫描成本超过一次完整遍历后 - 因此点查找保持其快速路径；当它们覆盖过滤器时，次级索引仍会首先被咨询：
```sql
SELECT * FROM products
WHERE vector NEAR $query AND in_stock = true AND price < 50.0
LIMIT 10
```
---
## 用例
### AI 代理内存
您的代理需要记住对话，学习错误并回忆相关知识。 VelesDB 在单个嵌入式数据库中提供所有三种内存类型 - 无需 Redis，无需 Pinecone，无需 Neo4j。
```python
memory = AgentMemory(db, dimension=384)
memory.semantic.store(1, "用户偏好深色模式", embedding)
memory.episodic.record(2, "用户询问账单", timestamp, embedding)
memory.procedural.learn(3, "处理退款", steps, embedding, confidence=0.9)
```
### 带有元数据过滤的 RAG
仅向量搜索返回噪音。 VelesDB 将向量搜索与元数据过滤器（二级索引 + 预选/后过滤器）相结合，以消除无关结果。
```sql
SELECT * FROM docs
WHERE vector NEAR $query AND department = 'engineering' AND updated_at > NOW() - INTERVAL '30 days'
LIMIT 10
```
### 电子商务：查询中的向量 + 图 + 过滤器
查找与查询相似的产品，过滤价格/库存，并遍历共同购买关系 - 所有这些都在一个 VelesQL 语句中。
```sql
MATCH (product)-[:BOUGHT_TOGETHER]->(related)
WHERE similarity(product.embedding, $query) > 0.7
AND related.price < 200 AND related.in_stock = true
RETURN related.name, related.price
ORDER BY similarity() DESC LIMIT 20
```
### 桌面和移动 AI
无需服务器即可提供 AI 功能。 VelesDB 直接嵌入到 Tauri、iOS 和 Android 应用程序中。
| 平台 | 集成 | 二进制大小 |
|----------|-------------|-------------|
| 桌面（Tauri） | `tauri-plugin-velesdb` | ~9 MB |
| iOS（Swift） | UniFFI 绑定 | ~4 MB |
| Android（Kotlin） | UniFFI 绑定 | ~4 MB |
| 浏览器 | WASM 模块 | ~430 KB（压缩后） |
---
## 路线图
| 里程碑 | 状态 |
|-----------|--------|
| v1.0 — 核心引擎（向量 + 图 + VelesQL） | ✅ 已发布 |
| v1.5 — Python SDK，WASM，移动绑定 | ✅ 已发布 |
| v1.10 — 代理内存 SDK，混合搜索，量化 | ✅ 已发布 |
| v1.11 — 跨集合 MATCH，位图预过滤，CSR 图 | ✅ 已发布 |
| v1.12 — 跨集合 MATCH（图/BM25/HNSW 混合），冲刺 4 阶段 B（TS SDK 稳定性） | ✅ 已发布 |
| v1.13 — 预种子补救：BM25 O(1) 冷启动，稀疏搜索 16 倍加速，HNSW 预取，EXPLAIN/CBO 路由，VelesQL 窗口函数，SIFT1M 标准化工具 | ✅ 已发布 |
| v1.14 — DX 正确性：MSRV 1.89 对齐，Dockerfile 自动同步；**Haystack 2.x DocumentStore** 完成 LangChain + LlamaIndex + Haystack Python RAG 三元组 | ✅ 已发布 |
| v1.15 — ACT-R 阶段 1 程序化学习，`EXPLAIN ANALYZE` 中的 CBO 校准，Python 自动维度 + `SearchOptions` 生成器 | ✅ 已发布 |
| v1.16 — `audit-2026q2` 安全强化波（9 个 PR），一流嵌入适配器（Python + TypeScript），多架构 GHCR 镜像 | ✅ 已发布 |
| v1.17 — 带有 did-you-mean 建议的 VelesQL 错误提示，载入-WAL 撕裂尾部崩溃恢复，OpenAPI id-type 准确性 | ✅ 已发布 |
| v1.18 — 引擎工件重新对齐到 VelesDB 核心许可 1.0，代理内存对齐（Python/Tauri 绑定，TS 程序化召回） | ✅ 已发布 |
| v2.0.0 — 代理内存图维度 (`relate()` API + NEAR + MATCH 旗舰查询动词)，GraphFirst 锚定检索，PQ/RaBitQ 量化在重启时连线，耐用 TTL 在每个读取路径上，`GET /metrics` 默认情况下 | ✅ 已发布 |
> VelesDB 核心是源代码可用的（可读，可修改，可在 VelesDB 核心许可 1.0 下重新分发 - 不是 OSI 批准的许可；参见 [docs/LICENSING.md](docs/LICENSING.md)）。企业功能（分布式复制，托管云，RBAC）通过 [VelesDB Premium](https://velesdb.com) 单独提供。
> 我们每周发布一次。 [完整变更日志](CHANGELOG.md) | [贡献指南](CONTRIBUTING.md)
---
## 完整生态系统
| 领域 | 组件 | 安装 |
|--------|-----------|---------|
| **核心** | [velesdb-core](crates/velesdb-core) — 向量 + 图 + 列式存储 + VelesQL | `cargo add velesdb-core` |
| **服务器** | [velesdb-server](crates/velesdb-server) — REST API（48 端点，OpenAPI） | `cargo install velesdb-server` |
| **CLI** | [velesdb-cli](crates/velesdb-cli) — 交互式 VelesQL REPL | `cargo install velesdb-cli` |
| **Python** | [velesdb-python](crates/velesdb-python) — PyO3 绑定 + NumPy | `pip install velesdb` |
| **TypeScript** | [typescript-sdk](sdks/typescript) — Node.js 和浏览器 SDK | `npm install @wiscale/velesdb-sdk` |
| **WASM** | [velesdb-wasm](crates/velesdb-wasm) — 浏览器端向量搜索 | `npm install @wiscale/velesdb-wasm` |
| **代理内存（MCP）** | [velesdb-memory](crates/velesdb-memory) — 本地优先的 MCP 内存服务器（`why()`楔块） | `cargo install velesdb-memory` |
| **代理内存（节点）** | [velesdb-node](crates/velesdb-node) — 内存楔块的进程内 napi 绑定 | `npm install @wiscale/velesdb-memory-node` |
| **移动端** | [velesdb-mobile](crates/velesdb-mobile) — iOS（Swift）和 Android（Kotlin） | [构建说明](docs/guides/INSTALLATION.md#-mobile-iosandroid) |
| **桌面端** | [tauri-plugin](crates/tauri-plugin-velesdb) — Tauri v2 AI 驱动的应用 | `cargo add tauri-plugin-velesdb` |
| **LangChain** | [langchain-velesdb](integrations/langchain) — 官方向量存储 | [源码](integrations/langchain/README.md) |
| **LlamaIndex** | [llama-index-vector-stores-velesdb](integrations/llamaindex) — 文档索引 | [源码](integrations/llamaindex/README.md) |
| **Haystack** | [haystack-velesdb](integrations/haystack) — Haystack 2.x 文档存储 | [源码](integrations/haystack/README.md) |
| **迁移** | [velesdb-migrate](crates/velesdb-migrate) — 从 Qdrant，Pinecone，Supabase 迁移 | `cargo install velesdb-migrate` |
> **Python RAG 框架对齐**: VelesDB 提供了一个针对三个主要 Python RAG 框架的第一方连接器 - **LangChain** (`VectorStore`)，**LlamaIndex** (`VectorStoreIndex`) 和 **Haystack 2.x** (`DocumentStore`) - 因此，您可以用一个依赖项更改将 VelesDB 交换到任何现有的 RAG 管道中。
## VelesDB 工作原理
```
INSERT INDEX SEARCH
┌──────────┐ upsert ┌──────────────┐ build ┌──────────────┐
│ 您的应用 │──────────> │ WAL（追加） │────────> │ HNSW 图 │
│ │ │ + mmap 存储 │ │ （内存中） │
└──────────┘ └──────┬───────┘ └──────┬───────┘
│ │
┌──────▼───────┐ │ 搜索
│ 列存储 │ 过滤 ┌────▼─────────┐
│ （类型列） │────────> │ SIMD 距离 │
└──────────────┘ │（AVX-512/NEON）│
结果 └──────┬───────┘
┌──────────┐ top-k ┌──────────────┐ 排名 │
│ 您的应用 │<──────────│ 有效载荷 │<────────────────┘
│ │ │ 水分补充 │
└──────────┘ └──────────────┘
```
**关键设计选择：**
- **本地优先**：进程内或单个二进制文件 — 无网络跳转，无云依赖
- **内存映射存储**：操作系统管理 RAM 和磁盘之间的分页
- **WAL 持久性**：每个写入操作都会记录。默认情况下崩溃安全（`fsync` 模式）。批量插入期间延迟同步以提高吞吐量
- **列存储**：具有字符串 intern、RoaringBitmap tombstones、PostgreSQL 启发的自动清理的键控列
<details>
<summary>Docker 部署</summary>
```bash
# 在本地构建和运行
docker build -t velesdb .
docker run -d -p 8080:8080 -v velesdb_data:/data --name velesdb velesdb
curl http://localhost:8080/health
# 或使用 docker-compose（构建 + 自动重启）
docker-compose up -d
```
| 变量 | 默认值 | 描述 |
|---|---|---|
| `VELESDB_DATA_DIR` | `/data` | 数据存储目录 |
| `VELESDB_HOST` | `0.0.0.0` | 绑定地址 |
| `VELESDB_PORT` | `8080` | HTTP 端口 |
| `RUST_LOG` | `info` | 日志级别 |
容器以非 root 用户 `velesdb` 运行。通过命名卷 `velesdb_data` 持久保存数据。内置健康检查（`GET /health`）配置为 30 秒间隔。
</details>
<details>
<summary>API 参考（48 个 REST 端点）</summary>
| 类别 | 关键端点 |
|----------|--------------|
| **集合** | `POST /collections`, `GET /collections`, `GET/DELETE /collections/{name}` |
| **点** | `/collections/{name}/points`, `/collections/{name}/points/scroll`, `/collections/{name}/stream/insert`, `/collections/{name}/points/{id}/relations`, `/collections/{name}/points/{id}/ttl`, `/collections/{name}/relations` |
| **搜索** | `/collections/{name}/search`, `/collections/{name}/search/batch`, `/collections/{name}/search/hybrid`, `/collections/{name}/search/text`, `/collections/{name}/search/multi`, `/collections/{name}/search/ids`, `/collections/{name}/match` |
| **图** | `/collections/{name}/graph/edges`, `/collections/{name}/graph/edges/{id}`, `/collections/{name}/graph/edges/count`, `/collections/{name}/graph/traverse`, `/collections/{name}/graph/traverse/stream`, `/collections/{name}/graph/traverse/parallel`, `/collections/{name}/graph/nodes`, `/collections/{name}/graph/nodes/{id}/degree`, `/collections/{name}/graph/nodes/{id}/edges`, `/collections/{name}/graph/nodes/{id}/payload`, `/collections/{name}/graph/search` |
| **索引** | `GET/POST /collections/{name}/indexes`, `DELETE /collections/{name}/indexes/{label}/{property}`, `/collections/{name}/index/rebuild` |
| **VelesQL** | `/query`, `/aggregate`, `/query/explain` |
| **管理员** | `/health`, `/ready`, `/metrics`, `/guardrails`, `/collections/{name}/stats`, `/collections/{name}/config`, `/collections/{name}/flush`, `/collections/{name}/analyze`, `/collections/{name}/empty`, `/collections/{name}/sanity` |
> **完整 API 参考：** [docs/reference/api-reference.md](docs/reference/api-reference.md) | **OpenAPI 规范：** [docs/openapi.yaml](docs/openapi.yaml)
</details>
<details>
<summary>安全性</summary>
- **API 密钥身份验证** — 通过 `VELESDB_API_KEYS` 环境变量进行 Bearer 令牌身份验证
- **TLS（HTTPS）** — 通过 rustls 内置（`VELESDB_TLS_CERT` / `VELESDB_TLS_KEY`）
- **正常关闭** — SIGTERM 触发连接排水 + WAL 刷新。零数据丢失
- **健康端点** — `GET /health` 和 `GET /ready` 始终公开
> [docs/guides/SERVER_SECURITY.md](docs/guides/SERVER_SECURITY.md)
</details>
---
## 演示和示例
```bash
cd examples/ecommerce_recommendation && cargo run --release
```
| 演示 | 描述 | 技术 |
|------|-------------|------|
| [电子商务推荐](examples/ecommerce_recommendation/) | 矢量 + 图 + 列存储（5K 产品） | Rust |
| [velesdb-memory](crates/velesdb-memory/) | MCP 内存服务器 — 图表回答做出决策的原因 | Rust |
| [rag-pdf-demo](demos/rag-pdf-demo/) | PDF 文档问答与 RAG | Python, FastAPI |
| [tauri-rag-app](demos/tauri-rag-app/) | 桌面 RAG 应用程序 | Tauri v2, React |
| [wasm-browser-demo](examples/wasm-browser-demo/) | 浏览器内矢量搜索 | WASM, 普通 JS |
| [mini_recommender](examples/mini_recommender/) | 产品推荐 | Rust |
---
<details>
<summary>研究基础</summary>
VelesDB 的性能建立在同行评审的研究基础上 — 以下六种技术中有五种已在引擎中实施并投入生产；双精度（VSAG）作为公共 API 与基准测试工具一起发布，引擎集成已跟踪。
| 技术 | 论文 | 状态 |
|-----------|-------|--------|
| HNSW | [Malkov & Yashunin, 2016](https://arxiv.org/abs/1603.09320) | 已投入生产 |
| VAMANA / DiskANN | [Subramanya et al., 2019](https://arxiv.org/abs/1907.05024) | 已投入生产（alpha pruning） |
| RaBitQ | [Gao & Long, 2024](https://arxiv.org/abs/2405.12497) | 已投入生产（查询路径，包括重启） |
| 双精度（VSAG） | [Xu et al., 2025](https://arxiv.org/abs/2503.17911) | 公共 API + 基准测试；引擎集成已跟踪 |
| 软件流水线 | [Jiang et al., 2025](https://arxiv.org/abs/2505.07621) | 已投入生产（搜索流水线） |
| PDX 布局 | [Pirk et al., 2025](https://arxiv.org/abs/2503.04422) | 已投入生产（通过 `ANALYZE` 重排序的列布局） |
</details>
## 贡献
```bash
git clone https://github.com/cyberlife-coder/VelesDB.git && cd VelesDB
cargo test --workspace --features persistence,gpu,update-check --exclude velesdb-python -- --test-threads=1
```
寻找一个起点？查看标记为 [`good first issue`](https://github.com/cyberlife-coder/VelesDB/labels/good%20first%20issue) 的问题。
---
## 使用 VelesDB 的项目
| 项目 | 用例 |
|---------|----------|
| [WPLink](https://wplink.ai) | AI 驱动的语义分析，用于查找和应用 WordPress 站点的内部链接机会 |
| *您的项目在此* | [获取列表 →](mailto:contact@wiscale.fr?subject=VelesDB%20Showcase) |
[](https://github.com/cyberlife-coder/VelesDB)
在生产环境中使用 VelesDB？打开 [GitHub Discussion](https://github.com/cyberlife-coder/VelesDB/discussions) 或发送电子邮件至 [contact@wiscale.fr](mailto:contact@wiscale.fr) 以获取特色。您的反馈塑造了路线图。
---
## 许可证
VelesDB 核心许可证 1.0（基于 ELv2）。免费用于生产环境，包括商业应用程序。两个限制：不提供 VelesDB 作为托管/管理的数据库服务，不构建竞争性数据库产品。 [阅读完整许可证](LICENSE)。
---
<p align="center">
<strong>VelesDB</strong> — 面向 AI 代理的本地知识引擎<br/>
<a href="https://velesdb.com">velesdb.com</a> • <a href="https://github.com/cyberlife-coder/VelesDB">GitHub</a>
</p>
连接信息
猜你喜欢
暂无推荐服务器