openJiuwen agent-core 向量存储指南:VectorStore 抽象接口、ChromaDB 与 Milvus 双实现及工厂函数解析

原创2026-10-11 12:23:241,894 阅读
文章标签:人工智能大模型AI Agent工具调用工作流编排提示工程

openJiuwen agent-core 向量存储指南:VectorStore 抽象接口、ChromaDB 与 Milvus 双实现及工厂函数解析

openjiuwen.core.retrieval.vector_store 是 openJiuwen agent-core 中负责向量存储与检索的模块,它通过统一的抽象基类 VectorStore 屏蔽不同向量数据库的差异,并内置 ChromaDB(本地持久化)与 Milvus(分布式服务)两套生产级实现,以及一个按配置动态创建实例的工厂函数。阅读本文后,你将掌握该模块的完整接口契约(增删查、向量/稀疏/混合三类检索、集合管理)、两种后端各自的能力边界与底层实现原理,并能够基于 VectorStoreConfig 用几行代码接入任意支持的向量数据库,将其嵌入 Agent 的检索增强(RAG)链路。

模块总览

该模块位于 openjiuwen/core/retrieval/vector_store,对外暴露三类核心构件:

构件 类型 说明 详细 API
VectorStore 抽象基类 向量存储的统一接口契约,定义创建客户端、写入、检索、删除、集合管理等全部能力 base.md
ChromaVectorStore 实现类 ChromaDB 向量存储实现,支持向量搜索、稀疏搜索(文本匹配)与混合搜索(RRF 融合) chroma_store.md
MilvusVectorStore 实现类 Milvus 向量存储实现,支持向量搜索、稀疏搜索(BM25)与混合搜索(原生混合 + RRF 排序) milvus_store.md
create_vector_store 工厂函数 根据 VectorStoreConfig 的 store_provider 字段动态创建对应向量存储实例 store.md

从源码结构看,该模块同时提供了第三种实现 PGVectorStore(位于 openjiuwen/core/retrieval/vector_store/pg_store.py),因此 create_vector_store 工厂实际可以路由到 Milvus、Chroma、PGVector 三种后端。

VectorStore:统一抽象基类

VectorStore 定义在 openjiuwen/core/retrieval/vector_store/base.py(class VectorStore(ABC)),继承自 Python 标准库 abc.ABC,用 @abstractmethod 声明了一组必须由具体实现补齐的接口。任何新的向量数据库接入,只要实现这套方法,就能无缝融入上层检索框架。

静态抽象方法:create_client

create_client(database_name: str, path_or_uri: str, token: str = "", **kwargs: Any) -> Any

创建向量数据库客户端并确保数据库存在。参数含义:

  • database_name(str):数据库名称;为空时使用各数据库默认库(Chroma 的 DEFAULT_DATABASE、Milvus 的 "default")。
  • path_or_uri(str):本地持久化路径(Chroma)或服务 URI(Milvus)。
  • token(str):访问令牌,默认 ""。
  • kwargs(Any):其他额外配置参数(如 Milvus 的连接别名 alias)。

返回向量数据库客户端实例。它同时是 staticmethod 与 abstractmethod,各实现类直接以静态方法形式覆写。

抽象方法:写入与检索

方法 签名(含默认值) 职责
check_vector_field check_vector_field() -> None 检查向量字段配置是否与实际数据库一致,不一致时抛出配置无效错误
add async add(data: dict | List[dict], batch_size: int | None = 128, **kwargs) -> None 添加向量数据;data 可为单个字典或字典列表,batch_size 默认 128,传 None 或非正数时回退到 128
search async search(query_vector: List[float], top_k: int = 5, filters: Optional[dict | QueryExpr] = None, **kwargs) -> List[SearchResult] 向量搜索(稠密向量相似度检索),返回 SearchResult 列表
sparse_search async sparse_search(query_text: str, top_k: int = 5, filters: Optional[dict | QueryExpr] = None, **kwargs) -> List[SearchResult] 稀疏搜索(BM25 / 文本匹配)
hybrid_search async hybrid_search(query_text: str, query_vector: Optional[List[float]] = None, top_k: int = 5, alpha: float = 0.5, filters: Optional[dict | QueryExpr] = None, **kwargs) -> List[SearchResult] 混合搜索(稀疏检索 + 向量检索);alpha 为混合权重,0 = 纯稀疏检索,1 = 纯向量检索,0.5 = 平衡
delete async delete(ids: Optional[List[str]] = None, filter_expr: str | QueryExpr | None = None, **kwargs) -> bool 按 ID 列表或过滤表达式删除向量,成功返回 True
table_exists async table_exists(table_name: str) -> bool 检查集合是否存在于当前数据库
delete_table async delete_table(table_name: str) -> None 从当前数据库删除指定集合

