diff --git "a/docs/BackendEntry\345\210\260RocksDB\346\230\240\345\260\204\350\257\246\350\247\243.md" "b/docs/BackendEntry\345\210\260RocksDB\346\230\240\345\260\204\350\257\246\350\247\243.md"
new file mode 100644
index 0000000000..5dd1709383
--- /dev/null
+++ "b/docs/BackendEntry\345\210\260RocksDB\346\230\240\345\260\204\350\257\246\350\247\243.md"
@@ -0,0 +1,272 @@
+# BackendEntry到RocksDB映射详解
+
+## 核心映射流程
+
+### 1. BackendEntry → BackendColumn
+
+```java
+// VectorBackendEntry.columns() 返回List<BackendColumn>
+@Override
+public Collection<BackendColumn> columns() {
+    List<BackendColumn> cols = new ArrayList<>();
+    
+    // 向量数据序列化为byte[]
+    if (this.vector != null) {
+        cols.add(BackendColumn.of(
+            "vector".getBytes(),           // name: 列名
+            this.serializeVector()         // value: 序列化后的向量数据
+        ));
+    }
+    
+    // 距离度量方式
+    if (this.metricType != null) {
+        cols.add(BackendColumn.of(
+            "metric".getBytes(),
+            this.metricType.getBytes()    // "L2" / "COSINE" / "DOT"
+        ));
+    }
+    
+    // 向量维度
+    if (this.dimension != null) {
+        cols.add(BackendColumn.of(
+            "dimension".getBytes(),
+            this.dimension.toString().getBytes()
+        ));
+    }
+    
+    return Collections.unmodifiableList(cols);
+}
+```
+
+### 2. BackendColumn结构
+
+```java
+public class BackendColumn {
+    public byte[] name;    // 列名（字节数组）
+    public byte[] value;   // 列值（字节数组）
+    
+    public static BackendColumn of(byte[] name, byte[] value) {
+        BackendColumn col = new BackendColumn();
+        col.name = name;
+        col.value = value;
+        return col;
+    }
+}
+```
+
+## RocksDB操作映射
+
+### 3. Action → RocksDB操作
+
+```java
+// RocksDBStore.mutate(BackendMutation mutation)
+public void mutate(BackendMutation mutation) {
+    for (HugeType type : mutation.types()) {
+        RocksDBSessions.Session session = this.session(type);
+        for (Iterator<BackendAction> it = mutation.mutation(type); it.hasNext(); ) {
+            BackendAction item = it.next();
+            BackendEntry entry = item.entry();
+            
+            // 根据Action类型调用不同的操作
+            switch (item.action()) {
+                case INSERT:
+                    table.insert(session, entry);
+                    break;
+                case APPEND:
+                    table.append(session, entry);  // 等同于insert
+                    break;
+                case DELETE:
+                    table.delete(session, entry);
+                    break;
+                case ELIMINATE:
+                    table.eliminate(session, entry);  // 等同于delete
+                    break;
+            }
+        }
+    }
+}
+```
+
+### 4. 具体的RocksDB操作
+
+```java
+// RocksDBTable.insert() - 写入操作
+public void insert(RocksDBSessions.Session session, BackendEntry entry) {
+    for (BackendColumn col : entry.columns()) {
+        // 对每个BackendColumn执行put操作
+        session.put(
+            this.table(),      // 表名（Column Family）
+            col.name,          // key: 列名的字节数组
+            col.value          // value: 列值的字节数组
+        );
+    }
+}
+
+// RocksDBTable.delete() - 删除操作
+public void delete(RocksDBSessions.Session session, BackendEntry entry) {
+    if (entry.columns().isEmpty()) {
+        // 如果没有列，删除整个entry
+        session.delete(this.table(), entry.id().asBytes());
+    } else {
+        // 删除指定的列
+        for (BackendColumn col : entry.columns()) {
+            session.delete(this.table(), col.name);
+        }
+    }
+}
+```
+
+### 5. Session操作 → WriteBatch
+
+```java
+// RocksDBStdSessions.Session.put()
+public void put(String table, byte[] key, byte[] value) {
+    try (OpenedRocksDB.CFHandle cf = cf(table)) {
+        // 添加到WriteBatch（不立即写入）
+        this.batch.put(cf.get(), key, value);
+    } catch (RocksDBException e) {
+        throw new BackendException(e);
+    }
+}
+
+// RocksDBStdSessions.Session.delete()
+public void delete(String table, byte[] key) {
+    try (OpenedRocksDB.CFHandle cf = cf(table)) {
+        // 添加到WriteBatch（不立即写入）
+        this.batch.delete(cf.get(), key);
+    } catch (RocksDBException e) {
+        throw new BackendException(e);
+    }
+}
+
+// RocksDBStdSessions.Session.commit() - 批量提交
+public Integer commit() {
+    int count = this.batch.count();
+    if (count <= 0) {
+        return 0;
+    }
+    
+    try {
+        // 一次性写入所有操作到RocksDB
+        rocksdb().write(this.writeOptions, this.batch);
+    } catch (RocksDBException e) {
+        throw new BackendException(e);
+    }
+    
+    // 清空batch
+    this.batch.clear();
+    return count;
+}
+```
+
+## 向量索引的具体映射示例
+
+### 写入向量索引
+
+```
+VectorBackendEntry {
+    type: VECTOR_INDEX
+    id: indexId_1
+    subId: vertexId_1
+    vectorId: "vertexId_1"
+    vector: [0.1, 0.2, 0.3, ...]
+    metricType: "L2"
+    dimension: 768
+}
+
+↓ entry.columns()
+
+BackendColumn[] {
+    {name: "vector".getBytes(),    value: [序列化后的float[]]},
+    {name: "metric".getBytes(),    value: "L2".getBytes()},
+    {name: "dimension".getBytes(), value: "768".getBytes()}
+}
+
+↓ session.put(table, key, value)
+
+WriteBatch {
+    put(CF_VECTOR_INDEX, "vector".getBytes(),    [序列化后的float[]]),
+    put(CF_VECTOR_INDEX, "metric".getBytes(),    "L2".getBytes()),
+    put(CF_VECTOR_INDEX, "dimension".getBytes(), "768".getBytes())
+}
+
+↓ rocksdb.write()
+
+RocksDB {
+    CF_VECTOR_INDEX: {
+        "vector"    → [序列化后的float[]],
+        "metric"    → "L2",
+        "dimension" → "768"
+    }
+}
+```
+
+### 删除向量索引
+
+```
+VectorBackendEntry {
+    type: VECTOR_INDEX
+    id: indexId_1
+    vector: []  // 空数组表示删除
+}
+
+↓ entry.columns()
+
+BackendColumn[] {
+    {name: "vector".getBytes(), value: []}
+}
+
+↓ session.delete(table, key)
+
+WriteBatch {
+    delete(CF_VECTOR_INDEX, "vector".getBytes())
+}
+
+↓ rocksdb.write()
+
+RocksDB {
+    CF_VECTOR_INDEX: {
+        "vector" → [已删除]
+    }
+}
+```
+
+## 关键点总结
+
+| 步骤 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| 1 | VectorBackendEntry | List<BackendColumn> | 调用columns()方法 |
+| 2 | BackendColumn | (table, key, value) | 提取name和value |
+| 3 | Action类型 | insert/delete | 决定操作类型 |
+| 4 | (table, key, value) | WriteBatch | 添加到批处理队列 |
+| 5 | WriteBatch | RocksDB | 一次性提交所有操作 |
+
+## 性能特点
+
+- **批处理**：所有操作先加入WriteBatch，最后一次性提交
+- **原子性**：WriteBatch中的所有操作要么全部成功，要么全部失败
+- **效率**：减少RocksDB的写入次数，提高吞吐量
+
+## 详细对照表
+
+### 表1: BackendEntry字段 → BackendColumn映射
+
+| BackendEntry字段 | 类型 | BackendColumn.name | BackendColumn.value | 说明 |
+|-----------------|------|------------------|-------------------|------|
+| vector | float[] | "vector" | 序列化后的byte[] | 向量数据 |
+| metricType | String | "metric" | "L2"/"COSINE"/"DOT" | 距离度量 |
+| dimension | int | "dimension" | "768" | 向量维度 |
+| id | Id | (entry.id()) | (col.name前缀) | 索引ID |
+| subId | Id | (entry.subId()) | (col.name前缀) | vertexId |
+
+### 表2: Action类型 → RocksDB操作映射
+
+| Action | 表方法 | Session方法 | WriteBatch操作 | 说明 |
+|--------|--------|-----------|--------------|------|
+| INSERT | insert() | put() | batch.put() | 插入新数据 |
+| APPEND | append() | put() | batch.put() | 追加数据（等同INSERT） |
+| DELETE | delete() | delete() | batch.delete() | 删除数据 |
+| ELIMINATE | eliminate() | delete() | batch.delete() | 消除数据（等同DELETE） |
+| UPDATE_IF_PRESENT | updateIfPresent() | put() | batch.put() | 存在时更新 |
+| UPDATE_IF_ABSENT | updateIfAbsent() | put() | batch.put() | 不存在时更新 |
+
diff --git "a/docs/hugegraph\345\220\221\351\207\217\347\264\242\345\274\225\350\256\276\350\256\241\346\226\207\346\241\243.md" "b/docs/hugegraph\345\220\221\351\207\217\347\264\242\345\274\225\350\256\276\350\256\241\346\226\207\346\241\243.md"
new file mode 100644
index 0000000000..e53447c1c0
--- /dev/null
+++ "b/docs/hugegraph\345\220\221\351\207\217\347\264\242\345\274\225\350\256\276\350\256\241\346\226\207\346\241\243.md"
@@ -0,0 +1,510 @@
+# HugeGraph 向量索引设计文档
+
+## 1. 概述
+
+### 1.1 设计目标
+
+在HugeGraph中实现向量索引功能，通过异步消费BackendMutation，构建jVector向量索引，支持高性能向量搜索。
+
+### 1.2 核心特性
+
+- **异步处理**：使用BlockingQueue + ExecutorService，不阻塞主流程
+- **三层恢复**：jVector持久化文件 + cf_vector_state + WAL/Raft Log，秒级恢复
+- **增量更新**：利用jVector增量能力，避免全量重建
+- **最终一致性**：支持单点和分布式部署
+
+### 1.3 核心流程
+
+```text
+写入 → RocksDB持久化 → 拦截器 → 队列(非阻塞) → 消费线程(批量) → jVector + cf_vector_state
+```
+
+## 2. 架构设计
+
+### 2.1 单点模式
+
+```mermaid
+graph TB
+    A["用户写入Vertex<br/>含向量属性"] --> B["GraphTransaction<br/>commit"]
+    B --> C["BackendMutation<br/>生成"]
+    C --> D["RocksDB<br/>持久化"]
+    D --> E["VectorIndexCoordinator<br/>拦截"]
+    E --> F["BlockingQueue<br/>容量10000<br/>非阻塞offer"]
+    F --> G["ExecutorService<br/>4个消费线程<br/>批量100条或1秒"]
+    G --> H["提取vector操作"]
+    H --> I["应用到jVector"]
+    H --> J["写入映射表"]
+    H --> K["更新本地watermark"]
+    I --> L["jVector索引"]
+    J --> M["RocksDB<br/>cf_vector_state"]
+    K --> N["本地文件<br/>apply.watermark"]
+
+    style A fill:#ffff99
+    style D fill:#99ff99
+    style F fill:#ffcccc
+    style G fill:#ffcccc
+    style L fill:#99ccff
+    style M fill:#99ccff
+    style N fill:#99ccff
+```
+
+**特点**：
+
+- 简单部署，无需分布式协调
+- 队列异步处理，不阻塞主流程
+- 批量消费，提高吞吐量
+- 轻量级WAL用于恢复
+- 本地搜索
+
+### 2.2 分布式模式
+
+```mermaid
+graph TB
+    A["Store Leader<br/>写入数据"] --> B["Raft Log<br/>持久化"]
+    B --> C["Vector Learner<br/>接收"]
+    C --> D["VectorIndexCoordinator<br/>拦截"]
+    D --> E["BlockingQueue<br/>容量10000<br/>非阻塞offer"]
+    E --> F["ExecutorService<br/>4个消费线程<br/>批量100条或1秒"]
+    F --> G["提取vector操作"]
+    G --> H["应用到jVector"]
+    G --> I["写入映射表"]
+    G --> J["更新本地watermark"]
+    H --> K["jVector索引"]
+    I --> L["RocksDB<br/>cf_vector_state"]
+    J --> M["本地文件<br/>apply.watermark"]
+
+    N["Server节点<br/>查询协调"] --> K
+    N --> L
+
+    style A fill:#ffff99
+    style B fill:#99ff99
+    style E fill:#ffcccc
+    style F fill:#ffcccc
+    style K fill:#99ccff
+    style L fill:#99ccff
+    style M fill:#99ccff
+    style N fill:#ffcccc
+```
+
+**特点**：
+
+- 高可用性，故障自动切换
+- 角色分离，故障隔离
+- 队列异步处理，批量消费
+- 基于Raft Log的异步同步
+- 最终一致性
+
+### 2.3 分布式恢复机制
+
+**关键前提**：
+
+1. **Partition 隔离**：每个 partition 有独立的 Raft Group 和 RocksDB 实例
+2. **Raft Index 作用域**：每个 partition 的 raftIndex 独立递增（从1开始）
+3. **RocksDB 可靠性**：由 Raft 保证，crash 后数据不丢失
+4. **cf_vector_state 可靠性**：存储在 RocksDB 中，随 RocksDB 一起恢复
+
+**恢复流程（每个 partition 独立执行）**：
+
+```mermaid
+graph TB
+    A[Partition启动] --> B{RocksDB恢复}
+    B --> C[cf_vector_state可用]
+    C --> D{jVector持久化文件存在?}
+
+    D -->|是| E[加载持久化文件]
+    D -->|否| F[创建空索引]
+
+    E --> G[扫描cf_vector_state<br/>找出所有记录]
+    F --> G
+
+    G --> H[判别并重放<br/>seq > apply_watermark]
+    H --> I[启动队列消费<br/>处理新的Raft Log]
+    I --> J[恢复完成]
+
+    style A fill:#ffcccc
+    style C fill:#99ff99
+    style J fill:#99ccf
+```
+
+**关键保证**：
+
+1. **Partition 独立性**：
+
+   - 每个 partition 独立恢复，互不影响
+   - Partition A crash 不影响 Partition B
+2. **Raft Index 隔离**：
+
+   - 每个 partition 的 raftIndex 独立递增
+   - cf_vector_state 的 sequence_number 就是 partition 内的 raftIndex
+3. **数据一致性**：
+
+   - RocksDB 由 Raft 保证一致性
+   - cf_vector_state 随 RocksDB 一起恢复
+   - jVector 从 cf_vector_state 重建，保证最终一致
+4. **Learner 角色恢复**：
+
+   - Learner crash 后，RocksDB 数据完整（Raft 同步）
+   - jVector 索引可能不完整（异步构建）
+   - 从 cf_vector_state 重建 jVector 即可
+
+**潜在问题与解决**：
+
+
+| 问题                    | 场景                                   | 解决方案                                 |
+| ----------------------- | -------------------------------------- | ---------------------------------------- |
+| Raft Log 压缩           | cf_vector_state 损坏且 Raft Log 已压缩 | cf_vector_state 随 RocksDB Snapshot 备份 |
+| 多 Partition 同时 crash | 集群故障                               | 每个 partition 独立恢复，并发执行        |
+| Learner 长时间离线      | Raft Log 已压缩                        | 从 Leader 的 RocksDB Snapshot 恢复       |
+
+## 3. 核心组件
+
+### 3.1 cf_vector_state映射表
+
+**三重角色**：
+
+1. **ID映射**：vector_id (jVector ordinal) → vertex_id
+2. **状态记录**：记录每个向量的状态和sequence_number
+3. **恢复基础**：高精度恢复点
+
+**存储结构**：
+
+存储结构（cf_vector_state）：
+
+
+| 项目            | 说明                                                 |
+| --------------- | ---------------------------------------------------- |
+| CF              | cf_vector_state                                      |
+| Key             | vector_id（jVector ordinal, int）                    |
+| Value.vertex_id | 顶点唯一标识（vertex_id）                            |
+| Value.seq       | sequence_number（单机: RocksSeq；分布式: RaftIndex） |
+| Value.status    | ACTIVE / DELETED                                     |
+| Value.timestamp | 写入/更新时间戳                                      |
+
+示例（文字化）：
+
+- 新增：写入 → BackendMutation(seq=100) → `addGraphNode(ordinal=5)` → cf_vector_state[5] = {vertex_id=v1, seq=100, status=ACTIVE, ...}
+- 更新：写入 → BackendMutation(seq=200) → `updateVector(ordinal=5)` → cf_vector_state[5] = {vertex_id=v1, seq=200, status=ACTIVE, ...}
+
+1. **删除时标记版本**：
+
+- 删除：写入 → BackendMutation(seq=300) → `markNodeDeleted(ordinal=5)` → cf_vector_state[5] = {vertex_id=v1, seq=300, status=DELETED, ...}
+
+**版本号作用** ：
+
+- 确定哪些操作已应用到jVector
+- 恢复时计算增量范围（Delta）
+- 避免重复应用相同操作
+
+## 4. 线程与任务调度（与现有 Task 调度方案结合）
+
+### 4.1 总览图
+
+```mermaid
+flowchart TD
+    W[写路径/变更事件] --> B[提交向量类 Job<br/>VectorIngest/Rebuild/Flush/Validate/Compact]
+    B --> S{TaskScheduler}
+    S -->|local| E1[StandardTaskScheduler\n taskExecutor]
+    S -->|distributed| E2[DistributedTaskScheduler\n olapTaskExecutor]
+    E1 --> J[批处理 N 条或 T 毫秒\n 推进 watermark]
+    E2 --> J
+```
+
+### 4.2 任务类型与路由表
+
+
+| Job 类型          | 职责                          | type()     | 路由执行器（local / distributed） | 批处理粒度                          |
+| ----------------- | ----------------------------- | ---------- | --------------------------------- | ----------------------------------- |
+| VectorIngestJob   | 增量摄取/追赶，推进 watermark | "computer" | taskExecutor / olapTaskExecutor   | N 条或 T 毫秒                       |
+| VectorRebuildJob  | 全量重建、切换映射            | "computer" | taskExecutor / olapTaskExecutor   | 分阶段（SCAN/BUILD/CLEANUP/SWITCH） |
+| VectorFlushJob    | 触发 jVector 持久化           | "computer" | taskExecutor / olapTaskExecutor   | 小批、快速                          |
+| VectorValidateJob | 一致性校验、报告              | "computer" | taskExecutor / olapTaskExecutor   | 取样/分片                           |
+| VectorCompactJob  | 删除收敛/图修剪               | "computer" | taskExecutor / olapTaskExecutor   | 受限时长                            |
+
+### 4.3 提交流程与去重
+
+1. 触发：写路径/WAL 监听到向量变更，尝试提交对应 Job（按 index/partition 粒度）
+2. 去重：查询 Task 表，若已存在同键（graph,indexId,partitionId,jobType）且状态 ∈ {NEW, QUEUED, RUNNING}，则跳过提交
+3. 执行：单次处理固定上限【N 条或 T 毫秒】，期间推进 watermark；批内失败记录并跳过（幂等保障）
+4. 续作：若 backlog 仍大，则在任务尾部轻量重投下一次 Ingest；或等待下一次写路径触发
+5. 观测：`backlog.gauge = last_committed_seq - watermark`，用于背压与告警
+
+### 4.4 队列与调度整合
+
+- 不新增“向量专用线程池/消费队列”，统一通过 HugeTask 调度承担异步处理
+- 分布式：`type() = computer` 的 Job 自动路由到 `olapTaskExecutor`，线程忙则保持 NEW（天然背压）
+- 本地：所有 Job 走 `taskExecutor`，通过“批大小/时间片”限制单次占用时长
+- 可选：如需短暂缓冲，仅作为“触发信号”，实际处理仍落在 Job 中
+
+### 4.5 参数与背压
+
+
+| 参数                        | 默认      | 说明                       |
+| --------------------------- | --------- | -------------------------- |
+| vector.ingest.batch_size    | 100~1000  | 每次处理的记录数上限       |
+| vector.ingest.time_slice_ms | 100~500ms | 单次任务的时间片上限       |
+| vector.cleanup.enable       | true      | 是否在合适窗口触发 cleanup |
+
+背压行为：
+
+- 分布式：执行器线程不空闲时，NEW 任务不启动，等待下一轮（无需额外限流）
+- 本地：通过批大小/时间片控制任务占用，避免长时间独占
+
+### 4.6 指标与观测
+
+
+| 指标                                                    | 含义                                       |
+| ------------------------------------------------------- | ------------------------------------------ |
+| hugegraph.vector.job.submitted/success/failed/cancelled | 任务生命周期统计                           |
+| hugegraph.vector.job.exec.timer                         | 执行耗时分布                               |
+| hugegraph.vector.backlog.gauge                          | 积压评估（last_committed_seq - watermark） |
+| 任务命名包含 indexId/partitionId                        | 便于排查定位                               |
+
+### 4.7 代码流程概览（示意）
+
+```mermaid
+sequenceDiagram
+    participant W as 写路径/WAL
+    participant JB as JobBuilder
+    participant TS as TaskScheduler
+    participant EX as Executor
+    W->>JB: 监听到向量变更
+    JB->>TS: schedule(VectorIngestJob)
+    TS->>EX: 按 type=computer 路由（local/distributed）
+    EX->>EX: 批处理 N 条或 T 毫秒
+    EX->>EX: 推进 watermark（幂等）
+    EX-->>JB: backlog > 0 ？轻量重投
+```
+
+### 4.8 事件源（队列）与读取
+
+- 术语约定：本文中的“队列”不限定为内存 BlockingQueue。为了具备可恢复与确定性，推荐以“可持久读取的事件源”承担队列角色。
+- 调度边界：不修改调度器与执行器，只定义向量类 Job 的读取来源与批处理方式。
+
+
+| 事件源（队列）              | 耐久性 | 顺序保证（分区内） | 读取方式                      | 推荐度     | 说明                                              |
+| --------------------------- | ------ | ------------------ | ----------------------------- | ---------- | ------------------------------------------------- |
+| cf_vector_seq_index（建议） | 持久化 | 严格递增（按 seq） | scanRange(W+1, W+N)           | ★★★★☆ | 与 cf_vector_state 同批原子写入，天然“队列”     |
+| cf_vector_state（兜底）     | 持久化 | 无全序（需过滤）   | 全量遍历后按 seq > W 过滤     | ★★☆☆☆ | 无二级索引时的兼容方案，需时间片/游标控制         |
+| Raft Log（仅特定场景）      | 持久化 | 严格递增           | 读取 partition Raft 日志      | ★★☆☆☆ | 分布式场景可行，但实现与权限更重，优先用 seq 索引 |
+| recent_event_buffer（可选） | 内存   | 近似时间顺序       | 批量poll/peek（不依赖正确性） | ★☆☆☆☆ | 仅作触发/加速信号；正确性仍依赖持久事件源         |
+
+说明：W 为 watermark（本地“已应用上界”）。若存在 cf_vector_seq_index，则它就是“队列”。
+
+### 4.9 消费与向量构建（批处理流程）
+
+- 起点：S = W（当前 watermark）
+- 读取：从首选事件源按 seq 升序读取，至多 N 条或 T 毫秒（二者其一到达即止）
+- 应用：
+  - ACTIVE：获取向量值（从顶点属性或缓存），判断 ordinal 是否存在 → addGraphNode 或 updateVector
+  - DELETED：若存在则 markNodeDeleted
+- 推进：批内周期性地推进 W = max(W, seq)，并按策略持久化（原子重命名，必要时 fsync）
+- 续作：若 backlog > 0，则依赖调度器空闲时再启动下一批（无需常驻线程）
+
+```mermaid
+sequenceDiagram
+  participant ES as 事件源
+  participant JB as VectorIngestJob
+  participant JV as jVector
+  participant W as Watermark
+  JB->>ES: scan seq ∈ (W, W+N]
+  ES-->>JB: 事件批（按 seq 升序）
+  loop 批内
+    JB->>JV: ACTIVE: add/update；DELETED: markDeleted
+    JV-->>JB: ok/skip
+    JB->>W: W = max(W, seq)
+  end
+  JB->>W: 条件满足时持久化 W
+```
+
+实施注意：
+
+- 每个 graph/indexId/partitionId 至多允许一个 IngestJob RUNNING，避免并发写 jVector（提交前去重 + 运行时轻锁）
+- 读放大控制：无二级索引时，记录“上次扫描游标”并限定时间片，逐批推进，避免每次全表扫
+- 取数路径：向量值可来自 Vertex 属性或增量缓存；优先使用一致性读（由存储层保证提交后可见）
+
+### 4.10 与任务分配的关系（澄清）
+
+- 本方案不改变 HugeGraph 的任务分配策略：
+  - local：仍在 taskExecutor 上执行；靠批大小/时间片防止长占用
+  - distributed：向量类 Job 标记 type()="computer"，自动路由至 olapTaskExecutor（仅此类 Job 如此，其他 Job 类型不变）
+- 背压保持：当执行器线程忙时，NEW 任务不启动；IngestJob 不需要常驻消费线程，由调度器在空闲时分批推进
+
+### 4.11 队列与恢复的衔接
+
+- 启动/恢复完成后，即以 4.9 的批处理方式从事件源“继续消费”直至追平 last_committed_seq
+- 三种常见状态：
+  - 冷启动：W=0 → 通过事件源快速补齐
+  - 热重启：W≈last_committed_seq → 少量补差
+  - 全量重建后切换：RebuildJob 完成后，IngestJob 从新映射/新 W 继续增量
+
+## 5. 恢复机制
+
+### 5.1 三层组件
+
+
+| 层级 | 组件              | 作用         | 更新频率           | 恢复时间 |
+| ---- | ----------------- | ------------ | ------------------ | -------- |
+| 1    | jVector持久化文件 | 快速恢复点   | 每10000操作或5分钟 | 秒级     |
+| 2    | cf_vector_state   | 高精度恢复点 | 每个操作后         | 毫秒级   |
+| 3    | WAL/Raft Log      | 实时增量源   | 实时               | 毫秒级   |
+
+### 5.2 恢复四步骤（利用 sequence_number 判别）
+
+**核心原理**：jVector 没有版本概念，通过 cf_vector_state 的 sequence_number 来判别哪些操作需要重放
+
+```mermaid
+graph TB
+    A["步骤1: 加载持久化文件<br/>jVector.load"] --> B["步骤2: 扫描映射表<br/>读取cf_vector_state<br/>找出所有记录"]
+    B --> C["步骤3: 判别并重放<br/>对每条记录判断seq"]
+    C --> D["步骤4: 连接队列<br/>处理新操作"]
+    D --> E["恢复完成"]
+
+    style A fill:#99ff99
+    style C fill:#ffcc99
+    style E fill:#99ccff
+```
+
+#### 详细步骤
+
+#### 步骤1：加载持久化文件
+
+- 若存在持久化文件：加载 jVector 索引文件
+- 读取本地 apply_watermark（默认 0）
+- 后续所有判断均以该水位作为“已应用上界”
+
+#### 步骤2：扫描映射表
+
+- 扫描 cf_vector_state 全表，收集 ordinal→state 映射（或按 seq 二级索引顺序扫描）
+- state = {vertex_id, seq, status, timestamp}
+- 如存在 cf_vector_seq_index，可直接按 seq 从小到大遍历，减少随机访问
+
+#### 步骤3：判别并重放（关键逻辑）
+
+```mermaid
+flowchart TB
+    subgraph 增量修复流程
+        direction TB
+        S[遍历每条 state 记录] --> C{state.seq > 快照版本 W?}
+        C -- 否 --> SKIP[跳过, 已在快照中]
+        C -- 是 --> CN{索引中已存在该节点?}
+
+        CN -- 是 --> T_Exist{记录的状态是什么?}
+        T_Exist -- ACTIVE --> U[更新向量 updateVector]
+        T_Exist -- DELETED --> MD[标记节点为删除 markDeleted]
+
+        CN -- 否 --> T_NotExist{记录的状态是什么?}
+        T_NotExist -- ACTIVE --> A[添加节点 addGraphNode]
+        T_NotExist -- DELETED --> NOP[无操作, 状态一致]
+    end
+```
+
+#### 步骤4：进入增量任务路径
+
+- 恢复完成后，转入第 4 章所述的 VectorIngestJob 正常增量处理路径（不依赖常驻消费线程/队列）
+
+#### 关键判别点
+
+1. **seq 判别**：`state.seq > apply_watermark` → 需要重放
+2. **status 判别**：
+   - `ACTIVE` → 需要添加或更新向量
+   - `DELETED` → 需要删除向量
+3. **新增 vs 更新判别**（针对 ACTIVE）：
+   - `index.containsNode(ordinal)` 返回 true → 更新操作
+   - `index.containsNode(ordinal)` 返回 false → 新增操作
+
+**为什么需要判别新增 vs 更新？**
+
+- jVector 的 `addGraphNode()` 和 `updateVector()` 是不同的 API
+- 如果对已存在的 ordinal 调用 `addGraphNode()`，可能会报错或行为未定义
+- 通过 `containsNode()` 检查可以确保调用正确的 API
+
+**总恢复时间**：秒级（vs 全量重建：分钟~小时级）
+
+### 5.3 本地 Watermark（必选）
+
+- 定义：last_applied_seq，表示“本节点上该 partition+index 已应用到 jVector 的最新序号”
+- 存放位置：节点本地 sidecar 文件，建议与索引文件同目录，例如：
+  - data/vector_index/{partition}/{index_id}/apply.watermark
+- 格式与容错：
+  - 文本或 8 字节整型均可（示例用文本，内容为十进制 long）
+  - 不存在或解析失败则视为 0（从头补齐，幂等）
+- 读取流程（启动时）：
+  - 如果文件存在 → 读取为 W；不存在 → W=0
+- 写入与落盘策略（运行中）：
+  - 每处理一批（N 条或 T 毫秒）推进一次到当前批最大 seq
+  - 使用“临时文件 + 原子重命名（atomic rename）”写法，必要时调用 fsync 确保落盘
+  - 单 writer 线程推进，避免并发竞态
+- 宕机/丢失语义：
+  - 最多回退到上一次写入的 W，导致多做幂等重放；不会影响正确性
+
+实现要点（不写代码）：
+
+- 路径：data/vector_index/{partition}/{index_id}/apply.watermark
+- 读取：若文件存在读取为 long，否则视为 0（兜底）
+- 写入：临时文件 + 原子重命名（atomic move），必要时 fsync 保证落盘
+- 并发：单 writer 推进，避免竞态
+
+恢复时的使用：
+
+```mermaid
+sequenceDiagram
+  participant W as Watermark
+  participant S as StateScan
+  participant J as jVector
+  W->>S: 读取 W
+  S->>S: 遍历 seq > W 的记录（或全量扫后过滤）
+  S->>J: 按状态应用（add/update/markDeleted）
+  J->>W: 推进 W = max(W, seq)，按策略持久化
+```
+
+### 5.4 可选优化：按 seq 的二级索引与提交水位
+
+- cf_vector_seq_index（推荐）：
+
+  - 结构：CF key = seq（long，按序）→ value = {index_id, ordinal, status}
+  - 写入路径：与 cf_vector_state 同一 batch 原子写入，保证确定性
+  - 恢复路径：从 W+1 开始顺序扫描至末尾，显著减少无效遍历
+- 写入路径：与 cf_vector_state 同批次原子写入 cf_vector_seq_index（key=seq，value={index_id, ordinal, status}）
+- 恢复扫描：从 W+1 开始顺序扫描 seq 索引，应用到 jVector，推进并周期性持久化 W
+- last_committed_seq（可选）：
+
+  - 定义：该 partition/index 已提交的最新 seq 上界
+  - 获取：可从 cf_vector_seq_index 的最大 key 推导，或另设 cf_vector_meta.last_committed_seq O(1) 读取
+  - 作用：用于评估“落后差值”和进度观测；不参与正确性判定
+
+### 5.5 兜底策略
+
+- ✅ 持久化文件完整 → 快速加载 + 增量修复（秒级）
+- ✅ 持久化文件损坏 → 从cf_vector_state重建（分钟级）
+- ✅ cf_vector_state损坏 → 从WAL/Raft Log重放（分钟级）
+- ✅ 全部损坏 → 从零构建（小时级，但数据不丢失）
+
+## 6. 剩余任务与安排
+
+
+| 任务项                              | 范围/说明                                                       | 优先级 | Owner | 里程碑 |
+| ----------------------------------- | --------------------------------------------------------------- | ------ | ----- | ------ |
+| VectorIngestJob 提交流程与去重      | 按 index/partition 去重；批处理 N 条或 T 毫秒；推进 watermark   | P0     | TBD   | M1     |
+| Rebuild/Flush/Validate/Compact Jobs | 定义参数、权限与幂等；长任务分阶段（SCAN/BUILD/CLEANUP/SWITCH） | P1     | TBD   | M2     |
+| cf_vector_state 存储与 API          | 建表、读写、扫描、求最大 seq；可选二级索引 cf_vector_seq_index  | P0     | TBD   | M1     |
+| Watermark 持久化                    | 本地水位读写（apply_watermark）；写入原子性与崩溃恢复           | P0     | TBD   | M1     |
+| 检索回译链路                        | search 结果 ordinal→vertex_id 回译返回 {vertex_id, score}      | P0     | TBD   | M1     |
+| 持久化文件管理                      | 定期落盘、加载校验、异常兜底；文件格式与校验信息                | P1     | TBD   | M2     |
+| 恢复流程                            | 加载文件→增量修复→处理新操作；分布式分区独立恢复              | P0     | TBD   | M2     |
+| 指标与告警                          | 任务级统计、backlog 指标、失败重试与告警                        | P0     | TBD   | M1     |
+| 配置与参数                          | 批大小、时间片、cleanup 开关；不新增线程池配置                  | P0     | TBD   | M1     |
+
+## 7. 后续优化步骤
+
+- 索引副本选择策略
+
+  - 为每个 partition 配置 index_replicas = 1~2（如 Leader + 1 热备）；减少重复 CPU 开销
+  - 查询路由到“索引副本”，故障时由热备接管
+- 持久化文件优化
+
+  - 增量落盘、并行加载、文件格式压缩；携带稀疏校验信息（校验/定位损坏）
+- 恢复加速
+
+  - 先加载持久化文件再并行扫描 cf_vector_state；按 partition/范围分片重放
+
+<!-- 原第11章内容已合并进第4章（线程与任务调度）。本节移除以避免重复。 -->
diff --git "a/docs/\344\270\211\347\247\215\346\201\242\345\244\215\346\226\271\346\241\210\345\257\271\346\257\224.md" "b/docs/\344\270\211\347\247\215\346\201\242\345\244\215\346\226\271\346\241\210\345\257\271\346\257\224.md"
new file mode 100644
index 0000000000..081a83cd8f
--- /dev/null
+++ "b/docs/\344\270\211\347\247\215\346\201\242\345\244\215\346\226\271\346\241\210\345\257\271\346\257\224.md"
@@ -0,0 +1,395 @@
+# 三种恢复方案对比分析
+
+## 问题背景
+
+你提出的核心问题：
+- Offset存储在哪里？
+- 增量扫描如何实现？
+- 是否需要全量更新？
+
+这三个问题涉及三种不同的恢复方案。
+
+## 方案对比
+
+### 方案1：全量重建（❌ 不推荐）
+
+```
+特点：
+  - 每次启动都扫描所有vertex
+  - 重新构建整个jVector索引
+  - 无需维护offset
+  - 实现简单
+```
+
+**实现代码**：
+
+```java
+public class VectorIndexBuilder {
+    public void rebuildAll() {
+        // 1. 扫描所有vertex
+        Iterator<Vertex> vertices = graph.vertices();
+        
+        // 2. 提取向量属性
+        while (vertices.hasNext()) {
+            Vertex v = vertices.next();
+            float[] vector = v.getProperty("embedding");
+            if (vector != null) {
+                // 3. 添加到jVector
+                jvector.add(v.id(), vector);
+            }
+        }
+    }
+}
+```
+
+**性能分析**：
+
+| 指标 | 值 |
+|------|-----|
+| 时间复杂度 | O(n) |
+| 空间复杂度 | O(1) |
+| 恢复时间 | 几分钟到几小时 |
+| 数据一致性 | 最终一致 |
+| 适用场景 | 小数据集 |
+
+**问题**：
+- ❌ 对于1000万vertex，恢复可能需要几分钟
+- ❌ 期间无法提供查询服务
+- ❌ 浪费计算资源
+- ❌ 不适合大规模数据
+
+---
+
+### 方案2：增量恢复（✅ 推荐）
+
+```
+特点：
+  - 维护offset（已处理到哪里）
+  - 只处理新增操作
+  - 从RocksDB WAL读取
+  - 实现复杂度中等
+```
+
+**实现代码**：
+
+```java
+public class VectorIndexUpdater {
+    private final RocksDB rocksDB;
+    private final VectorOffsetManager offsetManager;
+    
+    /**
+     * 启动时的增量恢复
+     */
+    public void recoverOnStartup() {
+        // 1. 加载上次处理的offset
+        long lastProcessedSeq = offsetManager.loadOffset();
+        
+        // 2. 获取当前最新的序列号
+        long currentSeq = rocksDB.getLatestSequenceNumber();
+        
+        // 3. 只处理新增的操作
+        for (long seq = lastProcessedSeq + 1; seq <= currentSeq; seq++) {
+            BackendMutation mutation = rocksDB.getWALEntry(seq);
+            if (hasVectorOperation(mutation)) {
+                processVectorMutation(mutation);
+            }
+        }
+        
+        // 4. 更新offset
+        offsetManager.saveOffset(currentSeq);
+    }
+}
+```
+
+**Offset存储**：
+
+```java
+public class VectorOffsetManager {
+    private static final String OFFSET_CF = "vector_offset";
+    private static final String OFFSET_KEY = "last_processed_seq";
+    
+    /**
+     * 保存offset到RocksDB
+     * 这样Crash后也能恢复
+     */
+    public void saveOffset(long seq) {
+        rocksDB.put(OFFSET_CF, OFFSET_KEY.getBytes(), 
+                    String.valueOf(seq).getBytes());
+    }
+    
+    /**
+     * 加载offset
+     */
+    public long loadOffset() {
+        byte[] value = rocksDB.get(OFFSET_CF, OFFSET_KEY.getBytes());
+        if (value == null) {
+            return 0; // 首次启动
+        }
+        return Long.parseLong(new String(value));
+    }
+}
+```
+
+**性能分析**：
+
+| 指标 | 值 |
+|------|-----|
+| 时间复杂度 | O(m) |
+| 空间复杂度 | O(1) |
+| 恢复时间 | 几秒到几十秒 |
+| 数据一致性 | 最终一致 |
+| 适用场景 | 大数据集 |
+
+**优势**：
+- ✅ m << n，恢复快得多
+- ✅ 对于1000万vertex，只需处理新增操作
+- ✅ 恢复时间从几分钟降低到几秒
+- ✅ 适合大规模数据
+
+**Crash场景**：
+
+```
+场景：Crash前处理了seq=102，但offset还是101
+
+恢复时：
+  1. 加载offset = 101
+  2. 从WAL读取seq 102-currentSeq的操作
+  3. 重新处理seq=102
+  4. 结果：可能重复处理，但由于幂等性，结果一致
+
+解决方案：
+  使用WriteBatch原子提交：
+  - 向量操作写入jVector
+  - offset写入RocksDB
+  - 一起提交，保证原子性
+```
+
+---
+
+### 方案3：混合方案（✅ 最优）
+
+```
+特点：
+  - 结合增量恢复和定期全量检查
+  - 维护offset
+  - 定期验证一致性
+  - 实现复杂度高
+```
+
+**实现代码**：
+
+```java
+public class VectorIndexManager {
+    private final VectorOffsetManager offsetManager;
+    private final ScheduledExecutorService scheduler;
+    
+    /**
+     * 启动时的增量恢复
+     */
+    public void recoverOnStartup() {
+        // 使用增量恢复
+        incrementalRecover();
+        
+        // 启动定期检查任务
+        scheduler.scheduleAtFixedRate(
+            this::verifyConsistency,
+            1, // 初始延迟
+            24, // 周期
+            TimeUnit.HOURS
+        );
+    }
+    
+    /**
+     * 定期验证一致性
+     */
+    private void verifyConsistency() {
+        // 1. 采样检查
+        List<Vertex> samples = graph.sampleVertices(1000);
+        
+        // 2. 验证向量是否在jVector中
+        for (Vertex v : samples) {
+            float[] vector = v.getProperty("embedding");
+            if (vector != null) {
+                boolean exists = jvector.contains(v.id());
+                if (!exists) {
+                    // 发现不一致，修复
+                    jvector.add(v.id(), vector);
+                }
+            }
+        }
+    }
+}
+```
+
+**性能分析**：
+
+| 指标 | 值 |
+|------|-----|
+| 时间复杂度 | O(m) + O(sample) |
+| 空间复杂度 | O(1) |
+| 恢复时间 | 几秒到几十秒 |
+| 数据一致性 | 强一致 |
+| 适用场景 | 超大规模数据 |
+
+**优势**：
+- ✅ 快速恢复（增量）
+- ✅ 定期验证（一致性）
+- ✅ 发现并修复不一致
+- ✅ 最高的可靠性
+
+---
+
+## 详细对比表
+
+| 特性 | 全量重建 | 增量恢复 | 混合方案 |
+|------|---------|---------|---------|
+| **恢复时间** | 几分钟-几小时 | 几秒-几十秒 | 几秒-几十秒 |
+| **Offset维护** | 无 | 必需 | 必需 |
+| **实现复杂度** | 低 | 中 | 高 |
+| **数据一致性** | 最终一致 | 最终一致 | 强一致 |
+| **资源消耗** | 高 | 低 | 中 |
+| **适用数据量** | <100万 | >100万 | >1000万 |
+| **Crash恢复** | 完整重建 | 增量恢复 | 增量恢复+验证 |
+| **查询延迟** | 恢复期间无法查询 | 快速恢复 | 快速恢复 |
+
+---
+
+## 推荐方案
+
+### 单点模式：增量恢复
+
+```
+原因：
+  1. 实现相对简单
+  2. 恢复快速
+  3. 资源消耗低
+  4. 适合大多数场景
+
+实现步骤：
+  1. 在RocksDB中创建vector_offset Column Family
+  2. 实现VectorOffsetManager
+  3. 启动时调用recoverOnStartup()
+  4. 每次处理操作后更新offset
+```
+
+### 分布式模式：增量恢复
+
+```
+原因：
+  1. Raft Log已经提供了持久化
+  2. 状态机可以存储offset
+  3. 自动处理分布式一致性
+  4. 无需额外的offset存储
+
+实现步骤：
+  1. 在状态机中维护lastProcessedIndex
+  2. 启动时从Raft Log恢复
+  3. 每次onApply时更新lastProcessedIndex
+  4. 自动处理Crash恢复
+```
+
+### 超大规模数据：混合方案
+
+```
+原因：
+  1. 增量恢复保证快速启动
+  2. 定期验证保证一致性
+  3. 采样检查降低开销
+  4. 最高的可靠性
+
+实现步骤：
+  1. 实现增量恢复
+  2. 启动定期验证任务
+  3. 采样检查而不是全量检查
+  4. 发现不一致时修复
+```
+
+---
+
+## 关键实现细节
+
+### 1. Offset的原子性
+
+```java
+// ❌ 错误：可能丢失操作
+processVectorMutation(mutation);
+offsetManager.saveOffset(seq); // 如果这里Crash，offset不会更新
+
+// ✅ 正确：原子提交
+WriteBatch batch = new WriteBatch();
+batch.put(vectorCF, key, value); // 向量操作
+batch.put(offsetCF, offsetKey, offsetValue); // offset
+rocksDB.write(batch); // 原子提交
+```
+
+### 2. 幂等性处理
+
+```java
+// 由于可能重复处理，必须保证幂等性
+public void processVectorMutation(BackendMutation mutation) {
+    for (BackendAction action : mutation.getActions()) {
+        if (action.isAppend()) {
+            // 使用put而不是add，保证幂等性
+            jvector.put(vertexId, vector);
+        } else if (action.isEliminate()) {
+            // 删除操作也是幂等的
+            jvector.delete(vertexId);
+        }
+    }
+}
+```
+
+### 3. 监控和告警
+
+```java
+public class VectorOffsetMonitor {
+    /**
+     * 监控offset lag
+     */
+    public void monitorLag() {
+        long lastProcessedSeq = offsetManager.loadOffset();
+        long currentSeq = rocksDB.getLatestSequenceNumber();
+        long lag = currentSeq - lastProcessedSeq;
+        
+        if (lag > THRESHOLD) {
+            // 告警：offset落后太多
+            alert("Vector index lag too high: " + lag);
+        }
+    }
+}
+```
+
+---
+
+## 总结
+
+### 核心答案
+
+1. **Offset存储在哪里？**
+   - 单点：RocksDB的vector_offset Column Family
+   - 分布式：Raft状态机
+
+2. **增量扫描如何实现？**
+   - 加载lastProcessedSeq
+   - 获取currentSeq
+   - 从WAL读取seq范围内的操作
+   - 不需要全量扫描
+
+3. **是否需要全量更新？**
+   - 不需要！
+   - 只处理新增操作
+   - 时间复杂度O(m)，m是新增操作数
+   - m << n（vertex总数），所以快得多
+
+### 性能对比
+
+```
+全量重建：O(n) = 1000万 vertex = 几分钟
+增量恢复：O(m) = 1万 新操作 = 几秒
+性能提升：100倍以上
+```
+
+### 立即可用的实现
+
+已提供完整的代码示例，可直接用于实现。
+
diff --git "a/docs/\345\217\214\345\220\221\346\230\240\345\260\204\350\241\250\350\256\276\350\256\241.md" "b/docs/\345\217\214\345\220\221\346\230\240\345\260\204\350\241\250\350\256\276\350\256\241.md"
new file mode 100644
index 0000000000..491b716980
--- /dev/null
+++ "b/docs/\345\217\214\345\220\221\346\230\240\345\260\204\350\241\250\350\256\276\350\256\241.md"
@@ -0,0 +1,254 @@
+# 双向映射表设计 - vertexId ↔ vectorId
+
+## 问题背景
+
+### 为什么需要映射表？
+
+1. **jVector的限制**：
+   - jVector内部使用自己的ID系统（vectorId）
+   - 向量搜索返回的是vectorId列表
+   - 用户需要的是vertexId（业务ID）
+
+2. **数据转换需求**：
+   - 写入时：vertexId → vectorId（存储映射）
+   - 查询时：vectorId → vertexId（查询转换）
+   - 删除时：vertexId → vectorId（查找映射）
+
+## 存储设计
+
+### RocksDB Column Family
+
+```
+Column Family: vector_mapping
+
+双向存储：
+  Key: "vertex_id:" + vertexId
+  Value: vectorId
+  
+  Key: "vector_id:" + vectorId
+  Value: vertexId
+```
+
+### 为什么双向存储？
+
+| 操作 | 需要的映射 | 查询方向 |
+|------|----------|--------|
+| **写入** | vertexId → vectorId | 单向 |
+| **查询** | vectorId → vertexId | 反向 |
+| **删除** | vertexId → vectorId | 单向 |
+| **恢复** | 两个方向都需要 | 双向 |
+
+## 实现细节
+
+### VectorMappingManager
+
+```java
+public class VectorMappingManager {
+    
+    private final RocksDB rocksDB;
+    private final ColumnFamilyHandle mappingCF;
+    
+    /**
+     * 写入映射关系
+     * 在向jVector添加向量后调用
+     */
+    public void putMapping(String vertexId, long vectorId) {
+        // 正向映射：vertexId → vectorId
+        rocksDB.put(mappingCF, 
+            ("vertex_id:" + vertexId).getBytes(), 
+            String.valueOf(vectorId).getBytes());
+        
+        // 反向映射：vectorId → vertexId
+        rocksDB.put(mappingCF, 
+            ("vector_id:" + vectorId).getBytes(), 
+            vertexId.getBytes());
+    }
+    
+    /**
+     * 删除映射关系
+     * 在从jVector删除向量后调用
+     */
+    public void deleteMapping(String vertexId, long vectorId) {
+        rocksDB.delete(mappingCF, ("vertex_id:" + vertexId).getBytes());
+        rocksDB.delete(mappingCF, ("vector_id:" + vectorId).getBytes());
+    }
+    
+    /**
+     * 根据vertexId查询vectorId
+     * 用于删除操作
+     */
+    public long getVectorId(String vertexId) {
+        byte[] value = rocksDB.get(mappingCF, 
+            ("vertex_id:" + vertexId).getBytes());
+        if (value == null) {
+            throw new VectorException("Vector not found for vertex: " + vertexId);
+        }
+        return Long.parseLong(new String(value));
+    }
+    
+    /**
+     * 根据vectorId查询vertexId
+     * 用于查询结果转换
+     */
+    public String getVertexId(long vectorId) {
+        byte[] value = rocksDB.get(mappingCF, 
+            ("vector_id:" + vectorId).getBytes());
+        if (value == null) {
+            throw new VectorException("Vertex not found for vector: " + vectorId);
+        }
+        return new String(value);
+    }
+    
+    /**
+     * 批量查询vertexId
+     * 用于查询结果转换
+     */
+    public List<String> getVertexIds(List<Long> vectorIds) {
+        return vectorIds.stream()
+            .map(this::getVertexId)
+            .collect(Collectors.toList());
+    }
+}
+```
+
+## 工作流程
+
+### 写入流程
+
+```
+1. 用户写入Vertex（含向量属性）
+   ↓
+2. GraphTransaction.commit()
+   ↓
+3. VectorIndexCoordinator拦截
+   ↓
+4. VectorManager处理向量操作
+   ↓
+5. 向jVector添加向量 → 获得vectorId
+   ↓
+6. VectorMappingManager.putMapping(vertexId, vectorId)
+   ↓
+7. 记录offset到RocksDB
+```
+
+### 查询流程
+
+```
+1. 用户调用VectorSearchAPI搜索
+   ↓
+2. jVector搜索 → 返回TopK的vectorId列表
+   ↓
+3. VectorMappingManager.getVertexIds(vectorIds)
+   ↓
+4. 返回vertexId列表给用户
+```
+
+### 删除流程
+
+```
+1. 用户删除Vertex
+   ↓
+2. GraphTransaction.commit()
+   ↓
+3. VectorIndexCoordinator拦截
+   ↓
+4. VectorManager处理删除操作
+   ↓
+5. VectorMappingManager.getVectorId(vertexId) → 获得vectorId
+   ↓
+6. 从jVector删除向量
+   ↓
+7. VectorMappingManager.deleteMapping(vertexId, vectorId)
+   ↓
+8. 记录offset到RocksDB
+```
+
+## 恢复时的处理
+
+### Crash恢复流程
+
+```
+启动时：
+  1. 读取offset
+  2. 扫描RocksDB中的Vertex数据
+  3. 对于每个包含向量属性的Vertex：
+     a. 提取向量数据
+     b. 向jVector添加向量 → 获得新的vectorId
+     c. 更新映射表（旧的vectorId可能不同）
+     d. 记录新的offset
+```
+
+### 为什么vectorId可能不同？
+
+- jVector是内存索引，Crash后重启会重新初始化
+- 重新添加向量时，jVector可能分配不同的ID
+- 因此需要更新映射表中的vectorId
+
+## 性能考虑
+
+### 写入性能
+
+| 操作 | 时间 | 说明 |
+|------|------|------|
+| jVector添加向量 | ~1ms | 主要耗时 |
+| RocksDB写入映射 | ~0.1ms | 快速 |
+| 总计 | ~1.1ms | 可接受 |
+
+### 查询性能
+
+| 操作 | 时间 | 说明 |
+|------|------|------|
+| jVector搜索 | ~10ms | 主要耗时 |
+| RocksDB查询映射 | ~0.1ms/条 | 快速 |
+| 总计 | ~10ms + 0.1ms*K | K为TopK数量 |
+
+### 存储开销
+
+```
+每个映射关系：
+  正向映射：key(~20B) + value(8B) = ~28B
+  反向映射：key(~20B) + value(~20B) = ~40B
+  总计：~68B/条
+
+假设100万个向量：
+  100万 * 68B = ~68MB
+  可接受
+```
+
+## 一致性保证
+
+### 写入一致性
+
+```
+VectorManager处理向量操作时：
+  1. 向jVector添加向量（内存）
+  2. 将映射关系写入RocksDB（持久化）
+  
+如果步骤2失败：
+  - jVector中有数据，但RocksDB中没有映射
+  - 恢复时会重新添加，可能导致重复
+  - 需要在恢复时检查并去重
+```
+
+### 查询一致性
+
+```
+查询时：
+  1. jVector搜索返回vectorId
+  2. 查询RocksDB获取vertexId
+  
+如果映射不存在：
+  - 说明向量索引还未完全同步
+  - 返回错误或等待
+```
+
+## 总结
+
+双向映射表是整个向量索引方案中的关键组件：
+
+✅ **必需**：连接jVector和HugeGraph的业务ID
+✅ **简单**：RocksDB中的KV存储
+✅ **高效**：查询性能快
+✅ **可靠**：持久化存储
+✅ **易恢复**：Crash后可重建
+
diff --git a/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/VertexAPI.java b/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/VertexAPI.java
index f2c79f3bc2..5adb33d65d 100644
--- a/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/VertexAPI.java
+++ b/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/VertexAPI.java
@@ -44,7 +44,9 @@
 import org.apache.hugegraph.traversal.optimize.QueryHolder;
 import org.apache.hugegraph.traversal.optimize.Text;
 import org.apache.hugegraph.traversal.optimize.TraversalUtil;
