1. LlamaIndex 示例#

1
from llama_index.core import VectorStoreIndex, Document, Settings
2
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

• llama_index.core ：这是 LlamaIndex 的核心基础包，这里我们导入了三个核心组件：
  • VectorStoreIndex ：向量索引类。它是 LlamaIndex 的入口核心，接收文档 → 自动调用嵌入模型转向量 → 构建可检索的索引。类似 LangChain 的 FAISS.from_documents()；
  • Document ：文档数据类。与 LangChain 的 Document 类似，封装文本内容和元数据。注意这里用法是 Document(text=t)，而 LangChain 是 Document(page_content=t)；
  • Settings ：全局配置对象。用来设置整个 LlamaIndex 的共享配置，比如嵌入模型、LLM、分块大小等。一次设置，全局生效。
• llama_index.embeddings.huggingface ：Hugging Face 嵌入模型的集成包：
  • HuggingFaceEmbedding ：将 Hugging Face 上的 Embedding 模型封装成 LlamaIndex 统一的嵌入接口。用法与 LangChain 版的 HuggingFaceEmbeddings 类似，只需指定 model_name.

1
# 1. 配置全局嵌入模型
2
Settings.embed_model = HuggingFaceEmbedding("BAAI/bge-small-zh-v1.5")

1
# 2. 创建示例文档
2
texts = [
3
    "张三是法外狂徒",
4
    "LlamaIndex是一个用于构建和查询私有或领域特定数据的框架。",
5
    "它提供了数据连接、索引和查询接口等工具。"
6
]
7
docs = [Document(text=t) for t in texts]

1
# 3. 创建索引并持久化到本地
2
index = VectorStoreIndex.from_documents(docs)
3
persist_path = "./llamaindex_index_store"
4
index.storage_context.persist(persist_dir=persist_path)
5
print(f"LlamaIndex 索引已保存至: {persist_path}")

LlamaIndex 默认会将数据存储为透明可读的 JSON 格式，运行上述代码会创建以下文件：

1
llamaindex_index_store/
2
├── default__vector_store.json   (35 KB)   ← 核心：向量数据
3
├── docstore.json                (3.7 KB)  ← 文档原文
4
├── index_store.json             (499 B)   ← 索引元信息
5
├── graph_store.json             (18 B)    ← 图关系（空）
6
└── image__vector_store.json     (72 B)    ← 图片向量（空）

1
[-0.0185, -0.0261, -0.0099, -0.0121, -0.0539, ...]

1
{
2
  "index_id": "5edfdf61-...",
3
  "nodes_dict": {
4
    "fd58b5...": "fd58b5...",   // 节点 ID → 自身
5
    "ee8dc7...": "ee8dc7...",
6
    "62bfb2...": "62bfb2..."
7
  }
8
}

1
{"graph_dict": {}}

1
{"embedding_dict": {}, "text_id_to_ref_doc_id": {}, "metadata_dict": {}}

1
你输入的3段文本                    LlamaIndex 的持久化
2
┌─────────────────────┐
3
│ "张三是法外狂徒"     │ ──→  docstore.json      (原始文本)
4
├─────────────────────┤
5
│ "LlamaIndex是..."    │ ──→  default__vector_store.json  (512维向量)
6
├─────────────────────┤
7
│ "它提供数据连接..."   │ ──→  index_store.json   (关联映射)
8
└─────────────────────┘

2. 实现对 LlamaIndex 存储数据的加载和相似性搜索#

1
# 1. 配置全局嵌入模型
2
Settings.embed_model = HuggingFaceEmbedding("BAAI/bge-small-zh-v1.5")

首先我们需要重新设置嵌入模型。虽然我们在前面介绍 Settings 时提到这是一个全局配置，但它只存在于 当前运行的 Python 进程中，不会随 JSON 文件一起持久化。

1
from llama_index.core import StorageContext
2
from llama_index.core import load_index_from_storage
3

4
# 2. 加载存储上下文
5
storage_context = StorageContext.from_defaults(persist_dir=persist_path)
6

7
# 3. 从存储上下文加载索引
8
loaded_vector_store = load_index_from_storage(storage_context)

• StorageContext ：存储上下文类，相当于统一管理 5 个 JSON 文件的”总管”。它知道你的 docstore.json、default__vector_store.json 等文件在哪，负责读取和恢复这些数据。可以理解为”打开仓库大门的钥匙”；
• load_index_from_storage ：从存储恢复索引的函数，接收 StorageContext，把 JSON 文件中的数据”还原”成一个可用的 VectorStoreIndex 对象。

1
# 4. 执行相似度搜索
2
retriever = loaded_vector_store.as_retriever(similarity_top_k=2) # 设置返回相似度最高的前2条结果
3
query = "什么是LlamaIndex？"
4

5
nodes = retriever.retrieve(query)

• as_retriever ：转化为检索器，将 loaded_vector_store 索引转化为检索器模式，等待接收查询语句，返回值类型为 VectorIndexRetriever；
• retrieve ：执行检索，返回值为 List[NodeWithScore]：
  • 每个元素包含 .text（匹配文本）和 .score（相似度分数）；
  • 作用是把查询语句用嵌入模型转成向量 → 去向量库中做相似度匹配 → 返回最相似的文档节点。

1
print(f"\n查询: '{query}'")
2
print("相似度最高的文档:")
3
for doc in nodes:
4
    print(f"- {doc.get_text()}")