28.llamaindex

1 核心概念

1.1 框架介绍

01.LlamaIndex简介
    a.核心定位
        a.功能说明
            LlamaIndex是专注于数据索引和检索的RAG框架。提供灵活的数据连接器和索引结构。支持多种查询引擎和检索策略。是构建知识库问答系统的利器。
        b.代码示例
            ---
            # 1. 快速开始

            from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

            # 加载文档
            documents = SimpleDirectoryReader("./data").load_data()

            # 构建索引
            index = VectorStoreIndex.from_documents(documents)

            # 查询
            query_engine = index.as_query_engine()
            response = query_engine.query("什么是AI？")

            print(response)

            # 2. 基础组件

            from llama_index.core import Document
            from llama_index.core.node_parser import SimpleNodeParser
            from llama_index.embeddings.openai import OpenAIEmbedding
            from llama_index.llms.openai import OpenAI

            # 创建文档
            doc = Document(text="LlamaIndex是一个数据框架")

            # Node解析器
            parser = SimpleNodeParser()
            nodes = parser.get_nodes_from_documents([doc])

            # Embedding模型
            embed_model = OpenAIEmbedding()

            # LLM模型
            llm = OpenAI(model="gpt-3.5-turbo")

            print(f"解析出{len(nodes)}个节点")

            # 3. Settings全局配置

            from llama_index.core import Settings

            # 配置全局LLM
            Settings.llm = OpenAI(model="gpt-3.5-turbo", temperature=0.7)

            # 配置全局Embedding
            Settings.embed_model = OpenAIEmbedding()

            # 配置chunk大小
            Settings.chunk_size = 512
            Settings.chunk_overlap = 50

            print("全局配置完成")

            # 4. 完整示例

            from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
            from llama_index.core import Settings
            from llama_index.llms.openai import OpenAI
            from llama_index.embeddings.openai import OpenAIEmbedding

            # 配置
            Settings.llm = OpenAI(model="gpt-3.5-turbo")
            Settings.embed_model = OpenAIEmbedding()

            # 加载数据
            documents = SimpleDirectoryReader("./data").load_data()

            # 构建索引
            index = VectorStoreIndex.from_documents(documents)

            # 创建查询引擎
            query_engine = index.as_query_engine(
                similarity_top_k=3,
                response_mode="compact"
            )

            # 查询
            response = query_engine.query("介绍一下LlamaIndex")
            print(response)

            print("✓ 快速开始示例完成")

            # 5. 与LangChain对比

            # LlamaIndex优势：
            # - 专注于数据索引和检索
            # - 丰富的索引类型（向量、树形、图等）
            # - 灵活的查询引擎
            # - 强大的数据连接器

            # LangChain优势：
            # - 通用的LLM应用框架
            # - 丰富的Chain组合
            # - Agent和工具生态
            # - 更广泛的应用场景

            # 两者可以结合使用
            print("✓ LlamaIndex核心特性")
            ---
    b.应用场景
        a.功能说明
            适用于企业知识库问答系统。支持多文档语义搜索和对比。实现智能文档助手和RAG应用。是构建企业AI应用的理想选择。
        b.代码示例
            ---
            # 1. 企业知识库场景

            from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

            # 加载企业文档
            documents = SimpleDirectoryReader("./company_docs").load_data()

            # 构建索引
            index = VectorStoreIndex.from_documents(documents)

            # 保存索引（持久化）
            index.storage_context.persist(persist_dir="./storage")

            # 加载已有索引
            from llama_index.core import StorageContext, load_index_from_storage

            storage_context = StorageContext.from_defaults(persist_dir="./storage")
            index = load_index_from_storage(storage_context)

            # 查询引擎
            query_engine = index.as_query_engine()

            # 员工提问
            response = query_engine.query("公司的请假政策是什么？")
            print(response)

            # 2. 多文档问答

            from llama_index.core import VectorStoreIndex
            from llama_index.core import Document

            # 多个文档源
            doc1 = Document(text="2023年财报：营收增长20%")
            doc2 = Document(text="2024年Q1财报：营收增长15%")
            doc3 = Document(text="2024年Q2财报：营收增长18%")

            # 构建索引
            index = VectorStoreIndex.from_documents([doc1, doc2, doc3])

            # 对比查询
            query_engine = index.as_query_engine()
            response = query_engine.query("对比各季度营收增长情况")

            print(response)

            # 3. 技术文档助手

            from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

            # 加载技术文档（API文档、教程等）
            documents = SimpleDirectoryReader("./tech_docs").load_data()

            # 构建索引
            index = VectorStoreIndex.from_documents(documents)

            # Chat模式
            chat_engine = index.as_chat_engine(
                chat_mode="context",
                verbose=True
            )

            # 多轮对话
            response1 = chat_engine.chat("如何安装Python？")
            print(response1)

            response2 = chat_engine.chat("如何配置虚拟环境？")
            print(response2)

            print("✓ 应用场景示例完成")
            ---            	

1.2 核心组件