+import org.apache.hugegraph.type.HugeType;
 import org.apache.hugegraph.type.define.IdStrategy;
+import org.apache.hugegraph.type.define.IndexType;
 import org.apache.hugegraph.util.E;
 import org.apache.hugegraph.util.JsonUtil;
 import org.apache.hugegraph.util.Log;
@@ -218,6 +220,83 @@ public String update(@Context GraphManager manager,
         return manager.serializer(g).writeVertex(vertex);
     }
 
+    @POST
+    @Timed(name = "ann-search")
+    @Path("annsearch")
+    @Consumes(APPLICATION_JSON)
+    @Produces(APPLICATION_JSON_WITH_CHARSET)
+    @RolesAllowed({"admin", "$owner=$graph $action=vertex_read"})
+    public String annSearch(@Context GraphManager manager,
+                            @PathParam("graph") String graph,
+                            AnnSearchRequest searchRequest) {
+        LOG.debug("Graph [{}] ANN search with request: {}", graph, searchRequest);
+
+        AnnSearchRequest.checkRequest(searchRequest);
+
+        HugeGraph g = graph(manager, graph);
+
+        // Check if vertex label exists
+        VertexLabel vertexLabel = g.vertexLabel(searchRequest.vertex_label);
+        if (vertexLabel == null) {
+            throw new IllegalArgumentException(
+                    "Vertex label not found: " + searchRequest.vertex_label);
+        }
+
+        // Check if the property exists in the vertex label
+        PropertyKey propertyKey = g.propertyKey(searchRequest.properties);
+        if (propertyKey == null) {
+            throw new IllegalArgumentException(
+                    "Property key not found: " + searchRequest.properties);
+        }
+
+        // Check if the property is defined in the vertex label
+        if (!vertexLabel.properties().contains(propertyKey.id())) {
+            throw new IllegalArgumentException("Property '" + searchRequest.properties +
+                                               "' is not defined in vertex label '" +
+                                               searchRequest.vertex_label + "'");
+        }
+
+        // Check if vector index exists for the property
+        boolean hasVectorIndex = g.indexLabels().stream().anyMatch(indexLabel ->
+                                                    indexLabel.indexType() == IndexType.VECTOR &&
+                                                    indexLabel.baseType() == HugeType.VERTEX_LABEL &&
+                                                    indexLabel.baseValue()
+                                                              .equals(vertexLabel.id()) &&
+                                                    indexLabel.indexFields()
+                                                              .contains(propertyKey.id()));
+
+        if (!hasVectorIndex) {
+            throw new IllegalArgumentException(
+                    "No vector index found for property '" + searchRequest.properties +
+                    "' in vertex label '" + searchRequest.vertex_label + "'");
+        }
+
+        // Log query information
+        LOG.debug(
+                "ANN query: vertex_label={}, property={}, vector_length={}, metric={}, " +
+                "dimension={}, hasVectorIndex={}",
+                searchRequest.vertex_label, searchRequest.properties,
+                searchRequest.user_vector.length,
+                searchRequest.metric, searchRequest.dimension, hasVectorIndex);
+
+        try {
+            // TODO: Here should call the actual ANN query from backend
+            LOG.debug("ANN query not yet implemented, returning empty result");
+
+            // Temporary: return empty result
+            return manager.serializer(g).writeVertices(g.traversal().V().limit(0), false);
+
+            // Future implementation:
+            // 1. Call JVector engine for similarity query
+            // 2. Return topk most similar vertices
+
+        } finally {
+            if (g.tx().isOpen()) {
+                g.tx().close();
+            }
+        }
+    }
+
     @GET
     @Timed
     @Compress
