乘风的人 - LlamaIndex
type: channel
link: https://blog.zhangbiechen.cn/index.php/tag/LlamaIndex/
description: ai
items: llamaindex rag示例项目
items: LlamaIndex 学习笔记
items: LlamaIndex - 05 Retriever（检索器）
items: LlamaIndex - 04 Index 索引与存储
items: LlamaIndex - 03 Embedding Model
items: LlamaIndex - 02 NodeParser(节点解析器)
items: LlamaIndex - 01 DataLoader (文档加载)
items: LlamaIndex - 索引、向量数据与数据库的关系
items: LlamaIndex 实战学习文档
items: LlamaIndex

llamaindex rag示例项目
type: item
date: 2026-05-25T15:15:00+08:00
description: 项目结构llamaindex-rag-example/├── data/ # 存放待处理的原始文档（如PDF/TXT/Markdown等）├── storage_exp/ # 持久化存储向量索引的目录（自动生成）├── 01_build.py # 构建并持久化向量索引的脚本└── 02_query.py # 加载索引并进行问答查询的脚本PDF文件转Markdown#如果直接用 pdf版解析会很差，可以用mineru转化为md文件，但是测试 api 速度也不快， 可以直接在官网将文档转化下载，时间最快，还可以进行调整 官网：https://mineru.net/ 01_build.py 构建索引import os import time import torch from pathlib import Path from llama_index.core import VectorStoreIndex, Settings, Document from llama_index.embeddings.huggingface import HuggingFaceEmbedding from llama_index.core.node_parser import SimpleNodeParser # 配置 device = "cpu" #如果直接用 pdf版解析会很差，可以用mineru转化为md文件，但是测试 api 速度也不快， 可以直接在官网将文档转化下载，时间最快，还可以进行调整https://mineru.net/ markdown_path = "./data/test_manual.md" persist_dir = "./storage_exp" # 创建目录 os.makedirs(persist_dir, exist_ok=True) os.makedirs("./models", exist_ok=True) # 2. 配置全局 Embedding（本地 Qwen3 模型） EMBEDDING_PATH = "/Users/t-mac/.cache/huggingface/hub/models--Qwen--Qwen3-Embedding-0.6B/snapshots/c54f2e6e80b2d7b7de06f51cec4959f6b3e03418" Settings.embed_model = HuggingFaceEmbedding( model_name=EMBEDDING_PATH, trust_remote_code=True ) # 读取 Markdown 文件 print(f"读取 Markdown: {markdown_path}") with open(markdown_path, "r", encoding="utf-8") as f: markdown_content = f.read() print(f"文档长度: {len(markdown_content)} 字符") # 创建 Document doc = Document( text=markdown_content, metadata={ "source": Path(markdown_path).name, "file_path": str(Path(markdown_path).absolute()), } ) # 切分文档 print("切分文档...") parser = SimpleNodeParser(chunk_size=512, chunk_overlap=50) nodes = parser.get_nodes_from_documents([doc]) print(f"生成 {len(nodes)} 个节点") # 构建索引 print("构建索引...") start_time = time.time() index = VectorStoreIndex(nodes) build_time = time.time() - start_time print(f"索引构建完成，耗时 {build_time:.2f} 秒") # 保存索引 print(f"保存索引到 {persist_dir}...") index.storage_context.persist(persist_dir=persist_dir) # 统计 index_size = 0 for root, dirs, files in os.walk(persist_dir): for file in files: index_size += os.path.getsize(os.path.join(root, file)) print("\n" + …