01.组件架构
    a.Document文档
        a.功能说明
            Document是LlamaIndex的基础数据单元。包含文本内容和元数据。支持自定义字段和关系。是数据处理的起点。
        b.代码示例
            ---
            # 1. 创建Document

            from llama_index.core import Document

            # 基础文档
            doc = Document(
                text="LlamaIndex是数据框架",
                metadata={
                    "source": "documentation",
                    "author": "LlamaIndex Team",
                    "date": "2024-01-01"
                }
            )

            print(f"文档ID: {doc.doc_id}")
            print(f"文本: {doc.text}")
            print(f"元数据: {doc.metadata}")

            # 2. 批量创建

            documents = [
                Document(
                    text="第一篇文章内容",
                    metadata={"category": "tech"}
                ),
                Document(
                    text="第二篇文章内容",
                    metadata={"category": "business"}
                ),
                Document(
                    text="第三篇文章内容",
                    metadata={"category": "tech"}
                )
            ]

            print(f"创建了{len(documents)}个文档")

            # 3. 文档关系

            doc1 = Document(text="主文档", doc_id="doc1")
            doc2 = Document(
                text="子文档",
                doc_id="doc2",
                relationships={
                    "parent": doc1.doc_id
                }
            )

            print(f"文档关系: {doc2.relationships}")

            print("✓ Document组件完成")
            ---
    a.Node节点
        a.功能说明
            Node是Document切分后的最小单元。包含chunk文本和embedding向量。支持父子关系和元数据继承。是索引和检索的基础。
        b.代码示例
            ---
            # 1. Node解析

            from llama_index.core import Document
            from llama_index.core.node_parser import SimpleNodeParser

            doc = Document(text="这是一段很长的文本内容。" * 100)

            # 创建解析器
            parser = SimpleNodeParser.from_defaults(
                chunk_size=512,
                chunk_overlap=50
            )

            # 解析为Nodes
            nodes = parser.get_nodes_from_documents([doc])

            print(f"解析出{len(nodes)}个节点")
            print(f"第一个节点内容: {nodes[0].text[:100]}")

            # 2. Node属性

            node = nodes[0]
            print(f"Node ID: {node.node_id}")
            print(f"文本: {node.text[:50]}")
            print(f"元数据: {node.metadata}")
            print(f"关系: {node.relationships}")

            # 3. 自定义Node

            from llama_index.core.schema import TextNode

            custom_node = TextNode(
                text="自定义节点内容",
                metadata={"custom_field": "custom_value"}
            )

            print(f"自定义节点: {custom_node.text}")

            print("✓ Node组件完成")
            ---
    a.Index索引
        a.功能说明
            Index管理和组织Node集合。提供多种索引类型（向量、树形、图等）。支持高效的检索和查询。是RAG的核心组件。
        b.代码示例
            ---
            # 1. VectorStoreIndex

            from llama_index.core import VectorStoreIndex, Document

            documents = [
                Document(text="Python是编程语言"),
                Document(text="Java也是编程语言"),
                Document(text="JavaScript用于Web开发")
            ]

            # 构建向量索引
            index = VectorStoreIndex.from_documents(documents)

            # 查询
            query_engine = index.as_query_engine()
            response = query_engine.query("什么是编程语言？")

            print(response)

            # 2. 索引持久化

            # 保存索引
            index.storage_context.persist(persist_dir="./index_storage")

            # 加载索引
            from llama_index.core import StorageContext, load_index_from_storage

            storage_context = StorageContext.from_defaults(
                persist_dir="./index_storage"
            )
            loaded_index = load_index_from_storage(storage_context)

            # 使用加载的索引
            query_engine = loaded_index.as_query_engine()
            response = query_engine.query("Python的特点")

            print(response)

            print("✓ Index组件完成")
            ---

1.3 工作流程

01.RAG流程
    a.数据处理流程
        a.功能说明
            完整的RAG流程包括数据加载、切分、索引、检索和生成五个阶段。每个阶段可独立配置和优化。理解流程有助于构建高质量RAG应用。
        b.代码示例
            ---
            # 1. 完整RAG流程

            from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
            from llama_index.core import Settings
            from llama_index.llms.openai import OpenAI
            from llama_index.embeddings.openai import OpenAIEmbedding

            # 阶段1: 配置
            Settings.llm = OpenAI(model="gpt-3.5-turbo")
            Settings.embed_model = OpenAIEmbedding()
            Settings.chunk_size = 512
            Settings.chunk_overlap = 50

            # 阶段2: 数据加载
            print("1. 加载数据...")
            documents = SimpleDirectoryReader("./data").load_data()
            print(f"加载了{len(documents)}个文档")

            # 阶段3: 构建索引（包含切分和向量化）
            print("2. 构建索引...")
            index = VectorStoreIndex.from_documents(
                documents,
                show_progress=True
            )
            print("索引构建完成")

            # 阶段4: 创建查询引擎
            print("3. 创建查询引擎...")
            query_engine = index.as_query_engine(
                similarity_top_k=3,
                response_mode="compact"
            )

            # 阶段5: 检索和生成
            print("4. 执行查询...")
            response = query_engine.query("什么是LlamaIndex？")
            print(f"响应: {response}")

            # 查看检索到的源节点
            print("\n5. 源节点:")
            for i, node in enumerate(response.source_nodes, 1):
                print(f"节点{i}: {node.text[:100]}...")
                print(f"相似度: {node.score}")

            print("✓ RAG流程完成")

            # 2. 流程自定义

            from llama_index.core.node_parser import SentenceSplitter
            from llama_index.core.extractors import TitleExtractor
            from llama_index.core.ingestion import IngestionPipeline

            # 自定义处理管道
            pipeline = IngestionPipeline(
                transformations=[
                    SentenceSplitter(chunk_size=512, chunk_overlap=50),
                    TitleExtractor(),
                    Settings.embed_model,
                ]
            )

            # 运行管道
            nodes = pipeline.run(documents=documents)

            # 构建索引
            index = VectorStoreIndex(nodes)

            print(f"处理了{len(nodes)}个节点")

            # 3. 流式处理

            query_engine = index.as_query_engine(
                streaming=True
            )

            # 流式查询
            streaming_response = query_engine.query("介绍Python")

            print("流式响应: ", end="")
            for text in streaming_response.response_gen:
                print(text, end="", flush=True)
            print()

            print("✓ 工作流程示例完成")
            ---

