openJiuwen agent-core 向量存储指南:VectorStore 抽象接口、ChromaDB 与 Milvus 双实现及工厂函数解析
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 |
从当前数据库删除指定集合 |
几个关键设计点:
filters支持两种形态:既可传普通dict(如{"category": "tech"}),也可传QueryExpr表达式对象。关于QueryExpr支持的比较/逻辑运算符与各数据库方言转换(to_expr("chroma")、to_expr("milvus")等),可参考 QueryExpr 文档。- 检索结果统一为
SearchResult:定义在 openjiuwen/core/retrieval/common/retrieval_result.py,包含id(结果 ID)、text(文本内容)、score(相关度分数)、metadata(元数据字典)四个字段;内部融合阶段还会用到携带doc_id、chunk_id的RetrievalResult模型。 - 配置一致性自检:基类通过
_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),其余调用代码保持不变,这正是本模块抽象设计带来的核心收益。
延伸阅读
- 向量字段配置(HNSW / IVF 等索引参数):chroma_fields.md 与 milvus_fields.md
- 结构化过滤表达式
QueryExpr的运算符与数据库方言:base.md - 检索结果模型
SearchResult/RetrievalResult:retrieval_result.py - 融合算法 RRF 实现:fusion.py
- 完整可运行示例:chroma_query_expr.py 与 milvus_query_expr.py
- 上层检索能力(知识库、索引、重排等):openjiuwen/core/retrieval 目录及其 API 文档