---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - typescript
  - integrations
  - embeddings
  - rag
  - vector-search
topic: LangChain JavaScript 主流云 Embedding 模型与索引不变量
sources:
  - https://docs.langchain.com/oss/javascript/integrations/embeddings/azure_openai
  - https://docs.langchain.com/oss/javascript/integrations/embeddings/bedrock
  - https://docs.langchain.com/oss/javascript/integrations/embeddings/cohere
  - https://docs.langchain.com/oss/javascript/integrations/embeddings/google_generative_ai
  - https://docs.langchain.com/oss/javascript/integrations/embeddings/google_vertex_ai
  - https://docs.langchain.com/oss/javascript/integrations/embeddings/ibm
  - https://docs.langchain.com/oss/javascript/integrations/embeddings/mistralai
  - https://docs.langchain.com/oss/javascript/integrations/embeddings/openai
last_verified: 2026-08-11
---
# Embedding 模型：主流云与索引不变量

## 集成矩阵

| 类 / 包 | 认证与初始化 | 示例模型 / 参数 | 运行时与特殊能力 |
|---|---|---|---|
| `AzureOpenAIEmbeddings` / `@langchain/openai` | instance、embedding deployment、API version；key 或 Managed Identity | deployment 名独立于 chat | 远程；支持非默认域、custom header、旧 Azure SDK 迁移 |
| `BedrockEmbeddings` / `@langchain/aws` | region + AWS identity，或自定义 `BedrockRuntimeClient` | `amazon.titan-embed-text-v1` | 远程；需先授权模型；custom client 可定制 retry/region |
| `CohereEmbeddings` / `@langchain/cohere` | `COHERE_API_KEY` 或 custom `CohereClient` | `embed-english-v3.0`；batch 默认 48、最大 96 | 远程；custom client 会覆盖 env/constructor key |
| `GoogleGenerativeAIEmbeddings` / `@langchain/google-genai` | `GOOGLE_API_KEY` | `gemini-embedding-001`，示例为 768 维 | 远程；旧包 LTS，不用于新 Chat 选型 |
| `VertexAIEmbeddings` / `@langchain/google-vertexai` | ADC / `GOOGLE_APPLICATION_CREDENTIALS`；Web 用专用包 | `gemini-embedding-001` | Node 与 Web/Edge import/auth 分离 |
| `WatsonxEmbeddings` / `@langchain/ibm` | IAM、bearer token、CP4D；model/project 或 gateway alias | model ID / alias | 远程；model gateway 是独立部署 profile |
| `MistralAIEmbeddings` / `@langchain/mistralai` | `MISTRAL_API_KEY` | `mistral-embed` | 远程；beforeRequest/requestError/response hooks |
| `OpenAIEmbeddings` / `@langchain/openai` | `OPENAI_API_KEY`，可 custom base URL | `text-embedding-3-large`；batch 默认 512、最大 2048；可设 dimensions | 远程；示例从 3072 降到 1024 维 |

## 初始化与接口

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

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

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

## 索引签名

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

```text
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。