---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - typescript
  - integrations
  - document-loader
topic: LangChain JavaScript 文档加载器与本地文件摄取
sources:
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/index
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/file_loaders
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/file_loaders/directory
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/file_loaders/json
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/file_loaders/jsonlines
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/file_loaders/multi_file
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/file_loaders/oracleai
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/file_loaders/text
last_verified: 2026-08-11
---
# 文档加载器与本地文件摄取

## 结论

- Document Loader 把不同数据源统一成 `Document`，共同接口是 `load()` 与 `loadAndSplit()`；加载与切分应在架构上分层，便于重跑、换切分策略和追踪来源。
- 文件加载器只适用于 Node.js。目录、文件路径、符号链接、压缩炸弹和超大文件都需要应用侧限制，不能让模型提供任意路径。
- `/document_loaders` 与 `/document_loaders/index` 是同正文别名；两条 source 保留、知识不重复。本组共 9 条原始路由。

## 统一数据契约

一个可维护的摄取管道应至少保留：

- `pageContent`：规范化后的正文；
- `metadata.source`：稳定、可追溯的 URI 或受控路径；
- 原始对象版本、内容哈希、采集时间、MIME/type、权限标签；
- parser/normalizer/splitter 的版本。

`loadAndSplit()` 适合快速试验，生产更推荐 `load()` 后显式调用 splitter：原文只需摄取一次，切分策略变化时无需重新访问源系统。

## 本地文件加载器

| Loader | 输入语义 | 关键边界 |
|---|---|---|
| `TextLoader` | 单个纯文本路径 | Node-only；一文件通常得到一个 Document |
| `DirectoryLoader` | 目录 + 扩展名到 loader factory 的映射 | 递归范围、符号链接和未知扩展名需明确策略 |
| `MultiFileLoader` | 多个独立路径 + 扩展名映射 | 输入顺序、失败隔离与部分成功要可观测 |
| `JSONLoader` | JSON，可选 JSON Pointer | 无 pointer 时抽取所有字符串，可能丢失结构上下文 |
| `JSONLinesLoader` | 每行一个 JSON + JSON Pointer | 每个 JSON 对象生成一个 Document，适合流式批处理 |
| `OracleDocLoader` | Oracle 表、文件或目录 | Node-only；借助 Oracle Text 处理 150+ 格式 |

`DirectoryLoader` 与 `MultiFileLoader` 的文档示例仍引入 `@langchain/community` 的 CSV/PDF loader，页面明确警告该包不再维护，示例可能过时或损坏。新增项目应寻找受维护的独立 integration package，或将相关解析器隔离并固定版本。

## JSON 与 JSONL

- JSON Pointer 决定抽取哪个字段；pointer 不应由外部用户任意控制，以免越权读取对象的其他部分。
- 无 pointer 的 JSONLoader 会遍历并加载发现的字符串。它适合小型内容文件，不适合直接处理含敏感字段或巨大嵌套结构的业务 JSON。
- JSONL 每行独立，天然适合 checkpoint、失败行隔离和并行；应保存行号/record id 到 metadata，以便恢复和去重。
- 摄取前先做字节大小、深度、编码和 schema 验证；坏记录进入隔离队列，而不是让整批静默丢失。

## Oracle 数据库内摄取

`OracleDocLoader` 可从数据库行、单文件或目录加载，并配合 `OracleTextSplitter` 在数据库能力附近切分。优势是能把 Oracle 的安全、事务、HA 与文档/向量流程放在同一系统；代价是 Node driver、数据库版本、Oracle Text/Vector 能力和连接池运维。

生产要点：

1. 不使用 `SYSTEM`；为摄取创建最小权限账户。
2. 凭据由 secret manager 注入，不出现在代码、日志或 metadata。
3. 数据库连接使用池并在任务结束释放；长文件解析设置 statement/request timeout。
4. 150+ 格式支持不代表每种格式都能无损提取；对目标格式建立 golden corpus，验证正文、页码、表格与编码。

## 可恢复摄取流程

1. 发现：只枚举 allowlist 根目录或受控对象列表。
2. 指纹：记录 source、mtime/version、size 和 content hash，跳过未变化对象。
3. 加载：限制单文件与批次资源；一个对象失败不吞掉整个批次。
4. 规范化：统一编码、换行与 metadata，不修改权威原件。
5. 持久化原始 Document，再独立切分、embedding、upsert。
6. 只有当目标索引提交成功才推进 checkpoint；重跑按稳定 id 幂等覆盖。