wehub-resource-sync
521 lines
17 KiB
Markdown
521 lines
17 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/memvid/memvid) · [上游 README](https://github.com/memvid/memvid/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<!-- HEADER:START -->
|
||
<img width="2000" height="524" alt="Social Cover (9)"
|
||
src="https://github.com/user-attachments/assets/cf66f045-c8be-494b-b696-b8d7e4fb709c" />
|
||
<!-- HEADER:END -->
|
||
|
||
<div style="height: 16px;"></div>
|
||
|
||
<p align="center">
|
||
<a href="https://trendshift.io/repositories/17293" target="_blank"><img src="https://trendshift.io/api/badge/repositories/17293" alt="memvid%2Fmemvid | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
|
||
</p>
|
||
<!-- BADGES:END -->
|
||
|
||
<p align="center">
|
||
<strong>Memvid 是面向 AI 智能体的单文件记忆层，支持即时检索与长期记忆。</strong><br/>
|
||
持久化、可版本化、可移植的记忆，无需数据库。
|
||
</p>
|
||
|
||
<!-- NAV:START -->
|
||
<p align="center">
|
||
<a href="https://www.memvid.com">官网</a>
|
||
·
|
||
<a href="https://sandbox.memvid.com">试用沙盒</a>
|
||
·
|
||
<a href="https://docs.memvid.com">文档</a>
|
||
·
|
||
<a href="https://github.com/memvid/memvid/discussions">讨论</a>
|
||
</p>
|
||
<!-- NAV:END -->
|
||
|
||
<!-- BADGES:START -->
|
||
<p align="center">
|
||
<a href="https://crates.io/crates/memvid-core"><img src="https://img.shields.io/crates/v/memvid-core?style=flat-square&logo=rust" alt="Crates.io" /></a>
|
||
<a href="https://docs.rs/memvid-core"><img src="https://img.shields.io/docsrs/memvid-core?style=flat-square&logo=docs.rs" alt="docs.rs" /></a>
|
||
<a href="https://github.com/memvid/memvid/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square" alt="License" /></a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="https://github.com/memvid/memvid/stargazers"><img src="https://img.shields.io/github/stars/memvid/memvid?style=flat-square&logo=github" alt="Stars" /></a>
|
||
<a href="https://github.com/memvid/memvid/network/members"><img src="https://img.shields.io/github/forks/memvid/memvid?style=flat-square&logo=github" alt="Forks" /></a>
|
||
<a href="https://github.com/memvid/memvid/issues"><img src="https://img.shields.io/github/issues/memvid/memvid?style=flat-square&logo=github" alt="Issues" /></a>
|
||
<a href="https://discord.gg/vHvRHhJnHC"><img src="https://img.shields.io/discord/1442910055233224745?style=flat-square&logo=discord&label=discord" alt="Discord" /></a>
|
||
</p>
|
||
|
||
|
||
## 基准测试亮点
|
||
|
||
**🚀 准确度高于任何其他记忆系统：** 在 LoCoMo 上达到 SOTA +35%，同类最佳的长程对话召回与推理能力
|
||
|
||
**🧠 卓越的多跳与时序推理能力：** 多跳 +76%、时序 +56%（相对行业平均水平）
|
||
|
||
**⚡ 大规模场景下的超低延迟：** P50 0.025ms、P99 0.075ms，吞吐量较标准方案高 1,372 倍
|
||
|
||
**🔬 完全可复现的基准测试：** LoCoMo（10 × 约 26K token 对话）、开源评测、LLM-as-Judge
|
||
|
||
|
||
## 什么是 Memvid？
|
||
|
||
Memvid 是一种可移植的 AI 记忆系统，将你的数据、嵌入向量、检索结构与元数据打包进单个文件。
|
||
|
||
无需运行复杂的 RAG 流水线或基于服务器的向量数据库，Memvid 可直接从文件中快速检索。
|
||
|
||
最终得到一个与模型无关、无需基础设施的记忆层，为 AI 智能体提供可随身携带的持久化长期记忆。
|
||
|
||
|
||
## 什么是 Smart Frames？
|
||
|
||
Memvid 借鉴视频编码思路，并非用于存储视频，而是**将 AI 记忆组织为仅追加、超高效率的 Smart Frame 序列。**
|
||
|
||
Smart Frame 是不可变单元，存储内容以及时间戳、校验和与基础元数据。
|
||
Frame 按特定方式分组，以实现高效压缩、索引与并行读取。
|
||
|
||
这种基于 Frame 的设计带来：
|
||
|
||
- 仅追加写入，无需修改或破坏已有数据
|
||
- 对历史记忆状态的查询
|
||
- 以时间线方式检视知识如何演化
|
||
- 通过已提交、不可变的 Frame 实现崩溃安全
|
||
- 采用借鉴自视频编码的技术实现高效压缩
|
||
|
||
最终得到一个文件，对 AI 系统而言就像可回放的记忆时间线。
|
||
|
||
|
||
## 核心概念
|
||
|
||
- **Living Memory Engine（活体记忆引擎）**
|
||
跨会话持续追加、分支并演化记忆。
|
||
|
||
- **Capsule Context（`.mv2`）**
|
||
自带规则与过期时间的、可独立共享的记忆胶囊。
|
||
|
||
- **Time-Travel Debugging（时光回溯调试）**
|
||
回退、重放或分支任意记忆状态。
|
||
|
||
- **Smart Recall（智能召回）**
|
||
亚 5ms 本地记忆访问，配合预测性缓存。
|
||
|
||
- **Codec Intelligence（编解码智能）**
|
||
随时间自动选择并升级压缩方案。
|
||
|
||
|
||
## 应用场景
|
||
|
||
Memvid 是可移植、无服务器的记忆层，为 AI 智能体提供持久记忆与快速召回。由于与模型无关、支持多模态且可完全离线运行，开发者已在众多实际应用中采用 Memvid。
|
||
|
||
- 长时运行 AI 智能体
|
||
- 企业知识库
|
||
- 离线优先 AI 系统
|
||
- 代码库理解
|
||
- 客户支持智能体
|
||
- 工作流自动化
|
||
- 销售与营销 Copilot
|
||
- 个人知识助手
|
||
- 医疗、法律与金融智能体
|
||
- 可审计、可调试的 AI 工作流
|
||
- 自定义应用
|
||
|
||
|
||
## SDK 与 CLI
|
||
|
||
使用你偏好的语言接入 Memvid：
|
||
|
||
| 软件包 | 安装 | 链接 |
|
||
| --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
||
| **CLI** | `npm install -g memvid-cli` | [](https://www.npmjs.com/package/memvid-cli) |
|
||
| **Node.js SDK** | `npm install @memvid/sdk` | [](https://www.npmjs.com/package/@memvid/sdk) |
|
||
| **Python SDK** | `pip install memvid-sdk` | [](https://pypi.org/project/memvid-sdk/) |
|
||
| **Rust** | `cargo add memvid-core` | [](https://crates.io/crates/memvid-core) |
|
||
|
||
---
|
||
|
||
## 安装（Rust）
|
||
|
||
### 环境要求
|
||
|
||
- **Rust 1.85.0+** — 从 [rustup.rs](https://rustup.rs) 安装
|
||
|
||
### 添加到你的项目
|
||
|
||
```toml
|
||
[dependencies]
|
||
memvid-core = "2.0"
|
||
```
|
||
|
||
### 功能特性（Feature Flags）
|
||
|
||
| 特性 | 说明 |
|
||
| ------------------- | ---------------------------------------------------------------- |
|
||
| `lex` | 基于 BM25 排序的全文检索（Tantivy） |
|
||
| `pdf_extract` | 纯 Rust PDF 文本提取 |
|
||
| `vec` | 向量相似度检索（HNSW + 通过 ONNX 的本地文本嵌入） |
|
||
| `clip` | 用于图像检索的 CLIP 视觉嵌入 |
|
||
| `whisper` | 使用 Whisper 进行音频转写 |
|
||
| `api_embed` | 云端 API 嵌入（OpenAI） |
|
||
| `temporal_track` | 自然语言日期解析（如 "last Tuesday"） |
|
||
| `parallel_segments` | 多线程数据摄入 |
|
||
| `encryption` | 基于密码的加密胶囊（.mv2e） |
|
||
| `symspell_cleanup` | 健壮的 PDF 文本修复（修复如 "emp lo yee" -> "employee"） |
|
||
|
||
按需启用特性：
|
||
|
||
```toml
|
||
[dependencies]
|
||
memvid-core = { version = "2.0", features = ["lex", "vec", "temporal_track"] }
|
||
```
|
||
|
||
|
||
## 快速开始
|
||
|
||
```rust
|
||
use memvid_core::{Memvid, PutOptions, SearchRequest};
|
||
|
||
fn main() -> memvid_core::Result<()> {
|
||
// Create a new memory file
|
||
let mut mem = Memvid::create("knowledge.mv2")?;
|
||
|
||
// Add documents with metadata
|
||
let opts = PutOptions::builder()
|
||
.title("Meeting Notes")
|
||
.uri("mv2://meetings/2024-01-15")
|
||
.tag("project", "alpha")
|
||
.build();
|
||
mem.put_bytes_with_options(b"Q4 planning discussion...", opts)?;
|
||
mem.commit()?;
|
||
|
||
// Search
|
||
let response = mem.search(SearchRequest {
|
||
query: "planning".into(),
|
||
top_k: 10,
|
||
snippet_chars: 200,
|
||
..Default::default()
|
||
})?;
|
||
|
||
for hit in response.hits {
|
||
println!("{}: {}", hit.title.unwrap_or_default(), hit.text);
|
||
}
|
||
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 构建
|
||
|
||
克隆仓库：
|
||
|
||
```bash
|
||
git clone https://github.com/memvid/memvid.git
|
||
cd memvid
|
||
```
|
||
|
||
以 debug 模式构建：
|
||
|
||
```bash
|
||
cargo build
|
||
```
|
||
|
||
以 release 模式（优化）构建：
|
||
|
||
```bash
|
||
cargo build --release
|
||
```
|
||
|
||
启用指定功能构建：
|
||
|
||
```bash
|
||
cargo build --release --features "lex,vec,temporal_track"
|
||
```
|
||
|
||
---
|
||
|
||
## 运行测试
|
||
|
||
运行全部测试：
|
||
|
||
```bash
|
||
cargo test
|
||
```
|
||
|
||
运行测试并输出结果：
|
||
|
||
```bash
|
||
cargo test -- --nocapture
|
||
```
|
||
|
||
运行指定测试：
|
||
|
||
```bash
|
||
cargo test test_name
|
||
```
|
||
|
||
仅运行集成测试：
|
||
|
||
```bash
|
||
cargo test --test lifecycle
|
||
cargo test --test search
|
||
cargo test --test mutation
|
||
```
|
||
|
||
---
|
||
|
||
## 示例
|
||
|
||
`examples/` 目录包含可运行的示例：
|
||
|
||
### 基础用法
|
||
|
||
演示 create、put、search 和 timeline 操作：
|
||
|
||
```bash
|
||
cargo run --example basic_usage
|
||
```
|
||
|
||
### PDF 导入
|
||
|
||
导入并搜索 PDF 文档（使用论文《Attention Is All You Need》）：
|
||
|
||
```bash
|
||
cargo run --example pdf_ingestion
|
||
```
|
||
|
||
### CLIP 视觉搜索
|
||
|
||
使用 CLIP 嵌入（embeddings）进行图像搜索（需要 `clip` 功能）：
|
||
|
||
```bash
|
||
cargo run --example clip_visual_search --features clip
|
||
```
|
||
|
||
### Whisper 转录
|
||
|
||
音频转录（需要 `whisper` 功能）：
|
||
|
||
```bash
|
||
cargo run --example test_whisper --features whisper -- /path/to/audio.mp3
|
||
```
|
||
|
||
**可用模型：**
|
||
|
||
| 模型 | 大小 | 速度 | 用途 |
|
||
| --------------------- | ------ | ------- | ----------------------------------- |
|
||
| `whisper-small-en` | 244 MB | 最慢 | 最高精度（默认） |
|
||
| `whisper-tiny-en` | 75 MB | 快 | 均衡 |
|
||
| `whisper-tiny-en-q8k` | 19 MB | 最快 | 快速测试、资源受限场景 |
|
||
|
||
**模型选择：**
|
||
|
||
```bash
|
||
# Default (FP32 small, highest accuracy)
|
||
cargo run --example test_whisper --features whisper -- audio.mp3
|
||
|
||
# Quantized tiny (75% smaller, faster)
|
||
MEMVID_WHISPER_MODEL=whisper-tiny-en-q8k cargo run --example test_whisper --features whisper -- audio.mp3
|
||
```
|
||
|
||
**编程配置：**
|
||
|
||
```rust
|
||
use memvid_core::{WhisperConfig, WhisperTranscriber};
|
||
|
||
// Default FP32 small model
|
||
let config = WhisperConfig::default();
|
||
|
||
// Quantized tiny model (faster, smaller)
|
||
let config = WhisperConfig::with_quantization();
|
||
|
||
// Specific model
|
||
let config = WhisperConfig::with_model("whisper-tiny-en-q8k");
|
||
|
||
let transcriber = WhisperTranscriber::new(&config)?;
|
||
let result = transcriber.transcribe_file("audio.mp3")?;
|
||
println!("{}", result.text);
|
||
```
|
||
|
||
|
||
## 文本嵌入（Text Embedding）模型
|
||
|
||
`vec` 功能包含基于 ONNX 模型的本地文本嵌入支持。使用本地文本嵌入前，你需要手动下载模型文件。
|
||
|
||
### 快速开始：BGE-small（推荐）
|
||
|
||
下载默认 BGE-small 模型（384 维，快速高效）：
|
||
|
||
```bash
|
||
mkdir -p ~/.cache/memvid/text-models
|
||
|
||
# Download ONNX model
|
||
curl -L 'https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/onnx/model.onnx' \
|
||
-o ~/.cache/memvid/text-models/bge-small-en-v1.5.onnx
|
||
|
||
# Download tokenizer
|
||
curl -L 'https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/tokenizer.json' \
|
||
-o ~/.cache/memvid/text-models/bge-small-en-v1.5_tokenizer.json
|
||
```
|
||
|
||
### 可用模型
|
||
|
||
| 模型 | 维度 | 大小 | 适用场景 |
|
||
| ----------------------- | ---------- | ------ | --------------- |
|
||
| `bge-small-en-v1.5` | 384 | ~120MB | 默认、快速 |
|
||
| `bge-base-en-v1.5` | 768 | ~420MB | 更高质量 |
|
||
| `nomic-embed-text-v1.5` | 768 | ~530MB | 通用任务 |
|
||
| `gte-large` | 1024 | ~1.3GB | 最高质量 |
|
||
|
||
### 其他模型
|
||
|
||
**BGE-base**（768 维）：
|
||
```bash
|
||
curl -L 'https://huggingface.co/BAAI/bge-base-en-v1.5/resolve/main/onnx/model.onnx' \
|
||
-o ~/.cache/memvid/text-models/bge-base-en-v1.5.onnx
|
||
curl -L 'https://huggingface.co/BAAI/bge-base-en-v1.5/resolve/main/tokenizer.json' \
|
||
-o ~/.cache/memvid/text-models/bge-base-en-v1.5_tokenizer.json
|
||
```
|
||
|
||
**Nomic**（768 维）：
|
||
```bash
|
||
curl -L 'https://huggingface.co/nomic-ai/nomic-embed-text-v1.5/resolve/main/onnx/model.onnx' \
|
||
-o ~/.cache/memvid/text-models/nomic-embed-text-v1.5.onnx
|
||
curl -L 'https://huggingface.co/nomic-ai/nomic-embed-text-v1.5/resolve/main/tokenizer.json' \
|
||
-o ~/.cache/memvid/text-models/nomic-embed-text-v1.5_tokenizer.json
|
||
```
|
||
|
||
**GTE-large**（1024 维）：
|
||
```bash
|
||
curl -L 'https://huggingface.co/thenlper/gte-large/resolve/main/onnx/model.onnx' \
|
||
-o ~/.cache/memvid/text-models/gte-large.onnx
|
||
curl -L 'https://huggingface.co/thenlper/gte-large/resolve/main/tokenizer.json' \
|
||
-o ~/.cache/memvid/text-models/gte-large_tokenizer.json
|
||
```
|
||
|
||
### 代码中的用法
|
||
|
||
```rust
|
||
use memvid_core::text_embed::{LocalTextEmbedder, TextEmbedConfig};
|
||
use memvid_core::types::embedding::EmbeddingProvider;
|
||
|
||
// Use default model (BGE-small)
|
||
let config = TextEmbedConfig::default();
|
||
let embedder = LocalTextEmbedder::new(config)?;
|
||
|
||
let embedding = embedder.embed_text("hello world")?;
|
||
assert_eq!(embedding.len(), 384);
|
||
|
||
// Use different model
|
||
let config = TextEmbedConfig::bge_base();
|
||
let embedder = LocalTextEmbedder::new(config)?;
|
||
```
|
||
|
||
参见 `examples/text_embedding.rs` 获取包含相似度计算和搜索排序的完整示例。
|
||
|
||
### 模型一致性
|
||
|
||
为防止意外混用模型（例如用 OpenAI 嵌入查询 BGE-small 索引），你可以将 Memvid 实例显式绑定到特定模型名称：
|
||
|
||
```rust
|
||
// Bind the index to a specific model.
|
||
// If the index was previously created with a different model, this will return an error.
|
||
mem.set_vec_model("bge-small-en-v1.5")?;
|
||
```
|
||
|
||
该绑定是持久化的。设置后，若尝试使用不同模型名称，将立即以 `ModelMismatch` 错误失败。
|
||
|
||
|
||
|
||
## API 嵌入（OpenAI）
|
||
|
||
`api_embed` 功能通过 OpenAI API 启用基于云的嵌入生成。
|
||
|
||
### 设置
|
||
|
||
设置你的 OpenAI API 密钥：
|
||
|
||
```bash
|
||
export OPENAI_API_KEY="sk-..."
|
||
```
|
||
|
||
### 用法
|
||
|
||
```rust
|
||
use memvid_core::api_embed::{OpenAIConfig, OpenAIEmbedder};
|
||
use memvid_core::types::embedding::EmbeddingProvider;
|
||
|
||
// Use default model (text-embedding-3-small)
|
||
let config = OpenAIConfig::default();
|
||
let embedder = OpenAIEmbedder::new(config)?;
|
||
|
||
let embedding = embedder.embed_text("hello world")?;
|
||
assert_eq!(embedding.len(), 1536);
|
||
|
||
// Use higher quality model
|
||
let config = OpenAIConfig::large(); // text-embedding-3-large (3072 dims)
|
||
let embedder = OpenAIEmbedder::new(config)?;
|
||
```
|
||
|
||
### 可用模型
|
||
|
||
| 模型 | 维度 | 适用场景 |
|
||
| ------------------------ | ---------- | -------------------------- |
|
||
| `text-embedding-3-small` | 1536 | 默认、最快、最便宜 |
|
||
| `text-embedding-3-large` | 3072 | 最高质量 |
|
||
| `text-embedding-ada-002` | 1536 | 旧版模型 |
|
||
|
||
参见 `examples/openai_embedding.rs` 获取完整示例。
|
||
|
||
|
||
|
||
## 文件格式
|
||
|
||
所有内容都存放在单个 `.mv2` 文件中：
|
||
|
||
```
|
||
┌────────────────────────────┐
|
||
│ Header (4KB) │ Magic, version, capacity
|
||
├────────────────────────────┤
|
||
│ Embedded WAL (1-64MB) │ Crash recovery
|
||
├────────────────────────────┤
|
||
│ Data Segments │ Compressed frames
|
||
├────────────────────────────┤
|
||
│ Lex Index │ Tantivy full-text
|
||
├────────────────────────────┤
|
||
│ Vec Index │ HNSW vectors
|
||
├────────────────────────────┤
|
||
│ Time Index │ Chronological ordering
|
||
├────────────────────────────┤
|
||
│ TOC (Footer) │ Segment offsets
|
||
└────────────────────────────┘
|
||
```
|
||
|
||
没有 `.wal`、`.lock`、`.shm` 或 sidecar 文件。永远如此。
|
||
|
||
参见 [MV2_SPEC.md](MV2_SPEC.md) 了解完整文件格式规范。
|
||
|
||
|
||
|
||
## 支持
|
||
|
||
有问题或反馈？
|
||
Email: contact@memvid.com
|
||
|
||
**点个 ⭐ 表示支持**
|
||
|
||
---
|
||
|
||
> **Memvid v1（基于 QR 的 memory）已弃用**
|
||
>
|
||
> 如果你在引用 QR 码，说明你使用的是过时信息。
|
||
>
|
||
> 参见：https://docs.memvid.com/memvid-v1-deprecation
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
Apache License 2.0 — 详见 [LICENSE](LICENSE) 文件。
|