trustgraph/docs/tech-specs/vector-store-lifecycle.zh-cn.md

---
layout: default
title: "向量存储生命周期管理"
parent: "Chinese (Beta)"
---

# 向量存储生命周期管理

> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

## 概述

本文档描述了 TrustGraph 如何管理跨不同后端实现（Qdrant、Pinecone、Milvus）的向量存储集合。该设计解决了在不硬编码维度值的情况下，支持具有不同维度的嵌入向量的挑战。

## 问题陈述

向量存储在创建集合/索引时需要指定嵌入维度。但是：
不同的嵌入模型会产生不同的维度（例如，384、768、1536）
直到生成第一个嵌入向量，维度才已知
单个 TrustGraph 集合可能会接收来自多个模型的嵌入向量
强制指定一个维度（例如，384）会导致使用其他嵌入向量大小时出现故障

## 设计原则

1. **延迟创建**: 集合是在首次写入时按需创建的，而不是在集合管理操作期间创建的。
2. **基于维度的命名**: 集合名称包含嵌入维度作为后缀。
3. **优雅降级**: 对不存在的集合执行的查询返回空结果，而不是错误。
4. **多维度支持**: 单个逻辑集合可以有多个物理集合（每个维度一个）。

## 架构

### 集合命名约定

向量存储集合使用维度后缀来支持多种嵌入向量大小：

**文档嵌入：**
Qdrant: `d_{user}_{collection}_{dimension}`
Pinecone: `d-{user}-{collection}-{dimension}`
Milvus: `doc_{user}_{collection}_{dimension}`

**图嵌入：**
Qdrant: `t_{user}_{collection}_{dimension}`
Pinecone: `t-{user}-{collection}-{dimension}`
Milvus: `entity_{user}_{collection}_{dimension}`

示例：
`d_alice_papers_384` - Alice 的论文集合，使用 384 维的嵌入向量
`d_alice_papers_768` - 相同的逻辑集合，使用 768 维的嵌入向量
`t_bob_knowledge_1536` - Bob 的知识图谱，使用 1536 维的嵌入向量

### 生命周期阶段

#### 1. 集合创建请求

**请求流程：**
```
User/System → Librarian → Storage Management Topic → Vector Stores
```

**行为：**
库管理员将 `create-collection` 请求广播到所有存储后端。
向量存储处理器确认该请求，但**不创建物理集合**。
立即返回成功响应。
实际集合的创建将在第一次写入时延迟。

**理由：**
在创建时，维度是未知的。
避免创建具有错误维度的集合。
简化集合管理逻辑。

#### 2. 写入操作（延迟创建）

**写入流程：**
```
Data → Storage Processor → Check Collection → Create if Needed → Insert
```

**行为：**
1. 从向量中提取嵌入维度：`dim = len(vector)`
2. 使用维度后缀构建集合名称
3. 检查是否存在具有该特定维度的集合
4. 如果不存在：
   创建具有正确维度的集合
   记录：`"Lazily creating collection {name} with dimension {dim}"`
5. 将嵌入信息插入到特定维度的集合中

**示例场景：**
```
1. User creates collection "papers"
   → No physical collections created yet

2. First document with 384-dim embedding arrives
   → Creates d_user_papers_384
   → Inserts data

3. Second document with 768-dim embedding arrives
   → Creates d_user_papers_768
   → Inserts data

Result: Two physical collections for one logical collection
```

#### 3. 查询操作

**查询流程：**
```
Query Vector → Determine Dimension → Check Collection → Search or Return Empty
```

**行为：**
1. 从查询向量中提取维度：`dim = len(vector)`
2. 使用维度后缀构建集合名称
3. 检查集合是否存在
4. 如果存在：
   执行相似度搜索
   返回结果
5. 如果不存在：
   记录日志：`"Collection {name} does not exist, returning empty results"`
   返回空列表（不引发错误）

**同一查询中的多个维度：**
如果查询包含不同维度的向量
每个维度查询其对应的集合
结果进行聚合
缺失的集合将被跳过（不被视为错误）

**原理：**
查询空集合是一种有效的用例
返回空结果在语义上是正确的
避免在系统启动或在数据摄取之前发生的错误

#### 4. 集合删除

**删除流程：**
```
Delete Request → List All Collections → Filter by Prefix → Delete All Matches
```

**行为：**
1. 构造前缀模式：`d_{user}_{collection}_` (注意尾随的下划线)
2. 列出向量存储中的所有集合
3. 过滤与前缀匹配的集合
4. 删除所有匹配的集合
5. 记录每个删除操作：`"Deleted collection {name}"`
6. 汇总日志：`"Deleted {count} collection(s) for {user}/{collection}"`