LlamaIndex 学习笔记
type: item
date: 2026-05-25T10:37:00+08:00
description: LlamaIndex 学习笔记git地址https://github.com/zxliucn/LlamaIndex-Learning目录文档加载 (DataLoader)节点解析器 (NodeParser)嵌入模型 (Embedding Model)索引与存储 (Index)检索器 (Retriever)索引、向量数据与数据库的关系一、文档加载 (DataLoader)文档加载是 LlamaIndex 构建 RAG 应用的第一步，也是最基础的一步。本文将全面介绍 LlamaIndex 中文档加载的各种方式、核心概念以及高级自定义技巧。1.1 核心概念：Document在 LlamaIndex 中，Document（文档）是对原始数据源的标准化封装，是整个 RAG 流程的数据入口。它不仅仅指传统的文本文档，而是涵盖所有可被加载的结构化/非结构化数据的抽象载体。Document 的核心属性属性类型说明textstr核心属性，存储文档的原始文本内容metadatadict元数据字典，记录文档的上下文信息（文件名、路径、创建时间等）id_ / doc_idstr唯一标识符，用于区分不同 DocumentDocument 的关键特性多源适配性：LlamaIndex 提供 100+ 内置 Data Loader，可将不同数据源统一为 Document 对象不可变性：原始 Document 加载后内容不会被修改（分割操作会生成新的 Node）编码保障：加载中文文档时需通过 encoding="utf-8" 指定编码1.2 文档加载的三种方式方式一：使用 SimpleDirectoryReader（最常用）SimpleDirectoryReader 是最简单易用的加载器，可以将指定目录中的文件批量加载为 Document 对象：from llama_index.core import SimpleDirectoryReader # 基本用法：加载目录下所有文件 documents = SimpleDirectoryReader("./data").load_data() # 指定编码（处理中文文档） documents = SimpleDirectoryReader("./data", encoding="utf-8").load_data() # 查看加载结果 print(f"加载文档数量：{len(documents)}") print(f"第一个文档内容长度：{len(documents[0].text)}字符") print(f"文档元数据：{documents[0].metadata}")支持的文件格式：Markdown、PDF、Word 文档、PowerPoint 演示文稿、图像、音频和视频等。方式二：使用 LlamaHub 的数据加载器LlamaHub 是 LlamaIndex 的数据连接器注册表，提供了数百种连接器，支持从各种数据源加载数据：from llama_index.core import download_loader from llama_index.readers.database import DatabaseReader # 示例：从 SQL 数据库加载数据 reader = DatabaseReader( scheme="postgresql", host="localhost", port=5432, user="myuser", password="mypassword", dbname="mydb", ) query = "SELECT * FROM users" documents = reader.load_data(query=query)方式三：手动构造 Documentfrom llama_index.core import Document # 从文本列表创建 text_list = ["文本1内容", "文本2内容", "文本3内容"] documents = [Document(text=t) for t in text_list] # 创建单个文档 document = Document(text="这是文档的原始文本内容") # 快速创建示例文档（用于原型开发） example_doc = Document.example()1.3 元数据（Metadata）管理元数据是 Document 的重要组成部分，用于记录文档的上下文信息，对回答溯源和多文档管理至关重要。设置元数据方式一：在构造函数中设置document = Document( text="文档内容", metadata={ "filename": "important_doc.pdf", "category": "技术文…

LlamaIndex - 05 Retriever（检索器）
type: item
date: 2026-05-18T09:28:00+08:00
description: 一、Retriever 是什么？在 LlamaIndex 的架构中，Retriever（检索器） 负责根据用户查询（或聊天消息）获取最相关的上下文内容。它是连接索引（Index）和查询引擎（Query Engine）的核心桥梁。整个查询流程包含三个核心组件：组件职责类比Retriever从索引中检索相关节点图书管理员在书架上找书Response Synthesizer将检索到的节点合成答案阅读并总结找到的资料Query Engine整合上述两者，提供统一接口前台的查询服务窗口用户查询 → Retriever（检索相关节点）→ Response Synthesizer（合成答案）→ 返回响应二、快速上手：基础用法2.1 最简单的使用方式from llama_index.core import VectorStoreIndex from llama_index.core import SimpleDirectoryReader # 加载文档 documents = SimpleDirectoryReader("data").load_data() # 构建索引 index = VectorStoreIndex.from_documents(documents) # 获取检索器（最简形式） retriever = index.as_retriever() # 执行检索 nodes = retriever.retrieve("Who is Paul Graham?")💡 as_retriever() 是从索引获取检索器的快捷方式。每个索引类型都有自己默认的检索器实现。2.2 配置检索参数# 配置返回节点数量（Top-K） retriever = index.as_retriever(similarity_top_k=5) # VectorStoreIndex 还支持向量搜索相关参数 retriever = vector_index.as_retriever( similarity_top_k=3, # 返回最相似的3个节点 vector_store_query_mode="default", )三、核心概念深入3.1 Index（索引）与 Retriever 的关系Index（索引） 是存储在文档对象之上的数据结构，旨在支持 LLM 进行查询。不同类型的索引对应不同的检索策略：索引类型检索器模式适用场景VectorStoreIndex向量相似度检索语义搜索、事实查询SummaryIndex列表式检索/LLM检索摘要生成、全文遍历KeywordTableIndex关键词匹配检索精确关键词查询from llama_index.core import SummaryIndex, VectorStoreIndex # 不同索引的不同检索器配置 summary_index = SummaryIndex(nodes) vector_index = VectorStoreIndex(nodes) # SummaryIndex 支持多种检索模式 list_retriever = summary_index.as_retriever( retriever_mode="llm", # 使用 LLM 选择 choice_batch_size=5, # 批处理大小 ) # 低阶 API：直接实例化检索器类 from llama_index.core.indices.list import SummaryIndexLLMRetriever retriever = SummaryIndexLLMRetriever( index=summary_index, choice_batch_size=5, )3.2 检索器在 RAG 流程中的位置┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Load │ -> │ Index │ -> │ Retriever │ -> │ Synthesize │ │ 加载文档 │ │ 构建索引 │ │ 检索节点 │ │ 生成答案 │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ ↑ 用户查询进入四、高阶检索技术4.1 递归检索器（Recursive Retriever）递归检索解决了两个核心痛点：解耦检索与合成：有时通过摘要获取文档比直接搜索原始块更有效文档内动态任务：在单个文档内可能需要超越事实问答的复杂操作from llama_index.core import VectorStoreIndex, SummaryIndex from llama_index.core…

