使用 LlamaIndex 在 Python 中构建…

适用于需要在 Python 中基于 LlamaIndex 实现 RAG、文档加载与切分、向量索引、查询引擎、Agent 和生产级优化的场景。

适用场景

解决思路

1. 编写简洁、技术性的回答，并提供准确的 Python 示例。
2. 使用函数式、声明式编程；尽可能避免类。
3. 优先保证代码质量、可维护性和性能。
4. 使用能反映用途的描述性变量名。
5. 遵循 PEP 8 风格指南。
6. 按项目目录结构组织代码：data/ 存放源文档和数据；indexes/ 存放持久化索引；loaders/ 存放自定义文档加载器；retrievers/ 存放自定义检索器实现；query_engines/ 存放查询引擎配置；prompts/ 存放自定义提示模板；transformations/ 存放文档变换；callbacks/ 存放自定义回调处理器；utils/ 存放工具函数；tests/ 存放测试文件；config/ 存放配置文件。
7. 文件名、函数名和变量名使用 snake_case。
8. 类名使用 PascalCase。
9. 私有函数以下划线前缀。
10. 使用描述性名称，例如 `create_vector_index`、`build_query_engine`。
11. 使用 `SimpleDirectoryReader` 从目录加载文档：`input_dir='./data'`、`recursive=True`、`required_exts=['.pdf', '.txt', '.md']`，调用 `.load_data()`。
12. 加载特定文件类型：使用 `PDFReader`、`DocxReader` 等，例如 `pdf_reader = PDFReader(); documents = pdf_reader.load_data(file='document.pdf')`。
13. 实现自定义加载器：继承 `llama_index.core.readers.base.BaseReader`，实现 `load_data(self, file_path: str) -> list[Document]`，读取文件内容并返回 `[Document(text=content, metadata={'source': file_path})]`。
14. 使用 `SentenceSplitter(chunk_size=1024, chunk_overlap=200)` 进行简单句子切分，并调用 `get_nodes_from_documents(documents)`。
15. 使用 `SemanticSplitterNodeParser(embed_model=OpenAIEmbedding(), breakpoint_percentile_threshold=95)` 进行语义切分以保留含义。
16. 使用 `MarkdownNodeParser()` 进行 Markdown 感知切分。
17. 分块最佳实践：根据嵌入模型的上下文窗口选择 chunk size。
18. 分块最佳实践：使用 overlap 保持块之间的上下文。
19. 分块最佳实践：尽可能保留文档结构。
20. 分块最佳实践：包含 metadata 以便过滤和检索。
21. 分块最佳实践：使用语义切分获得更好的连贯性。
22. 创建内存索引：`index = VectorStoreIndex.from_documents(documents)`。
23. 使用持久化向量存储创建索引：`chroma_client = chromadb.PersistentClient(path='./chroma_db')`；`chroma_collection = chroma_client.get_or_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)`。
24. 可选择 Chroma 作为向量存储（本地开发）。
25. 可选择 Pinecone 作为向量存储（生产、托管）。
26. 可选择 Weaviate 作为向量存储（生产、自托管或托管）。
27. 可选择 Qdrant 作为向量存储（生产、自托管或托管）。
28. 可选择 PostgreSQL with pgvector 作为向量存储。
29. 可选择 MongoDB Atlas Vector Search 作为向量存储。
30. 持久化索引：`index.storage_context.persist(persist_dir='./storage')`。
31. 加载持久化索引：`storage_context = StorageContext.from_defaults(persist_dir='./storage')`；`index = load_index_from_storage(storage_context)`。
32. 创建基本查询引擎：`query_engine = index.as_query_engine(similarity_top_k=5, response_mode='compact')`；调用 `response = query_engine.query('What is the main topic?')`；读取 `response.response`。
33. 选择响应模式 `refine`：通过每个节点迭代优化答案。
34. 选择响应模式 `compact`：发送给 LLM 前合并块。
35. 选择响应模式 `tree_summarize`：构建树并总结。
36. 选择响应模式 `simple_summarize`：截断并总结。
37. 选择响应模式 `accumulate`：累积每个节点的响应。
38. 创建高级查询引擎：使用 `RetrieverQueryEngine.from_args`，传入 `retriever=index.as_retriever(similarity_top_k=10)`、`node_postprocessors=[SimilarityPostprocessor(similarity_cutoff=0.7)]`、`response_mode='compact'`。
39. 使用基本检索器：`retriever = VectorIndexRetriever(index=index, similarity_top_k=10)`；调用 `nodes = retriever.retrieve('search query')`。
40. 实现混合搜索：使用 `QueryFusionRetriever([index.as_retriever(similarity_top_k=5), bm25_retriever], num_queries=4, use_async=True)` 组合多种检索策略。
41. 配置 OpenAI embeddings：`Settings.embed_model = OpenAIEmbedding(model='text-embedding-3-small', dimensions=512)`（可选降维）。
42. 配置本地 embeddings：`Settings.embed_model = HuggingFaceEmbedding(model_name='BAAI/bge-small-en-v1.5')`。
43. 配置 OpenAI LLM：`Settings.llm = OpenAI(model='gpt-4o', temperature=0.1)`。
44. 配置 Anthropic LLM：`Settings.llm = Anthropic(model='claude-sonnet-4-20250514', temperature=0.1)`。
45. 构建 Agent 工具：使用 `QueryEngineTool(query_engine=documents_query_engine, metadata=ToolMetadata(name='documents', description='Search through documents'))` 等从查询引擎创建工具。
46. 创建 Agent：使用 `ReActAgent.from_tools(tools, llm=llm, verbose=True)`；调用 `response = agent.chat('Find information about X')`。
47. 性能优化-缓存：启用 LLM 响应缓存，设置 `Settings.llm = OpenAI(model='gpt-4o')` 和 `Settings.llm_cache = LLMCache()`。
48. 性能优化-异步：使用 `response = await query_engine.aquery('question')` 提升性能。
49. 性能优化-批量处理：使用 `responses = await asyncio.gather(*[query_engine.aquery(q) for q in questions])`。
50. 嵌入优化：尽可能批量生成 embeddings。
51. 嵌入优化：当准确率允许时使用更小的 embedding dimensions。
52. 嵌入优化：缓存重复文档的 embeddings。
53. 嵌入优化：成本敏感应用使用本地模型。
54. 错误处理：使用 `LlamaDebugHandler()` 和 `CallbackManager([debug_handler])`，并设置 `Settings.callback_manager = callback_manager` 进行故障排查。
55. 测试：对文档加载器和变换进行单元测试。
56. 测试：用已知查询测试检索质量。
57. 测试：验证索引持久化和加载。
58. 测试：测试查询引擎响应。
59. 测试：监控检索指标（precision、recall）。
60. 安装依赖 `llama-index`。
61. 安装依赖 `llama-index-embeddings-openai`。
62. 安装依赖 `llama-index-llms-openai`。
63. 安装依赖 `llama-index-vector-stores-chroma`。
64. 安装依赖 `chromadb`。
65. 安装依赖 `python-dotenv`。
66. 安装依赖 `pydantic`。

适用边界 · 注意事项

• 不打算使用 LlamaIndex 或 Python 的项目不适用。
• 需要非 Python 技术栈，或不想引入 LlamaIndex、向量存储等依赖时不宜照搬。
• 使用 OpenAI、Anthropic 或托管向量库时通常需要 API key/账号/付费服务；缺少这些时需改用本地模型和本地向量库，或不要按本文对应配置执行。