LlamaIndex最佳实践：从入门到精通

▌ 技术引导
LlamaIndex 入门不难，但精通需要解决大量隐藏问题。在开发一个大规模 RAG 系统时，我最常遇到的坑是数据加载效率低下、索引构建不均衡、查询结果不准确、内存泄露和分布式部署难。这些都直接影响落地效果。使用 LlamaIndex 时，一定要用 `SimpleDirectoryReader` 代替手动读取 JSON，因为前者自动校验格式且支持异步加载。索引构建时，避免使用默认的 `VectorStoreIndex`，优先选 `GPTVectorIndex`，因为它对长文本更友好。查询阶段，建议用 `QueryEngine` 的 `get_query_engine` 方法，结合 `response_mode` 设置为 `compact` 或 `tree` 来提升输出质量。另外，记得在 `ServiceContext` 里配置 `llm` 和 `embed_model`，特别是当使用本地模型时，必须设定 `model` 类型为 `local`，并配置 `model_config` 里的 `device` 和 `temperature`。这些设置会显著影响推理速度和结果准确性。

具体加载数据时，如果文档体量超过 10GB，直接用 `GPTSimpleVectorIndex` 会卡死，必须切换到 `GPTKeywordTableIndex` 或者用 `IndexManager` 分片加载。构建索引后，如果查询时出现歧义，可以手动设置 `similarity_top_k`，比如 100 就算，但别超过 500，否则会拖慢执行。文档嵌入时，如果模型参数不匹配，比如用 `sentence-transformers` 嵌入模型却传入 `openai` 的 token，会导致内存溢出。在部署时，如果用 Docker，记得挂载 `/tmp` 目录，否则缓存会丢失。再强调一次，配置 `service_context` 时，不要漏掉 `transformations`，这些是后期查询优化的核心。

实际项目中，我发现用 `GPTKeywordTableIndex` + `GPTVectorIndex` 的双重索引结构，查询准确率能提升 20% 以上。但代价是内存占用翻倍，所以要评估是否真的需要。如果用 `IndexManager` 部署，记得设置 `num_workers` 为 CPU 核数，比如 8，这样可以并行处理。另外，加载文档时，如果文档包含图片或表格，建议用 `PDFReader` 或 `MarkdownReader`，但注意这些 reader 只能处理某些特定格式，比如 PDF 需要 PDFminer，Markdown 需要 PyYAML。调试阶段，用 `ListIndex` 还原数据结构会更直观，适合验证字段是否正确映射。

在实战中，我还发现 `IndexingLayer` 的 `chunk_size` 设置是关键。如果设得太小，比如 100 字，会导致太多 chunk，查询时响应时间暴涨。如果设得太大，比如 1000 字，个别长文本又会丢失语义。最佳方式是用 `RecursiveCharacterSplitter` 切分，设置 `chunk_size` 为 500，同时开启 `split_overlap` 为 100，这样既能保持语义，又不会造成过多碎片。另外，查询时别忘了用 `QueryEngine` 的 `query` 方法，而不要直接调用 `llm`，因为后者缺乏索引支持。性能方面，如果用 `GPTVectorIndex`，建议在 `service_context` 里开启 `use_async`，这样能提升 30% 左右的吞吐量。最后，别盲目依赖 `GPTVectorIndex`，某些场景下用 `KeywordTableIndex` 单独处理关键词会更高效。

▌ 技术参考
一 用 LlamaIndex 构建 RAG 系统时，文档加载必须用 `SimpleDirectoryReader` 混合 `GPTSimpleVectorIndex`。比如，当加载几十万文档时，推荐使用 `SimpleDirectoryReader` 的 `file_extensions` 参数过滤非文本文件，如 `['txt', 'md', 'csv']`，同时设置 `show_progress` 为 True。这能避免手动处理 JSON 带来的格式错误。如果文档中有大量图片，建议用 `PDFReader` 读取 PDF，这样会自动提取文字，并在 `GPTVectorIndex` 构建时忽略非文字部分。注意，PDFReader 依赖 PDFminer，如果文档格式不标准，会抛出 `PDFParseError`，所以必须先预处理 PDF 文件。