**示例：**
```
Collections in store:
- d_alice_papers_384
- d_alice_papers_768
- d_alice_reports_384
- d_bob_papers_384

Delete "papers" for alice:
→ Deletes: d_alice_papers_384, d_alice_papers_768
→ Keeps: d_alice_reports_384, d_bob_papers_384
```

**原理：**
确保彻底清理所有维度变体。
模式匹配可防止意外删除不相关的集合。
从用户角度来看，这是一个原子操作（所有维度一起删除）。

## 行为特性

### 正常操作

**集合创建：**
✓ 立即返回成功。
✓ 不分配任何物理存储空间。
✓ 快速操作（没有后端 I/O）。

**首次写入：**
✓ 创建具有正确维度的集合。
✓ 由于集合创建的开销，速度略慢。
✓ 之后对同一维度的写入速度很快。

**在任何写入之前进行查询：**
✓ 返回空结果。
✓ 没有错误或异常。
✓ 系统保持稳定。

**混合维度写入：**
✓ 自动为每个维度创建单独的集合。
✓ 每个维度都隔离在自己的集合中。
✓ 没有维度冲突或模式错误。

**集合删除：**
✓ 移除所有维度变体。
✓ 彻底清理。
✓ 没有孤立的集合。

### 边界情况

**多个嵌入模型：**
```
Scenario: User switches from model A (384-dim) to model B (768-dim)
Behavior:
- Both dimensions coexist in separate collections
- Old data (384-dim) remains queryable with 384-dim vectors
- New data (768-dim) queryable with 768-dim vectors
- Cross-dimension queries return results only for matching dimension
```

**并发首次写入：**
```
Scenario: Multiple processes write to same collection simultaneously
Behavior:
- Each process checks for existence before creating
- Most vector stores handle concurrent creation gracefully
- If race condition occurs, second create is typically idempotent
- Final state: Collection exists and both writes succeed
```

**维度迁移：**
```
Scenario: User wants to migrate from 384-dim to 768-dim embeddings
Behavior:
- No automatic migration
- Old collection (384-dim) persists
- New collection (768-dim) created on first new write
- Both dimensions remain accessible
- Manual deletion of old dimension collections possible
```

**空集合查询：**
```
Scenario: Query a collection that has never received data
Behavior:
- Collection doesn't exist (never created)
- Query returns empty list
- No error state
- System logs: "Collection does not exist, returning empty results"
```

## 实现说明

### 存储后端特定说明

**Qdrant:**
使用 `collection_exists()` 进行存在性检查
使用 `get_collections()` 在删除期间进行列表操作
集合创建需要 `VectorParams(size=dim, distance=Distance.COSINE)`

**Pinecone:**
使用 `has_index()` 进行存在性检查
使用 `list_indexes()` 在删除期间进行列表操作
索引创建需要等待 "ready" 状态
Serverless 规格配置为云/区域

**Milvus:**
直接类 (`DocVectors`, `EntityVectors`) 管理生命周期
内部缓存 `self.collections[(dim, user, collection)]` 用于提高性能
集合名称经过清理（仅限字母数字 + 下划线）
支持具有自动递增 ID 的模式

### 性能考虑

**首次写入延迟:**
由于集合创建而产生的额外开销
Qdrant: ~100-500 毫秒
Pinecone: ~10-30 秒 (serverless 预配置)
Milvus: ~500-2000 毫秒 (包括索引)

**查询性能:**
存在性检查会增加最小的开销 (~1-10 毫秒)
集合存在后，不会对性能产生影响
每个维度集合都独立优化

**存储开销:**
每个集合的元数据非常少
主要开销是每个维度的存储
权衡：存储空间与维度灵活性

## 未来考虑

**自动维度合并:**
可以添加后台进程来识别和合并未使用的维度变体
这将需要重新嵌入或降维

**维度发现:**
可以公开 API 来列出集合中使用的所有维度
对于管理和监控非常有用

**默认维度偏好:**
可以跟踪每个集合的 "主" 维度
用于在维度上下文不可用的情况下进行查询

**存储配额:**
可能需要每个集合的维度限制
防止维度变体的过度繁殖

## 迁移说明

**从预维度后缀系统:**
旧集合：`d_{user}_{collection}` (没有维度后缀)
新集合：`d_{user}_{collection}_{dim}` (带有维度后缀)
没有自动迁移 - 旧集合仍然可以访问
如果需要，请考虑手动迁移脚本
可以同时运行这两种命名方案

## 引用

集合管理：`docs/tech-specs/collection-management.md`
存储模式：`trustgraph-base/trustgraph/schema/services/storage.py`
Librarian 服务：`trustgraph-flow/trustgraph/librarian/service.py`