几个关键设计点:

  1. filters 支持两种形态:既可传普通 dict(如 {"category": "tech"}),也可传 QueryExpr 表达式对象。关于 QueryExpr 支持的比较/逻辑运算符与各数据库方言转换(to_expr("chroma")、to_expr("milvus") 等),可参考 QueryExpr 文档。
  2. 检索结果统一为 SearchResult:定义在 openjiuwen/core/retrieval/common/retrieval_result.py,包含 id(结果 ID)、text(文本内容)、score(相关度分数)、metadata(元数据字典)四个字段;内部融合阶段还会用到携带 doc_id、chunk_id 的 RetrievalResult 模型。
  3. 配置一致性自检:基类通过 _check_configs_matching(configured, actual) 静态方法比较「配置的字段参数」与「数据库中实际索引参数」,支持字符串大小写不敏感比较以及数值近似比较(isclose,相对容差 1e-2、绝对容差 1e-3),不一致时抛出 RETRIEVAL_KB_DATABASE_CONFIG_INVALID 错误,其中 efSearchFactor 字段会被跳过(它在不同后端有换算差异)。这从源码层面保证了「建库时的索引配置」与「实际库」始终一致。

VectorStoreConfig 与 StoreType:如何描述一个向量存储

create_vector_store 与各实现类的核心输入是 VectorStoreConfig,定义在 openjiuwen/core/retrieval/common/config.py,基于 Pydantic BaseModel:

class VectorStoreConfig(BaseModel):
    store_provider: StoreType = Field(..., description="Vector store provider identification")
    database_name: str = Field(default="", pattern=r"^[A-Za-z0-9_]*$", description="Database name")
    collection_name: str = Field(..., description="Collection name")
    distance_metric: Literal["cosine", "euclidean", "dot"] = Field(default="cosine", description="Distance metric")

字段含义与约束:

  • store_provider(必填):后端提供商标识,取值为 StoreType 枚举的成员。
  • database_name(可选,默认 ""):数据库名,仅允许 [A-Za-z0-9_] 字符;为空时使用后端默认数据库。
  • collection_name(必填):集合(Collection)名称。
  • distance_metric(可选,默认 "cosine"):距离度量,取值限定 cosine、euclidean、dot 三者之一。

StoreType 是一个字符串枚举:

class StoreType(str, Enum):
    Milvus = "milvus"
    Chroma = "chroma"
    PGVector = "pgvector"

注意实现中的度量映射:Chroma 侧将 dot 替换为 ip、euclidean 替换为 l2(chroma_store.py);Milvus 侧做同样替换后还会转为大写(COSINE / L2 / IP,见 milvus_store.py),因此在传入 distance_metric 时统一使用配置层的三种取值即可,无需关心后端方言。

create_vector_store:按配置动态创建实例的工厂

工厂函数 create_vector_store 定义在 openjiuwen/core/retrieval/vector_store/store.py:

create_vector_store(config: VectorStoreConfig, **kwargs) -> VectorStore

其路由逻辑是:读取 config.store_provider,命中 StoreType.Milvus 返回 MilvusVectorStore(config=config, **kwargs),命中 StoreType.Chroma 返回 ChromaVectorStore(...),命中 StoreType.PGVector 返回 PGVectorStore(...);否则抛出 BaseError(错误码 RETRIEVAL_VECTOR_STORE_PROVIDER_INVALID),错误信息中会列出全部可用提供商。值得注意的实现细节:

  • 各实现类采用函数内延迟导入,只有真正用到某个后端时才 import 对应模块,避免强制引入所有向量数据库依赖;
  • kwargs 会原样透传给具体构造函数,因此后端特有的参数(milvus_uri、milvus_token、chroma_path、pg_uri 等)直接通过工厂函数传入即可。