二 构建索引时，别直接用 `GPTVectorIndex`，特别是当文档长度在 5000 字以上。LlamaIndex 提供的 `GPTKeywordTableIndex` 单独处理关键词，能提升查询性能。比如，当构建完 `GPTKeywordTableIndex` 后，再用 `GPTSimpleVectorIndex` 处理长文本，这样能兼顾语义和关键词双重检索。具体做法是，先用 `GPTKeywordTableIndex` 读取预处理过的 JSON 数据，再用 `GPTSimpleVectorIndex` 导入原始文档。如果文档中存在大量重复字段，建议用 `FaissIndex` 替代 `GPTSimpleVectorIndex`，因为它对向量相似度的计算更高效。但要注意，FaissIndex 必须配合 `GPTVectorIndex` 使用才能生效。

三 实际部署时，如果遇到内存溢出，必须检查 `embed_model` 和 `llm` 的参数是否匹配。比如，使用 `sentence-transformers` 的 `all-MiniLM-L6-v2` 模型时，设置 `embedding_dim` 为 384，否则会出现维度不匹配错误。如果在 `service_context` 里调用 `llm` 时忘记设置 `temperature`，会导致输出过于保守，影响结果多样性。另外，一定要在 `IndexManager` 中进行分片加载，否则加载数十万文档会卡死。比如，用 `IndexManager` 的 `load_index` 方法加载索引，设置 `num_workers` 为 CPU 核数，比如 8，这样可以并行处理，避免阻塞主线程。如果文档路径是 `/data/docs/`，确保其权限为 755，否则会抛出 `PermissionError`。

四 查询时别直接调用 `llm`，而是使用 `QueryEngine` 的 `query` 方法。比如，用 `get_query_engine` 拿到引擎后，调用 `query("如何维护高效的数据管道？")`，会自动从索引中提取相关内容，而不是像 `llm.chat_completion` 那样完全依赖模型。如果查询结果不准确，可以调整 `similarity_top_k` 参数，比如从 10 提升到 20，但不要超过 500，否则会拖慢执行速度。对于长文档，建议设置 `response_mode` 为 `tree`，这样能保持上下文连贯。如果出现 `IndexError`，说明索引未正确加载，必须检查 `IndexManager` 是否初始化成功。

五 在处理非文本文档时，如 PDF 或 DOCX，必须使用对应的 reader。比如，`PDFReader` 可以处理 PDF，但只支持某些格式，比如非加密文档。如果文档被加密了，会抛出 `PDFProcessingError`，这时候必须手动解密再重新加载。另外，`MarkdownReader` 需要 PyYAML 包，否则会报 `ImportError`。如果文档中嵌入了表格或图片，在加载时建议用 `LangChain` 的 `TableReader` 预处理，将其转换为纯文本，再用 `GPTSimpleVectorIndex` 嵌入。否则，模型可能无法解析表格内容，导致信息遗漏。

六 当使用 `GPTVectorIndex` 时，确保 `embed_model` 的 `device` 参数正确。比如，如果模型是本地部署的，必须设置 `device` 为 `cuda`，否则会使用 CPU，导致执行速度慢。如果没有 CUDA 环境，可以设为 `mps`，但注意只有苹果芯片支持。另外，`temperature` 参数控制输出的随机性，如果设为 0，结果会非常保守，不适用于需要多样性的场景。如果发现模型频繁报错，比如 `IndexError` 或 `ValueError`，必须检查 `tokenizer` 是否与模型匹配，比如 `gpt2` 的 tokenizer 和 `gpt-3.5-turbo` 是不同的，必须用对应的参数。

七 部署时，如果用 Docker，必须挂载 `/tmp` 目录，否则缓存会丢失。比如，在运行容器时，执行 `docker run -v /tmp:/app/tmp -v /data:/app/data ...`，这样确保临时文件和持久化数据都可用。如果使用 `GPTKeywordTableIndex`，建议开启 `use_async` 参数，这样能提升 30% 的查询吞吐量。同时，必须在 `service_context` 中配置 `llm` 和 `embed_model`，否则会报 `ServiceContextNotSet` 的错误。例如，配置 `llm` 时，可以设置 `model` 为 `gpt-3.5-turbo`，并用 `temperature` 控制输出质量。

八 在处理大规模数据时，建议使用 `IndexManager` 分片加载，同时设置 `num_workers` 为 CPU 核数。比如，当加载 `/data/docs/` 路径下的文档时，执行 `IndexManager.load_index("/data/docs/", num_workers=8)`，可以并行处理。如果文档存储在远程 NAS，记得设置 `timeout` 参数，比如 `timeout=300`，避免超时。另外，如果使用 `GPTSimpleVectorIndex`，必须确保 `chunk_size` 设置合理，比如 500 字，否则会因为内容碎片化导致查询不准。

