docs: make Chinese README the default

2026-07-13 10:43:33 +00:00
parent 6a5049ca11
commit cd42f85876
1 changed files with 146 additions and 140 deletions
@@ -1,3 +1,9 @@
+<!-- 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" />
@@ -11,19 +17,19 @@
 <!-- BADGES:END -->

 <p align="center">
-  <strong>Memvid is a single-file memory layer for AI agents with instant retrieval and long-term memory.</strong><br/>
-  Persistent, versioned, and portable memory, without databases.
+  <strong>Memvid 是面向 AI 智能体的单文件记忆层，支持即时检索与长期记忆。</strong><br/>
+  持久化、可版本化、可移植的记忆，无需数据库。
 </p>

 <!-- NAV:START -->
 <p align="center">
-  <a href="https://www.memvid.com">Website</a>
+  <a href="https://www.memvid.com">官网</a>
  ·
-  <a href="https://sandbox.memvid.com">Try Sandbox</a>
+  <a href="https://sandbox.memvid.com">试用沙盒</a>
  ·
-  <a href="https://docs.memvid.com">Docs</a>
+  <a href="https://docs.memvid.com">文档</a>
  ·
-  <a href="https://github.com/memvid/memvid/discussions">Discussions</a>
+  <a href="https://github.com/memvid/memvid/discussions">讨论</a>
 </p>
 <!-- NAV:END -->

@@ -42,84 +48,84 @@
 </p>


-## Benchmark Highlights
+## 基准测试亮点

-**🚀 Higher accuracy than any other memory system :** +35% SOTA on LoCoMo, best-in-class long-horizon conversational recall & reasoning
+**🚀 准确度高于任何其他记忆系统：** 在 LoCoMo 上达到 SOTA +35%，同类最佳的长程对话召回与推理能力

-**🧠 Superior multi-hop & temporal reasoning:**  +76% multi-hop, +56% temporal vs. the industry average
+**🧠 卓越的多跳与时序推理能力：** 多跳 +76%、时序 +56%（相对行业平均水平）

-**⚡ Ultra-low latency at scale** 0.025ms P50 and 0.075ms P99, with 1,372× higher throughput than standard
+**⚡ 大规模场景下的超低延迟：** P50 0.025ms、P99 0.075ms，吞吐量较标准方案高 1,372 倍

-**🔬 Fully reproducible benchmarks:** LoCoMo (10 × ~26K-token conversations), open-source eval, LLM-as-Judge
+**🔬 完全可复现的基准测试：** LoCoMo（10 × 约 26K token 对话）、开源评测、LLM-as-Judge


-## What is Memvid?
+## 什么是 Memvid？

-Memvid is a portable AI memory system that packages your data, embeddings, search structure, and metadata into a single file.
+Memvid 是一种可移植的 AI 记忆系统，将你的数据、嵌入向量、检索结构与元数据打包进单个文件。

-Instead of running complex RAG pipelines or server-based vector databases, Memvid enables fast retrieval directly from the file.
+无需运行复杂的 RAG 流水线或基于服务器的向量数据库，Memvid 可直接从文件中快速检索。

-The result is a model-agnostic, infrastructure-free memory layer that gives AI agents persistent, long-term memory they can carry anywhere.
+最终得到一个与模型无关、无需基础设施的记忆层，为 AI 智能体提供可随身携带的持久化长期记忆。

    
-## What are Smart Frames?
+## 什么是 Smart Frames？

-Memvid draws inspiration from video encoding, not to store video, but to **organize AI memory as an append-only, ultra-efficient sequence of Smart Frames.**
+Memvid 借鉴视频编码思路，并非用于存储视频，而是**将 AI 记忆组织为仅追加、超高效率的 Smart Frame 序列。**

-A Smart Frame is an immutable unit that stores content along with timestamps, checksums and basic metadata.
-Frames are grouped in a way that allows efficient compression, indexing, and parallel reads.
+Smart Frame 是不可变单元，存储内容以及时间戳、校验和与基础元数据。
+Frame 按特定方式分组，以实现高效压缩、索引与并行读取。