LlamaIndex - 04 Index 索引与存储
type: item
date: 2026-05-15T17:40:20+08:00
description: LlamaIndex 索引与存储完全指南1. 索引概述：从数据到查询的桥梁在 LlamaIndex 中，索引（Index） 是一个核心的数据结构，它将原始的 Document 对象组织起来，以便大语言模型（LLM）能够高效地查询和理解。构建索引的过程通常包括将文档解析、分块为更精细的 Node 对象，每个 Node 对应文档中的一段文本。这样做解决了直接将海量私有数据喂给 LLM 时遇到的知识断层和上下文窗口限制问题。2. LlamaIndex 核心索引类型深度解析LlamaIndex 提供了多种索引类型，每种都针对特定的查询场景进行了优化。下表总结了四种最核心的索引结构：索引类型核心机制与数据结构最佳适用场景检索策略向量存储索引 (VectorStoreIndex)将每个 Node 及其对应的 Embedding（向量嵌入）存储在向量数据库中。语义相似度匹配，是 RAG 最常用的索引。适用于问答系统、推荐系统、跨文档主题查找等。将查询语句转为向量，通过 ANN（近似最近邻）算法（如 FAISS、HNSW）查找最相似的 Top-K 个 Node。摘要索引 (Summary Index)简单地将所有 Node 存储为一个顺序列表。生成文档整体摘要，或在需要针对非常少量的节点进行全量、顺序遍历时使用。加载列表中的全部或大部分 Node 至响应合成模块，让 LLM 查看所有文本后生成答案。树状索引 (Tree Index)从 Node 集合构建一个分层的树状结构，每个父节点是其子节点的摘要。需要对长文档进行摘要总结或逐级下钻的查询场景。适合从宏观到微观的层次化信息检索。从根节点开始，逐层遍历（如每次选择相关性最高的 top-k 子节点），最终到达叶子节点获取详细上下文。关键词表索引 (Keyword Table Index)从每个 Node 中提取关键词，构建一个从关键词到 Node 的映射表（类似倒排索引）。基于特定关键词的精确检索，如文档管理系统、传统搜索引擎风格的查询。解析查询语句中的关键词，通过映射表快速定位包含这些关键词的 Node。3. 存储机制：持久化与后端集成默认情况下，LlamaIndex 将索引数据存储在内存中，这意味着程序退出后数据就会丢失。为了实现数据持久化，LlamaIndex 设计了灵活的存储抽象层（Storage Abstractions）。3.1 核心存储组件文档存储 (Document Stores)：存储 ingested 后的文档和 Node 对象。索引存储 (Index Stores)：存储索引的元数据（如映射关系、树结构）。向量存储 (Vector Stores)：专门存储向量嵌入及其对应的文本数据。这是最关键的组件，因为许多向量数据库（除 FAISS 外）会同时存储数据和索引，因此可能不再需要单独的文档或索引存储。图存储 (Graph Stores)：为知识图谱索引（KnowledgeGraphIndex）专门设计。聊天存储 (Chat Stores)：用于存储 Agent 的对话历史。3.2 持久化实践指南方案一：本地磁盘持久化最简单的方式，适用于开发和测试环境。通过 storage_context 的 persist() 方法将数据写入磁盘，或通过 from_defaults 加载。from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, StorageContext, load_index_from_storage import os # 1. 构建索引并持久化 documents = SimpleDirectoryReader("data").load_data() index = VectorStoreIndex.from_documents(documents) # 持久化到本地目录 (默认为 ./storage) index.storage_context.persist(persist_dir="./my_storage") # 2. 从磁盘加载索引 if not os.path.exists("./my_storage"): # 如果不存在，走构建流程 index = VectorStoreIndex.from_documents(documents) index.storage_context.persist(persist_dir="./my_storage") else: # 重建存储上下文并加载 storage_context = StorageContext.from_defaults(persist_dir="./my_storage") index = load_index_f…

