学习笔记 · Obsidian
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 继承与增量删除，因此这些仍是上线前必须完成的环境验证。