2 数据加载

2.1 Document Loaders

01.数据加载器
    a.SimpleDirectoryReader
        a.功能说明
            SimpleDirectoryReader自动加载目录下的文件。支持txt、pdf、docx等多种格式。递归扫描子目录。是最常用的数据加载器。
        b.代码示例
            ---
            # 1. 基础加载

            from llama_index.core import SimpleDirectoryReader

            # 加载单个目录
            documents = SimpleDirectoryReader("./data").load_data()

            print(f"加载了{len(documents)}个文档")
            for doc in documents[:3]:
                print(f"文档: {doc.metadata.get('file_name')}")
                print(f"内容预览: {doc.text[:100]}...")

            # 2. 指定文件类型

            documents = SimpleDirectoryReader(
                input_dir="./data",
                required_exts=[".txt", ".md"]  # 只加载txt和md文件
            ).load_data()

            print(f"加载了{len(documents)}个txt/md文档")

            # 3. 递归加载

            documents = SimpleDirectoryReader(
                input_dir="./data",
                recursive=True  # 递归扫描子目录
            ).load_data()

            print(f"递归加载了{len(documents)}个文档")

            # 4. 排除文件

            documents = SimpleDirectoryReader(
                input_dir="./data",
                exclude=["*.log", "*.tmp"]  # 排除日志和临时文件
            ).load_data()

            print(f"加载了{len(documents)}个文档（已排除日志）")

            # 5. 文件编码

            documents = SimpleDirectoryReader(
                input_dir="./data",
                encoding="utf-8"  # 指定编码
            ).load_data()

            # 6. 元数据提取

            documents = SimpleDirectoryReader(
                input_dir="./data",
                filename_as_id=True  # 使用文件名作为doc_id
            ).load_data()

            for doc in documents[:2]:
                print(f"文档ID: {doc.doc_id}")
                print(f"文件名: {doc.metadata['file_name']}")
                print(f"文件路径: {doc.metadata['file_path']}")

            print("✓ SimpleDirectoryReader完成")
            ---
    a.专用加载器
        a.功能说明
            支持PDF、Word、Excel等特定格式。提供格式特定的解析选项。集成LlamaHub丰富的加载器生态。满足多样化数据源需求。
        b.代码示例
            ---
            # 1. PDF加载器

            from llama_index.readers.file import PDFReader

            loader = PDFReader()
            documents = loader.load_data(file="./document.pdf")

            print(f"PDF文档页数: {len(documents)}")

            # 2. Markdown加载器

            from llama_index.readers.file import MarkdownReader

            loader = MarkdownReader()
            documents = loader.load_data(file="./README.md")

            print(f"Markdown内容: {documents[0].text[:200]}")

            # 3. 数据库加载器

            from llama_index.readers.database import DatabaseReader

            reader = DatabaseReader(
                connection_string="postgresql://user:pass@localhost/db"
            )

            documents = reader.load_data(
                query="SELECT content FROM articles"
            )

            print(f"从数据库加载了{len(documents)}条记录")

            # 4. Web加载器

            from llama_index.readers.web import SimpleWebPageReader

            loader = SimpleWebPageReader()
            documents = loader.load_data(
                urls=["https://example.com/page1", "https://example.com/page2"]
            )

            print(f"从网页加载了{len(documents)}个文档")

            print("✓ 专用加载器完成")
            ---

2.2 Node Parser

