datawhalechina/wow-rag: A simple and trans-platform rag framework and tutorial

datawhale AI共学
本节聚焦索引层的增删查改：直面 node／docstore 细节、手动维护向量库。

脏、累，是线上知识库长寿的基石。

---

1. 初始化与回顾

• 环境与模型接入（dotenv → ZhipuAI/ZhipuAIEmbedding）同前几课。

• 读取 ./问答手册.txt → VectorStoreIndex.from_documents()，一次性完成 切分->嵌入->建索引。

• 索引默认挂在内存，但核心数据（向量 + 文本）都封装在 docstore / index_struct 中。

2. 索引

API	作用	典型输出
index.docstore.docs	显示所有 Document / TextNode 对象	{doc_id: Document, ...}
index.index_struct.nodes_dict	向量库登记簿	{node_id: Node, ...}
index.ref_doc_info	doc-node 映射 + metadata	{doc_id: {...}}

docs 保存原文，nodes_dict 向量，ref_doc_info 关联

---

2. 定位单节点

node = index.docstore.get_node(node_id)# 等价于 index.docstore.docs[nid]
print(node.text, node.metadata)

• 输出包含：text、metadata、向量 (embedding 可能延迟加载)、关系字段。
  有了 Node 对象，后续可以做增量写入，或业务侧重。

• 可快速定位脏数据、调试检索偏差

• metadata 检索，也承担版本溯源

---

3. 删除

index.docstore.delete_document(doc_id)

• Faiss/Qdrant 本身不支持“软删除”，底层向量仍在，只是索引关系断

• 删除后若不 rebuild，可能引发空引用；谨慎在线环境使用。

• 流程建议：备份 → delete → persist() → reload 验证

---

4. 新增两条路径

1. 直接构造 TextNode

   node = TextNode(text="patch content", metadata={"source":"hotfix"})
   index.insert_nodes([node])
   

2. 文档-切分管线  更自动，但多一步 SentenceSplitter

   docs  = SimpleDirectoryReader(['./docs/new.txt']).load_data()
   nodes = run_transformations(docs, [SentenceSplitter(chunk_size=512)])
   index.insert_nodes(nodes)
   

插入后向量会即时写入底层 Faiss/Qdrant，不需手动 index.update()

---

5. 更新（没有捷径）

• lama-index 暂无“就地修改 Node 文本”API。

• 最佳实践：delete → rebuild Node → insert

  • 能保持 idempotent，避免索引与向量库不一致。

  • 对小批量改动成本可接受；大规模应该离线重构索引

---

6. 持久化 & 版本化

index.storage_context.persist("./storage/snap_2025-07-21")

• 快照命名，加日期/commit hash，便于 diff & rollback

• 大批量 patch 后，统一 rebuild → 生成新快照，再切换流量

---

7. 实战建议

• 增量 vs 全量

  • 小型知识库（百-千条）：直接 insert / delete 

  • 大型库（10w+）：倾向批量离线重建 + 快照持久化

• 版本化

  • 建议索引快照 (storage/ or qdrant/) 加上时间戳/commit hash，利于回滚。

• 元数据先行

  • 更新节点时可以同步刷新 metadata，否则 filter 检索会出现“脏读”

• 事务思维

  • 理想状态：封装一层 “begin-commit-rollback” manager；

  • 当前 llama-index 未内置，后续自行扩展。

---

8. 总结

• 掌握了 索引动态增删 与 底层结构巡检 的核心操作，为后续 在线知识库更新、权限隔离、数据治理 奠定基础。

• 要点：查 → 删 → 增 → 存；更新不支持就“删后再增”。

这一节没有模型、没有 fancy UI，纯粹体力活。但是 document hygiene 决定了 RAG 的上限。