@@ -471,4 +550,34 @@ public String toString() {
                                  this.label, this.properties);
         }
     }
+
+    // ANN search request class
+    private static class AnnSearchRequest {
+        @JsonProperty("vertex_label")
+        public String vertex_label;
+        @JsonProperty("properties")
+        public String properties;
+        @JsonProperty("user_vector")
+        public float[] user_vector;
+        @JsonProperty("metric")
+        public String metric;
+        @JsonProperty("dimension")
+        public Integer dimension;
+        
+        private static void checkRequest(AnnSearchRequest req) {
+            E.checkArgumentNotNull(req, "AnnSearchRequest can't be null");
+            E.checkArgumentNotNull(req.vertex_label, "Parameter 'vertex_label' can't be null");
+            E.checkArgumentNotNull(req.properties, "Parameter 'properties' can't be null");
+            E.checkArgumentNotNull(req.user_vector, "Parameter 'user_vector' can't be null");
+            E.checkArgument(req.user_vector.length > 0, "Parameter 'user_vector' can't be empty");
+            E.checkArgumentNotNull(req.metric, "Parameter 'metric' can't be null");
+            E.checkArgumentNotNull(req.dimension, "Parameter 'dimension' can't be null");
+        }
+        
+        @Override
+        public String toString() {
+            return String.format("AnnSearchRequest{vertex_label=%s, properties=%s, user_vector=%s, metric=%s, dimension=%s}",
+                                 vertex_label, properties, Arrays.toString(user_vector), metric, dimension);
+        }
+    }
 }