官方文档(store.md)给出的完整三种用法:

>>> from openjiuwen.core.retrieval.common.config import VectorStoreConfig, StoreType
>>> from openjiuwen.core.retrieval.vector_store.store import create_vector_store
>>>
>>> # 创建 Milvus 向量存储
>>> config = VectorStoreConfig(
...     store_provider=StoreType.Milvus,
...     collection_name="my_collection",
...     distance_metric="cosine",
... )
>>> store = create_vector_store(config, milvus_uri="http://localhost:19530")
>>>
>>> # 创建 ChromaDB 向量存储
>>> config = VectorStoreConfig(
...     store_provider=StoreType.Chroma,
...     collection_name="my_collection",
... )
>>> store = create_vector_store(config, chroma_path="/tmp/chroma_data")
>>>
>>> # 创建 PGVector 存储
>>> config = VectorStoreConfig(
...     store_provider=StoreType.PGVector,
...     collection_name="my_collection",
... )
>>> store = create_vector_store(config, pg_uri="postgresql+asyncpg://user:pass@localhost/db")

借助工厂函数,上层业务(如知识库、检索器)只需持有 VectorStoreConfig,即可在三种后端之间平滑切换,无需改动调用代码。

ChromaVectorStore:本地持久化的 ChromaDB 实现

ChromaVectorStore 定义在 openjiuwen/core/retrieval/vector_store/chroma_store.py,基于 chromadb.PersistentClient 提供持久化存储,适合单机、低运维成本的场景。仓库提供了可直接运行的示例 chroma_query_expr.py(演示 QueryExpr 在 ChromaDB 上的 eq/ne/gt/gte/lt/lte/in_list 等过滤组合)。

构造函数与字段约定

ChromaVectorStore(config: VectorStoreConfig, chroma_path: str, text_field: str = "content",
                  vector_field: str | ChromaVectorField = "embedding",
                  sparse_vector_field: str = "sparse_vector",
                  metadata_field: str = "metadata",
                  doc_id_field: str = "document_id", **kwargs: Any)
  • config(VectorStoreConfig):向量存储配置,其中 collection_name、distance_metric 等直接决定集合行为。
  • chroma_path(str,必需):ChromaDB 持久化路径。源码中会先校验其非空,否则抛出 RETRIEVAL_VECTOR_STORE_PATH_NOT_FOUND。
  • text_field(str,默认 "content"):文本字段名。
  • vector_field(str 或 ChromaVectorField,默认 "embedding"):向量字段;传入字符串时内部会用该名字构造默认配置的 ChromaVectorField。ChromaVectorField 的详细配置项(HNSW 参数等)见 ChromaVectorField 文档。
  • sparse_vector_field(str,默认 "sparse_vector"):稀疏向量字段名。由于 ChromaDB 不原生支持稀疏向量,该字段会被序列化为 JSON 存储在元数据中。
  • metadata_field(str,默认 "metadata"):元数据字段名。
  • doc_id_field(str,默认 "document_id"):文档 ID 字段名。

核心属性

属性 类型 说明
client chromadb.PersistentClient 获取 ChromaDB 持久化客户端
collection chromadb.Collection 获取当前集合实例
distance_metric str 原始距离度量字符串(已做过 dot→ip、euclidean→l2 映射)