01.节点解析
    a.SentenceSplitter
        a.功能说明
            SentenceSplitter基于句子边界切分文本。保持语义完整性。支持自定义chunk大小和overlap。是最常用的解析器。
        b.代码示例
            ---
            # 1. 基础切分

            from llama_index.core.node_parser import SentenceSplitter
            from llama_index.core import Document

            doc = Document(text="这是第一句。这是第二句。" * 100)

            parser = SentenceSplitter(
                chunk_size=512,
                chunk_overlap=50
            )

            nodes = parser.get_nodes_from_documents([doc])

            print(f"切分出{len(nodes)}个节点")
            print(f"第一个节点: {nodes[0].text[:100]}")

            # 2. 自定义分隔符

            parser = SentenceSplitter(
                chunk_size=512,
                chunk_overlap=50,
                separator="\n\n"  # 按段落切分
            )

            nodes = parser.get_nodes_from_documents([doc])
            print(f"段落切分: {len(nodes)}个节点")

            print("✓ Node Parser完成")
            ---

2.3 自定义Loader

01.自定义实现
    a.BaseReader实现
        a.功能说明
            继承BaseReader实现自定义加载器。适配特殊数据源和格式。扩展LlamaIndex的数据接入能力。
        b.代码示例
            ---
            # 自定义Loader

            from llama_index.core.readers.base import BaseReader
            from llama_index.core import Document
            from typing import List

            class CustomReader(BaseReader):
                """自定义数据加载器"""

                def load_data(self, source: str) -> List[Document]:
                    # 实现加载逻辑
                    documents = []

                    # 模拟加载数据
                    data = f"从{source}加载的数据"

                    doc = Document(
                        text=data,
                        metadata={"source": source}
                    )
                    documents.append(doc)

                    return documents

            # 使用自定义loader
            loader = CustomReader()
            documents = loader.load_data("custom_source")

            print(f"加载了{len(documents)}个文档")
            print("✓ 自定义Loader完成")
            ---

3 索引构建

3.1 VectorStoreIndex

01.向量索引
    a.基础构建
        a.功能说明
            VectorStoreIndex是最常用的索引类型。基于向量相似度检索。支持增量更新和持久化。适合大规模文档检索。
        b.代码示例
            ---
            # 1. 基础构建

            from llama_index.core import VectorStoreIndex, Document

            documents = [
                Document(text="Python是编程语言"),
                Document(text="Java也是编程语言"),
                Document(text="JavaScript用于Web")
            ]

            index = VectorStoreIndex.from_documents(documents)

            # 查询
            query_engine = index.as_query_engine(similarity_top_k=2)
            response = query_engine.query("编程语言有哪些？")

            print(response)

            # 2. 增量更新

            new_doc = Document(text="Go语言用于并发编程")
            index.insert(new_doc)

            # 3. 持久化

            index.storage_context.persist(persist_dir="./index_store")

            print("✓ VectorStoreIndex完成")
            ---

3.2 TreeIndex

01.树形索引
    a.层次结构
        a.功能说明
            TreeIndex构建文档的树形层次结构。适合长文档摘要和层次查询。自底向上构建摘要树。适合多层次信息提取。
        b.代码示例
            ---
            # TreeIndex示例

            from llama_index.core import TreeIndex, Document

            documents = [
                Document(text="第一章内容很长..."),
                Document(text="第二章内容很长..."),
                Document(text="第三章内容很长...")
            ]

            index = TreeIndex.from_documents(documents)

            # 查询（会递归摘要）
            query_engine = index.as_query_engine()
            response = query_engine.query("全书的主要内容？")

            print(response)
            print("✓ TreeIndex完成")
            ---

3.3 KeywordTableIndex

01.关键词索引
    a.关键词提取
        a.功能说明
            KeywordTableIndex基于关键词构建索引。支持精确关键词匹配。适合结构化查询。补充向量检索的不足。
        b.代码示例
            ---
            # KeywordTableIndex示例

            from llama_index.core import KeywordTableIndex, Document

            documents = [
                Document(text="Python编程语言特点"),
                Document(text="Java企业级开发"),
                Document(text="JavaScript前端框架")
            ]

            index = KeywordTableIndex.from_documents(documents)

            # 关键词查询
            query_engine = index.as_query_engine()
            response = query_engine.query("Python")

            print(response)
            print("✓ KeywordTableIndex完成")
            ---

3.4 KnowledgeGraphIndex

01.知识图谱索引
    a.图结构
        a.功能说明
            KnowledgeGraphIndex构建实体关系图。提取实体和关系三元组。支持图遍历查询。适合复杂关系推理。
        b.代码示例
            ---
            # KnowledgeGraphIndex示例

            from llama_index.core import KnowledgeGraphIndex, Document

            documents = [
                Document(text="张三在阿里巴巴工作，他是工程师"),
                Document(text="李四在腾讯工作，他是产品经理"),
                Document(text="张三和李四是大学同学")
            ]

            index = KnowledgeGraphIndex.from_documents(documents)

            # 关系查询
            query_engine = index.as_query_engine()
            response = query_engine.query("张三的工作和关系？")

            print(response)
            print("✓ KnowledgeGraphIndex完成")
            ---

3.5 DocumentSummaryIndex

