VectorStore集成

向量库负责存 embedding 并做近邻搜索。各库 API（Chroma、FAISS、pgvector）不同，换库就要改业务代码。VectorStore 抽象统一 add_documents、similarity_search、as_retriever，与 Embeddings 专篇配合完成 RAG 索引层。

段末注释：VectorStore（向量存储）= 存储向量并支持相似度检索的后端抽象。

---

1. 一句话定位

维度	内容
角色	能力层 向量索引：Document ↔ embedding ↔ 检索
输入 → 输出	add：list[Document]；search：str → list[Document]
典型调用入口	store.add_documents(...)、store.similarity_search(q, k=4)
与 LangGraph	索引多为离线；在线检索作为 Runnable 节点

---

2. 实现逻辑

1. embeddings = HuggingFaceEmbeddings(...) 或 OpenAIEmbeddings
2. store = InMemoryVectorStore(embeddings)  # 或 FAISS.from_documents / Chroma
3. store.add_documents([Document(...), ...])  # 内部 embed_documents
4. hits = store.similarity_search("query", k=3)
5. retriever = store.as_retriever(search_kwargs={"k": 3})
6. retriever.invoke("query")  # 等价检索路径

字段级变形：

Document(page_content="段落A")
  → add_documents → 向量存入 index
"问题" → similarity_search → [Document(段落A), ...]

---

3. 原理说明

3.1 核心接口

VectorStore（抽象类）
功能：存 embedding 并近邻搜索。

add_documents(documents, **kwargs)（方法）
功能：内部调 embed_documents 再写入。默认无 ids 则自动生成。
最小维度：documents len≥1；每条 page_content 建议非空。返回 id 列表，len 与输入相同。

store.add_documents([Document(page_content="LCEL 用 | 组合。")])

add_texts(texts, metadatas=None, **kwargs)（方法）
texts: list[str] len≥1；metadatas 为 None 或与 texts 等长的 list[dict]。

similarity_search(query, k=4, **kwargs)（方法）
功能：把 query 编码后近邻检索。默认 k=4。
最小维度：query 非空；k ≥ 1；库空则 []。返回 list[Document]，len ≤ k。

hits = store.similarity_search("什么是 LCEL", k=1)

similarity_search_by_vector(embedding, k=4)（方法）
功能：已有向量直接搜，不再 embed_query。embedding 长度必须 = 索引 dim。

delete(ids)（方法，视实现）
ids len≥1。

as_retriever(*, search_type="similarity", search_kwargs=None)（方法）
默认 similarity；search_kwargs["k"] 不传则用实现默认（常 4）。把 store 变成 invoke(str) → list[Document]，才能进 LCEL。

store.as_retriever(search_kwargs={"k": 3}).invoke("管道怎么组合")

3.2 集成包分布

• 内存：InMemoryVectorStore（langchain-core，v0.3+）。
• FAISS / Chroma：community 或 partner 包。
• 生产：pgvector、Milvus、Pinecone 等。

InMemoryVectorStore（类）
功能：进程内向量库。构造必填 embedding。重启即失。
最小维度：embedding 模型 dim 固定后，所有向量必须同 dim。

InMemoryVectorStore.from_documents(docs, embedding=embeddings)  # docs len≥1

from_documents(documents, embedding, **kwargs)（类方法）
一步 add。documents len≥1。

3.3 持久化

FAISS.save_local(folder_path) / FAISS.load_local(folder_path, embeddings, allow_dangerous_deserialization=True)
功能：索引落盘 / 读回。load_local 须同一 Embeddings；pickle 需显式允许反序列化。
最小维度：目录内至少 index.faiss + index.pkl。

Chroma(..., persist_directory=str)
persist_directory 非空路径；空目录会建新 collection。

3.4 Embeddings 一致性

构造时绑定的 Embeddings 必须与后续 add/search 同一模型、同一 dim，否则召回无意义。

---

4. 最小可运行示例

pip install -U langchain-huggingface sentence-transformers

from langchain_core.documents import Document
from langchain_core.vectorstores import InMemoryVectorStore
from langchain_huggingface import HuggingFaceEmbeddings

embeddings = HuggingFaceEmbeddings(
    model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
    encode_kwargs={"normalize_embeddings": True},
)
store = InMemoryVectorStore.from_documents(
    [
        Document(page_content="LangChain 提供 LCEL 管道，用 | 组合 Runnable。"),
        Document(page_content="Python 是一种编程语言。"),
        Document(page_content="Retriever 根据 query 返回相关 Document。"),
    ],
    embedding=embeddings,
)
hits = store.similarity_search("什么是 LCEL", k=1)
print(hits[0].page_content)
print(store.as_retriever(search_kwargs={"k": 1}).invoke("管道怎么组合")[0].page_content[:20])
# 预期：两条都命中 LCEL 那条（真实语义）

Chroma（需额外包）示意：

pip install langchain-chroma

# from langchain_chroma import Chroma
# store = Chroma.from_documents(docs, embeddings, persist_directory="./chroma_db")

重要配置参数

参数（API 名）	类型 / 默认值	功能说明	作用与影响	参考起点	配置指导
embedding	Embeddings，构造必填	入库与查询时把文本编成向量的实现	换模型必须重建整库，否则召回无意义	与索引同一实例/同一模型	禁止 add 用 A、search 用 B
k	int，search，常默认 4	相似度检索返回几条	同 Retriever 的 k：噪声 vs 漏召回	3～5	与 as_retriever 的 k 对齐
collection_name	str，Chroma 等	逻辑隔离的集合名	写错集合等于搜空库	单应用单集合	多租户分 collection
persist_directory	str，Chroma 等	索引落盘目录	不设则进程结束数据丢	./data/chroma	生产勿用纯内存
distance_metric	视后端	近邻用余弦还是 L2 等	须与 embedding 是否归一化一致	cosine / l2	归一化向量用 cosine/点积
ids	list[str]，add 时可选	文档主键，供更新/删除	不设则无法精确 delete；重复 id 覆盖	可选	更新删除时必需

---

5. 易踩坑

1. 换 Embeddings 不重建索引：检索结果随机化。
2. add 与 search 用不同 store 实例：内存 store 未共享则 search 为空。
3. 社区包 import 路径变更：v1 部分集成迁 partner 包，以官方文档为准。

---

小结

• VectorStore 统一 add + similarity_search + as_retriever。
• 原型可用 InMemoryVectorStore + HuggingFaceEmbeddings；生产选持久化后端。
• Embeddings 与维度须 全链路一致。
• 具体厂商集成查对应 langchain-* 包文档。

---

参考链接

• Vector stores
• InMemoryVectorStore
• Integrations: vectorstores