---
type: study
status: verified
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
tags:
  - study
  - langchain
  - python
  - integrations
  - vector-store
  - rag
topic: LangChain Python 向量存储索引一致性与迁移
sources:
  - https://docs.langchain.com/oss/python/integrations/vectorstores
  - https://docs.langchain.com/oss/python/integrations/vectorstores/astradb
  - https://docs.langchain.com/oss/python/integrations/vectorstores/azure_cosmos_db_mongo_vcore
  - https://docs.langchain.com/oss/python/integrations/vectorstores/azure_cosmos_db_no_sql
  - https://docs.langchain.com/oss/python/integrations/vectorstores/azure_db_for_postgresql
  - https://docs.langchain.com/oss/python/integrations/vectorstores/chroma
  - https://docs.langchain.com/oss/python/integrations/vectorstores/databricks_vector_search
  - https://docs.langchain.com/oss/python/integrations/vectorstores/elasticsearch
  - https://docs.langchain.com/oss/python/integrations/vectorstores/google_alloydb
  - https://docs.langchain.com/oss/python/integrations/vectorstores/google_bigquery_vector_search
  - https://docs.langchain.com/oss/python/integrations/vectorstores/google_cloud_sql_mysql
  - https://docs.langchain.com/oss/python/integrations/vectorstores/google_cloud_sql_pg
  - https://docs.langchain.com/oss/python/integrations/vectorstores/google_firestore
  - https://docs.langchain.com/oss/python/integrations/vectorstores/google_memorystore_redis
  - https://docs.langchain.com/oss/python/integrations/vectorstores/google_spanner
  - https://docs.langchain.com/oss/python/integrations/vectorstores/google_vertex_ai_feature_store
  - https://docs.langchain.com/oss/python/integrations/vectorstores/google_vertex_ai_vector_search
  - https://docs.langchain.com/oss/python/integrations/vectorstores/in_memory
  - https://docs.langchain.com/oss/python/integrations/vectorstores/index
  - https://docs.langchain.com/oss/python/integrations/vectorstores/memorydb
  - https://docs.langchain.com/oss/python/integrations/vectorstores/milvus
  - https://docs.langchain.com/oss/python/integrations/vectorstores/mongodb_atlas
  - https://docs.langchain.com/oss/python/integrations/vectorstores/neo4jvector
  - https://docs.langchain.com/oss/python/integrations/vectorstores/oracle
  - https://docs.langchain.com/oss/python/integrations/vectorstores/pgvector
  - https://docs.langchain.com/oss/python/integrations/vectorstores/pgvectorstore
  - https://docs.langchain.com/oss/python/integrations/vectorstores/pinecone
  - https://docs.langchain.com/oss/python/integrations/vectorstores/pinecone_sparse
  - https://docs.langchain.com/oss/python/integrations/vectorstores/qdrant
  - https://docs.langchain.com/oss/python/integrations/vectorstores/redis
  - https://docs.langchain.com/oss/python/integrations/vectorstores/sap_hanavector
  - https://docs.langchain.com/oss/python/integrations/vectorstores/turbopuffer
  - https://docs.langchain.com/oss/python/integrations/vectorstores/valkey
  - https://docs.langchain.com/oss/python/integrations/vectorstores/weaviate
last_verified: 2026-08-11
---
# Vector Stores：索引、一致性与迁移

## 公共契约

向量库保存 embedding 并执行相似度搜索。LangChain 的最小公共面是：

- `add_documents(documents, ids=...)`：写入文本、metadata 和向量；
- `delete(ids=...)`：按稳定 ID 删除；
- `similarity_search(query, k, filter=...)`：返回相似 `Document`；
- 多数实现还提供 score、按向量搜索、MMR、`as_retriever()`，但参数和语义不完全可移植。

`/vectorstores` 与 `/vectorstores/index` 当前同正文。官方明确指出 metadata filter 支持因实现而异；cosine、Euclidean、dot product 的分数方向和量纲也不同，不能跨库用同一个阈值。

## 34 个路由的选型地图