01.文档摘要索引
    a.摘要构建
        a.功能说明
            DocumentSummaryIndex为每个文档生成摘要。支持摘要和原文两级检索。适合长文档场景。提升检索准确性。
        b.代码示例
            ---
            # DocumentSummaryIndex示例

            from llama_index.core import DocumentSummaryIndex, Document

            documents = [
                Document(text="第一篇长文章内容..." * 100),
                Document(text="第二篇长文章内容..." * 100)
            ]

            index = DocumentSummaryIndex.from_documents(documents)

            # 基于摘要检索
            query_engine = index.as_query_engine()
            response = query_engine.query("文章主题？")

            print(response)
            print("✓ DocumentSummaryIndex完成")
            ---

4 查询引擎

4.1 基础查询

01.Query Engine
    a.基础查询引擎
        a.功能说明
            QueryEngine执行查询并返回响应。支持多种响应模式。可配置检索参数。是用户交互的主要接口。
        b.代码示例
            ---
            # 基础查询

            from llama_index.core import VectorStoreIndex, Document

            index = VectorStoreIndex.from_documents([
                Document(text="LlamaIndex是数据框架")
            ])

            # 创建查询引擎
            query_engine = index.as_query_engine(
                similarity_top_k=3,
                response_mode="compact"
            )

            # 执行查询
            response = query_engine.query("什么是LlamaIndex？")
            print(response)

            # 查看源节点
            for node in response.source_nodes:
                print(f"来源: {node.text[:50]}")
                print(f"相似度: {node.score}")

            print("✓ 基础查询完成")
            ---

4.2 SubQuestionQueryEngine

01.子问题查询
    a.问题分解
        a.功能说明
            SubQuestionQueryEngine将复杂问题分解为子问题。并行查询多个数据源。汇总子答案生成最终响应。适合多源数据查询。
        b.代码示例
            ---
            # SubQuestion查询

            from llama_index.core.query_engine import SubQuestionQueryEngine
            from llama_index.core.tools import QueryEngineTool

            # 创建多个索引
            tech_index = VectorStoreIndex.from_documents(tech_docs)
            business_index = VectorStoreIndex.from_documents(business_docs)

            # 创建工具
            tools = [
                QueryEngineTool.from_defaults(
                    query_engine=tech_index.as_query_engine(),
                    description="技术文档"
                ),
                QueryEngineTool.from_defaults(
                    query_engine=business_index.as_query_engine(),
                    description="商业文档"
                )
            ]

            # 创建子问题引擎
            query_engine = SubQuestionQueryEngine.from_defaults(
                query_engine_tools=tools
            )

            response = query_engine.query("技术和商业方面的优势？")
            print(response)
            print("✓ SubQuestion查询完成")
            ---

4.3 MultiStepQueryEngine

01.多步查询
    a.迭代查询
        a.功能说明
            MultiStepQueryEngine支持多轮迭代查询。根据上一步结果调整下一步查询。适合需要逐步推理的场景。
        b.代码示例
            ---
            # MultiStep查询

            from llama_index.core.query_engine import MultiStepQueryEngine

            index = VectorStoreIndex.from_documents(documents)

            query_engine = MultiStepQueryEngine(
                query_engine=index.as_query_engine(),
                num_steps=3  # 最多3步
            )

            response = query_engine.query("复杂推理问题")
            print(response)
            print("✓ MultiStep查询完成")
            ---

4.4 RouterQueryEngine

01.路由查询
    a.智能路由
        a.功能说明
            RouterQueryEngine根据问题选择最合适的索引。支持多种路由策略。提升查询效率和准确性。
        b.代码示例
            ---
            # Router查询

            from llama_index.core.query_engine import RouterQueryEngine
            from llama_index.core.selectors import LLMSingleSelector

            # 创建路由器
            query_engine = RouterQueryEngine(
                selector=LLMSingleSelector.from_defaults(),
                query_engine_tools=[tech_tool, business_tool]
            )

            response = query_engine.query("技术问题")
            print(response)
            print("✓ Router查询完成")
            ---

4.5 响应合成器

01.Response Synthesizer
    a.响应生成
        a.功能说明
            ResponseSynthesizer将检索结果合成最终响应。支持多种合成模式（compact、refine等）。可配置prompt模板。
        b.代码示例
            ---
            # 响应合成

            from llama_index.core.response_synthesizers import get_response_synthesizer

            synthesizer = get_response_synthesizer(
                response_mode="compact"  # compact, refine, tree_summarize
            )

            # 使用合成器
            query_engine = index.as_query_engine(
                response_synthesizer=synthesizer
            )

            response = query_engine.query("问题")
            print(response)
            print("✓ 响应合成完成")
            ---

5 检索器

5.1 VectorIndexRetriever

01.向量检索器
    a.相似度检索
        a.功能说明
            VectorIndexRetriever基于向量相似度检索。可配置top_k和相似度阈值。支持元数据过滤。是最常用的检索器。
        b.代码示例
            ---
            # 向量检索

            from llama_index.core import VectorStoreIndex
            from llama_index.core.retrievers import VectorIndexRetriever

            index = VectorStoreIndex.from_documents(documents)

            retriever = VectorIndexRetriever(
                index=index,
                similarity_top_k=5
            )

            nodes = retriever.retrieve("查询问题")

            for node in nodes:
                print(f"内容: {node.text[:100]}")
                print(f"分数: {node.score}")

            print("✓ 向量检索完成")
            ---