-This frame-based design enables:
+这种基于 Frame 的设计带来：

-   Append-only writes without modifying or corrupting existing data
-   Queries over past memory states
-   Timeline-style inspection of how knowledge evolves
-   Crash safety through committed, immutable frames
-   Efficient compression using techniques adapted from video encoding
+-   仅追加写入，无需修改或破坏已有数据
+-   对历史记忆状态的查询
+-   以时间线方式检视知识如何演化
+-   通过已提交、不可变的 Frame 实现崩溃安全
+-   采用借鉴自视频编码的技术实现高效压缩

-The result is a single file that behaves like a rewindable memory timeline for AI systems.
+最终得到一个文件，对 AI 系统而言就像可回放的记忆时间线。


-## Core Concepts
+## 核心概念

-   **Living Memory Engine**
-    Continuously append, branch, and evolve memory across sessions.
+-   **Living Memory Engine（活体记忆引擎）**
+    跨会话持续追加、分支并演化记忆。

-   **Capsule Context (`.mv2`)**
-    Self-contained, shareable memory capsules with rules and expiry.
+-   **Capsule Context（`.mv2`）**
+    自带规则与过期时间的、可独立共享的记忆胶囊。

-   **Time-Travel Debugging**
-    Rewind, replay, or branch any memory state.
+-   **Time-Travel Debugging（时光回溯调试）**
+    回退、重放或分支任意记忆状态。

-   **Smart Recall**
-    Sub-5ms local memory access with predictive caching.
+-   **Smart Recall（智能召回）**
+    亚 5ms 本地记忆访问，配合预测性缓存。

-   **Codec Intelligence**
-    Auto-selects and upgrades compression over time.
+-   **Codec Intelligence（编解码智能）**
+    随时间自动选择并升级压缩方案。


-## Use Cases
+## 应用场景

-Memvid is a portable, serverless memory layer that gives AI agents persistent memory and fast recall. Because it's model-agnostic, multi-modal, and works fully offline, developers are using Memvid across a wide range of real-world applications.
+Memvid 是可移植、无服务器的记忆层，为 AI 智能体提供持久记忆与快速召回。由于与模型无关、支持多模态且可完全离线运行，开发者已在众多实际应用中采用 Memvid。

-   Long-Running AI Agents
-   Enterprise Knowledge Bases
-   Offline-First AI Systems
-   Codebase Understanding
-   Customer Support Agents
-   Workflow Automation
-   Sales and Marketing Copilots
-   Personal Knowledge Assistants
-   Medical, Legal, and Financial Agents
-   Auditable and Debuggable AI Workflows
-   Custom Applications
+-   长时运行 AI 智能体
+-   企业知识库
+-   离线优先 AI 系统
+-   代码库理解
+-   客户支持智能体
+-   工作流自动化
+-   销售与营销 Copilot
+-   个人知识助手
+-   医疗、法律与金融智能体
+-   可审计、可调试的 AI 工作流
+-   自定义应用


-## SDKs & CLI
+## SDK 与 CLI

-Use Memvid in your preferred language:
+使用你偏好的语言接入 Memvid：

