---
type: study
status: verified
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
tags:
  - study
  - langchain
  - python
  - integrations
  - document-loader
  - ingestion
topic: LangChain Python 文档加载摄取与增量一致性
sources:
  - https://docs.langchain.com/oss/python/integrations/document_loaders
  - https://docs.langchain.com/oss/python/integrations/document_loaders/astradb
  - https://docs.langchain.com/oss/python/integrations/document_loaders/azure_blob_storage
  - https://docs.langchain.com/oss/python/integrations/document_loaders/docling
  - https://docs.langchain.com/oss/python/integrations/document_loaders/docugami
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_alloydb
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_bigquery
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_bigtable
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_classroom
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_cloud_sql_mssql
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_cloud_sql_mysql
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_cloud_storage_directory
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_cloud_storage_file
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_datastore
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_drive
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_firestore
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_memorystore_redis
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_spanner
  - https://docs.langchain.com/oss/python/integrations/document_loaders/google_speech_to_text
  - https://docs.langchain.com/oss/python/integrations/document_loaders/index
  - https://docs.langchain.com/oss/python/integrations/document_loaders/langsmith
  - https://docs.langchain.com/oss/python/integrations/document_loaders/oracleadb_loader
  - https://docs.langchain.com/oss/python/integrations/document_loaders/oracleai
  - https://docs.langchain.com/oss/python/integrations/document_loaders/powerscale
  - https://docs.langchain.com/oss/python/integrations/document_loaders/unstructured_file
  - https://docs.langchain.com/oss/python/integrations/document_loaders/upstage
last_verified: 2026-08-11
---
# Document Loaders：摄取、解析与增量一致性

## 公共接口不是完整摄取协议

所有 loader 以 `BaseLoader` 为共同抽象，把不同来源转成 `Document(page_content, metadata)`：

- `load()` 一次把全部文档装入内存；
- `lazy_load()` 逐条产生文档，适合大数据集。

`/document_loaders` 与 `/document_loaders/index` 当前同正文。官方明确警告：community loaders 是用户贡献且未经 LangChain 审核。标准化 `Document` 形状不代表解析正确、权限继承、增量游标、删除同步或 exactly-once 已经实现。

## 路由与实现矩阵

| 路由 | 包/类 | 数据面与重要边界 |
|---|---|---|
| `document_loaders`、`index` | `BaseLoader` 索引 | `.load()`/`.lazy_load()`；按 productivity、web、PDF、cloud、file type 分类。 |
| `astradb` | `langchain-astradb` / `AstraDBLoader` | 从 Astra DB collection/namespace 加载；token 与 API endpoint 分离配置。 |
| `azure_blob_storage` | `langchain-azure-storage` / `AzureBlobStorageLoader` | 容器、指定 blob、自定义 parser；推荐替代旧 community file/container loader，可用 Managed Identity 或 SAS。 |
| `docling` | `langchain-docling` / `DoclingLoader` | PDF/DOCX/PPTX/HTML 等统一结构、layout/table；支持 lazy，不提供原生 async。 |
| `docugami` | `docugami-langchain` + `dgml-utils==0.3.0` | 加载 Docugami XML/语义 chunk/knowledge graph metadata；示例依赖旧 classic/community 组合。 |
| `google_alloydb` | `langchain-google-alloydb-pg` / `AlloyDBLoader` | 默认表或自定义 query、content/metadata columns；教程 async `aload`，有 sync 对应。 |
| `google_bigquery` | `langchain-google-community[bigquery]` / `BigQueryLoader` | 查询结果每行一个 `Document`，可指定 content、metadata 和 source 列。 |
| `google_bigtable` | `langchain-google-bigtable` / `BigtableLoader`、`BigtableSaver` | row filter/range、content/metadata 映射，同时展示保存与删除；写面不属于纯 loader 契约。 |
| `google_classroom` | `langchain-google-classroom` | course、courseWork、announcement、material、submission、rubric、topic、roster；附件经 Drive 解析，支持 lazy 和 `alazy_load()`。 |
| `google_cloud_sql_mssql` | `langchain-google-cloud-sql-mssql` | `MSSQLLoader` + saver，表/query、自定义 content/metadata、写删。 |
| `google_cloud_sql_mysql` | `langchain-google-cloud-sql-mysql` | `MySQLLoader` + saver，连接池、表/query、自定义 content/metadata、写删。 |
| `google_cloud_storage_directory` | `langchain-google-community[gcs]` / `GCSDirectoryLoader` | bucket/prefix 批量读取；可选择单文件失败后继续。 |
| `google_cloud_storage_file` | 同上 / `GCSFileLoader` | 单 blob，可注入替代 parser；页面的 PyPDF 示例来自不再维护的 `langchain-community`。 |
| `google_datastore` | `langchain-google-datastore` | Datastore kind/query、content/metadata 映射，配套 saver/delete 和自定义 client。 |
| `google_drive` | `langchain-google-community[drive]` 与 `langchain-googledrive` | 旧入口当前只支持 Google Docs；页面同时展示新包的 identity、extended metadata、search 和 Slides/Sheets mode，导入路径不能混用。 |
| `google_firestore` | `langchain-google-firestore` | collection/subcollection/document/collection group/query，配套 saver/delete。 |
| `google_memorystore_redis` | `langchain-google-memorystore-redis` | key prefix 下的文档加载、保存和删除；依赖 Redis endpoint。 |
| `google_spanner` | `langchain-google-spanner` | table/query、staleness/data boost、schema/JSON metadata、自定义 client，配套 saver/delete。 |
| `google_speech_to_text` | `langchain-google-community[speech]` | Google Speech-to-Text v2 把音频转成文档，可传 recognition config。 |
| `langsmith` | `langchain-core` / `LangSmithLoader` | 从 LangSmith dataset/example 加载；支持 lazy，不提供原生 async。 |
| `oracleadb_loader` | `langchain-oracledb` / `OracleAutonomousDatabaseLoader` | 从 Autonomous Database 加载；连接参数应由外部 settings/secret 注入。 |
| `oracleai` | `langchain-oracledb` / `OracleDocLoader`、`OracleTextSplitter` | 从表、文件或目录加载，并在 Oracle 侧处理/切分；官方建议应用使用最小权限专用用户。 |
| `powerscale` | `powerscale-rag-connector` | 利用 MetadataIQ 只返回自上次运行后修改的文件；lazy；内部异步但公开 load/lazy 返回 Python generator。 |
| `unstructured_file` | `langchain-unstructured` / `UnstructuredLoader` | 70+ 类文件、本地或 API、post-processor/chunking；lazy，当前页面标注无原生 async。 |
| `upstage` | `langchain-upstage` / `UpstageDocumentParseLoader` | 远程文档解析；使用 Upstage API key。 |