九 查询时，如果结果太冗长，建议用 `response_mode` 设置为 `compact`。比如，执行 `engine = query_engine.get_query_engine(response_mode="compact")`，会自动优化输出长度。对于高准确率需求，可以将 `response_mode` 设为 `tree`，但这会牺牲性能，适合小规模数据。如果发现 `similarity_top_k` 设置不合理，可以调整 `GPTVectorIndex` 的 `similarity_top_k` 参数，比如从 50 提升到 100，但别超过 500，否则会拖慢执行速度。同时，建议在 `GPTKeywordTableIndex` 中设置 `similarity_top_k` 为 20，这样能快速定位关键词。

十 当使用 `RecursiveCharacterSplitter` 分割文本时，必须设置 `chunk_size` 为 500，`split_overlap` 为 100，才能保持语义连贯。例如，执行 `splitter = RecursiveCharacterSplitter(chunk_size=500, split_overlap=100)`，再用 `GPTVectorIndex` 的 `from_documents` 方法导入文本。如果文档中包含大量重复内容，可以使用 `RemoveDuplicatesStrategy` 过滤，避免索引浪费。此外，如果发现索引构建后无法查询，必须检查 `IndexManager` 是否正确初始化，并确保 `service_context` 中的 `llm` 和 `embed_model` 配置正确。

十一 LlamaIndex 支持多种嵌入模型，比如 `sentence-transformers` 和 `openai`，但要注意参数兼容性。如果使用 `sentence-transformers`，必须确保 `device` 参数是 `cuda` 或 `mps`，否则会使用 CPU，导致执行速度慢。如果使用 `openai` 的 `text-embedding-ada-002`，必须设置 `model` 为 `text-embedding-ada-002`，否则出现 `ModelError`。同时，不能混用不同模型，比如 `gpt-3.5` 和 `text-embedding-ada`，必须统一。如果模型版本不匹配，会导致 `IncompatibleModelError`，必须升级或更换模型。

十二 在处理分布式部署时，建议用 `IndexManager` 的 `get_index` 方法获取远程索引，同时设置 `timeout` 参数为 300，避免连接超时。如果多个节点同时加载索引，必须确保 `num_workers` 为 CPU 核数，防止资源争抢。当使用 `GPTVectorIndex` 时，在 `service_context` 中设置 `use_async` 为 True，提升多线程处理能力。如果发现 `IndexManager` 挂载失败，必须检查远程存储的权限，并确保 `/tmp` 目录存在，否则会报 `DirectoryNotFoundError`。

十三 如果文档中存在大量非文本内容，比如 Excel 或 Word 表格，建议使用 `LangChain` 的 `TableReader` 预处理，提取表格内容后再用 `GPTSimpleVectorIndex` 嵌入。这样能避免模型无法解析表格内容导致的遗漏。否则，`GPTKeywordTableIndex` 可能会忽略这些字段。另外，如果文档包含多个语言内容，必须在 `service_context` 中配置 `language` 参数，比如 `language="zh"`，否则模型可能无法正确理解中文。如果设置错误，会出现 `LanguageNotSupportedException` 的错误。

十四 使用 `GPTKeywordTableIndex` 时，建议设置 `vector_index` 为 `GPTSimpleVectorIndex`，这样能同时支持关键词和语义检索。例如，在构建索引时，执行 `index = GPTKeywordTableIndex.from_documents(docs, vector_index=GPTSimpleVectorIndex) `，确保两层索引协同工作。如果查询结果太分散，可以调整 `similarity_top_k` 为 150，但别超过 500。同时，建议开启 `use_async` 参数，提升查询吞吐量。如果发现查询时 `similarity_top_k` 无效，必须检查 `vector_index` 是否正确配置，并确保 `IndexManager` 已加载索引。

十五 在资源有限的情况下，推荐使用 `GPTKeywordTableIndex` 单独处理关键词，而不是直接用 `GPTVectorIndex`。例如，当处理 10万篇日志文档时，先用 `GPTKeywordTableIndex` 抽取关键词，再用 `GPTSimpleVectorIndex` 嵌入长文本，这样能减少内存占用。如果发现 `GPTVectorIndex` 内存占用过高，必须检查是否开启了 `use_async`，并确保 `similarity_top_k` 不超过 500。另外，如果文档中有大量重复内容，建议使用 `RemoveDuplicatesStrategy` 避免冗余存储。最后，记住所有配置都必须在 `service_context` 中完成，否则会抛出 `ServiceContextNotSet` 的错误。