用LlamaIndex构建RAG应用时，文档加载和节点解析是最容易出问题的环节。明明代码写得很简单，调一下SimpleDirectoryReader再加个向量索引，结果却抛出一堆Node parse相关的异常，很多人对着报错信息束手无策。其实这类问题九成以上集中在两个地方：一是文档格式本身有问题，解析器读不出来或者读出来的内容是乱的；二是TextSplitter的参数配置和文档内容不匹配，切分逻辑直接崩掉。下面按照排查思路把这两个方向都讲透。
先搞清楚报错发生在哪个环节
LlamaIndex把文档转成节点的流程大致分三步：读取原始文件、抽取纯文本内容、调用TextSplitter切分成Node。报错信息里如果出现类似ValueError、KeyError、无法识别文件类型等提示，大概率是第一步或第二步出了问题；如果是chunk size相关的断言失败，或者切出来的节点内容为空，那就是第三步TextSplitter的问题。排查的第一件事就是把异常堆栈看完整，而不是只看最后一行。
一个实用的调试方法是在VectorStoreIndex.from_documents之前，先用reader.load_data()把文档读出来，直接print一下返回的Document对象列表的长度和text属性。如果load_data本身就抛异常，说明问题在读取层；如果读出来了但text是空字符串或者一堆乱码，说明问题在内容抽取层；如果这两步都正常，那么问题基本可以锁定在分割器参数上。这种分段验证的思路比对着报错瞎猜要高效得多。
from llama_index.core import SimpleDirectoryReader
# 分步排查：先只做读取，不建索引
reader = SimpleDirectoryReader(input_dir="./docs")
documents = reader.load_data()
print(f"共读取 {len(documents)} 个文档")
for i, doc in enumerate(documents[:3]):
print(f"--- 文档{i} 长度: {len(doc.text)} ---")
print(doc.text[:200]) # 检查内容是否正常抽取另外一个常见的坑是文件扩展名和真实格式不一致。比如有些系统导出的所谓docx文件实际上是伪装的HTML或者加密文件，扩展名对但内容完全不是那么回事。遇到这种情况可以把可疑文件单独拎出来，用file命令（Linux/Mac）或者直接用记事本打开看文件头，确认真实格式后再决定用哪个解析器处理。
文档格式转换：让内容在进入分割器前变干净
LlamaIndex对不同格式的支持程度差别很大。纯文本和Markdown基本不会有问题，但PDF、扫描件、旧版Office文档就麻烦很多。PDF尤其坑，因为它内部存的是渲染指令而不是结构化文本，用默认的pypdf解析双栏排版、表格、带批注的文档时经常抽取出一堆错乱字符，甚至直接抛异常。扫描版PDF更是重灾区，里面根本没文本层，解析出来必然是空的。
针对格式问题，最有效的办法是在进入LlamaIndex之前先做一次预处理转换。推荐用unstructured这个库，它对PDF、Word、HTML、PPT等格式都有专门的分区处理逻辑，能识别标题、段落、表格、页眉页脚，并且可以过滤掉垃圾内容。安装的时候把extra依赖装全，比如处理PDF需要poppler相关工具，处理图片OCR需要tesseract。安装完之后在SimpleDirectoryReader里指定对应的解析方式即可。
from llama_index.core import SimpleDirectoryReader
# 使用unstructured作为PDF解析后端
reader = SimpleDirectoryReader(
input_dir="./docs",
file_extractor={".pdf": "unstructured_pdf"},
)
documents = reader.load_data()
# 处理扫描版PDF：开启OCR的分区模式
from unstructured.partition.pdf import partition_pdf
elements = partition_pdf(
"scan_report.pdf",
strategy="ocr_only", # 强制走OCR
languages=["chi_sim"], # 中文场景指定简体中文包
)
clean_text = "\n\n".join(str(el) for el in elements)如果unstructured也不好用，还有一条更稳妥的路线：先把所有文档统一转成Markdown或纯文本。PDF可以用pdfplumber配合pymupdf处理，Word用python-docx或者直接用libreoffice命令行批量转格式，HTML用BeautifulSoup抽取正文。统一格式之后再交给LlamaIndex，后续所有环节都会稳定很多。很多生产环境的RAG系统就是这么做的，专门有一个ETL预处理管道负责格式归一化，把脏活累活和主流程解耦开。
还有一点容易被忽略：文件编码问题。GBK编码的txt文件用默认UTF-8去读会直接报UnicodeDecodeError。SimpleDirectoryReader允许通过file_metadata或者自己重写reader来指定encoding参数，或者干脆提前用chardet探测编码后统一转存为UTF-8，一次性消灭这类问题。
TextSplitter参数调整：让切分逻辑不再失败
格式没问题之后，剩下的失败原因基本都在分割器上。LlamaIndex默认使用SentenceSplitter，它有两个核心参数：chunk_size控制每块的目标长度，chunk_overlap控制相邻块的重叠量。最常见的报错是chunk_overlap大于等于chunk_size，或者单个句子本身就超过了chunk_size导致切不开。报错信息里通常会有chunk size必须大于overlap之类的断言提示，照着调就行。
更隐蔽的问题是中文场景下的token计量问题。LlamaIndex默认的tokenizer是针对英文的tiktoken编码，一个中文字符往往会被算成一到两个token，这意味着你以为chunk_size设512能装下512个汉字，实际上可能只能装两百多个字，语义会被切得更碎。中文项目建议显式指定tokenizer，或者干脆把chunk_size往大调一档，预留足够余量。
from llama_index.core.node_parser import (
SentenceSplitter, TokenTextSplitter, SemanticSplitterNodeParser
)
from llama_index.core import VectorStoreIndex, Settings
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
# 方案一：调整默认SentenceSplitter参数
splitter = SentenceSplitter(
chunk_size=512,
chunk_overlap=64, # 必须小于chunk_size
paragraph_separator="\n\n\n", # 自定义段落分隔符
)
# 方案二：中文场景用本地embedding配套的tokenizer
Settings.embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-small-zh-v1.5"
)
Settings.text_splitter = splitter
nodes = splitter.get_nodes_from_documents(documents)
print(f"切分出 {len(nodes)} 个节点")
for n in nodes[:2]:
print(len(n.get_content()), n.get_content()[:80])分割器怎么选也要看文档特性。TokenTextSplitter严格按token数硬切，速度快但可能把句子拦腰斩断；SentenceSplitter优先在句子边界切分，语义保持更好，是大多数场景的默认选择；如果对检索质量要求高，可以用SemanticSplitterNodeParser做语义切分，它根据相邻句子的embedding相似度决定在哪里分块，效果通常更好但计算成本也更高。处理代码、配置文件这类结构化文本时，还有专门的CodeSplitter可以按语法树切分，不会把函数切成两半。
最后总结一下排查顺序：先分步执行load_data确认读取层正常，格式有问题就用unstructured或转Markdown预处理，编码不对就统一转UTF-8；读取正常后再检查分割器的chunk_size和chunk_overlap关系，中文场景注意token计量偏差，必要时换用更合适的分割器。把这套流程走一遍，绝大多数Node parse失败都能定位并解决。
LlamaIndex文档解析文本分割器修改时间：2026-09-08 06:09:41