diff --git a/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/IndexLabelAPI.java b/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/IndexLabelAPI.java
index f2a05d406d..77a28b08a8 100644
--- a/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/IndexLabelAPI.java
+++ b/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/IndexLabelAPI.java
@@ -244,6 +244,12 @@ public void checkCreate(boolean isBatch) {
             E.checkArgumentNotNull(this.indexType,
                                    "The index type of index label '%s' " +
                                    "can't be null", this.name);
+            if (this.indexType == IndexType.VECTOR) {
+                E.checkArgumentNotNull(this.userdata,
+                                       "The user_data(dimension and metric) of " +
+                                       "vector index label '%s' " + "can't be null", this.name);
+            }
+
         }
 
         @Override
@@ -292,6 +298,9 @@ private IndexLabel.Builder convert2Builder(HugeGraph g) {
             if (this.rebuild != null) {
                 builder.rebuild(this.rebuild);
             }
+            if (this.indexType == IndexType.VECTOR) {
+                builder.rebuild(false);
+            }
             return builder;
         }
 
diff --git a/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/schema/Userdata.java b/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/schema/Userdata.java
index d485e558b8..b13fbe2314 100644
--- a/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/schema/Userdata.java
+++ b/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/schema/Userdata.java
@@ -20,8 +20,10 @@
 import java.util.HashMap;
 import java.util.Map;
 