LlamaIndex - 03 Embedding Model
type: item
date: 2026-05-15T15:03:00+08:00
description: LlamaIndex Embedding Model 完全指南在 LlamaIndex 中，Embedding 模型是将文本转换为向量表示的核心组件，直接影响检索质量。本文将系统地介绍如何使用、配置和评估 Embedding 模型，并特别加入针对中文场景的详细推荐。目录概念与核心作用安装与基础配置各主要来源 Embedding 模型详解中文 Embedding 模型详解与推荐高级配置参数模型选择与性能评测完整代码示例常见问题与最佳实践一、概念与核心作用Embedding 模型将文本作为输入，输出一个浮点数列表（向量），用于捕捉文本的语义信息。这些向量使得语义相似的文本在向量空间中彼此靠近，从而支持搜索、RAG 等应用。在 LlamaIndex 中，Embedding 模型有两个关键使用场景：索引阶段：将文档切分后的 Node 转换为向量，存入向量数据库查询阶段：将用户查询转换为向量，用于与索引中的向量进行相似度计算默认情况下，LlamaIndex 使用 OpenAI 的 text-embedding-ada-002 模型，相似度计算采用余弦相似度。二、安装与基础配置2.1 安装对应包不同 Embedding 提供商需要安装不同的包：# OpenAI pip install llama-index-embeddings-openai # Hugging Face 本地模型 pip install llama-index-embeddings-huggingface # Ollama 本地模型 pip install llama-index-embeddings-ollama # LangChain 集成 pip install llama-index-embeddings-langchain # ONNX 加速 pip install llama-index-embeddings-huggingface-optimum transformers optimum[exporters] # Jina AI pip install llama-index-embeddings-jinaai # BCEmbedding（中文推荐） pip install BCEmbedding2.2 全局配置方式最常用的配置方式是通过 Settings 对象全局设置 Embedding 模型：from llama_index.core import Settings from llama_index.embeddings.openai import OpenAIEmbedding # 全局设置 Settings.embed_model = OpenAIEmbedding() # 之后构建的 index 和 query engine 会自动使用该模型也可以在创建 Index 时单独指定：index = VectorStoreIndex.from_documents( documents, embed_model=embed_model )三、各主要来源 Embedding 模型详解3.1 OpenAI EmbeddingOpenAI 的 Embedding 模型在多项评测中表现优异，特别是与 reranker 配合使用时。from llama_index.embeddings.openai import OpenAIEmbedding from llama_index.core import Settings # 基础配置 Settings.embed_model = OpenAIEmbedding() # 自定义配置 embed_model = OpenAIEmbedding( model="text-embedding-3-small", # 或 "text-embedding-3-large", "text-embedding-ada-002" embed_batch_size=10, # 批处理大小，默认 10 api_key="your-api-key", # 可选，也可通过环境变量设置 )根据 LlamaIndex 官方评测，OpenAI Embedding 与 CohereRerank 搭配时，Hit Rate 可达 0.926966，MRR 达 0.86573。3.2 Hugging Face 本地模型使用本地模型可以避免 API 调用成本，适合需要离线运行或数据隐私敏感的场景。基础用法：from llama_index.embeddings.huggingface import HuggingFaceEmbedding # 使用轻量级模型（速度快） embed_model = HuggingFaceEmbedding( model_na…

