学习笔记 · Obsidian
Provider 生态与跨组件边界
Provider 不是统一能力层
Provider 页面主要回答“这个生态有哪些 LangChain 组件和 npm 包”。真正的参数、feature matrix 和运行时要求仍以具体 chat、embedding、retriever、tool 或 loader 页面为准。生产选型不能把 provider index 当接口契约。
| Provider | 包与组件 | 认证 / 运行时 | 关键边界 |
|---|---|---|---|
| Anthropic | @langchain/anthropic：ChatAnthropic | ANTHROPIC_API_KEY | system message 必须位于首条；优先 ChatPromptTemplate |
| AWS | @langchain/aws：ChatBedrockConverse、BedrockEmbeddings、AmazonKnowledgeBaseRetriever | AWS region、身份链、模型访问授权 | Converse、embedding、Knowledge Base 是不同服务面；模型能力需逐 ID 核验 |
新项目用 @langchain/google 的 ChatGoogle；Cloud SQL 另包 | AI Studio key、Vertex Express key 或 Vertex ADC | 旧 google-genai / google-vertexai* 仅 LTS；Node 与 Web/Edge 认证包不可混用 | |
| Microsoft | 模型用 @langchain/openai；Cosmos/DocumentDB 用 @langchain/azure-cosmosdb；动态会话另包 | Azure key 或 Managed Identity；deployment 与 API version | chat、completion、embedding deployment 名不同；数据库和 sandbox 不是模型包的一部分 |
| OpenAI | @langchain/openai：chat、legacy LLM、embedding；langchain 提供 moderation middleware | OPENAI_API_KEY | moderation 可检查 input/output/tool result，但不能代替业务授权或人工升级策略 |
| Perplexity | @langchain/perplexity：ChatPerplexity、search retriever、search tool | PERPLEXITY_API_KEY | Chat/Agent API、Retriever 与 Tool 返回形态不同，不应互换 |
| Sourcey | langchain-sourcey：SourceyRetriever | 无 API key | 读取站点 search-index.json，存在时用 llms-full.txt；只适用于公开 Sourcey 构建 |
| Supadata | @supadata/langchain-js：SupadataLoader | SUPADATA_API_KEY | 面向视频 transcript/metadata loader，不是模型 provider；输入 URL 要做域名与租户校验 |
| Tavily | @langchain/tavily：Search、Extract、Crawl、Map、Research、GetResearch tools | TAVILY_API_KEY | Crawl/Extract 是外部内容入口；必须限制域、深度、结果体积与超时 |
| You.com | @youdotcom-oss/langchain：youSearch、youResearch、youContents | YDC_API_KEY | 三个导出是 structured tools；生产侧仍要做来源、配额和内容安全控制 |
Google 包迁移与运行时
@langchain/google 是新 ChatGoogle 的统一入口，可在 AI Studio 与 Vertex AI 间选择。旧包关系如下：
@langchain/google-genai基于已弃用 Google SDK，不再获得新特性；只维护既有系统。@langchain/google-vertexai面向 Node.js，并依赖@langchain/google-gauth。@langchain/google-vertexai-web面向 browser/Edge，并依赖@langchain/google-webauth。@langchain/google-common是旧集成内部共享层，不是独立使用入口。@langchain/google-gauth与@langchain/google-webauth不应同时装入一个项目。
Node 端旧认证顺序为 constructor apiKey、constructor authOptions、环境 API_KEY、GOOGLE_APPLICATION_CREDENTIALS、ADC。Web/Edge 即使存在专用包，也不能把长期 service-account credential 发送到不可信浏览器；应优先服务端代理或短期、受限凭据。
Azure 边界
Azure OpenAI 新集成已归入 @langchain/openai，旧 @langchain/azure-openai 路径需要迁移。生产建议优先 Managed Identity，且分别管理：
- instance name；
- chat/completion deployment；
- embedding deployment；
- API version；
- 非默认域名时的 base path。
Cosmos DB vector store、DocumentDB vector store、semantic cache 与 Container Apps dynamic sessions 分属其他包和权限域。不要因为同属 Microsoft provider 就共享过宽连接串、角色或网络出口。
OpenAI moderation 的位置
openAIModerationMiddleware 可配置 checkInput、checkOutput、checkToolResults，并以 end、error 或 replace 处理命中。生产上还需：
- 在工具真正执行前做权限和参数校验；
- 区分安全拒绝、provider 故障与业务校验失败；
- 对误报、申诉与人工升级建立可审计流程；
- 避免把原始敏感内容写入 moderation 日志。
搜索、抓取与 Loader 风险
- 所有 URL 输入都要防 SSRF：协议白名单、DNS/IP 重绑定检查、私网和 metadata endpoint 禁止、重定向上限。
- 对 crawl/map/research 设置最大深度、页面数、响应体、并发、总时限和预算。
- 返回的网页、字幕与 metadata 均是不可信内容；进入 prompt 前做大小限制和 prompt-injection 隔离。
- 保存 canonical URL、抓取时间与 provider request id，引用不能只保留模型生成的标题。
- research 异步任务以 request id 幂等关联租户，轮询要退避并设置最终超时。
依赖治理
Provider 独立包改善版本、依赖与测试隔离，也意味着升级面分散。锁定每个 @langchain/* 包和 @langchain/core 的兼容组合；升级时验证公开 exports、类型检查、目标 bundler、真实 API smoke 和回滚。不要从 provider index 的下载量或“热门”标签推断 SLA、安全或适用性。