+import org.apache.hugegraph.backend.id.Id;
 import org.apache.hugegraph.exception.NotAllowException;
 import org.apache.hugegraph.type.define.Action;
+import org.apache.hugegraph.util.E;
 
 public class Userdata extends HashMap<String, Object> {
 
@@ -61,4 +63,10 @@ public static void check(Userdata userdata, Action action) {
                         "Unknown schema action '%s'", action));
         }
     }
+
+    public static void checkDimensionAndMetric(Userdata userdata) {
+        E.checkArgument((userdata.get("dimension") != null) &&
+                        (userdata.get("metric") != null),
+                        "The vector index dimension and metric can't not be null");
+    }
 }
diff --git a/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/schema/builder/IndexLabelBuilder.java b/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/schema/builder/IndexLabelBuilder.java
index 397df66229..1d9da004dd 100644
--- a/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/schema/builder/IndexLabelBuilder.java
+++ b/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/schema/builder/IndexLabelBuilder.java
@@ -42,6 +42,7 @@
 import org.apache.hugegraph.schema.VertexLabel;
 import org.apache.hugegraph.type.HugeType;
 import org.apache.hugegraph.type.define.Action;
+import org.apache.hugegraph.type.define.Cardinality;
 import org.apache.hugegraph.type.define.CollectionType;
 import org.apache.hugegraph.type.define.DataType;
 import org.apache.hugegraph.type.define.IndexType;
