---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - typescript
  - integrations
  - vector-store
topic: LangChain JavaScript 向量库统一接口与本地基线
sources:
  - https://docs.langchain.com/oss/javascript/integrations/vectorstores
  - https://docs.langchain.com/oss/javascript/integrations/vectorstores/index
  - https://docs.langchain.com/oss/javascript/integrations/vectorstores/memory
last_verified: 2026-08-11
---
# 向量库统一接口与本地基线

## 结论

- LangChain 统一 `addDocuments`、`delete`、`similaritySearch` 与 `asRetriever`，但过滤、ID、删除、索引、分数方向和一致性语义仍由具体后端决定。
- Embedding model、维度、预处理、distance metric 和索引算法必须作为同一版本契约；不能在一个索引中混用。
- `MemoryVectorStore` 是 exact linear search 的易用基线，只适合测试/小数据，不支持 ID 或删除，不能作为生产持久库。

## 路由去重

`/vectorstores` 与 `/vectorstores/index` 返回同一正文，两条原始路由都保留。本组覆盖 3 条路由。

## 统一接口与不可统一部分

| 能力 | 统一入口 | 后端差异 |
|---|---|---|
| 写入 | `addDocuments()` | ID/upsert、批量、可见延迟、事务 |
| 删除 | `delete()` | 按 ID、filter、全删或不支持 |
| 检索 | `similaritySearch(query, k, filter?)` | filter DSL、距离与分数方向 |
| 带分数 | `similaritySearchWithScore()` | score 是否归一化、越大/越小越好 |
| Retriever | `asRetriever()` | MMR、filter、search kwargs 支持不同 |

切换实现前必须用契约测试验证这些差异，不能因为 TypeScript 接口相同就直接替换。

## 相似度与索引

常见度量为 cosine、Euclidean/L2、dot product；ANN 常用 HNSW，也可能是 IVF 或后端专有算法。选择原则：

- distance 与 embedding 模型建议匹配；
- exact search 适合小集合与召回基线；
- ANN 用延迟换近似召回，需联合调 `m`、construction/search ef、probe 等；
- metadata 预过滤必须有字段索引，否则可能先扫后滤或显著拖慢查询。

## MemoryVectorStore

它把 embedding 保存在进程内，以 cosine 为默认 metric，逐个做 exact linear search；可传自定义 `ml-distance` similarity。能力包括 predicate filter、带 score 查询、`asRetriever()` 与 MMR。

明确边界：

- 进程重启数据消失，实例间不共享；
- O(n) 扫描，数据量和并发上升后延迟线性增长；
- 当前不支持 ID 和 deletion；
- 适合单元测试、算法验证和作为召回正确性的参照。

## 生产契约测试

1. 同一固定语料验证 top-k、score 顺序、filter、空结果和重复 ID。
2. 写后立即查、批量写、失败重试、delete 与 delete-all 验证一致性。
3. 启动时校验 embedding dimension 与索引 schema，不匹配直接失败。
4. 测量 p50/p95/p99、QPS、召回率、索引构建时长、存储与网络成本。
5. 保存 index version 和 embedding fingerprint；重建后用双读/影子流量验证再切换。