---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - typescript
  - integrations
  - document-loader
  - transformer
topic: LangChain JavaScript 远程文档加载与元数据转换
sources:
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/web_loaders
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/web_loaders/google_cloudsql_pg
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/web_loaders/langsmith
  - https://docs.langchain.com/oss/javascript/integrations/document_loaders/web_loaders/soniox
  - https://docs.langchain.com/oss/javascript/integrations/document_transformers
  - https://docs.langchain.com/oss/javascript/integrations/document_transformers/index
  - https://docs.langchain.com/oss/javascript/integrations/document_transformers/openai_metadata_tagger
last_verified: 2026-08-11
---
# 远程文档加载与元数据转换

## 结论

- Web Loader 表示“不依赖本地文件系统”的远程数据源，不表示可在浏览器安全运行；凭据、数据库连接和私有数据仍应留在服务端。
- Google Cloud SQL loader 把每一行变成一个 Document；LangSmithLoader 把 dataset/example 或 trace 转成 Document；Soniox 把音频异步转写成一个带丰富 metadata 的 Document。
- MetadataTagger 用函数调用从完整文档抽取结构化元数据，应在切分前运行；输出仍需 schema 和业务校验。

## 路由边界

`/document_transformers` 与 `/document_transformers/index` 是同正文别名。本组覆盖 4 个 remote loader 路由与 3 个 transformer 路由，共 7 条。

## Google Cloud SQL PostgreSQL Loader

使用 `PostgresEngine` 建立 Cloud SQL 连接，再由 `PostgresLoader.initialize()` 从表或自定义 SQL 加载：

- 表模式默认把第一列作为 `pageContent`、其他列作为 metadata；每一行得到一个 Document。
- 自定义 SQL 可筛选目标数据，但查询文本应由应用固定或参数化，不能由模型自由拼接。
- page content 可格式化为 text、JSON、YAML、CSV；格式变化会改变 embedding 输入，应纳入索引版本。
- 前置要求包括 GCP project、billing、Cloud SQL Admin API、认证、实例、数据库和用户。

生产中优先 Workload Identity / ADC，数据库用户只授予目标视图的 SELECT；用高水位或更新时间做增量，避免全表扫描。

## LangSmithLoader

`LangSmithLoader` 位于 `@langchain/core`，可加载 LangSmith dataset/examples 和 traces，且不是 Node-only。典型用途是把历史输入、输出、metadata 转成 few-shot 或评估语料。

- Dataset/trace 可能包含 prompt、用户输入和工具输出，使用前要按原权限与敏感级别过滤。
- 文档中的示例会先创建和删除 dataset，仅用于演示；生产读取任务不应隐式修改 dataset。
- “Serializable: beta” 是实现成熟度边界，不应把序列化格式当稳定长期契约。

## Soniox 音频加载

`SonioxAudioTranscriptLoader` 接受 URL 或 `Uint8Array`，调用异步转写 API并返回单个 Document：

- 支持 60+ 语言、language hints、翻译、双向翻译、说话人分离、语言识别和上下文增强。
- `language_hints` 默认只是偏置而非限制；只有明确启用 strict 才收窄语言。
- 默认轮询间隔 1 秒（最小 1 秒），默认超时 180 秒；生产应配取消、全局截止时间和任务状态恢复。
- metadata 可含 token、speaker、language、translation 和 timing。长期存储前评估生物特征/个人数据和音频合规。
- 支持 AAC、AIFF、AMR、ASF、FLAC、MP3、OGG、WAV、WebM；仍需限制输入大小、时长、下载重定向与 MIME 欺骗。

## MetadataTagger

`createMetadataTaggerFromZod()` 使用 OpenAI function-capable chat model，按 Zod schema 给文档添加 title、tone、rating 等 metadata；也有接收 JSON Schema 的构造方式。

关键顺序是：

```text
完整文档加载 → 元数据抽取与验证 → 文本规范化 → 切分 → embedding/index
```

先切分会让标签器缺少全局上下文，导致同一文档的片段得到冲突标签。自定义 prompt 可以强调抽取规则，但不能代替：

- 枚举、长度、数值范围和必填字段校验；
- 受信字段与模型推断字段的区分；
- 失败/低置信结果的隔离；
- 批处理成本、重试和幂等缓存；
- 原始 metadata 不被模型结果覆盖的命名空间策略。

该集成路径位于 `@langchain/classic/document_transformers/openai_functions`，且自定义 LLM 必须支持 OpenAI Functions 语义。迁移时要核对包路径与模型能力。

## 生产摄取检查表

1. 每个远程 source 保存稳定 id、版本、采集时间与权限标签。
2. URL/SQL/dataset id 均由服务端 allowlist 或参数化构造。
3. 采集和转换分别建立 checkpoint；转换模型或 schema 变化触发新版本重算。
4. 音频、trace、数据库行进入 embedding 前做最小化与脱敏；日志只记计数和状态。
5. 远端 429/5xx 有界退避；鉴权与 schema 错误立即失败，不做无限重试。