@@ -389,6 +390,11 @@ public IndexLabelBuilder unique() {
         return this;
     }
 
+    public IndexLabelBuilder vector() {
+        this.indexType = IndexType.VECTOR;
+        return this;
+    }
+
     @Override
     public IndexLabelBuilder on(HugeType baseType, String baseValue) {
         E.checkArgument(baseType == HugeType.VERTEX_LABEL ||
@@ -525,6 +531,21 @@ private void checkFields(Set<Id> propertyIds) {
                             "Search index can only build on text property, " +
                             "but got %s(%s)", dataType, field);
         }
+
+        // Vector index must build on float list
+        if(this.indexType.isVector()){
+            E.checkArgument(fields.size() == 1,
+                            "vector index can only build on " +
+                            "one field, but got %s fields: '%s'",
+                            fields.size(), fields);
+            String field = fields.iterator().next();
+            DataType dataType = this.graph().propertyKey(field).dataType();
+            Cardinality cardinality = this.graph().propertyKey(field).cardinality();
+            E.checkArgument((dataType == DataType.FLOAT) &&
+                            (cardinality == Cardinality.LIST),
+                            "vector index can only build on Float List, " +
+                            "but got %s(%s)", dataType, cardinality);
+        }
     }
 
     private void checkFields4Range() {
@@ -586,6 +607,9 @@ private void checkRepeatIndex(SchemaLabel schemaLabel) {
             case UNIQUE:
                 this.checkRepeatUniqueIndex(schemaLabel);
                 break;
+            case VECTOR:
+                this.checkRepeatVectorIndex(schemaLabel);
+                break;
             default:
                 throw new AssertionError(String.format(
                         "Unsupported index type: %s", this.indexType));
@@ -674,6 +698,11 @@ private void checkRepeatShardIndex(SchemaLabel schemaLabel) {
         }
     }
 
+    private void checkRepeatVectorIndex(SchemaLabel schemaLabel) {
+        this.checkRepeatIndex(schemaLabel, IndexType.VECTOR);
+    }
+
+
     private void checkRepeatUniqueIndex(SchemaLabel schemaLabel) {
         this.checkRepeatIndex(schemaLabel, List::containsAll, IndexType.UNIQUE);
     }
diff --git a/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/type/HugeType.java b/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/type/HugeType.java
index 122036ae38..6b5e7bd0a9 100644
--- a/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/type/HugeType.java
+++ b/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/type/HugeType.java
@@ -64,6 +64,7 @@ public enum HugeType implements SerialEnum {
     SEARCH_INDEX(170, "AI"),
     SHARD_INDEX(175, "HI"),
     UNIQUE_INDEX(178, "UI"),
+    VECTOR_INDEX(180, "VI"),
 
     TASK(180, "T"),
     SERVER(181, "SERVER"),
diff --git a/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/type/define/IndexType.java b/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/type/define/IndexType.java
index 019ac98df9..e6fe7caeef 100644
--- a/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/type/define/IndexType.java
+++ b/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/type/define/IndexType.java
@@ -38,7 +38,10 @@ public enum IndexType implements SerialEnum {
     SHARD(4, "shard"),
 
     // For unique index
-    UNIQUE(5, "unique");
+    UNIQUE(5, "unique"),
+
+    //For vector index
+    VECTOR(6, "vector");
 
     private byte code = 0;
     private String name = null;
@@ -80,6 +83,8 @@ public HugeType type() {
                 return HugeType.SHARD_INDEX;
             case UNIQUE:
                 return HugeType.UNIQUE_INDEX;
+            case VECTOR:
+                return HugeType.VECTOR_INDEX;
             default:
                 throw new AssertionError(String.format(
                         "Unknown index type '%s'", this));
@@ -117,4 +122,8 @@ public boolean isShard() {
     public boolean isUnique() {
         return this == UNIQUE;
     }
+
+    public boolean isVector() {
+        return this == VECTOR;
+    }
 }