| 路由 | 包/部署 | 文档中的主要能力与边界 |
|---|---|---|
| `vectorstores`、`index` | 总索引 | 公共 CRUD/search 接口、embedding 选择、距离与过滤；索引表远多于本站深链页面。 |
| `astradb` | `langchain-astradb`，Astra DB | 客户端 embedding、server-side vectorize、已有 collection 自动检测；支持 hybrid search，异步初始化细节在 API Reference。 |
| `azure_cosmos_db_mongo_vcore` | `langchain-azure-ai` + PyMongo | Mongo vCore 的 COS/L2/IP ANN 和 preview filtered search。页面仍含不再维护的 `langchain-community` loader 示例。 |
| `azure_cosmos_db_no_sql` | `langchain-azure-cosmosdb` | NoSQL vector/full-text/BM25/hybrid/filter；v1.0 独立包支持 sync/async client 和 Entra ID。 |
| `azure_db_for_postgresql` | `langchain-azure-postgresql` | Flexible Server、pgvector、DiskANN、密码或 Entra 认证、过滤与 CRUD。 |
| `chroma` | `langchain-chroma` | 进程内、`persist_directory`、独立 server、Chroma Cloud 四种连接方式。 |
| `databricks_vector_search` | `databricks-langchain` | serverless Vector Search，可从 Unity Catalog Delta table 构建自动更新索引；外部访问需要 host/token。 |
| `elasticsearch` | `langchain-elasticsearch` | dense、ELSER sparse、BM25、hybrid、script score、自定义 query/document builder；本地 start 脚本仅测试。 |
| `google_alloydb` | `langchain-google-alloydb-pg` | AlloyDB table、ScaNN/IVFFlat、re-index、metadata filter；教程以 async 为主且均有 sync 对应。 |
| `google_bigquery_vector_search` | `langchain-google-community[featurestore]` | GoogleSQL brute-force/exact 或 vector index/ANN，适合批量/原型；可批量搜索和写入已有 embedding。 |
| `google_cloud_sql_mysql` | `langchain-google-cloud-sql-mysql` | MySQL table、vector index、metadata columns/filter；engine 管理连接池。 |
| `google_cloud_sql_pg` | `langchain-google-cloud-sql-pg` | PostgreSQL table、IVFFlat、re-index/filter；教程 async，所有 async 方法有 sync 对应。 |
| `google_firestore` | `langchain-google-firestore` | Firestore vector 写入、更新、删除、similarity search 和原生 FieldFilter。 |
| `google_memorystore_redis` | `langchain-google-memorystore-redis` | Redis vector index、KNN、range、MMR、retriever；可删除文档和整个 index。 |
| `google_spanner` | `langchain-google-spanner` | Spanner 强一致关系数据上的 vector search、secondary index、写删查。 |
| `google_vertex_ai_feature_store` | `langchain-google-community[featurestore]` | BigQuery 数据同步到 Feature Store Online Store 后做低延迟 ANN；同步可手动或计划执行。 |
| `google_vertex_ai_vector_search` | `langchain-google-vertexai` | V2 collection CRUD/search/filter/delete，以及传统 Matching Engine 的 index、endpoint、deploy、hybrid 流程。 |
| `in_memory` | `langchain-core` | `InMemoryVectorStore` 仅进程内、易失，适合测试，不是生产持久层。 |
| `memorydb` | `langchain-aws` + Redis client | Amazon MemoryDB vector index、查询、retriever 和删 index；页面类名也叫 `InMemoryVectorStore`，导入路径必须明确避免与 core 类混淆。 |
| `milvus` | `langchain-milvus` | Milvus Lite 本地文件或 server/cloud；collection、dense/hybrid/full-text/BM25/rerank、按用户过滤。 |
| `mongodb_atlas` | `langchain-mongodb` | Atlas Vector Search、BM25、hybrid、HNSW、Voyage embedding/rerank；搜索 index 与普通 Mongo collection 生命周期不同。 |
| `neo4jvector` | `langchain-neo4j` | Neo4j ANN、cosine/Euclidean、hybrid、metadata filter、自定义 retrieval query。 |
| `oracle` | `langchain-oracledb` | `OracleVS`、HNSW/IVF、关系过滤、Oracle Text hybrid；hybrid/text retriever 有部分 async API。 |
| `pgvector` | `langchain-postgres` | `PGVector` 经典入口、Postgres+pgvector、CRUD/filter；连接字符串和 collection/schema 是持久化契约。 |
| `pgvectorstore` | `langchain-postgres` | `PGEngine`/`PGVectorStore` 新入口、async SQLAlchemy engine、HNSW/IVFFlat、已有表和自定义 metadata。 |
| `pinecone` | `langchain-pinecone` | 托管 dense vector、namespace/index CRUD、score 和 retriever。 |
| `pinecone_sparse` | 文档固定 `langchain-pinecone==0.2.5` | Pinecone sparse embedding/store；页面版本固定且出现 async extra 警告，不能与最新版 dense 示例直接拼装。 |
| `qdrant` | `langchain-qdrant`，要求 Qdrant ≥1.10 | 内存、on-disk、server/cloud；dense、sparse、hybrid Query API、named vector 和 payload filter。 |
| `redis` | `langchain-redis` | vector/full-text、metadata filter、MMR；只有在 metadata schema 声明的字段才能过滤。 |
| `sap_hanavector` | `langchain-hana` | HANA vector、HNSW、MMR、高级 filter、reranker、自定义表/列。 |
| `turbopuffer` | `langchain-turbopuffer` | 托管 vector CRUD、score、retriever 和 filter。 |
| `valkey` | `langchain-aws>=1.5.0` | ElastiCache/MemoryDB for Valkey、Bedrock/Ollama embedding、metadata filter、自定义 schema。 |
| `weaviate` | `langchain-weaviate` | 现有 collection、过滤、multi-tenancy、持久化、MMR；原生 async 需 ≥0.0.8 且显式连接 async client。 |