5.2 KeywordTableRetriever

01.关键词检索
    a.精确匹配
        a.功能说明
            KeywordTableRetriever基于关键词精确匹配。补充向量检索。适合结构化查询。提升检索准确性。
        b.代码示例
            ---
            # 关键词检索

            from llama_index.core.retrievers import KeywordTableSimpleRetriever

            retriever = KeywordTableSimpleRetriever(index=keyword_index)

            nodes = retriever.retrieve("Python")
            print(f"检索到{len(nodes)}个节点")
            print("✓ 关键词检索完成")
            ---

5.3 自定义Retriever

01.自定义检索
    a.BaseRetriever实现
        a.功能说明
            继承BaseRetriever实现自定义检索逻辑。灵活组合多种检索策略。扩展检索能力。
        b.代码示例
            ---
            # 自定义Retriever

            from llama_index.core.retrievers import BaseRetriever

            class CustomRetriever(BaseRetriever):
                def _retrieve(self, query_bundle):
                    # 实现检索逻辑
                    nodes = []
                    # ... 检索实现
                    return nodes

            retriever = CustomRetriever()
            nodes = retriever.retrieve("查询")
            print("✓ 自定义检索完成")
            ---

5.4 高级检索策略

01.混合检索
    a.多策略组合
        a.功能说明
            组合向量检索和关键词检索。支持重排序和过滤。提升检索质量。
        b.代码示例
            ---
            # 混合检索

            from llama_index.core.retrievers import QueryFusionRetriever

            retrievers = [vector_retriever, keyword_retriever]

            fusion_retriever = QueryFusionRetriever(
                retrievers=retrievers,
                similarity_top_k=5,
                num_queries=3
            )

            nodes = fusion_retriever.retrieve("查询")
            print(f"混合检索：{len(nodes)}个节点")
            print("✓ 高级检索完成")
            ---

6 向量存储集成

6.1 Milvus

01.Milvus集成
    a.向量存储
        a.功能说明
            Milvus是开源向量数据库。支持大规模向量检索。提供高性能和高可用。是企业级向量存储首选。
        b.代码示例
            ---
            # Milvus集成

            from llama_index.vector_stores.milvus import MilvusVectorStore
            from llama_index.core import VectorStoreIndex, StorageContext

            vector_store = MilvusVectorStore(
                host="localhost",
                port=19530,
                dim=1536
            )

            storage_context = StorageContext.from_defaults(
                vector_store=vector_store
            )

            index = VectorStoreIndex.from_documents(
                documents,
                storage_context=storage_context
            )

            print("✓ Milvus集成完成")
            ---

6.2 Chroma

01.Chroma集成
    a.轻量存储
        a.功能说明
            Chroma是轻量级向量数据库。易于部署和使用。支持本地和云端部署。适合快速原型开发。
        b.代码示例
            ---
            # Chroma集成

            from llama_index.vector_stores.chroma import ChromaVectorStore
            import chromadb

            chroma_client = chromadb.Client()
            chroma_collection = chroma_client.create_collection("my_collection")

            vector_store = ChromaVectorStore(chroma_collection=chroma_collection)

            storage_context = StorageContext.from_defaults(vector_store=vector_store)

            index = VectorStoreIndex.from_documents(
                documents,
                storage_context=storage_context
            )

            print("✓ Chroma集成完成")
            ---

6.3 Qdrant

01.Qdrant集成
    a.高性能存储
        a.功能说明
            Qdrant专注于向量相似度搜索。支持过滤和元数据查询。提供REST和gRPC接口。性能优异。
        b.代码示例
            ---
            # Qdrant集成

            from llama_index.vector_stores.qdrant import QdrantVectorStore
            import qdrant_client

            client = qdrant_client.QdrantClient(url="http://localhost:6333")

            vector_store = QdrantVectorStore(
                client=client,
                collection_name="my_collection"
            )

            storage_context = StorageContext.from_defaults(vector_store=vector_store)

            index = VectorStoreIndex.from_documents(
                documents,
                storage_context=storage_context
            )

            print("✓ Qdrant集成完成")
            ---

6.4 Pinecone

01.Pinecone集成
    a.云端服务
        a.功能说明
            Pinecone是托管向量数据库服务。全托管无需运维。支持大规模向量检索。适合云原生应用。
        b.代码示例
            ---
            # Pinecone集成

            from llama_index.vector_stores.pinecone import PineconeVectorStore
            import pinecone

            pinecone.init(api_key="your_api_key", environment="us-west1-gcp")

            vector_store = PineconeVectorStore(
                pinecone_index=pinecone.Index("my-index")
            )

            storage_context = StorageContext.from_defaults(vector_store=vector_store)

            index = VectorStoreIndex.from_documents(
                documents,
                storage_context=storage_context
            )

            print("✓ Pinecone集成完成")
            ---

7 Chat Engine

7.1 对话引擎

