存储：索引持久化与向量存储

原文：Storing 存储

一句话

将已索引的数据持久化存储，避免重复 embedding 和索引的高昂时间与成本，支持使用向量存储如 Chroma 保存嵌入向量。

什么时候翻这页

当你已经完成数据加载和索引，希望避免每次重新运行应用时都重新进行索引操作，或者需要使用专门的 vector store 存储嵌入向量时。

核心概念

持久化(Persisting): 将索引数据从内存保存到磁盘的过程
存储上下文(StorageContext): 管理索引存储配置的对象，包含 vector_store 等设置
向量存储(Vector Store): 专门用于存储和检索 embedding 的数据库，如 Chroma
嵌入向量(Embedding): 文档转换为的数值向量表示，用于相似性检索

怎么做

基本持久化: 使用索引的 .persist() 方法将数据保存到磁盘
```
index.storage_context.persist(persist_dir="<persist_dir>")
```
使用 Chroma 向量存储:
- 安装 Chroma: pip install chromadb
- 初始化客户端和集合
- 创建 ChromaVectorStore 并赋值给 StorageContext
- 使用该 StorageContext 创建 VectorStoreIndex

加载已存储的索引:

from llama_index.core import StorageContext, load_index_from_storage

storage_context = StorageContext.from_defaults(persist_dir="<persist_dir>")
index = load_index_from_storage(storage_context)

向现有索引插入文档:
```
index.insert(doc)
```

命令 / API 速查

index.storage_context.persist(persist_dir="<persist_dir>") - 持久化索引到磁盘
StorageContext.from_defaults(persist_dir="<persist_dir>") - 从持久化目录创建存储上下文
load_index_from_storage(storage_context) - 从存储上下文加载索引
chromadb.PersistentClient(path="./chroma_db") - 创建持久化 Chroma 客户端
db.get_or_create_collection("quickstart") - 创建或获取 Chroma 集合
ChromaVectorStore(chroma_collection=chroma_collection) - 创建 Chroma 向量存储
VectorStoreIndex.from_documents(documents, storage_context=storage_context) - 从文档创建索引
VectorStoreIndex.from_vector_store(vector_store, storage_context=storage_context) - 从向量存储创建索引
index.insert(doc) - 向索引插入文档

与 Hello-Agents / LangGraph / 本博客 handbook 索引的联系

本页介绍的 Chroma 向量存储与本博客 handbook 中使用的 Chroma 索引直接相关。Chroma 是一种开源的 vector store，专门用于存储和检索 embedding，是构建 RAG 系统的核心组件。通过将文档转换为 embedding 并存储在 Chroma 中，我们可以实现高效的语义检索，这与本手册中讨论的检索增强生成(RAG)流程完全一致。使用 Chroma 持久化存储 embedding 后，可以在多次应用运行间保持向量索引，避免重复计算 embedding 的成本。

初学者易错点

初始化参数不匹配: 如果索引使用了自定义的 transformations、embed_model 等参数，在加载索引时必须提供相同选项，否则会导致不一致
路径错误: 使用 Chroma 时，确保指定的持久化路径正确且有写入权限
忽略存储上下文: 直接使用索引而不正确配置 storage_context 会导致存储失败
集合名称冲突: 在 Chroma 中使用相同的集合名称时，可能会覆盖已有数据，应使用有意义的唯一名称
忘记插入文档: 创建空索引后需要使用 insert 方法添加文档，否则查询将无结果

语义检索