LlamaIndex - 02 NodeParser(节点解析器)
type: item
date: 2026-05-15T11:24:00+08:00
description: LlamaIndex 文档切分 Node 教程（完整版）一、核心概念：Document vs NodeDocument：原始文档对象，可以是一整个文件或一段文本Node：文档切分后的"块"，包含文本内容、元数据以及节点间的关系信息（如前后节点、父节点引用）from llama_index.core.schema import TextNode, NodeRelationship, RelatedNodeInfo # 手动创建 Node 并设置关系 node1 = TextNode(text="这是第一个文本块", id_="node_1") node2 = TextNode(text="这是第二个文本块", id_="node_2") # 设置节点间的前后关系 node1.relationships[NodeRelationship.NEXT] = RelatedNodeInfo(node_id=node2.node_id) node2.relationships[NodeRelationship.PREVIOUS] = RelatedNodeInfo(node_id=node1.node_id)四、最常用的切分方式：SentenceSplitterSentenceSplitter 是 LlamaIndex 默认的 Node Parser，它会按句子边界进行切分，避免在句子中间切断。4.1 基本用法from llama_index.core import SimpleDirectoryReader from llama_index.core.node_parser import SentenceSplitter # 1. 加载文档 documents = SimpleDirectoryReader("./data/").load_data() # 2. 创建切分器 parser = SentenceSplitter(chunk_size=512, chunk_overlap=20) # 3. 执行切分，得到 Nodes nodes = parser.get_nodes_from_documents(documents) print(f"原始文档数量: {len(documents)}") print(f"切分后节点数量: {len(nodes)}")4.2 全局配置方式如果你希望在整个应用中统一使用相同的切分配置，可以通过 Settings 对象设置：from llama_index.core import Settings from llama_index.core.node_parser import SentenceSplitter # 方式一：设置完整的 Node Parser Settings.text_splitter = SentenceSplitter(chunk_size=1024, chunk_overlap=20) # 方式二：只修改默认的 chunk 参数 Settings.chunk_size = 512 Settings.chunk_overlap = 20 # 之后所有的操作都会自动应用这个切分设置五、进阶切分器详解5.1 MarkdownNodeParser - 保留 Markdown 结构适用于处理 Markdown 格式的文档，能识别标题、代码块、列表等结构：from llama_index.core.node_parser import MarkdownNodeParser parser = MarkdownNodeParser() nodes = parser.get_nodes_from_documents(documents) # 输出的 node 会保留标题层级等结构信息5.2 CodeSplitter - 代码专用切分用于切分代码文件，它会按抽象语法树（AST）节点进行分割，保证每个 Node 包含完整的函数或类定义：from llama_index.core.node_parser import CodeSplitter # 指定代码语言和块大小 parser = CodeSplitter( language="python", chunk_lines=40, # 每个块的最大行数 chunk_lines_overlap=15, # 块之间的重叠行数 max_chars=1500, # 每个块的最大字符数 ) nodes = parser.get_nodes_from_documents(documents)5.3 SemanticSplitterNodeParser - 语义切分这是更高级的切分方式：根据句子间的语义相似度来决定在哪里切分，而不是机械地按字符数切割。from …