01.Chat Engine
    a.对话模式
        a.功能说明
            ChatEngine支持多轮对话。维护对话历史上下文。支持context、condense等多种模式。是构建聊天机器人的基础。
        b.代码示例
            ---
            # Chat Engine

            from llama_index.core import VectorStoreIndex

            index = VectorStoreIndex.from_documents(documents)

            chat_engine = index.as_chat_engine(
                chat_mode="context",
                verbose=True
            )

            response = chat_engine.chat("你好")
            print(response)

            response = chat_engine.chat("继续")
            print(response)

            print("✓ Chat Engine完成")
            ---

7.2 上下文管理

01.Memory管理
    a.对话历史
        a.功能说明
            管理对话历史和上下文。支持有限窗口和摘要策略。优化token使用。提升对话连贯性。
        b.代码示例
            ---
            # 上下文管理

            from llama_index.core.memory import ChatMemoryBuffer

            memory = ChatMemoryBuffer.from_defaults(token_limit=3000)

            chat_engine = index.as_chat_engine(
                chat_mode="context",
                memory=memory
            )

            response = chat_engine.chat("问题1")
            response = chat_engine.chat("问题2")

            print("✓ 上下文管理完成")
            ---

7.3 流式对话

01.Streaming
    a.流式输出
        a.功能说明
            支持流式对话响应。实时输出生成内容。提升用户体验。适合长文本生成。
        b.代码示例
            ---
            # 流式对话

            chat_engine = index.as_chat_engine(
                chat_mode="context",
                streaming=True
            )

            streaming_response = chat_engine.stream_chat("讲个故事")

            for token in streaming_response.response_gen:
                print(token, end="", flush=True)

            print("\n✓ 流式对话完成")
            ---

8 高级特性

8.1 Agent工具

01.ReActAgent
    a.工具调用
        a.功能说明
            ReActAgent支持工具调用和推理。结合检索和外部工具。实现复杂任务自动化。
        b.代码示例
            ---
            # ReAct Agent

            from llama_index.core.agent import ReActAgent
            from llama_index.core.tools import QueryEngineTool

            tools = [
                QueryEngineTool.from_defaults(
                    query_engine=index.as_query_engine(),
                    name="文档查询",
                    description="查询文档内容"
                )
            ]

            agent = ReActAgent.from_tools(tools, verbose=True)

            response = agent.chat("查询相关信息")
            print(response)
            print("✓ Agent工具完成")
            ---

8.2 Query Transformation

01.查询转换
    a.查询优化
        a.功能说明
            QueryTransformation优化和重写查询。生成多个查询版本。提升检索效果。
        b.代码示例
            ---
            # Query Transformation

            from llama_index.core.indices.query.query_transform import HyDEQueryTransform

            hyde = HyDEQueryTransform()

            query_engine = index.as_query_engine(
                query_transform=hyde
            )

            response = query_engine.query("复杂查询")
            print(response)
            print("✓ Query Transformation完成")
            ---

8.3 PostProcessor

01.后处理器
    a.结果优化
        a.功能说明
            PostProcessor处理检索结果。支持重排序、过滤、去重。提升最终结果质量。
        b.代码示例
            ---
            # PostProcessor

            from llama_index.core.postprocessor import SimilarityPostprocessor

            postprocessor = SimilarityPostprocessor(similarity_cutoff=0.7)

            query_engine = index.as_query_engine(
                node_postprocessors=[postprocessor]
            )

            response = query_engine.query("查询")
            print(response)
            print("✓ PostProcessor完成")
            ---

8.4 Evaluation评估

01.评估指标
    a.质量评估
        a.功能说明
            评估RAG系统的检索和生成质量。支持多种评估指标。帮助优化系统性能。
        b.代码示例
            ---
            # Evaluation

            from llama_index.core.evaluation import RelevancyEvaluator

            evaluator = RelevancyEvaluator()

            response = query_engine.query("测试查询")

            eval_result = evaluator.evaluate_response(
                query="测试查询",
                response=response
            )

            print(f"评估分数: {eval_result.score}")
            print(f"评估反馈: {eval_result.feedback}")
            print("✓ Evaluation完成")
            ---

9 实战案例

9.1 文档问答

01.QA系统
    a.实现步骤
        a.功能说明
            构建完整的文档问答系统。加载文档、构建索引、实现查询。是最典型的RAG应用场景。
        b.代码示例
            ---
            # 文档问答系统

            from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
            from llama_index.llms.openai import OpenAI
            from llama_index.embeddings.openai import OpenAIEmbedding

            Settings.llm = OpenAI(model="gpt-3.5-turbo")
            Settings.embed_model = OpenAIEmbedding()

            documents = SimpleDirectoryReader("./docs").load_data()

            index = VectorStoreIndex.from_documents(documents)

            index.storage_context.persist(persist_dir="./storage")

            query_engine = index.as_query_engine(similarity_top_k=3)

            response = query_engine.query("文档的主要内容？")
            print(response)
            print("✓ 文档问答完成")
            ---

9.2 多文档对比

