学习笔记 · Obsidian
远程文档加载与元数据转换
结论
- 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 的构造方式。
关键顺序是：
完整文档加载 → 元数据抽取与验证 → 文本规范化 → 切分 → embedding/index先切分会让标签器缺少全局上下文，导致同一文档的片段得到冲突标签。自定义 prompt 可以强调抽取规则，但不能代替：
- 枚举、长度、数值范围和必填字段校验；
- 受信字段与模型推断字段的区分；
- 失败/低置信结果的隔离；
- 批处理成本、重试和幂等缓存；
- 原始 metadata 不被模型结果覆盖的命名空间策略。
该集成路径位于 @langchain/classic/document_transformers/openai_functions，且自定义 LLM 必须支持 OpenAI Functions 语义。迁移时要核对包路径与模型能力。
生产摄取检查表
- 每个远程 source 保存稳定 id、版本、采集时间与权限标签。
- URL/SQL/dataset id 均由服务端 allowlist 或参数化构造。
- 采集和转换分别建立 checkpoint；转换模型或 schema 变化触发新版本重算。
- 音频、trace、数据库行进入 embedding 前做最小化与脱敏；日志只记计数和状态。
- 远端 429/5xx 有界退避；鉴权与 schema 错误立即失败，不做无限重试。