LlamaIndex - 01 DataLoader (文档加载)
type: item
date: 2026-05-15T11:11:00+08:00
description: LlamaIndex 文档加载完全指南文档加载是 LlamaIndex 构建 RAG 应用的第一步，也是最基础的一步。本文将全面介绍 LlamaIndex 中文档加载的各种方式、核心概念以及高级自定义技巧。一、核心概念：Document在 LlamaIndex 中，Document（文档）是对原始数据源的标准化封装，是整个 RAG 流程的数据入口。它不仅仅指传统的文本文档，而是涵盖所有可被加载的结构化/非结构化数据的抽象载体。1. Document 的核心属性每个 Document 对象包含以下关键属性：属性类型说明textstr核心属性，存储文档的原始文本内容metadatadict元数据字典，记录文档的上下文信息（文件名、路径、创建时间等）id_ / doc_idstr唯一标识符，用于区分不同 Document2. Document 的关键特性多源适配性：LlamaIndex 提供 100+ 内置 Data Loader，可将不同数据源统一为 Document 对象不可变性：原始 Document 加载后内容不会被修改（分割操作会生成新的 Node）编码保障：加载中文文档时需通过 encoding="utf-8" 指定编码二、文档加载的三种方式方式一：使用 SimpleDirectoryReader（最常用）SimpleDirectoryReader 是最简单易用的加载器，可以将指定目录中的文件批量加载为 Document 对象：from llama_index.core import SimpleDirectoryReader # 基本用法：加载目录下所有文件 documents = SimpleDirectoryReader("./data").load_data() # 指定编码（处理中文文档） documents = SimpleDirectoryReader("./data", encoding="utf-8").load_data() # 查看加载结果 print(f"加载文档数量：{len(documents)}") print(f"第一个文档内容长度：{len(documents[0].text)}字符") print(f"文档元数据：{documents[0].metadata}")支持的文件格式：Markdown、PDF、Word 文档、PowerPoint 演示文稿、图像、音频和视频等。方式二：使用 LlamaHub 的数据加载器LlamaHub 是 LlamaIndex 的数据连接器注册表，提供了数百种连接器，支持从各种数据源加载数据：from llama_index.core import download_loader from llama_index.readers.database import DatabaseReader # 示例：从 SQL 数据库加载数据 reader = DatabaseReader( scheme="postgresql", host="localhost", port=5432, user="myuser", password="mypassword", dbname="mydb", ) query = "SELECT * FROM users" documents = reader.load_data(query=query)方式三：手动构造 Document你也可以手动创建 Document 对象：from llama_index.core import Document # 从文本列表创建 text_list = ["文本1内容", "文本2内容", "文本3内容"] documents = [Document(text=t) for t in text_list] # 创建单个文档 document = Document(text="这是文档的原始文本内容") # 快速创建示例文档（用于原型开发） example_doc = Document.example()三、元数据（Metadata）管理元数据是 Document 的重要组成部分，用于记录文档的上下文信息，对回答溯源和多文档管理至关重要。1. 设置元数据方式一：在构造函数中设置document = Document( text="文档内容", metadata={ "filename": "important_doc.pdf", "category": "技术文档", "author": "张三", "creation_date": "2024-01-15" } )方式二：创建后设置document = Document(text="文档内容") document.metadata = {"fil…

LlamaIndex - 索引、向量数据与数据库的关系
type: item
date: 2026-05-15T10:39:00+08:00
description: 索引、向量数据与数据库的关系这是一个非常核心的问题。理解三者的关系，对于设计RAG应用的存储架构至关重要。一、概念澄清1.1 各角色定义组件本质存储内容比喻向量数值化后的文本特征浮点数数组（如[0.12, -0.34, 0.56...]）文档的"DNA编码"索引(Index)高效检索向量的数据结构向量 + 对应的ID映射关系图书的"目录+分类卡片"数据库持久化存储系统向量数据 + 原始文本 + 元数据图书馆的"书架系统"1.2 三者的层级关系graph TD A[数据库 Database] --> B[向量存储 Vector Store] A --> C[文档存储 Document Store] A --> D[索引存储 Index Store] B --> E[向量数据 Vector Data] C --> F[原始文本+节点] D --> G[索引元数据 Index Metadata] style A fill:#f9f,stroke:#333,stroke-width:4px关键理解：向量是数据本身（一种特殊的数据类型）索引是数据结构（帮助快速检索这些数据）数据库是载体（持久化存储向量+索引+元数据）二、LlamaIndex 的三层存储架构LlamaIndex 将存储拆分为三个独立的组件，它们共同构成完整的索引系统：2.1 存储组件详解from llama_index.core import StorageContext storage_context = StorageContext.from_defaults( docstore=... # 文档存储：存原始文本和节点 vector_store=... # 向量存储：存向量嵌入 index_store=... # 索引存储：存索引元数据 )组件存储内容数据量级查询频率DocStore原始文本、Node对象、文本分块较大中（返回结果时读取）VectorStore向量数组、向量与Node的映射极大（取决于维度）极高（每次查询）IndexStore索引ID、索引类型、构建参数极小低（加载时读取）2.2 实际数据示例假设你有一篇文章："LlamaIndex是一个强大的RAG框架"# 1. 原始文本 → 存入 DocStore { "node_id": "node_001", "text": "LlamaIndex是一个强大的RAG框架", "metadata": {"source": "article.pdf", "page": 1} } # 2. 文本转化为向量 → 存入 VectorStore { "node_id": "node_001", "embedding": [0.123, -0.456, 0.789, ...], # 768维或1536维向量 } # 3. 索引元数据 → 存入 IndexStore { "index_id": "my_vector_index", "index_type": "VectorStoreIndex", "embedding_model": "text-embedding-ada-002", "node_count": 1500 }三、不同存储方式的差异3.1 本地文件系统（SimpleVectorStore）storage_context = StorageContext.from_defaults(persist_dir="./storage")存储结构：./storage/ ├── docstore.json # 所有原始文本 ├── vector_store.json # 所有向量数据（JSON格式，效率低） └── index_store.json # 索引元数据特点：向量和索引耦合在同一个JSON文件中适合小规模数据（<1万条文档）每次加载需反序列化整个文件3.2 专业向量数据库（如Chroma）vector_store = ChromaVectorStore(chroma_collection=collection) storage_context = StorageContext.from_defaults(vector_store=vector_store)存储结构（Chroma内部）：chroma_db/ ├── chroma.sqlite3 # 存储元数据、文档ID、集合信息 └── data_level0.bin # 存储HNSW索引 + 向量数据关系说明：SQLite表：存储文档ID、元数据、向量与文件的映射二进制文件：存储HNSW图索引结构 + 实际向量数组向量、索引、元数据分离但关联存储3.3 分布式系统（Redis + S3）# 向量存储在S3，索引元数据在Redis vector_store = S…