关键能力与底层实现

  • 写入(add):支持单条/批量写入,按 batch_size 分批落库,每处理 100 条记录一次日志;单条数据无 embedding 时会告警跳过。写入前会把元数据、document_id、chunk_id 等合并进 metadata,稀疏向量则 json.dumps 后存入 metadata。
  • 向量搜索(search):通过 collection.query(query_embeddings=[...], n_results=top_k) 执行。过滤条件处理上,普通 dict 会经 _as_chroma_where 转换为 Chroma 的 where 语法(多条件自动包成 $and),QueryExpr 则通过 to_expr("chroma") 转换。返回的距离会按度量类型换算为相似度分数:l2 用 convert_l2_squared、cosine 用 convert_cosine_distance(Chroma 的余弦距离范围 0~2,相似度 = (2.0 - distance) / 2.0)、ip 用 convert_ip_distance。
  • 稀疏搜索(sparse_search):ChromaDB 不原生支持 BM25,实现上使用 collection.query(query_texts=[...]) 的文本查询(基于 TF-IDF)作为替代,并按距离阈值换算分数;失败时返回空列表并告警。
  • 混合搜索(hybrid_search):并发执行向量搜索与文本搜索(各取 top_k * 2),随后调用 rrf_fusion(..., k=60) 进行倒数排名融合(Reciprocal Rank Fusion),再截取前 top_k 返回。融合算法定义在 openjiuwen/core/retrieval/utils/fusion.py:以文本内容为唯一标识,对每条结果累加 1 / (k + rank) 作为融合分数,最后按分数降序输出——这意味着同时被两种检索命中的文档会获得明显更高的排名。
  • 删除(delete):支持按 ids 列表删除;filter_expr 仅接受 QueryExpr(会转成 to_expr("chroma")),不接受字符串过滤表达式(传入字符串会告警并返回 False)。
  • 集合管理:table_exists 通过遍历 client.list_collections() 判断;delete_table 直接调用 client.delete_collection(name)。
  • 关闭(close):ChromaDB 持久化客户端通常无需显式关闭,方法内部为兼容占位。

MilvusVectorStore:分布式 Milvus 实现

MilvusVectorStore 定义在 openjiuwen/core/retrieval/vector_store/milvus_store.py,基于 pymilvus.MilvusClient 接入 Milvus 服务,具备真正的 BM25 全文检索与原生混合搜索能力,适合海量向量与高并发检索场景。仓库配套示例 milvus_query_expr.py。

构造函数与字段约定

MilvusVectorStore(config: VectorStoreConfig, milvus_uri: str, milvus_token: Optional[str] = None,
                  text_field: str = "content",
                  vector_field: str | MilvusVectorField = "embedding",
                  sparse_vector_field: str = "sparse_vector",
                  metadata_field: str = "metadata",
                  doc_id_field: str = "document_id", **kwargs: Any)
  • config(VectorStoreConfig):向量存储配置。
  • milvus_uri(str):Milvus 服务 URI,如 http://localhost:19530。
  • milvus_token(str,可选,默认 None):Milvus 访问令牌。
  • text_field(str,默认 "content"):文本字段名。
  • vector_field(str 或 MilvusVectorField,默认 "embedding"):向量字段;传入字符串时内部构造 MilvusAUTO(自动索引)。MilvusVectorField 的完整配置选项(如 MilvusHNSW、MilvusIVF 等索引类型及其参数)见 MilvusVectorField 文档。
  • sparse_vector_field(str,默认 "sparse_vector"):稀疏向量字段名,Milvus 中作为独立的稀疏向量列存在(非元数据)。
  • metadata_field(str,默认 "metadata")、doc_id_field(str,默认 "document_id"):同上。
  • 另支持 milvus_alias 可选参数,指定连接别名;不传时由 create_milvus_alias 根据 uri/token 自动生成。

核心属性

属性 类型 说明
client MilvusClient 获取 Milvus 客户端
distance_metric str 原始距离度量字符串(已转为 COSINE / L2 / IP 大写形式)