## 同步与异步边界

不能从方法名相似推断所有 provider 都有真正异步 I/O。当前页面明确给出的证据是：

- AlloyDB、Cloud SQL PostgreSQL、`PGVectorStore` 教程使用 `aadd_*`、`adelete`、`asimilarity_search*`，并说明每个 async 方法有 sync 对应。
- Astra DB 页面只指向 API Reference 的异步初始化说明。
- Weaviate 在 `langchain-weaviate>=0.0.8` 且传入已连接的 `client_async` 时才是原生 async；否则异步方法把同步 client 放进 executor，并记录 warning。
- Oracle 页只明确 hybrid/text index/retriever 的部分异步入口。
- 其余页面多为同步示例；这只表示本次文档没有提供 async 契约，实施时需按锁定版本 API 核对。

向量库的 query 通常一次返回 top-k，并非 token 流。应用层可以流式报告“embedding、写入、建索引、切换完成”等进度，但不能把调用封装为 async 就宣称后端非阻塞或实时可见。

## 数据与索引契约

### embedding 是 schema，不是普通配置

必须版本化保存 model/provider、dimension、归一化方式、distance metric 和预处理版本。更换 embedding 后旧向量与新查询不再处于同一语义空间；可靠做法是建新 collection/index，双写或回填，shadow query 对比，再通过 alias/config 原子切换并保留回滚窗口。

### ID、写入和删除

- 用业务稳定 ID，而不是每次生成随机 UUID；同一文档版本重复入库应成为 upsert 或可检测重复。
- 把 source ID、content hash、chunk version、embedding version 放入受控 metadata；不要依赖 page content 去重。
- 批量 API 可能部分成功。记录批次、成功 ID、失败 ID和 provider request ID；只对幂等子批重试。
- delete 返回成功不必然等于查询立即不可见。对需要“删除即不可检索”的业务增加 tombstone/ACL 层，并验证索引刷新完成。

### 搜索一致性与过滤

数据库事务提交、embedding 写入、ANN index refresh/deploy 是三个不同完成点。生产 read-after-write 测试要按 provider 实测；建索引和 re-index 用可恢复 job 状态，不在请求线程阻塞。

metadata filter 的操作符、类型、嵌套、数组和前/后过滤位置不同。ACL 必须在服务端强制，优先使用后端原生 pre-filter；如果只能 post-filter，应扩大候选并监控召回损失，但不能因结果不足而绕过权限。

## 部署与持久化边界

- `InMemoryVectorStore` 进程退出即丢；Chroma/Qdrant/Milvus 的 in-memory/local 模式也不自动具备多副本、备份或并发保证。
- Chroma `persist_directory`、Milvus Lite、Qdrant on-disk 适合单机开发或明确受限场景；多实例服务应使用受支持的 server/cloud 部署。
- BigQuery Vector Search 偏批量，Vertex Feature Store 偏低延迟在线；二者联用时要监控数据同步水位，而不是假设同一时刻可见。
- Databricks 自动更新 index 仍需观察 Delta source 到 serving index 的 lag。
- 关系数据库内置 vector 的收益是事务/治理靠近业务数据，但 ANN index、embedding 和业务行仍需明确事务与回填边界。

## 生产验证清单

- [ ] 锁定 integration、client、server 和 index schema 版本。
- [ ] 验证 dimension/metric 不匹配会 fail-fast，而不是静默写错。
- [ ] 覆盖重复写、部分失败、网络超时、重试、删除、重建和回滚。
- [ ] 用目标规模测试 recall@k、过滤后召回、P95/P99、索引大小和成本。
- [ ] 验证 tenant/ACL filter 无跨租户泄漏，并对 filter 字段建正确索引。
- [ ] 监控写入水位、index lag、查询错误、空结果率、embedding 版本分布和容量。
- [ ] 备份恢复后核对 document、metadata、vector、index 和 alias 一致。

## 验证边界

已逐页验证 34 个官方 Markdown 路由及其当前示例能力。没有连接任何真实向量服务，也没有据在线文档推断目标安装版本的实时 SLA、事务隔离、索引可见延迟或费用；这些必须以锁文件、provider 文档和真实压测为准。