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 文档和真实压测为准。