duxxdb

<div align="center"> <img src="assets/duxxdb-banner.svg" alt="DuxxDB — 面向 AI 智能体的数据库" width="860"> <h1></h1> 混合检索（向量 + BM25 + 结构化）、面向智能体的原生数据类型（`MEMORY` / `TOOL_CACHE` / `SESSION`）以及从一个 Rust 代码库部署嵌入或服务器，支持 RESP2/3、gRPC 和 MCP 协议。 [](https://github.com/bankyresearch/duxxdb/actions/workflows/ci.yml) [](LICENSE) [](https://www.rust-lang.org/) [](https://github.com/bankyresearch/duxxdb/actions/workflows/ci.yml) [](docs/PROJECT_OVERVIEW.md) [](docs/) [**安装**](#安装) · [**快速开始**](#快速开始) · [**为什么选择 DuxxDB**](#为什么选择DuxxDB) · [**功能**](#功能) · [**集成**](#集成) · [**FAQ**](docs/FAQ.md) · [**架构**](#架构) · [**基准测试**](#基准测试) · [**路线图**](docs/ROADMAP.md) · [**贡献**](CONTRIBUTING.md) </div> --- ## 概要 ```bash docker run -d --name duxxdb -p 6379:6379 ghcr.io/bankyresearch/duxxdb:latest redis-cli -p 6379 REMEMBER alice "我丢失了钱包，在咖啡馆" redis-cli -p 6379 RECALL alice "钱包" 3 # 1) 1) (integer) 1 # 2) "0.032787" # 3) "我丢失了钱包，在咖啡馆" ``` DuxxDB 支持 RESP 协议 — `redis-cli`、`valkey-cli`、`redis-rs`、`node-redis`、`go-redis` 均可无缝使用。现在切换到 [快速开始](#快速开始) 页面，了解 Python、gRPC 或 MCP 的使用方法。 > **状态：** 自托管测试版 — 功能已完成，达到第 7 阶段，具备身份验证 + RBAC、原生 TLS、健康检查、Prometheus、优雅关闭、持久化、mTLS 客户端验证、可配置协议限制、离线快照/恢复、基于重要性的驱逐和删除安全召回（图压缩）。参见 [路线图](docs/ROADMAP.md)。 > > 多租户、控制平面、复制/高可用性和云控制台位于 **DuxxDB Cloud**（一个独立的管理服务产品）；此仓库是 Apache-2.0 单节点引擎。参见 [LICENSING.md](LICENSING.md)。 --- ## Duxx 堆栈 DuxxDB 是 **存储引擎** 部分。**框架** 部分是 [**duxx-ai**](https://github.com/bankyresearch/duxx-ai) — 一个 Apache 2.0 Python SDK，用于构建、微调、编排和治理 AI 智能体： ``` ┌─ duxx-ai (Python) ────────────────────────────────────┐ │ 智能体 · 图 · 团队 · 工具 · 内存 · 守卫 │ │ RBAC · 可观察性 · 微调 · 自适应路由 │ └────────────────────┬──────────────────────────────────┘ │ 使用（内存 / 跟踪 / 提示 / 评估 / 成本） ┌────────────────────▼──────────────────────────────────┐ │ DuxxDB（Rust）— 存储 + 检索 + 可观察性 │ │ 混合召回 · TLS · MCP · gRPC · RESP · Parquet │ └───────────────────────────────────────────────────────┘ ``` | 您正在构建... | 使用 | |---|---| | 智能体本身（Python） | [`duxx-ai`](https://pypi.org/project/duxx-ai/) — 智能体、团队、工具、治理 | | 存储/检索层 | **`duxxdb`**（此仓库）— 单个二进制文件，六个客户端接口 | | 两者结合 | `pip install duxx-ai duxxdb` — 完整的 Apache 2.0 智能体堆栈 | **为什么选择一个堆栈，两个项目？** Rust 提供了亚毫秒级混合召回 + TLS + 多平台二进制文件。Python 提供了智能体开发人员所需的便利性 — 类型化基元、LLM SDK、工具、治理 — 而无需将 C++ 部署的复杂性带入存储层。每个部分都发挥了其优势；它们独立发布，遵循语义版本控制。 --- ## 为什么选择 DuxxDB？ 典型的智能体堆栈今天将三个数据库组合在一起： ``` ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ Redis │ │ Qdrant │ │ Postgres │ │ 会话 │ │ 向量 │ │ 事实/用户 │ │ ~0.5ms │ │ ~10ms │ │ ~1-5ms │ └────┬─────┘ └────┬─────┘ └──────┬───────┘ ▼ ▼ ▼ 3 次往返/回合 3 个客户端库 · 3 套凭证 它们之间的一致性问题 ``` 这种设计带来了三个方面的开销： | 开销 | 成本 | |---|---| | **延迟** | 3 次跳转 = 300 µs–3 ms（在任何工作开始之前）。语音机器人在其 200 ms 预算内会受到影响。 | | **一致性** | 用户消息、其嵌入和会话元数据分别存储在三个不同的存储中。 | | **胶水代码** | 跨存储事务、重试、漂移 — 智能体可靠性的沉默杀手。 | **DuxxDB 将三者合并为一个引擎**，具备一流的智能体基元、单个混合查询计划（向量 ANN + BM25 + 结构化过滤器融合，通过 Reciprocal Rank Fusion）和六个集成接口，全部来自一个代码库。纯 Rust，无 GC 暂停。 --- ## 功能 <table> <tr><td valign="top" width="50%"> #### 混合检索 - HNSW 向量 ANN（[`hnsw_rs`](https://crates.io/crates/hnsw_rs)） - BM25 全文检索（[`tantivy`](https://github.com/quickwit-oss/tantivy)） - 结构化过滤器 - **所有三个功能融合在一个查询计划中**（RRF，k=60） #### 面向智能体的原生数据类型 - `MEMORY` — 带有 **重要性衰减** 的粘性长期召回 - `TOOL_CACHE` — 精确 + **语义近似命中** 查找（余弦 ≥ 0.95） - `SESSION` — 带有惰性驱逐的滑动 TTL KV - 所有一流类型 — 而不是通用表格 </td><td valign="top"> #### 六个集成接口 - **嵌入式** Rust crate - **Python** 轮（PyO3，abi3-py38，一个适用于 3.8–3.13 的轮） - **Node / TypeScript** 原生模块（napi-rs v2） - **RESP2/3** TCP 服务器（与 Valkey/Redis 兼容） - **gRPC**，带有流式 `Subscribe`（tonic） - **MCP stdio**，适用于 Claude / GPT / Cline 智能体 #### 生产强化（第 6.1 + 6.2 阶段） - 令牌身份验证（`--token` / `DUXX_TOKEN`） - 基于角色的 RESP API 密钥（`DUXX_AUTH_KEYS`），具有 read/write/admin 角色 - JSON 行安全审计日志（`DUXX_AUDIT_LOG`） - **原生 TLS**，适用于 RESP + gRPC（rustls） - **mTLS 客户端验证**，使用 `--tls-client-ca` - **可配置的 RESP 资源限制**（`DUXX_MAX_*`） - 连接和每个连接的命令速率上限 - Prometheus `/metrics` + `/health` - gRPC `grpc.health.v1.Health` 协议 - 优雅关闭排空 - **内存上限 + 基于重要性的驱逐** - 离线 `duxx-snapshot create/verify/restore` - Apache Parquet 冷层导出 </td></tr> </table> --- ## 安装 根据您的平台选择安装方式。 | 平台 | 命令 | 详情 | |---|---|---| | 🐳 **Docker**（任意操作系统） | `docker run -p 6379:6379 ghcr.io/bankyresearch/duxxdb:latest` | [Docker 指南](docs/INSTALLATION.md#docker-single-command) | | 🐳 **Docker Compose**（生产环境） | `cd packaging/docker && cp .env.example .env && docker compose up -d` | [Compose 指南](docs/INSTALLATION.md#docker-compose-production-grade) | | 🐧 **Debian / Ubuntu** | `sudo apt install ./duxxdb_*.deb` | [.deb 安装](docs/INSTALLATION.md#linux--debian--ubuntu-apt-deb) | | 🐧 **RHEL / Fedora / Rocky** | `curl -fsSL …/install.sh \| sudo sh` + systemd 单元 | [.rpm 安装](docs/INSTALLATION.md#linux--rhel--fedora--rocky--alma-dnf-rpm) | | 🍏 **macOS** | `brew install bankyresearch/duxxdb/duxxdb` | [Homebrew](docs/INSTALLATION.md#macos--homebrew) | | 🐚 **一键安装** | `curl -fsSL …/install.sh \| sh` | [安装程序](docs/INSTALLATION.md#linux--macos--one-line-installer) | | 🪟 **Windows** | 从 [Releases](https://github.com/bankyresearch/duxxdb/releases) 下载 zip | [Windows 指南](docs/INSTALLATION.md#windows--zip-download-manual) | | ☸ **Kubernetes** | `kubectl apply -f packaging/k8s/duxxdb.yaml` | [k8s 指南](docs/INSTALLATION.md#kubernetes) | | 🐍 **Python** | `pip install …`（本地构建的轮） | [Python](docs/INSTALLATION.md#embed--python-wheel) | | 📦 **Node / TS** | `npm install …`（本地构建的 `.node`） | [Node](docs/INSTALLATION.md#embed--node--typescript) | | 🦀 **Rust crate** | `cargo add duxx-memory --git …` | [Cargo](docs/INSTALLATION.md#embed--rust-crate) | | 📐 **从源码** | `cargo build --release --workspace` | [源码](docs/INSTALLATION.md#from-source-any-os) | → 完整的平台安装 + 卸载 + 服务控制速查表：**[docs/INSTALLATION.md](docs/INSTALLATION.md)**。 --- ## 快速开始 #### 从 redis 客户端（任意语言） ```bash redis-cli -p 6379 127.0.0.1:6379> REMEMBER alice "我想退款，订单 #9910" (integer) 1 127.0.0.1:6379> RECALL alice "退款" 5 1) 1) (integer) 1 2) "0.032787" 3) "我想退款，订单 #9910" 127.0.0.1:6379> PSUBSCRIBE memory.* ``` #### 从 Python ```python import duxxdb store = duxxdb.MemoryStore(dim=32) store.remember(key="alice", text="我丢失了钱包") hits = store.recall(key="alice", query="钱包", k=5) for hit in hits: print(hit.id, hit.score, hit.text) ``` #### 从 Node / TypeScript ```ts import { MemoryStore } from "duxxdb"; const store = new MemoryStore({ dim: 32 }); store.remember("alice", "我丢失了钱包"); console.log(store.recall("alice", "钱包", 5)); ``` #### 嵌入在 Rust 应用中 ```rust use duxx_memory::MemoryStore; use duxx_embed::HashEmbedder; use std::sync::Arc; let store = MemoryStore::new(Arc::new(HashEmbedder::new(32))); store.remember("alice", "我丢失了钱包", None)?; let hits = store.recall("alice", "钱包", 5)?; ``` #### 通过 gRPC（任意 tonic / grpcio / grpc-go 客户端） ```bash grpcurl -plaintext -d '{"key":"alice","text":"我丢失了钱包"}' \ localhost:50051 duxx.v1.Duxx/Remember grpcurl -plaintext -d '{"key":"alice","query":"钱包","k":5}' \ localhost:50051 duxx.v1.Duxx/Recall ``` #### 通过 MCP（Claude Desktop / Cline / 任意 MCP 智能体） ```jsonc // claude_desktop_config.json { "mcpServers": { "duxxdb": { "command": "/usr/local/bin/duxx-mcp" } } } ``` → 全面的表面级指南： **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)**。 → 将其集成到真正的智能体中（聊天机器人/语音机器人/迁移）： **[docs/INTEGRATION_GUIDE.md](docs/INTEGRATION_GUIDE.md)**。 --- ## 架构 ``` 智能体（聊天机器人/语音机器人/自主） │ ┌─────────────────────┴─────────────────────┐ ▼ ▼ 嵌入式 ┌───────────────┐ duxx-memory（库） │ duxx-server │ RESP TCP │ ├───────────────┤ ▼ │ duxx-grpc │ gRPC + 流式 Python / Node 绑定 ├───────────────┤ │ duxx-mcp │ 标准输入 JSON-RPC └───────┬───────┘ │ ┌───────────────────────┼──────────────────┐ │ │ │ ▼ ▼ ▼ duxx-memory duxx-reactive duxx-coldtier MEMORY / TOOL_CACHE （变更总线） （Parquet） / SESSION + 衰减 │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ duxx-query duxx-index duxx-storage duxx-embed （RRF + tantivy + redb / 哈希 / OpenAI / 混合） hnsw_rs 内存 Cohere ``` 21 个 Rust 仓库，全部采用 Apache 2.0 许可。完整的设计： **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**。 --- ## 基准测试 混合召回，k = 10，单线程，调试发布，玩具 32 维嵌入器。重现：`cargo bench -p duxx-bench`。 | 语料库 | 中位数召回 | 吞吐量 | vs 10 ms 目标 | |---:|---:|---:|---:| | 100 文档 | **123 µs** | 8.1 k QPS | 81× 余量 | | 1,000 文档 | **166 µs** | 6.0 k QPS | 60× 余量 | | 10,000 文档 | **373 µs** | 2.7 k QPS | 27× 余量 | 即使在本地 gRPC 往返（Python 客户端，维度 128，N=1k）： 召回 p50 = **2.4 ms** — **30× 比嵌入式 LanceDB 快**，在相同工作负载下。完整数字 + 警告： [`bench/comparative/README.md`](bench/comparative/README.md)。 --- ## DuxxDB 对比 | | 向量 | BM25 | 结构化 | 嵌入式 | 服务器 | 反应式 | 智能体基元 | MCP | |---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:| | **Redis** | ✗ | ✗ | ⚠ | ✗ | ✅ | ✅ | ✗ | ✗ | | **Valkey** | ⚠ (mod) | ⚠ (mod) | ⚠ | ✗ | ✅ | ✅ | ✗ | ✗ | | **Qdrant** | ✅ | ⚠ | ⚠ | ✗ | ✅ | ⚠ | ✗ | ✗ | | **Pinecone** | ✅ | ✗ | ⚠ | ✗ | ✅ | ✗ | ✗ | ✗ | | **Milvus** | ✅ | ⚠ | ✅ | ✗ | ✅ | ✗ | ✗ | ✗ | | **Weaviate** | ✅ | ✅ | ✅ | ✗ | ✅ | ✗ | ✗ | ✗ | | **pgvector** | ✅ | ⚠ | ✅ | ✗ | ✅ | ⚠ | ✗ | ✗ | | **LanceDB** | ✅ | ⚠ | ✅ | ✅ | ⚠ | ✗ | ✗ | ✗ | | **ChromaDB** | ✅ | ✗ | ⚠ | ✅ | ✅ | ✗ | ⚠ | ✗ | | **DuxxDB** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 完整说明 + 何时选择每种：[docs/PROJECT_OVERVIEW.md § 8](docs/PROJECT_OVERVIEW.md#8-competitive-landscape). --- ## 文档 | 文档 | 使用场景 | |---|---| | [INSTALLATION.md](docs/INSTALLATION.md) | 选择每种操作系统的安装方法 | | [USER_GUIDE.md](docs/USER_GUIDE.md) | 在任意 6 种语言中编写客户端代码 | | [INTEGRATION_GUIDE.md](docs/INTEGRATION_GUIDE.md) | 将 DuxxDB 集成到聊天机器人、语音机器人或自主智能体（附图） | | [DUXX_STACK_INTEGRATION.md](docs/DUXX_STACK_INTEGRATION.md) | **duxx-ai**（Python 框架）如何插入 DuxxDB — 后端协议、API 契约、部署方式 | | [DRAGONFLY_COMPARISON.md](docs/DRAGONFLY_COMPARISON.md) | 企业可靠性路线图，灵感来自 DragonflyDB 的运维模型 | | [FAQ.md](docs/FAQ.md) | “DuxxDB 是否适合我？” — 何时使用，何时不用，框架支持，迁移 | | [PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md) | 向队友推介 DuxxDB / 进行构建与购买决策 | | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | 在贡献之前了解内部机制 | | [ROADMAP.md](docs/ROADMAP.md) | 了解已发布和计划的功能 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 开启您的第一个 PR | --- ## 仓库布局 ``` duxxdb/ ├── Cargo.toml 工作区根目录（21 个 crate） ├── Dockerfile 多阶段、多架构镜像 ├── packaging/ Postgres 风格的安装程序 │ ├── docker/ docker-compose.yml + .env.example + prometheus.yml │ ├── systemd/ duxxdb.service + duxx.env │ ├── debian/ .deb postinst / prerm / postrm │ ├── homebrew/ duxxdb.rb 公式 │ ├── k8s/ StatefulSet + Service + ConfigMap │ └── scripts/install.sh curl-pipe 安装程序 ├── crates/ │ ├── duxx-core/ 模式 · 值 · 错误 │ ├── duxx-storage/ 存储特征 + redb / 内存后端 │ ├── duxx-index/ tantivy BM25 + hnsw_rs HNSW (+ 整理） │ ├── duxx-query/ RRF，混合召回 │ ├── duxx-memory/ MEMORY / TOOL_CACHE / SESSION + 衰减 + 整理 │ ├── duxx-reactive/ 变更总线发布/订阅 │ ├── duxx-embed/ 哈希 + OpenAI + Cohere 嵌入器 │ ├── duxx-trace/ 智能体跟踪存储（第 7.1 阶段） │ ├── duxx-prompts/ 版本提示注册表（第 7.2 阶段） │ ├── duxx-datasets/ 版本评估数据集（第 7.3 阶段） │ ├── duxx-eval/ 评估运行 + 回归（第 7.4 阶段） │ ├── duxx-replay/ 确定性智能体重放（第 7.5 阶段） │ ├── duxx-cost/ 代币 + 成本分类账（第 7.6 阶段） │ ├── duxx-docs/ 文档智能层（摄入→引用） │ ├── duxx-token/ 签名短期凭证（JWT） │ ├── duxx-server/ RESP2/3 守护进程 + 身份验证 + Prometheus │ ├── duxx-mcp/ MCP 标准输入 JSON-RPC 服务器 │ ├── duxx-grpc/ tonic gRPC 守护进程（流式订阅） │ ├── duxx-coldtier/ Apache Parquet 导出器 │ ├── duxx-cli/ shell + 聊天机器人内存示例 │ └── duxx-bench/ 基准测试 ├── bindings/ │ ├── python/ PyO3 + maturin abi3 轮 │ └── node/ napi-rs v2（工作区排除） ├── bench/comparative/ DuxxDB 与 LanceDB / Redis / Qdrant / pgvector └── docs/ 安装 · 用户指南 · 架构 · … ``` --- ## 贡献 我们欢迎 PR。 三个原则： 1. **选择一个开放的盒子**，在 [ROADMAP.md](docs/ROADMAP.md) 中 — 或 [问题跟踪器](https://github.com/bankyresearch/duxxdb/issues) 中标记为 `good first issue` / `help wanted` 的任何问题。 2. **测试 + clippy 保持绿色**（`cargo test --workspace` + `cargo clippy --workspace -- -D warnings`）。 3. **不要将基准测试降低 > 5%**（`cargo bench -p duxx-bench`）。 完整的指南，包括如何在本地运行测试矩阵、提交消息样式和 PR 审查流程： **[CONTRIBUTING.md](CONTRIBUTING.md)**。 本项目遵循项目 [行为准则](CODE_OF_CONDUCT.md)。 --- ## 安全 请通过 [SECURITY.md](SECURITY.md) 中的流程**私下**报告漏洞，而不是通过公开的问题。 --- ## 许可 **[Apache License 2.0](LICENSE)** — 整个存储库中的引擎均被许可使用。 可以自由使用、嵌入、自行托管，甚至作为服务运行。 无每座许可费，无功能门控，无过期密钥。 DuxxDB 是 **开放核心**：可选的管理服务层 — 多租户、控制平面、复制/高可用性和云控制台 + 工作室 — 是一个单独的源代码可用产品，**DuxxDB Cloud**。此存储库中没有任何内容依赖于它，它永远不会依赖。 参见 **[LICENSING.md](LICENSING.md)**。 第三方依赖通知，适用于分发所需，维护在 [NOTICE](NOTICE). --- <div align="center"> **[⬆ 返回顶部](#duxxdb)** 由 [Bankatesh Choudhary](https://github.com/bankyresearch) 构建 </div>