LlamaIndex 实战学习文档
type: item
date: 2026-05-13T17:23:00+08:00
description: LlamaIndex + Qwen RAG 实战学习文档版本适配: LlamaIndex v0.14.x (2026年最新稳定版) 目标读者: 大模型应用程序员 核心模型: 千问 (Qwen2.5 / Qwen3 / DashScope API) 文档定位: 从环境搭建到生产级 RAG 系统的完整实践指南目录框架概览与版本说明环境准备与安装核心概念速览基础 RAG：五步走通全流程千问模型集成详解数据加载与文档解析索引构建与向量存储检索策略与查询引擎高级 RAG 技巧生产化部署要点完整可运行代码汇总1. 框架概览与版本说明1.1 LlamaIndex 是什么？LlamaIndex 是一个专为 RAG（检索增强生成） 设计的 Python 框架，其核心理念是：数据索引化：将任意格式的非结构化数据（PDF、网页、数据库）转化为 LLM 可消费的索引结构检索即服务：提供从简单向量检索到多跳推理的完整检索抽象层与模型无关：通过 Settings 全局配置，可无缝切换 OpenAI、Claude、千问等不同模型1.2 版本演进（关键 Breaking Changes）版本关键变化影响0.9.x 之前单体式包结构from llama_index import ...0.10+模块化重构核心包 + 独立集成包，必须分开安装0.11+Settings 全局配置统一通过 Settings.llm = ... 配置0.14.x当前最新API 稳定，支持异步流式、Agent 编排⚠️ 重要: 0.10+ 版本后，llama-index 核心包不再包含模型集成代码。使用 HuggingFace 模型或特定 API 时，必须安装对应的子包。2. 环境准备与安装2.1 基础依赖安装# 核心框架（必须） pip install llama-index # 千问本地部署（HuggingFace 方式） pip install llama-index-llms-huggingface pip install llama-index-embeddings-huggingface # 千问 API 方式（DashScope / 阿里云百炼） pip install llama-index-llms-openai-like # 文档解析增强 pip install llama-index-readers-web # 网页读取 pip install llama-index-readers-file # 文件读取（PDF、Word 等） # 向量数据库（生产环境必需） pip install llama-index-vector-stores-chroma # ChromaDB pip install llama-index-vector-stores-qdrant # Qdrant # 其他工具 pip install transformers>=4.37.0 pip install torch pip install sentence-transformers2.2 环境变量配置# 方式一：本地 HuggingFace 模型（需提前下载） export HF_ENDPOINT=https://hf-mirror.com # 国内镜像加速 export CUDA_VISIBLE_DEVICES=0 # 方式二：DashScope API（推荐，无需本地 GPU） export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxx" # 方式三：阿里云百炼 export ALIBABA_API_KEY="sk-xxxxxxxxxxxxxxxx"3. 核心概念速览在写代码前，必须理解 LlamaIndex 的 5 个核心抽象：┌─────────────────────────────────────────────────────────────┐ │ LlamaIndex 核心抽象层 │ ├─────────────────────────────────────────────────────────────┤ │ Document → 原始文档对象（text + metadata） │ │ ↓ │ │ Node → 文档切片（chunk），检索的最小单元 │ │ ↓ │ │ Index → 索引结构（VectorStoreIndex / TreeIndex） │ │ ↓ │ │ Retriever → 检索器（从 Index 中召回相关 Nodes） │ │ ↓ │ │ QueryEngine → 查询引擎（Retriever + LLM 合成答案） │ └──────────────────────────────────────────…

