升级llama-index后使用SimpleDirectoryReader加载数据报错：找不到readers文件

问题背景 #

近期升级llama-index到0.10.17版本，已安装的相关包如下：

llama-index               0.10.17                  pypi_0    pypi
llama-index-agent-openai  0.1.5                    pypi_0    pypi
llama-index-cli           0.1.8                    pypi_0    pypi
llama-index-core          0.10.17                  pypi_0    pypi
llama-index-embeddings-openai 0.1.6                    pypi_0    pypi
llama-index-indices-managed-llama-cloud 0.1.3                    pypi_0    pypi
llama-index-legacy        0.9.48                   pypi_0    pypi
llama-index-llms-openai   0.1.7                    pypi_0    pypi
llama-index-multi-modal-llms-openai 0.1.4                    pypi_0    pypi
llama-index-program-openai 0.1.4                    pypi_0    pypi
llama-index-question-gen-openai 0.1.3                    pypi_0    pypi
llama-index-readers-file  0.1.8                    pypi_0    pypi
llama-index-readers-llama-parse 0.1.3                    pypi_0    pypi
llama-index-vector-stores-chroma 0.1.5                    pypi_0    pypi

运行以下代码时触发错误：

# Load data into 'Documents' a custom type by LlamaIndex
from llama_index.core import SimpleDirectoryReader

documents = SimpleDirectoryReader('./data').load_data()

报错信息：

---------------------------------------------------------------------------
ImportError                               Traceback (most recent call last)
File ~/anaconda3/envs/llama_index_env/lib/python3.10/site-packages/llama_index/core/readers/file/base.py:22, in _try_loading_included_file_formats()
     21 try:
---> 22     from llama_index.readers.file import (
     23         DocxReader,
     24         EpubReader,
     25         HWPReader,
     26         ImageReader,
     27         IPYNBReader,
     28         MarkdownReader,
     29         MboxReader,
     30         PandasCSVReader,
     31         PDFReader,
     32         PptxReader,
     33         VideoAudioReader,
     34     )  # pants: no-infer-dep
     35 except ImportError:

ImportError: cannot import name 'DocxReader' from 'llama_index.readers.file' (unknown location)

During handling of the above exception, another exception occurred:

ImportError                               Traceback (most recent call last)
Cell In[7], line 11
      7 import llama_index.readers.file
      9 from llama_index.readers.file.docs import DocxReader
---> 11 documents = SimpleDirectoryReader('./data').load_data()

File ~/anaconda3/envs/llama_index_env/lib/python3.10/site-packages/llama_index/core/readers/file/base.py:465, in SimpleDirectoryReader.load_data(self, show_progress, num_workers, fs)
    460         files_to_process = tqdm(
    461             self.input_files, desc="Loading files", unit="file"
    462         )
    463     for input_file in files_to_process:
    464         documents.extend(
--> 465             SimpleDirectoryReader.load_file(
    466                 input_file=input_file,
    467                 file_metadata=self.file_metadata,
    468                 file_extractor=self.file_extractor,
    469                 filename_as_id=self.filename_as_id,
    470                 encoding=self.encoding,
    471                 errors=self.errors,
    472                 fs=fs,
    473             )
    474         )
    476 return self._exclude_metadata(documents)

File ~/anaconda3/envs/llama_index_env/lib/python3.10/site-packages/llama_index/core/readers/file/base.py:360, in SimpleDirectoryReader.load_file(input_file, file_metadata, file_extractor, filename_as_id, encoding, errors, fs)
    329 """Static method for loading file.
    330 
    331 NOTE: necessarily as a static method for parallel processing.
   (...)
    357     List[Document]: loaded documents
    358 """
    359 # TODO: make this less redundant
--> 360 default_file_reader_cls = SimpleDirectoryReader.supported_suffix_fn()
    361 default_file_reader_suffix = list(default_file_reader_cls.keys())
    362 metadata: Optional[dict] = None

File ~/anaconda3/envs/llama_index_env/lib/python3.10/site-packages/llama_index/core/readers/file/base.py:36, in _try_loading_included_file_formats()
     22     from llama_index.readers.file import (
     23         DocxReader,
     24         EpubReader,
   (...)
     33         VideoAudioReader,
     34     )  # pants: no-infer-dep
     35 except ImportError:
---> 36     raise ImportError("`llama-index-readers-file` package not found")
     38 default_file_reader_cls: Dict[str, Type[BaseReader]] = {
     39     ".hwp": HWPReader,
     40     ".pdf": PDFReader,
   (...)
     54     ".ipynb": IPYNBReader,
     55 }
     56 return default_file_reader_cls

ImportError: `llama-index-readers-file` package not found

问题原因 #

llama-index 0.10.x版本对包结构进行了拆分，原llama_index.readers.file下的各类阅读器（如DocxReader、PDFReader）已迁移到子模块中（比如DocxReader在llama_index.readers.file.docs，PDFReader在llama_index.readers.file.pdf），但SimpleDirectoryReader内部的默认导入逻辑仍沿用旧路径，导致无法找到对应类，进而误报llama-index-readers-file包未安装。

修复方案 #

方案1：手动指定文件阅读器 #

显式导入对应格式的阅读器，通过file_extractor参数传递给SimpleDirectoryReader，替代默认的导入逻辑：

from llama_index.core import SimpleDirectoryReader
# 根据你需要处理的文件格式导入对应的阅读器
from llama_index.readers.file.docs import DocxReader
from llama_index.readers.file.pdf import PDFReader
from llama_index.readers.file.markdown import MarkdownReader

# 配置文件格式与阅读器的映射
file_extractor = {
    ".docx": DocxReader(),
    ".pdf": PDFReader(),
    ".md": MarkdownReader(),
    # 添加其他需要支持的格式
}

# 加载数据
documents = SimpleDirectoryReader('./data', file_extractor=file_extractor).load_data()

方案2：修复包缓存问题 #

如果是Python缓存导致的路径识别异常，可清理缓存后重新运行：

# 清理当前目录下的__pycache__文件夹
find . -name "__pycache__" -type d -exec rm -rf {} +

方案3：重新安装阅读器包 #

确保llama-index-readers-file包安装完整，可卸载后重新安装：

pip uninstall llama-index-readers-file -y
pip install llama-index-readers-file==0.1.8

内容的提问来源于stack exchange，提问作者user3476463