-| Package         | Install                     | Links                                                                                                               |
+| 软件包         | 安装                     | 链接                                                                                                               |
 | --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | **CLI**         | `npm install -g memvid-cli` | [![npm](https://img.shields.io/npm/v/memvid-cli?style=flat-square)](https://www.npmjs.com/package/memvid-cli)       |
 | **Node.js SDK** | `npm install @memvid/sdk`   | [![npm](https://img.shields.io/npm/v/@memvid/sdk?style=flat-square)](https://www.npmjs.com/package/@memvid/sdk)     |
@@ -128,35 +134,35 @@ Use Memvid in your preferred language:

 ---

-## Installation (Rust)
+## 安装（Rust）

-### Requirements
+### 环境要求

-   **Rust 1.85.0+** — Install from [rustup.rs](https://rustup.rs)
+-   **Rust 1.85.0+** — 从 [rustup.rs](https://rustup.rs) 安装

-### Add to Your Project
+### 添加到你的项目

 ```toml
 [dependencies]
 memvid-core = "2.0"
 ```

-### Feature Flags
+### 功能特性（Feature Flags）

-| Feature             | Description                                                      |
+| 特性             | 说明                                                      |
 | ------------------- | ---------------------------------------------------------------- |
-| `lex`               | Full-text search with BM25 ranking (Tantivy)                     |
-| `pdf_extract`       | Pure Rust PDF text extraction                                    |
-| `vec`               | Vector similarity search (HNSW + local text embeddings via ONNX) |
-| `clip`              | CLIP visual embeddings for image search                          |
-| `whisper`           | Audio transcription with Whisper                                 |
-| `api_embed`         | Cloud API embeddings (OpenAI)                                    |
-| `temporal_track`    | Natural language date parsing ("last Tuesday")                   |
-| `parallel_segments` | Multi-threaded ingestion                                         |
-| `encryption`        | Password-based encryption capsules (.mv2e)                       |
-| `symspell_cleanup`  | Robust PDF text repair (fixes "emp lo yee" -> "employee")        |
+| `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"）        |

-Enable features as needed:
+按需启用特性：

 ```toml
 [dependencies]
@@ -164,7 +170,7 @@ memvid-core = { version = "2.0", features = ["lex", "vec", "temporal_track"] }
 ```


-## Quick Start
+## 快速开始

 ```rust
 use memvid_core::{Memvid, PutOptions, SearchRequest};
@@ -200,28 +206,28 @@ fn main() -> memvid_core::Result<()> {

 ---

-## Build
+## 构建

-Clone the repository:
+克隆仓库：

 ```bash
 git clone https://github.com/memvid/memvid.git
 cd memvid
 ```

-Build in debug mode:
+以 debug 模式构建：

 ```bash
 cargo build
 ```

-Build in release mode (optimized):
+以 release 模式（优化）构建：

 ```bash
 cargo build --release
 ```

-Build with specific features:
+启用指定功能构建：

 ```bash
 cargo build --release --features "lex,vec,temporal_track"
@@ -229,27 +235,27 @@ cargo build --release --features "lex,vec,temporal_track"

 ---

-## Run Tests
+## 运行测试

-Run all tests:
+运行全部测试：

 ```bash
 cargo test
 ```

-Run tests with output:
+运行测试并输出结果：

 ```bash
 cargo test -- --nocapture
 ```

-Run a specific test:
+运行指定测试：

 ```bash
 cargo test test_name
 ```

-Run integration tests only:
+仅运行集成测试：

 ```bash
 cargo test --test lifecycle
@@ -259,51 +265,51 @@ cargo test --test mutation

 ---

-## Examples
+## 示例

-The `examples/` directory contains working examples:
+`examples/` 目录包含可运行的示例：

-### Basic Usage
+### 基础用法

-Demonstrates create, put, search, and timeline operations:
+演示 create、put、search 和 timeline 操作：

 ```bash
 cargo run --example basic_usage
 ```

-### PDF Ingestion
+### PDF 导入

-Ingest and search PDF documents (uses the "Attention Is All You Need" paper):
+导入并搜索 PDF 文档（使用论文《Attention Is All You Need》）：

 ```bash
 cargo run --example pdf_ingestion
 ```

-### CLIP Visual Search
+### CLIP 视觉搜索

-Image search using CLIP embeddings (requires `clip` feature):
+使用 CLIP 嵌入（embeddings）进行图像搜索（需要 `clip` 功能）：

 ```bash
 cargo run --example clip_visual_search --features clip
 ```

-### Whisper Transcription
+### Whisper 转录

-Audio transcription (requires `whisper` feature):
+音频转录（需要 `whisper` 功能）：

 ```bash
 cargo run --example test_whisper --features whisper -- /path/to/audio.mp3
 ```

-**Available Models:**
+**可用模型：**

-| Model                 | Size   | Speed   | Use Case                            |
+| 模型                 | 大小   | 速度   | 用途                            |
 | --------------------- | ------ | ------- | ----------------------------------- |
-| `whisper-small-en`    | 244 MB | Slowest | Best accuracy (default)             |
-| `whisper-tiny-en`     | 75 MB  | Fast    | Balanced                            |
-| `whisper-tiny-en-q8k` | 19 MB  | Fastest | Quick testing, resource-constrained |
+| `whisper-small-en`    | 244 MB | 最慢 | 最高精度（默认）             |
+| `whisper-tiny-en`     | 75 MB  | 快    | 均衡                            |
+| `whisper-tiny-en-q8k` | 19 MB  | 最快 | 快速测试、资源受限场景 |

-**Model Selection:**
+**模型选择：**

 ```bash
 # Default (FP32 small, highest accuracy)
@@ -313,7 +319,7 @@ cargo run --example test_whisper --features whisper -- audio.mp3
 MEMVID_WHISPER_MODEL=whisper-tiny-en-q8k cargo run --example test_whisper --features whisper -- audio.mp3
 ```

-**Programmatic Configuration:**
+**编程配置：**

 ```rust
 use memvid_core::{WhisperConfig, WhisperTranscriber};
@@ -333,13 +339,13 @@ println!("{}", result.text);
 ```


-## Text Embedding Models
+## 文本嵌入（Text Embedding）模型

-The `vec` feature includes local text embedding support using ONNX models. Before using local text embeddings, you need to download the model files manually.
+`vec` 功能包含基于 ONNX 模型的本地文本嵌入支持。使用本地文本嵌入前，你需要手动下载模型文件。

-### Quick Start: BGE-small (Recommended)
+### 快速开始：BGE-small（推荐）

-Download the default BGE-small model (384 dimensions, fast and efficient):
+下载默认 BGE-small 模型（384 维，快速高效）：

 ```bash
 mkdir -p ~/.cache/memvid/text-models
@@ -353,18 +359,18 @@ curl -L 'https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/tokenizer.js
  -o ~/.cache/memvid/text-models/bge-small-en-v1.5_tokenizer.json
 ```

-### Available Models
+### 可用模型

-| Model                   | Dimensions | Size   | Best For        |
+| 模型                   | 维度 | 大小   | 适用场景        |
 | ----------------------- | ---------- | ------ | --------------- |
-| `bge-small-en-v1.5`     | 384        | ~120MB | Default, fast   |
-| `bge-base-en-v1.5`      | 768        | ~420MB | Better quality  |
-| `nomic-embed-text-v1.5` | 768        | ~530MB | Versatile tasks |
-| `gte-large`             | 1024       | ~1.3GB | Highest quality |
+| `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 | 最高质量 |

-### Other Models
+### 其他模型

-**BGE-base** (768 dimensions):
+**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
@@ -372,7 +378,7 @@ curl -L 'https://huggingface.co/BAAI/bge-base-en-v1.5/resolve/main/tokenizer.jso
  -o ~/.cache/memvid/text-models/bge-base-en-v1.5_tokenizer.json
 ```

-**Nomic** (768 dimensions):
+**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
@@ -380,7 +386,7 @@ curl -L 'https://huggingface.co/nomic-ai/nomic-embed-text-v1.5/resolve/main/toke
  -o ~/.cache/memvid/text-models/nomic-embed-text-v1.5_tokenizer.json
 ```

-**GTE-large** (1024 dimensions):
+**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
@@ -388,7 +394,7 @@ curl -L 'https://huggingface.co/thenlper/gte-large/resolve/main/tokenizer.json'
  -o ~/.cache/memvid/text-models/gte-large_tokenizer.json
 ```

-### Usage in Code
+### 代码中的用法

 ```rust
 use memvid_core::text_embed::{LocalTextEmbedder, TextEmbedConfig};
@@ -406,11 +412,11 @@ let config = TextEmbedConfig::bge_base();
 let embedder = LocalTextEmbedder::new(config)?;
 ```

-See `examples/text_embedding.rs` for a complete example with similarity computation and search ranking.
+参见 `examples/text_embedding.rs` 获取包含相似度计算和搜索排序的完整示例。

-### Model Consistency
+### 模型一致性

-To prevent accidental model mixing (e.g., querying a BGE-small index with OpenAI embeddings), you can explicitly bind your Memvid instance to a specific model name:
+为防止意外混用模型（例如用 OpenAI 嵌入查询 BGE-small 索引），你可以将 Memvid 实例显式绑定到特定模型名称：

 ```rust
 // Bind the index to a specific model.
@@ -418,23 +424,23 @@ To prevent accidental model mixing (e.g., querying a BGE-small index with OpenAI
 mem.set_vec_model("bge-small-en-v1.5")?;
 ```

-This binding is persistent. Once set, future attempts to use a different model name will fail fast with a `ModelMismatch` error.
+该绑定是持久化的。设置后，若尝试使用不同模型名称，将立即以 `ModelMismatch` 错误失败。



-## API Embeddings (OpenAI)
+## API 嵌入（OpenAI）

-The `api_embed` feature enables cloud-based embedding generation using OpenAI's API.
+`api_embed` 功能通过 OpenAI API 启用基于云的嵌入生成。

-### Setup
+### 设置

-Set your OpenAI API key:
+设置你的 OpenAI API 密钥：

 ```bash
 export OPENAI_API_KEY="sk-..."
 ```

-### Usage
+### 用法

 ```rust
 use memvid_core::api_embed::{OpenAIConfig, OpenAIEmbedder};
@@ -452,21 +458,21 @@ let config = OpenAIConfig::large();  // text-embedding-3-large (3072 dims)
 let embedder = OpenAIEmbedder::new(config)?;
 ```

-### Available Models
+### 可用模型

-| Model                    | Dimensions | Best For                   |
+| 模型                    | 维度 | 适用场景                   |
 | ------------------------ | ---------- | -------------------------- |
-| `text-embedding-3-small` | 1536       | Default, fastest, cheapest |
-| `text-embedding-3-large` | 3072       | Highest quality            |
-| `text-embedding-ada-002` | 1536       | Legacy model               |
+| `text-embedding-3-small` | 1536       | 默认、最快、最便宜 |
+| `text-embedding-3-large` | 3072       | 最高质量            |
+| `text-embedding-ada-002` | 1536       | 旧版模型               |

-See `examples/openai_embedding.rs` for a complete example.
+参见 `examples/openai_embedding.rs` 获取完整示例。



-## File Format
+## 文件格式

-Everything lives in a single `.mv2` file:
+所有内容都存放在单个 `.mv2` 文件中：

 ```
 ┌────────────────────────────┐
@@ -486,29 +492,29 @@ Everything lives in a single `.mv2` file:
 └────────────────────────────┘
 ```

-No `.wal`, `.lock`, `.shm`, or sidecar files. Ever.
+没有 `.wal`、`.lock`、`.shm` 或 sidecar 文件。永远如此。

-See [MV2_SPEC.md](MV2_SPEC.md) for the complete file format specification.
+参见 [MV2_SPEC.md](MV2_SPEC.md) 了解完整文件格式规范。



-## Support
+## 支持

-Have questions or feedback?
+有问题或反馈？
 Email: contact@memvid.com

-**Drop a ⭐ to show support**
+**点个 ⭐ 表示支持**

 ---

-> **Memvid v1 (QR-based memory) is deprecated**
+> **Memvid v1（基于 QR 的 memory）已弃用**
 >
-> If you are referencing QR codes, you are using outdated information.
+> 如果你在引用 QR 码，说明你使用的是过时信息。
 >
-> See: https://docs.memvid.com/memvid-v1-deprecation
+> 参见：https://docs.memvid.com/memvid-v1-deprecation

 ---

-## License
+## 许可证

-Apache License 2.0 — see the [LICENSE](LICENSE) file for details.
+Apache License 2.0 — 详见 [LICENSE](LICENSE) 文件。