跳至主要內容

使用指南

JustQ2026/3/3大约 4 分钟AI SpaceLlamaIndex

使用指南

1.加载文档

from llama_index import SimpleDirectoryReader

# 加载目录下的所有文档
documents = SimpleDirectoryReader('path/to/docs').load_data()

SimpleDirectoryReader的常用参数有：

  • input_dir (str): 目标文件夹的路径（也就是你上面填入 'path/to/docs' 的位置）。

  • input_files (List): 如果你不想读取整个文件夹，只想精准读取某几个文件，可以传入文件路径列表。
    示例: SimpleDirectoryReader(input_files=["data/report.pdf", "data/notes.txt"])

  • recursive (bool): 是否递归读取子文件夹。如果设为 True，它不仅会读取 data 文件夹里的文件，还会把 data 里面的所有子文件夹（以及子文件夹的子文件夹）里的内容全翻出来。默认是 False。

  • required_exts (List): 格式白名单。如果你只想读取特定格式的文件（比如只读 PDF 和 Word，忽略里面的图片），可以用这个。
    示例: SimpleDirectoryReader('data', required_exts=['.pdf', '.docx'])

  • exclude (List): 黑名单。指定不想读取的特定文件或文件夹。

  • exclude_hidden (bool): 是否自动忽略隐藏文件（比如 Mac 自动生成的 .DS_Store）。默认是 True，非常省心。

举例：

SimpleDirectoryReader(
    'path/to/docs', # 目标文件夹的路径
    recursive=True, # 是否递归读取子文件夹
    required_exts=['.pdf', '.docx'], # 格式白名单
    exclude=['report.pdf'], # 黑名单
    exclude_hidden=False, # 是否自动忽略隐藏文件
)

2. 将文档解析为节点

可以选择直接定义节点及其所有属性。也可以通过我们的NodeParser类“解析”源文档为节点。

NodeParser节点解析器

对于纯文本，最经典也是最常用的解析器是 SentenceSplitter。它很聪明，会尽量在句号、换行符等自然断句的地方进行切分，保证句子的完整性。

from llama_index import SimpleDirectoryReader, SentenceSplitter

# 加载目录下的所有文档
documents = SimpleDirectoryReader('path/to/docs').load_data()

# 使用NodeParser解析文档，NodeParser是Base接口
# node_parser = NodeParser()
# SentenceSplitter是NodeParser的一个子类
node_parser = SentenceSplitter(chunk_size=512, chunk_overlap=50)

# 将Document转换为Node使用NodeParser
nodes = node_parser.get_nodes_from_documents(documents)

切出来的 Node 可不仅仅是孤立的一段文字。LlamaIndex 在切分时，会保留很多有用的信息：

  • Metadata（元数据）：这个 Node 会继承原来 Document 的信息，比如它来自哪个文件（file_name）、在第几页。
  • Relationships（关系）：每个 Node 都会记得自己的“爸爸”是谁（所属的 Document ID），以及自己的“哥哥”和“弟弟”是谁（前一个 Node 和后一个 Node 的 ID）。这让后续的大模型能够顺藤摸瓜，串联起更长的上下文。

手动构建节点

您也可以选择手动构造Node对象，并跳过第一节。例如，

from llama_index.data_structs.node import Node, DocumentRelationship

node1 = Node(text="<text_chunk>", doc_id="<node_id>")
node2 = Node(text="<text_chunk>", doc_id="<node_id>")
# set relationships
node1.relationships[DocumentRelationship.NEXT] = node2.get_doc_id()
node2.relationships[DocumentRelationship.PREVIOUS] = node1.get_doc_id()
nodes = [node1, node2]

3.索引构建

默认情况下，LlamaIndex 使用的是 OpenAI 的 Embedding 模型，需要通过Settings.embed_model来设置其他的Embedding模型。

默认向量数据库是SimpleVectorStore是基于内存的，适合测试，不适合生产环境。

构建索引

Document构建索引
如果你不想手动切分 Node，LlamaIndex 可以帮你把 Document 直接变成 Index。它会在底层自动使用默认的切分器和默认的 Embedding 模型：

index = VectorStoreIndex.from_documents(documents)

Node构建索引

# 从节点构建向量索引
index = VectorStoreIndex(nodes)

切换模型

LlamaIndex 支持来自 OpenAI、Azure 和 Langchain 、还有很多种的嵌入。但如果这还不够，你也可以实现任何嵌入模型！

可以通过以下步骤实现模型支持langchain的模型

# 1. 加载 .env 文件中的环境变量
# 这一步会自动把 .env 里的内容注入到系统的环境变量中
load_dotenv()

# 2. 安全地获取变量
# os.getenv 如果找不到对应的名字，会返回 None
api_key = os.getenv("SILICONFLOW_API_KEY")
base_url = os.getenv("SILICONFLOW_BASE_URL")
model_name = os.getenv("SILICONFLOW_MODEL_NAME")

## 构建langchain嵌入模型
lc_embed_model = OpenAIEmbeddings(
    model=model_name,
    openai_api_key=api_key,   # 👈 核心修复：把读取到的变量传进来
    openai_api_base=base_url  # 👈 建议改为 openai_api_base
)
# llamaIndex使用langchain模型,通过Settings.embed_model来设置其他的Embedding模型。
llama_index_embed_model = LangchainEmbedding(lc_embed_model)
Settings.embed_model = llama_index_embed_model
print("✅ 成功从 .env 加载配置，并完成了 bge-m3 模型的挂载！")

切换向量数据库

# 1. 初始化 Chroma 客户端，指定数据持久化保存的本地路径
# 比如在你当前项目下建一个叫 "chroma_db_storage" 的文件夹
db = chromadb.PersistentClient(path="./chroma_db_storage")

# 2. 创建或获取一个“集合” (Collection，类似于关系型数据库里的表)
# 名字可以自己起，比如叫 "my_research_data"
chroma_collection = db.get_or_create_collection("my_research_data")

# 3. 把 Chroma 的集合包装成 LlamaIndex 认识的 VectorStore 格式
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)

# 4. 创建存储上下文 (StorageContext)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

print("💾 Chroma 向量数据库连接完毕！")

4. 构建查询引擎

# 1. 检索器
retriever = index.as_retriever(similarity_top_k=5)
# 2. 检索
context = retriever.retrieve("LCEL 组件总览")
默认页脚
Copyright © 2026 JustQ