学习笔记 · Obsidian
Embedding 模型：边缘、本地、数据库与长尾
集成矩阵
| 类 / 包 | 认证与初始化 | 运行位置 | 生产关注点 |
|---|---|---|---|
BaiduQianfanEmbeddings / @langchain/baidu-qianfan | BAIDU_API_KEY + BAIDU_SECRET_KEY | 远程 | 页面为旧格式，无标准 integration details；先核对当前模型与限额 |
CloudflareWorkersAIEmbeddings / @langchain/cloudflare | Worker env.AI binding + model | Cloudflare Worker | 必须配置 [ai] binding；与 account token 模式的 chat/LLM 示例不同 |
FireworksEmbeddings / @langchain/fireworks | FIREWORKS_API_KEY + model | 远程 | 模型 ID 与限额由托管服务决定 |
MinimaxEmbeddings / @langchain/classic/embeddings/minimax | 账号、API key、Group ID | 远程 | 页面未给安装包与环境变量契约；属于高验证成本的旧入口 |
MixedbreadAIEmbeddings / @langchain/mixedbread-ai | MXBAI_API_KEY；可设 model/baseUrl/maxRetries | 远程 | embedDocuments 自动按 batchSize 分批；错误与自定义 endpoint 要分类 |
NomicEmbeddings / @langchain/nomic | 文档要求 Nomic API key，但未声明环境变量名 | 远程 | 部署前查当前 package API/type declaration，不凭经验猜变量名 |
OllamaEmbeddings / @langchain/ollama | model + baseUrl，默认本机 11434 | 本地服务 | 固定模型 digest；容量、预热、端口和持久化自运维 |
OracleEmbeddings / @oracle/langchain-oracledb | Oracle connection + provider/model | Node.js + Oracle DB | 可在库内跑 ONNX，或由数据库调用 OCI/HF；连接池与 DB credential 必须治理 |
PineconeEmbeddings / @langchain/pinecone | PINECONE_API_KEY + inference model | 远程 | 另装 Pinecone client v5；embedding service 与 vector index 配置要匹配 |
TogetherAIEmbeddings / @langchain/together-ai | TOGETHER_AI_API_KEY + model | 远程 | 托管开源模型可能变更；固定精确 ID 和维度 |
VoyageEmbeddings / @langchain/mongodb | VOYAGE_API_KEY + model | 远程 | 官方页明确从 MongoDB 包导出；不要想当然安装 @langchain/voyage |
Cloudflare binding 边界
Cloudflare embedding 集成是为 Worker binding 设计的：CloudflareWorkersAIEmbeddings({ binding: env.AI, model })。Vectorize 通过另一个 env.VECTORIZE_INDEX binding 注入。生产部署需要同时验证 wrangler binding 名、模型维度与 Vectorize index schema；本地 Node 单测不能证明 Worker runtime 可用。
Oracle 的两条数据路径
OracleEmbeddings 只支持 Node.js，并接收数据库 connection：
provider: "database"：先把 ONNX 模型加载进 Oracle，再在库内生成向量。收益是数据不外发、减少网络延迟；成本是模型加载、数据库 CPU/内存和版本兼容由 DBA 运维。provider: "ocigenai"或"huggingface"：由 Oracle 内部凭据调用托管服务，可配置 proxy。数据仍会离开数据库，需审查 egress、credential object、区域与第三方保留政策。
无论哪条路径，都要使用 connection pool、finally 归还连接、限制并发，并把 ONNX/model/credential name 纳入索引签名。示例中的明文数据库变量只是占位形式，真实 secret 不进入笔记、源码或日志。
长尾页面的证据等级
Minimax、Baidu、Nomic 页面没有统一 feature/integration table；Minimax 甚至只展示 @langchain/classic 深层 import，未给安装与环境契约。这些路由可证明“文档存在和基本调用形态”，不能证明当前 package export、模型可用性或生产支持级别。
采用前必须补：
package.json/lockfile 固定版本；- 公开 exports 与
.d.ts编译验证； - credential 缺失和无权限负向测试；
- 单条、批量、空文本、超长文本和非 ASCII contract test；
- 维度、finite number、限流、超时和重试实测；
- 服务条款、数据驻留、SLA 和退出迁移方案。
本地 Ollama
Ollama 省去第三方 API key，却把模型分发、硬件容量、升级、监控和恢复转移给自己。索引发布应记录 model digest，而不是只记可变 tag；滚动升级用新 collection 回填，禁止两台实例使用不同权重却写同一索引。
Pinecone inference 与 vector store
PineconeEmbeddings 是 Pinecone inference model wrapper，不等同于 Pinecone vector store。要分别核对 embedding model 的 dimension/metric 和目标 index schema。API key 也应按最小权限区分 inference 与数据面；如果平台权限模型无法细分，则通过独立 project/key 降低爆炸半径。
Mixedbread、Fireworks、Together 与 Voyage
- custom base URL 只允许配置受信 endpoint；禁止把用户输入直接拼入。
maxRetries只覆盖可重试 transport/provider 错误；schema、认证、额度和输入长度错误应立即失败。- 批量请求要按条目数与总 token 双重切分，部分成功时以 document id 恢复。
- Voyage 当前官方导出路径是
@langchain/mongodb，升级时特别检查 package 迁移公告，避免重复安装或错误 tree-shaking。
统一验收
所有组件都要遵守 00-模型与Provider选型总览 中的索引签名与重建规则。Provider 切换不是普通配置变更，而是数据迁移：新旧 embedding 不能在同一向量空间混查。