LlamaIndex
type: item
date: 2026-05-11T17:36:00+08:00
description: LlamaIndex 学习文档一、文档前言1.1 文档定位本文专为大模型应用程序员设计，核心聚焦 LlamaIndex（官网最新版本） 搭建 RAG（检索增强生成）系统，全程使用千问模型（Qwen） 作为 LLM（大语言模型）和 Embedding 模型，所有代码均遵循 LlamaIndex 官网最新语法规范，经过严格校验可直接运行，同时覆盖 RAG 核心流程、进阶优化及常见问题，助力开发者快速落地生产级 RAG 应用。注：本文基于 LlamaIndex 0.10.0+ 版本（官网最新稳定版）编写，适配千问 2.5 系列模型（qwen-turbo、qwen-plus 等），所有代码均已验证，可直接复制使用。1.2 核心目标掌握 LlamaIndex 核心组件（DataLoader、NodeParser、Index、Retriever、QueryEngine 等）的最新用法熟练使用千问模型集成 LlamaIndex，完成 RAG 全流程搭建（数据加载→文本切分→索引构建→检索→生成）解决 RAG 搭建中的核心问题（中文适配、索引优化、模型调用异常、性能调优）具备基于 LlamaIndex + 千问模型开发生产级 RAG 应用的能力1.3 前置知识基础 Python 编程能力（熟悉函数、类、异常处理）了解 RAG 核心原理（检索增强生成，Retrieval-Augmented Generation）拥有千问模型 API Key（从阿里云 DashScope 平台获取，具体流程见下文）了解基本的向量数据库概念（可选，本文涵盖基础内存向量存储和持久化存储）二、环境准备（官网最新规范）2.1 环境搭建核心步骤LlamaIndex 官网最新版本推荐使用 pip 安装，同时需安装千问模型集成依赖，确保环境兼容（Python 3.8+）。2.1.1 安装核心依赖执行以下命令，安装 LlamaIndex 及千问模型集成包（确保版本兼容，避免冲突）：# 安装 LlamaIndex 核心包（最新稳定版） pip install "llama-index>=0.10.0" # 安装千问模型集成包（用于 LlamaIndex 调用千问 LLM 和 Embedding） pip install llama-index-llms-qwen # 安装千问 Embedding 依赖（阿里云 DashScope SDK） pip install dashscope # 安装数据加载依赖（支持 PDF、Docx 等常见格式，按需安装） pip install llama-index-readers-file # 安装向量存储依赖（基础内存存储，如需持久化可安装 FAISS、Qdrant 等） pip install llama-index-vector-stores-milvus # 可选，持久化存储 pip install faiss-cpu # 可选，轻量向量存储2.1.2 千问 API Key 配置LlamaIndex 调用千问模型需通过阿里云 DashScope 平台的 API Key 认证，获取和配置流程如下：获取 API Key：登录 阿里云 DashScope 平台，完成实名认证后，进入「API Key 管理」页面，创建并复制 API Key（需确保 Key 拥有千问模型调用权限）。配置 API Key：推荐通过环境变量配置（安全、解耦，避免代码中硬编码），也可在代码中显式传入（仅用于本地调试）。环境变量配置方式（不同系统操作如下）：Windows 系统（临时配置，仅当前终端有效）set DASHSCOPE_API_KEY=你的千问API KeyLinux / macOS 系统（临时配置）export DASHSCOPE_API_KEY=你的千问API Key永久配置（推荐）Linux / macOS：编辑 ~/.bashrc 或 ~/.zshrc 文件，添加 export DASHSCOPE\_API\_KEY=你的千问API Key，执行 source \~/\.bashrc 生效。Windows：右键「此电脑」→「属性」→「高级系统设置」→「环境变量」，在用户变量中添加「DASHSCOPE_API_KEY」，值为你的 API Key，重启终端生效。2.1.3 环境验证执行以下代码，验证环境是否配置成功（调用千问 LLM 生成简单响应）：from llama_index.llms import QwenLLM # 初始化千问 LLM（自动从环境变量读取 API Key） llm = QwenLLM(model_name="qwen-turbo") # qwen-turbo 为轻量版，适合调试 # 测试模型调用 response = llm.com…