# remdb-ai 向量数据库需求
[TOC]
## ✅ 用户故事与验收条件
### **阶段一：最小可行产品（MVP）**
**核心存储引擎**
#### **US-101：AI原生向量数据模型**
作为AI应用开发者，我希望向量是与INT、STRING同等的基础数据类型，支持直接在CREATE TABLE中定义维度、距离度量及量化算法，以便于构建原生向量数据库应用。
**验收条件：**
1. 能够使用CREATE TABLE语句创建包含向量字段的表，语法为：CREATE TABLE table_name (id INT PRIMARY KEY, vec VECTOR(768) WITH DISTANCE=L2, meta STRING);
2. 支持至少3种距离度量（Cosine, L2, IP）
3. 支持至少2种量化算法（SQ, PQ）
4. 向量字段支持基本的CRUD操作
**技术约束：**
- 向量维度必须在创建表时指定，不支持动态修改
- 单向量最大维度：4096
**测试场景：**
- 功能测试：执行CREATE TABLE语句创建向量表，验证语法正确性
- 功能测试：对向量字段执行INSERT、SELECT、UPDATE、DELETE操作，验证结果正确性
- 性能测试：插入100万条向量数据，验证插入性能
---
#### **US-102：混合查询支持**
作为AI应用开发者，我希望向量相似度搜索能与标量过滤、范围查询无缝组合，无需应用层拼接，以便实现复杂查询逻辑。
**验收条件：**
1. 支持向量相似度搜索与标量过滤的组合查询，语法为：SELECT * FROM docs WHERE VECTOR_SIMILAR(embedding, $query_vec) AND category = 'tech' LIMIT 10;
2. 支持向量相似度搜索与范围查询的组合，语法为：SELECT * FROM docs WHERE VECTOR_SIMILAR(embedding, $query_vec) AND timestamp > '2023-01-01' LIMIT 10;
3. 混合查询性能损耗<30%（相较于纯向量查询）
**测试场景：**
- 功能测试：执行多种组合查询，验证结果正确性
- 性能测试：比较纯向量查询与混合查询的性能差异，验证性能损耗<30%
---
#### **US-103：工业级单机存储引擎**
作为系统架构师，我希望数据库具备ACID事务支持、预写日志和检查点机制，以保证数据的可靠性和持久性。
**验收条件：**
1. 支持事务语法：BEGIN TRANSACTION; INSERT INTO docs VALUES (...); INSERT INTO docs VALUES (...); COMMIT;
2. 事务中任一操作失败，整个事务回滚，数据保持一致性
3. 系统崩溃后重启，已提交数据不丢失
4. 所有数据修改先写入WAL，再更新内存和主存储
5. 支持至少2种WAL刷盘策略：per write 和 per N seconds
6. 后台自动创建检查点，检查点创建不影响前端查询性能
7. 支持手动触发检查点，语法为：CREATE CHECKPOINT;
**技术约束：**
- 事务嵌套深度：1层
- WAL文件自动轮转和清理
**测试场景：**
- 功能测试：执行包含多个操作的事务，验证原子性
- 可靠性测试：执行事务后kill -9进程，重启后验证数据一致性
- 功能测试：验证自动和手动检查点的创建
- 可靠性测试：创建检查点后kill -9进程，重启后验证恢复正确性
---
#### **US-104：生产级索引管理器**
作为AI应用开发者，我希望数据库支持高性能的向量索引，包括HNSW和IVF_FLAT，以实现快速的相似性搜索。
**验收条件：**
1. 支持至少2种索引类型：HNSW、IVF_FLAT
2. 支持至少3种距离度量：Cosine、L2、IP
3. 支持索引类型相关参数配置，如HNSW的M和ef_construction
4. 支持在线创建索引，语法为：CREATE INDEX idx_embedding ON docs(embedding) USING HNSW WITH (M=16, ef_construction=200);
5. 索引构建过程中，前端读写查询正常执行
6. 支持SHOW INDEX BUILD STATUS命令查看构建进度
7. 索引数据与主数据一同持久化，服务重启后无需重建索引
8. 千万级向量索引加载时间 < 1分钟
9. 亿级向量索引加载时间 < 5分钟
**性能与精度需求：**
- 在千万级向量数据集中，使用HNSW索引（ef_search=128）进行单次查询：P95延迟 < 50ms，召回率（Recall@10）> 98%
- 混合查询性能损耗 < 30%（相较于纯向量查询）
**测试场景：**
- 功能测试：创建不同类型和配置的索引，验证语法正确性和功能正常
- 性能测试：比较不同索引配置的性能差异
- 功能测试：在已有数据上创建索引，验证构建过程不阻塞读写
- 功能测试：使用SHOW INDEX BUILD STATUS命令查看构建进度
- 性能测试：在千万级向量数据集上执行10,000次查询，测量P95延迟
- 精度测试：将近似搜索结果与精确搜索结果对比，计算Recall@10
---
**计算与查询栈**
#### **US-105：工业级AINQL与查询引擎**
作为AI应用开发者，我希望数据库支持完备的客户端协议与SDK，以及SQL-like的查询语法，以便于快速集成和开发应用。
**验收条件：**
1. 同时支持 gRPC（高性能，生产推荐）和 RESTful HTTP（易调试）协议
2. gRPC协议支持所有核心功能，性能测试中吞吐量>10,000 QPS
3. RESTful HTTP协议支持所有核心功能，便于调试和集成
4. 提供功能完整的 Python SDK（支持异步），以及基础的 Go/Java SDK
5. 支持SQL-like查询语法，核心示例：
```sql
SELECT id, doc, cosine_distance(vector, $query_vec) AS score
FROM my_collection
WHERE category = '科技' AND year > 2023
ORDER BY score ASC
LIMIT 10;
```
6. 支持查询参数化，防止注入攻击
7. 支持查询级超时配置，语法为：SELECT * FROM docs WHERE VECTOR_SIMILAR(embedding, $query_vec) TIMEOUT 500ms;
8. 支持最大返回结果数限制
9. 当系统负载超过阈值时，能优雅拒绝新查询，保护系统稳定性
**测试场景：**
- 功能测试：使用不同协议和SDK执行各种查询操作，验证功能完整性
- 性能测试：测量gRPC协议的吞吐量，验证>10,000 QPS
- 集成测试：验证SDK与数据库服务的兼容性
- 功能测试：执行各种AINQL查询，验证语法正确性和结果准确性
- 安全测试：尝试SQL注入攻击，验证系统能有效防御
- 功能测试：执行长查询，验证超时机制生效
- 压力测试：模拟高负载场景，验证查询熔断机制生效
---
#### **US-106：内置模型运行时**
作为AI应用开发者，我希望数据库内置模型推理运行时，支持在查询管道中直接调用嵌入模型，以便实现检索即推理。
**验收条件：**
1. 模型在独立的Model Worker进程中运行，与主数据库进程隔离
2. 支持配置Model Worker的CPU核心数和内存上限
3. Model Worker崩溃或被杀死时，主数据库服务继续正常运行
4. 提供同步调用接口，用于实时查询时的文本向量化
5. 同步接口延迟P99<100ms，支持每秒至少1,000次调用
6. 内置至少1个高质量嵌入模型（如BGE-M3）
7. 支持在查询中直接调用内置模型，语法为：SELECT text_embedding(text, 'BGE-M3') AS embedding FROM docs;
8. 支持从HTTP URL或本地文件路径挂载自定义模型，语法为：CREATE MODEL custom_model USING 'https://example.com/model.onnx' TYPE embedding;
**测试场景：**
- 功能测试：启动数据库服务，验证Model Worker进程独立运行
- 可靠性测试：杀死Model Worker进程，验证主数据库服务继续正常运行
- 资源测试：配置Model Worker资源限制，验证资源使用不超过限制
- 性能测试：测量同步接口的延迟和吞吐量
- 功能测试：使用内置模型生成嵌入向量，验证结果正确性
- 功能测试：从HTTP URL和本地文件加载自定义模型，验证能正常使用
---
**部署与运维**
#### **US-107：单一二进制部署**
作为系统管理员，我希望整个数据库为一个独立的、无外部运行时依赖的可执行文件，以便于部署和运维。
**验收条件：**
1. 数据库为单一可执行文件，无外部依赖（如Java Runtime、Python等）
2. 支持主流操作系统：Linux、Windows、macOS
3. 可直接运行，无需额外安装步骤
**测试场景：**
- 功能测试：在不同操作系统上直接运行二进制文件，验证能正常启动
- 依赖测试：使用ldd（Linux）或otool（macOS）检查二进制文件依赖，验证无外部运行时依赖
---
#### **US-108：基础认证与安全**
作为系统管理员，我希望数据库支持简单的API Key认证和网络安全配置，以保护数据安全。
**验收条件：**
1. 支持API Key认证，配置语法为：SET GLOBAL api_keys=['key1', 'key2'];
2. API Key通过HTTP Header或gRPC Metadata传递
3. 无效API Key请求被拒绝，返回401 Unauthorized
4. 支持API Key的动态更新，无需重启服务
5. 支持配置监听IP，语法为：SET GLOBAL listen_address='0.0.0.0:9000';
6. 支持SSL/TLS加密传输，配置语法为：SET GLOBAL ssl_cert='server.crt'; SET GLOBAL ssl_key='server.key';
7. 支持至少TLS 1.2版本
**测试场景：**
- 功能测试：使用有效和无效API Key发送请求，验证认证机制生效
- 安全测试：尝试各种API Key伪造攻击，验证系统能有效防御
- 功能测试：动态更新API Key，验证无需重启服务即可生效
- 功能测试：配置不同的监听IP，验证服务能正确绑定
- 安全测试：使用OpenSSL验证TLS版本和加密套件
---
### **阶段二：核心优化**
**性能优化**
#### **US-201：动态AI数据流优化**
作为实时AI应用开发者，我希望数据库支持流式摄取与实时索引，以及工作负载感知的缓存，以处理动态数据流。
**验收条件：**
1. 支持从Kafka消费数据，配置语法为：CREATE STREAM ingestion FROM KAFKA TOPIC 'docs' WITH CONFIG (bootstrap_servers='kafka:9092');
2. 数据摄入后可见延迟<1s
3. 支持每秒至少10,000条数据的持续摄入
4. 自动识别高频查询，缓存命中率>80%
5. 自动识别热点数据，热点数据访问延迟<1ms
6. 支持动态调整缓存大小和策略
**测试场景：**
- 功能测试：从Kafka发送测试数据，验证数据能被正确摄入和索引
- 性能测试：测量数据摄入到可见的延迟，验证<1s
- 性能测试：测试持续摄入10,000条/秒数据的稳定性
- 性能测试：模拟高频查询，测量缓存命中率，验证>80%
- 性能测试：访问热点数据，测量延迟，验证<1ms
---
#### **US-202：模型计算下推**
作为AI应用开发者，我希望可将轻量级嵌入模型、重排序模型以UDF形式部署在存储层，实现"数据在哪里，计算就在哪里"，避免大规模数据移动。
**验收条件：**
1. 支持将模型作为UDF部署，语法为：CREATE MODEL udf_embedding USING 'bge-m3.onnx' AS (text STRING) RETURNS VECTOR(768);
2. 模型UDF支持在查询中调用，语法为：SELECT udf_embedding(text) AS embedding FROM docs;
3. 模型计算下推能减少至少50%的数据传输量
**测试场景：**
- 功能测试：部署模型UDF，在查询中调用，验证结果正确性
- 性能测试：比较模型计算下推前后的数据传输量，验证减少至少50%
---
**数据智能**
#### **US-203：数据谱系与版本化**
作为AI研究者，我希望支持对指定集合创建数据快照，并可通过快照ID进行历史数据查询或恢复，服务于AI实验的可复现性。
**验收条件：**
1. 支持创建集合快照，语法为：CREATE SNAPSHOT docs_snapshot ON docs;
2. 支持通过快照ID查询历史数据，语法为：SELECT * FROM docs@docs_snapshot WHERE id = 1;
3. 支持从快照恢复数据，语法为：RESTORE TABLE docs FROM SNAPSHOT docs_snapshot;
4. 快照创建时间<1分钟（对于100万条数据的集合）
5. 每条数据自动记录谱系信息，包括源文件、提取位置、嵌入模型版本、处理时间
6. 支持通过数据ID查询完整谱系，语法为：SELECT lineage FROM docs_lineage WHERE data_id = 1;
**测试场景：**
- 功能测试：创建快照、查询快照数据、从快照恢复，验证各操作正确性
- 性能测试：测量快照创建时间，验证<1分钟
- 可靠性测试：从快照恢复数据后，验证数据完整性
- 功能测试：插入数据，验证谱系信息自动记录
- 功能测试：查询数据谱系，验证信息完整性
---
#### **US-204：可观测性**
作为系统管理员，我希望数据库提供全面的监控指标和结构化日志，以便于运维和故障排查。
**验收条件：**
1. 通过 /metrics 端点暴露Prometheus格式指标，至少包括：vecdb_query_duration_seconds (分位数)、vecdb_index_cache_hit_rate、vecdb_active_connections、vecdb_wal_size_bytes
2. 所有操作日志以JSON格式输出，包含请求ID、用户、耗时等关键字段
3. 提供 /health（健康检查）、/config（配置查看）、/debug/pprof（性能剖析）等运维端点
4. 日志包含关键查询的召回率估算，格式为JSON
5. Model Worker暴露Prometheus格式的模型推理指标，包括P99延迟、吞吐量和错误率
6. 提供AI专属监控指标：vecdb_index_recall_rate、vecdb_query_cache_hit_rate、vecdb_retrieval_token_cost
**测试场景：**
- 功能测试：访问 /metrics 端点，验证返回有效的Prometheus格式指标
- 监控测试：验证指标能被Prometheus正确采集
- 功能测试：执行操作，验证日志格式和内容符合要求
- 功能测试：访问各个管理端点，验证返回内容符合要求
- 健康检查测试：模拟服务异常，验证/health端点返回非200状态码
- 功能测试：执行查询，验证日志中包含召回率估算信息
- 功能测试：访问Model Worker的metrics端点，验证模型推理指标存在
---
### **阶段三：高级功能**
**高级查询功能**
#### **US-301：分数可编程**
作为AI应用开发者，我希望提供SCORE FUSION子句，允许用户自定义函数（如RRF, 加权求和）来融合来自向量、关键词、图关系的多元相关性分数。
**验收条件：**
1. 支持SCORE FUSION子句，语法为：SELECT * FROM docs WHERE SCORE FUSION([VECTOR_SIMILAR(embedding, $query_vec), FULLTEXT_MATCH(content, $query_str)]) USING RRF LIMIT 10;
2. 支持至少2种内置融合算法（RRF, 加权求和）
3. 支持自定义融合函数
**测试场景：**
- 功能测试：使用不同融合算法执行查询，验证结果正确性
- 功能测试：使用自定义融合函数执行查询，验证结果正确性
---
#### **US-302：多模态联合检索**
作为AI应用开发者，我希望支持单一查询语句跨不同模态（文本、图像、音频）的向量空间进行联合检索与结果归并，以便实现多模态AI应用。
**验收条件：**
1. 支持跨模态联合检索，语法为：SELECT * FROM multimodal_docs WHERE CROSS_MODAL_SIMILAR(vector, $query_vec, modalities=['text', 'image']) LIMIT 10;
2. 支持至少3种模态（文本、图像、音频）
3. 支持结果归并与排序
**测试场景：**
- 功能测试：执行跨模态联合检索，验证结果正确性
- 功能测试：验证不同模态的结果能够正确归并排序
---
#### **US-303：会话与序列原生支持**
作为会话AI开发者，我希望提供SESSION或SEQUENCE类型，用于直接存储和管理多轮对话、Agent执行链等具有严格时序关系的数据单元。
**验收条件：**
1. 能够创建包含SESSION类型的表，语法为：CREATE TABLE conversations (session_id SESSION PRIMARY KEY, message STRING, timestamp TIMESTAMP);
2. 支持按会话ID查询完整会话历史，保持时序关系
3. 支持会话数据的原子更新
**测试场景：**
- 功能测试：创建会话表，插入多条会话数据，验证查询结果保持时序
- 并发测试：多个客户端同时更新同一会话，验证数据一致性
---
**高级存储功能**
#### **US-304：分级存储自动化**
作为系统管理员，我希望基于数据访问模式（热度、时效性），自动在内存 -> SSD -> 对象存储间迁移数据，并对查询保持透明，以优化存储成本。
**验收条件：**
1. 支持配置多级存储策略，语法为：ALTER TABLE docs SET STORAGE_POLICY (hot_ttl=2h, warm_ttl=30d);
2. 数据自动根据访问模式在不同存储层级间迁移
3. 分级存储对查询透明，无需修改查询语句
**测试场景：**
- 功能测试：配置分级存储策略，验证数据根据访问模式自动迁移
- 功能测试：查询不同存储层级的数据，验证结果正确性和透明性
- 成本测试：测量分级存储的存储成本节约
---
#### **US-305：图向量融合**
作为图AI应用开发者，我希望支持在图数据库的节点和关系上直接附加向量属性，并能基于向量相似度进行图遍历的路径剪枝或起点选择。
**验收条件：**
1. 能够创建包含向量属性的图节点和关系，语法为：CREATE NODE TYPE user (id INT PRIMARY KEY, profile_vec VECTOR(768));
2. 支持基于向量相似度的图遍历，语法为：TRAVERSE FROM (SELECT * FROM user WHERE VECTOR_SIMILAR(profile_vec, $query_vec) LIMIT 5) MAX_DEPTH 3;
3. 图遍历过程中支持基于向量相似度进行路径剪枝
**测试场景：**
- 功能测试：创建图节点和关系，附加向量属性，执行向量相似度图遍历，验证结果正确性
- 性能测试：在包含100万节点的图上执行向量相似度图遍历，验证性能
---
### **阶段四：可选扩展**
**性能极致优化**
#### **US-401：无锁高并发架构**
作为高性能AI应用开发者，我希望数据库核心使用无锁数据结构和细粒度并发控制，以便在多核服务器上实现更高的查询性能。
**验收条件：**
1. 核心数据结构（哈希表、B+树）实现无锁版本
2. 支持多核并行查询，查询性能随核心数线性扩展
3. 内存操作使用RCU（Read-Copy-Update）或类似技术，实现零拷贝读取
4. 实现NUMA感知的内存分配和线程绑定
5. 单个查询延迟99分位线<50μs
**测试场景：**
- 多线程并发测试，验证线性扩展性
- 不同NUMA节点配置下的性能测试
- 长时间压力测试（24小时）验证无锁算法的正确性
---
#### **US-402：零拷贝网络栈优化**
作为网络敏感AI应用开发者，我希望数据库网络层实现零拷贝和批处理，以便最大化网络吞吐量并降低CPU使用率。
**验收条件：**
1. 实现基于io_uring的异步网络I/O（Linux 5.1+）
2. 支持零拷贝数据发送（sendfile、splice等技术）
3. 命令批处理：单次系统调用处理多个客户端请求
4. 网络吞吐量：单节点>40Gbps，CPU使用率<50%
**测试场景：**
- 使用dpdk-testpmd测试网络吞吐量
- 高并发连接测试
- 网络延迟测试（P99延迟<100μs）
---
**高级安全与管理**
#### **US-403：完整的RBAC支持**
作为企业级AI应用开发者，我希望数据库支持完整的基于角色的访问控制（RBAC），以便于管理不同用户的权限。
**验收条件：**
1. 支持创建角色，语法为：CREATE ROLE developer;
2. 支持为角色授予权限，语法为：GRANT SELECT, INSERT ON docs TO developer;
3. 支持为用户分配角色，语法为：GRANT ROLE developer TO user1;
4. 支持细粒度的权限控制，包括表级、行级、列级权限
**测试场景：**
- 功能测试：创建角色、授予权限、分配角色，验证权限控制生效
- 安全测试：验证用户只能执行被授予的操作
---
## 🧠 设计要点说明
### **核心理念**
1. **计算贴近数据**：将模型推理（如嵌入生成、重排序）作为一等公民内置，减少数据搬运。
2. **动态数据与静态数据同等重要**：为实时流式数据（如对话、传感器数据）设计原生摄入、索引和查询路径。
3. **语义理解超越字节存储**：数据模型以"向量"、"文档"、"图谱关系"为核心，而非传统的"行"与"列"。
4. **工作负载感知的自优化**：系统能感知检索、会话管理、Agent推理等不同模式，并自动优化资源分配和索引策略。
5. **开发即生产**：为AI应用快速迭代的特性设计，支持无缝的架构演进、数据版本化和实验管理。
### **架构设计**
#### 一、架构与引擎层
- **存算分离与统一数据层**：计算节点（执行查询、嵌入模型）可独立于存储节点弹性伸缩。底层为所有数据（向量、标量、图、非结构化文件）提供统一的寻址、缓存和事务视图。
- **混合负载处理引擎**：
- **实时分析处理（RTAP）**：在同一数据上同时支持高吞吐的向量检索（OLAP）和低延迟的点更新（如Agent状态写入，OLTP）。
- **流批一体摄入**：支持批量历史数据灌入与实时流数据（如Kafka流）的毫秒级摄入与索引同步构建。
- **多粒度索引自动管理**：
- 支持在字段、集合、租户级别创建和管理不同的向量索引（如HNSW, DiskANN, ScaNN）。
- 索引热切换与在线重建：在数据持续写入时，支持后台异步构建新索引，并能在不中断服务的情况下完成切换。
- 成本感知的分级存储：热数据在内存/SSD，温冷数据自动降级至对象存储，并对查询透明。
#### 二、查询与计算层
- **AI原生查询语言（AINQL）扩展**：
- `FIND vec_similar TO @query_vec WHERE metadata.color = "red" LIMIT 10 WITH score_cutoff=0.7`
- JOIN 操作支持相似度连接（如找出相关对话和订单）。
- 内置聚合函数如 `centroid(vector_column)`、`diversity(vector_results)`。
- **内置模型推理运行时**：
- 支持将嵌入模型、重排序模型、分类模型等以UDF形式部署，在查询管道中调用。
- 例如：`RETRIEVE doc FROM knowledge_base RERANK BY bge-reranker-large LIMIT 5`。
- **多模态与混合检索**：
- 原生支持跨模态联合检索，例如"用这张图片搜索相关文本描述"。
- 支持混合分数融合：支持自定义算法（如加权平均、RRF）融合来自关键词、向量、图遍历路径的多种相关性分数。
#### 三、数据模型与存储层
- **灵活且强类型的模式**：
- 支持动态字段，但核心字段可强制类型约束（如向量维度、数据类型）。
- 支持嵌套文档和数组，特别是对长上下文对话的天然存储。
- **向量优化存储格式**：
- 向量数据采用针对SIMD指令集优化的压缩格式存储。
- 支持标量量化（SQ）、乘积量化（PQ）等，在精度和存储/计算效率间取得平衡。
- **图向量一体化存储**：
- 节点和关系均可附加向量属性，支持在图遍历过程中进行向量相似度剪枝。
## 产品核心定位
一个性能卓越、稳定可靠、开箱即用、具备完整可观测性的单机AI原生向量数据库。它必须能直接用于中小型生产环境（如RAG应用、智能体、会话AI），并为未来分布式扩展（V2.0）打下坚实的内核基础。
## 阶段一（V1.0）成功标准
1. **功能完整**：具备上述所有核心功能，可作为独立数据库服务部署。
2. **性能达标**：所有性能指标在参考硬件（8核CPU，32GB内存，1TB NVMe SSD）上通过标准测试验证。
3. **稳定可靠**：通过72小时连续稳定性压测，无内存泄漏，各项指标（延迟、吞吐）波动在10%以内。
4. **生产就绪**：提供完整的部署文档、运维手册、监控告警指南，并实现与LangChain等主流AI框架的官方集成。