SimpleDirectoryReader: încărcarea fișierelor locale în LlamaIndex: sintaxă Python, RAG și exemple practice

from llama_index.core import SimpleDirectoryReader reader = SimpleDirectoryReader(input_dir="./documente", recursive=True) documents = reader.load_data() print(f"S-au încărcat {len(documents)} documente.")

Documentația îl prezintă ca cel mai simplu mod de a încărca fișiere locale; pentru producție recomandă și integrările de tip Reader. Recunoaște după extensie .csv, .docx, .epub, .hwp, .ipynb, .jpeg/.jpg, .mbox, .md, .mp3/.mp4, .pdf, .png și .ppt/.pptm/.pptx; celelalte fișiere le citește ca text. Pentru JSON documentația recomandă JSON Loader. Cititorii dedicați (PDF, Word, PowerPoint, imagini, audio) sunt în pachetul llama-index-readers-file; fără el, llama-index-core afișează un avertisment și acele formate nu mai au cititor dedicat.

load_data() întoarce o listă de obiecte Document. Metadatele implicite sunt file_path, file_name, file_type (tipul MIME), file_size și creation_date, last_modified_date, last_accessed_date, cu datele în format %Y-%m-%d, normalizate la UTC. Cititorul de PDF creează câte un Document pe pagină și adaugă page_label.

Implicit se citește doar nivelul de sus al directorului; recursive=True include subdirectoarele. load_data(num_workers=4) încarcă în paralel cu multiprocessing; documentația notează că pe Windows câștigul poate fi mic sau zero. iter_data() întoarce documentele fișier cu fișier, iar parametrul fs acceptă orice sistem de fișiere fsspec (S3, Azure Blob, Google Drive, SFTP).

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
`input_dir / input_files`	Directorul de citit sau o listă explicită de fișiere (`input_files` are prioritate).
`recursive`	Citește și subdirectoarele. Implicit `False`.
`required_exts`	Încarcă doar extensiile din listă, de exemplu `[".pdf", ".docx"]`.
`exclude`	Fișiere de exclus.
`num_files_limit`	Numărul maxim de fișiere încărcate.
`file_metadata`	Funcție care primește calea fișierului și întoarce dicționarul de metadate. Înlocuiește funcția implicită.
`file_extractor`	Dicționar extensie → cititor (`BaseReader`). Suprascrie cititorul implicit pentru extensiile date.
`filename_as_id`	Folosește calea fișierului ca `doc_id`; util pentru actualizări incrementale.
`encoding`	Codificarea fișierelor text. Implicit `utf-8`.
`fs`	Sistem de fișiere `fsspec` pentru stocare la distanță.
`load_data(num_workers=...)`	Numărul de procese pentru încărcarea în paralel.

Exemple practice și scenarii reale

Exemplul 1: Doar PDF și Word, din toate subdirectoarele

from llama_index.core import SimpleDirectoryReader

reader = SimpleDirectoryReader(
    input_dir="./acte",
    recursive=True,
    required_exts=[".pdf", ".docx"],
    filename_as_id=True,
)
documents = reader.load_data(num_workers=4)
print(documents[0].metadata["file_name"], documents[0].metadata.get("page_label"))

Exemplul 2: Metadate proprii, fără să pierzi numele fișierului

Funcția dată în file_metadata înlocuiește metadatele implicite, așa că pui înapoi cheile de care ai nevoie.

import os

def metadate(cale: str) -> dict:
    return {"file_name": os.path.basename(cale), "departament": "HR"}

documents = SimpleDirectoryReader("./hr", file_metadata=metadate).load_data()

Exemplul 3: Cititor propriu pentru o extensie nouă

După exemplul din documentație.

from llama_index.core import Document, SimpleDirectoryReader
from llama_index.core.readers.base import BaseReader

class CititorNote(BaseReader):
    def load_data(self, file, extra_info=None):
        with open(file, "r", encoding="utf-8") as f:
            return [Document(text=f.read(), extra_info=extra_info or {})]

reader = SimpleDirectoryReader("./date", file_extractor={".nota": CititorNote()})
documents = reader.load_data()

Greșeli frecvente și capcane

Să instalezi doar llama-index-core și să încarci PDF-uri. Fără llama-index-readers-file nu există cititorul dedicat de PDF.
Să dai file_metadata și să aștepți în continuare file_name sau creation_date. Funcția ta înlocuiește dicționarul implicit.
Să aștepți ca fișierele JSON să fie parsate ca structură. SimpleDirectoryReader nu are cititor dedicat pentru JSON; documentația recomandă JSON Loader (llama-index-readers-json).

`SimpleDirectoryReader: încărcarea fișierelor locale` în LlamaIndex & Data RAG