## 认证与数据暴露

- Google Cloud 数据库/存储通常使用 ADC、project/region 和资源级 IAM；Classroom/Drive 还涉及用户 OAuth 或 Workspace service account impersonation。
- Azure Blob 优先 Managed Identity；SAS 必须限制 container/blob、权限和过期时间。
- Astra、Docugami、LangSmith、Unstructured、Upstage token 只能从 secret manager/环境注入。
- 数据库 loader 使用只读账号或受限 view。配套 saver/delete 示例需要独立写账号，不能因为同一页面展示就复用权限。
- 加载到 `Document` 会把源数据带入模型/向量库链路。必须在摄取前执行租户授权、分类、DLP/PII 处理和地域检查，metadata 中不要复制 secret 或不可公开 ACL 信息。

## 同步、异步与大数据边界

`lazy_load()` 是同步 iterator，不等于异步 I/O，也不等于有 checkpoint。当前页面明确：

- AlloyDB 使用 `aload`，并说明 async 有 sync 对应；
- Google Classroom 提供 `alazy_load()`；
- Docling、LangSmith、Unstructured 标注无原生 async；
- PowerScale 内部请求是异步的，但公开方法返回 generator。

对未知规模默认用 lazy；批次写向量库时用固定 batch 和 bounded queue，避免 loader 比 embedding/index 快导致内存膨胀。网络 loader 要设置分页、总量、超时、有限重试和可恢复游标；不要把 `load()` 包进线程池就宣称获得了端到端背压。

## 解析与增量一致性

### 稳定身份与版本

每个输出 chunk 至少需要：`tenant_id`（服务端控制）、source system、source object ID、source version/etag/modified time、page/row locator、parser version、content hash。由这些字段派生稳定 document/chunk ID，才能可靠 upsert 和 delete。

### 增量不是“只处理新增”

需要同时处理 create、update、move/rename、permission change 和 delete。PowerScale/MetadataIQ 提供修改检测仍不等于目标向量库同步完成；source cursor 只能在整个 batch 成功或失败项持久化后推进。GCS directory 的 `continue_on_failure` 需输出失败清单，不能静默形成永久缺口。

### Parser 质量是数据契约

- Docling/Unstructured/Upstage/DocAI 类解析应保存页码、表格/图片位置和原文件 hash，建立代表性 golden corpus。
- OCR、layout、table 和附件解析要分别统计空页率、乱码率、表格结构保真、耗时和成本。
- Google Classroom 附件和 Drive 文件继承源权限；仅能解析不代表可向当前查询用户展示。
- BigQuery/SQL 的一行一文档可能产生巨大 row；必须限制列、行数和 content 大小。

## 推荐摄取状态机

`discovered → authorized → fetched → parsed → chunked → embedded → indexed → verified`。每阶段保存版本、输入 hash、输出计数和错误分类；重试从最近安全阶段继续。索引完成后用抽样 read-after-write 验证，再推进 source watermark。删除走 tombstone → index delete → 验证不可检索 → 清理原始 artifact。

## 生产验证清单

- [ ] 用最小权限真实账号验证分页、配额、附件、删除和 ACL 变化。
- [ ] 大文件/大表使用 lazy/batch，验证背压、取消和进程重启恢复。
- [ ] 同一 source version 重跑不重复；新版本覆盖且旧 chunk 全部删除。
- [ ] parser/embedding 升级走新版本索引，保留回滚。
- [ ] 记录成功、跳过、失败、空内容、权限拒绝和 cursor lag 指标。
- [ ] secrets、原始敏感正文和 OAuth token 不进入日志或 trace。

## 验证边界

已逐页读取 26 个官方 Markdown 路由并核对接口、包、认证和页面声明的 async/lazy 边界。没有连接真实数据源或校验实际文档解析质量、ACL 继承与增量删除，因此这些仍是上线前必须完成的环境验证。