Embedding 模型：主流云与索引不变量

集成矩阵

初始化与接口

所有类都实现查询与文档两条路径：

const queryVector = await embeddings.embedQuery(query);
const documentVectors = await embeddings.embedDocuments(chunks);

即使某个 provider 内部当前使用同一端点，也不要用 embedQuery 代替批量文档索引。部分模型会根据 query/document task type 生成不同分布，混用会直接降低召回质量。

索引签名

每个向量索引必须保存不可变签名：

provider + packageVersion + model + dimensions + taskType
+ normalization + preprocessingVersion + distanceMetric

模型、维度或预处理变化时创建新 index/collection，完成全量 backfill、双读评估与 alias 切换后再删除旧索引。不能把 1024 维新向量写进既有 3072 维索引，也不能只更新查询侧模型。

批处理与恢复

• provider 文档给出的 batch 上限只是请求层上限，还要按 token/字符总量切块。
• 用稳定 document id + chunk id 做幂等 upsert；批次失败记录原始 id 集合，而不是重新扫描全部数据。
• 对 429、明确的 5xx 与网络瞬断做指数退避加抖动；认证、配额耗尽和输入过长要快速失败并告警。
• 并发以 provider rate limit 和 vector store 写入能力的较小值为准。
• backfill 输出必须验证向量数量、维度、finite number、空文本策略与源文档版本。

Provider 特殊项

Azure

embedding deployment 使用 AZURE_OPENAI_API_EMBEDDINGS_DEPLOYMENT_NAME，不能复用 chat deployment 假设。Managed Identity 通过 token provider 注入，优先于静态 key；API version 是兼容性的一部分，应随索引签名和发布记录保存。

Bedrock

默认示例传 access key/secret，但生产宜走 AWS 默认身份链或短期角色。自定义 BedrockRuntimeClient 可统一 retry policy、region 与 credential provider；不要在 constructor 中固化长期凭据。

Cohere

自定义 client 适用于 Azure、AWS Bedrock 或独立 Cohere endpoint。提供 client 后，COHERE_API_KEY 和 constructor apiKey 都会被忽略；配置审计必须识别这个优先级，否则会误判实际数据出口。

Google

google-genai 与 google-vertexai 是旧 embedding 路径，不能因新 @langchain/google 已统一 chat 就擅自替换 embedding。迁移前以目标 package 的公开 exports 和真实向量对照为准，并执行重建索引。

IBM

IAM、bearer、CP4D 和 model gateway 需要不同配置集合。把 auth type、service URL、project/space/deployment 和 model alias 作为一个原子 profile，避免跨环境拼接。

Mistral hooks

hooks 适合采集 request latency、错误类别与 provider request id，但不得记录 embedding 原文或 Authorization header。手工修改 hook 数组后需调用官方的重新绑定方法；否则可能重复或漏装 hook。

OpenAI dimensions

dimensions 能降低存储与检索成本，但会改变索引契约和可能的召回效果。先用固定评估集比较 recall@k、MRR、延迟、索引大小与成本，再决定维度；不能只依据示例从 3072 降到 1024。

缓存

缓存 namespace 至少包含完整索引签名；升级模型或预处理版本后必须换 namespace。缓存命中率、旧 key 淘汰和 query cache 的隐私保留期都需监控。内存 store 只适合示例和测试，生产使用持久 store 并配置容量与 TTL。