关键能力与底层实现

  • 客户端与库管理(create_client):创建 MilvusClient(uri=..., token=...);若指定了非 "default" 的 database_name,会先 list_databases() 检查、不存在则 create_database,再 use_database 切换,保证目标库存在。
  • 写入(add):先确保集合已 Loaded,按 batch_size 分批调用 client.insert,结束后调用 client.flush(collection_name) 落盘,保证查询能立刻读到刚写入的数据。
  • 向量搜索(search):调用 client.search,anns_field 为向量字段,search_params 携带 metric_type 与索引参数(含 get_search_params 对 efSearchFactor 的动态换算:ef = round(top_k * efSearchFactor))。过滤条件构造上,普通 dict 会被拼接成 key == value 并以 && 连接的布尔表达式,字符串值经 QueryExpr.sanitize_str 转义;QueryExpr 则通过 to_expr("milvus") 生成原生表达式。
  • 稀疏搜索(sparse_search):直接使用 Milvus 原生 BM25 全文检索——client.search 时 anns_field 指向稀疏向量字段、search_params={"metric_type": "BM25"},查询文本直接作为输入(由 BM25 函数完成分词),这是与 Chroma 文本匹配实现最大的能力差异。
  • 混合搜索(hybrid_search):优先走 Milvus 原生混合搜索——分别构造稠密 AnnSearchRequest(向量字段 + metric_type)与稀疏 AnnSearchRequest(稀疏字段 + BM25),调用 client.hybrid_search(..., ranker=RRFRanker(k=60)),由 Milvus 服务端完成 RRF 排序。若原生混合搜索抛错,则自动降级为「分别执行向量搜索与 BM25 搜索,再用本地 rrf_fusion(k=60) 融合」的兜底路径(_hybrid_search_fallback),保证功能可用性。
  • 删除(delete):支持 ids 与 filter_expr(字符串或 QueryExpr);成功后 flush,并通过 delete_count > 0 判断是否真有数据被删。
  • 集合管理:table_exists / delete_table 对应 Milvus 的 has_collection / drop_collection 语义;close(release_collection: bool = False) 关闭时可选释放处于 Loaded 状态的集合(release_collection=True 时释放)。
  • 配置一致性检查(check_vector_field):通过 describe_index 读取实际索引,校验索引类型与配置的 index_type/variant 是否匹配(如 HNSW 的 HNSW_ 前缀),并复用基类的 _check_configs_matching 做参数级比对;若库中根本不存在向量字段,会抛出 RETRIEVAL_KB_DATABASE_CONFIG_INVALID,并提示可以调用 delete_collection 重建集合。

双实现对比与选型建议

维度 ChromaVectorStore MilvusVectorStore
部署形态 本地持久化(chroma_path),无需独立服务 独立服务(milvus_uri),可集群化
稀疏检索 文本匹配(TF-IDF,作为 BM25 替代) 原生 BM25 全文检索
混合检索 本地并发检索 + rrf_fusion(k=60) 服务端原生混合搜索 + RRFRanker(k=60),失败自动降级本地融合
过滤条件 dict 自动转 $and where 语法;QueryExpr 转 chroma 方言 dict 拼接布尔表达式;QueryExpr 转 milvus 方言
删除 仅支持 ids 或 QueryExpr 支持 ids 或字符串/QueryExpr 过滤
适用场景 单机、原型验证、轻量 RAG 大规模向量、多实例、高并发生产检索

从实现层面看,两者都实现了同一套 VectorStore 接口,因此上层(知识库、Retriever)完全无感知;差异主要集中在稀疏检索的检索质量与混合搜索的执行位置。若对关键词精确检索(如专有名词、代码标识符)要求高,Milvus 的原生 BM25 更合适;若追求零运维、本地化部署,Chroma 足以支撑中小规模检索。

快速接入示例

结合 chroma_query_expr.py 中的数据形态(每条记录含 id、content、embedding、metadata),一个最小可用链路如下:

import asyncio
from openjiuwen.core.retrieval.common.config import VectorStoreConfig, StoreType
from openjiuwen.core.retrieval.vector_store.store import create_vector_store

async def main():
    config = VectorStoreConfig(
        store_provider=StoreType.Chroma,
        collection_name="my_collection",
        distance_metric="cosine",
    )
    store = create_vector_store(config, chroma_path="/tmp/chroma_data")

    # 写入
    await store.add({
        "id": "doc_1",
        "content": "openJiuwen agent-core provides retrieval SDK",
        "embedding": [0.1, 0.2, 0.3, ...],  # 实际为模型产出的稠密向量
        "metadata": {"category": "tech", "document_id": "doc_1"},
    })

    # 向量检索 + 元数据过滤
    results = await store.search([0.1, 0.2, 0.3, ...], top_k=5,
                                 filters={"category": "tech"})
    # 稀疏检索
    sparse = await store.sparse_search("retrieval SDK", top_k=5)
    # 混合检索
    hybrid = await store.hybrid_search("retrieval SDK", query_vector=[0.1, 0.2, 0.3, ...],
                                       top_k=5, alpha=0.5)
    for r in hybrid:
        print(r.id, r.text, r.score, r.metadata)

    await store.delete(ids=["doc_1"])
    store.close()

asyncio.run(main())

切换后端时只需改 store_provider 与对应连接参数(如 StoreType.Milvus + milvus_uri),其余调用代码保持不变,这正是本模块抽象设计带来的核心收益。

延伸阅读

登录后查看全文
agent-core