01.对比分析
    a.多源查询
        a.功能说明
            对比多个文档的内容。使用SubQuestionQueryEngine分解查询。汇总对比结果。
        b.代码示例
            ---
            # 多文档对比

            from llama_index.core.query_engine import SubQuestionQueryEngine
            from llama_index.core.tools import QueryEngineTool

            doc1_index = VectorStoreIndex.from_documents(doc1_list)
            doc2_index = VectorStoreIndex.from_documents(doc2_list)

            tools = [
                QueryEngineTool.from_defaults(
                    query_engine=doc1_index.as_query_engine(),
                    description="文档1"
                ),
                QueryEngineTool.from_defaults(
                    query_engine=doc2_index.as_query_engine(),
                    description="文档2"
                )
            ]

            query_engine = SubQuestionQueryEngine.from_defaults(query_engine_tools=tools)

            response = query_engine.query("对比两个文档的异同")
            print(response)
            print("✓ 多文档对比完成")
            ---

9.3 知识库构建

01.企业知识库
    a.完整方案
        a.功能说明
            构建企业级知识库系统。支持多格式文档、持久化存储、权限控制。实现企业知识管理。
        b.代码示例
            ---
            # 企业知识库

            from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
            from llama_index.core import StorageContext
            from llama_index.vector_stores.milvus import MilvusVectorStore

            documents = SimpleDirectoryReader("./company_docs").load_data()

            vector_store = MilvusVectorStore(host="localhost", port=19530)

            storage_context = StorageContext.from_defaults(vector_store=vector_store)

            index = VectorStoreIndex.from_documents(
                documents,
                storage_context=storage_context
            )

            query_engine = index.as_query_engine()
            response = query_engine.query("公司政策查询")

            print(response)
            print("✓ 知识库构建完成")
            ---

9.4 智能搜索

01.语义搜索
    a.搜索系统
        a.功能说明
            实现语义搜索引擎。支持自然语言查询。返回相关文档和片段。提升搜索体验。
        b.代码示例
            ---
            # 智能搜索

            from llama_index.core import VectorStoreIndex

            index = VectorStoreIndex.from_documents(all_documents)

            retriever = index.as_retriever(similarity_top_k=10)

            query = "Python编程最佳实践"
            nodes = retriever.retrieve(query)

            for i, node in enumerate(nodes, 1):
                print(f"\n结果{i}:")
                print(f"内容: {node.text[:200]}...")
                print(f"相似度: {node.score:.4f}")
                print(f"来源: {node.metadata.get('file_name')}")

            print("✓ 智能搜索完成")
            ---

10 最佳实践

10.1 性能优化

01.优化策略
    a.索引优化
        a.功能说明
            优化索引构建和查询性能。合理配置chunk大小。使用缓存和批处理。提升系统响应速度。
        b.代码示例
            ---
            # 性能优化

            from llama_index.core import Settings
            from llama_index.core.node_parser import SentenceSplitter

            Settings.chunk_size = 512
            Settings.chunk_overlap = 50

            parser = SentenceSplitter(
                chunk_size=512,
                chunk_overlap=50
            )

            index = VectorStoreIndex.from_documents(
                documents,
                transformations=[parser],
                show_progress=True
            )

            query_engine = index.as_query_engine(
                similarity_top_k=3,
                response_mode="compact"
            )

            print("✓ 性能优化完成")
            ---

10.2 Chunk策略

01.切分策略
    a.优化切分
        a.功能说明
            选择合适的chunk大小和overlap。保持语义完整性。平衡检索精度和召回率。优化chunk策略提升效果。
        b.代码示例
            ---
            # Chunk策略

            from llama_index.core.node_parser import SentenceSplitter

            small_chunk = SentenceSplitter(chunk_size=256, chunk_overlap=20)

            medium_chunk = SentenceSplitter(chunk_size=512, chunk_overlap=50)

            large_chunk = SentenceSplitter(chunk_size=1024, chunk_overlap=100)

            nodes_small = small_chunk.get_nodes_from_documents(documents)
            nodes_medium = medium_chunk.get_nodes_from_documents(documents)
            nodes_large = large_chunk.get_nodes_from_documents(documents)

            print(f"小chunk: {len(nodes_small)}个节点")
            print(f"中chunk: {len(nodes_medium)}个节点")
            print(f"大chunk: {len(nodes_large)}个节点")
            print("✓ Chunk策略完成")
            ---

10.3 成本控制

01.成本优化
    a.Token管理
        a.功能说明
            优化embedding和LLM调用次数。使用本地embedding模型。批处理减少API调用。控制token消耗降低成本。
        b.代码示例
            ---
            # 成本控制

            from llama_index.embeddings.huggingface import HuggingFaceEmbedding
            from llama_index.core import Settings

            Settings.embed_model = HuggingFaceEmbedding(
                model_name="BAAI/bge-small-zh-v1.5"
            )

            Settings.chunk_size = 512

            index = VectorStoreIndex.from_documents(documents)

            query_engine = index.as_query_engine(
                similarity_top_k=3,
                response_mode="compact"
            )

            response = query_engine.query("查询")
            print(f"响应: {response}")
            print("✓ 使用本地embedding降低成本")
            print("✓ 成本控制完成")
            ---