CAMEL 多智能体框架中的 PgVectorStorage基于 PostgreSQL pgvector 的向量存储实战指南【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel导读本文围绕 CAMEL 框架中基于 PostgreSQL pgvector 扩展实现的向量存储组件PgVectorStorageAPI 参考见 docs/reference/camel.storages.vectordb_storages.pgvector.md系统讲解其初始化参数、表结构与 HNSW 索引的自动管理、批量写入、按 ID 删除、三种距离度量下的相似性查询以及状态统计与连接生命周期管理。读完本文你将掌握如何在 CAMEL 的多智能体应用中直接使用 pgvector 承载 RAG 检索、语义缓存等场景下的向量数据并理解每个方法背后的 SQL 实现与相似度换算逻辑。一、PgVectorStorage 在 CAMEL 向量存储生态中的定位CAMEL 的camel.storages模块以抽象基类BaseVectorStorage定义于 camel/storages/vectordb_storages/base.py统一了各类向量数据库的接入契约其核心抽象方法包括add(records)批量保存VectorRecorddelete(ids)按 ID 删除向量query(query)按相似度检索status()返回维度与数量clear()清空存储load()加载云端集合对本地型数据库通常为空操作client属性暴露底层客户端对象在该契约之下camel/storages/vectordb_storages/init.py 同时导出了 Chroma、Qdrant、Milvus、FAISS、Weaviate、TiDB、OceanBase、Surreal 以及本文主角PgVectorStorage等多种实现并在 camel/storages/init.py 中对外统一暴露。PgVectorStorage是其中面向 PostgreSQL 生态的实现——它借助 pgvector 扩展让开发者无需引入独立向量数据库即可在关系型数据库中完成向量检索从而复用 PostgreSQL 成熟的备份、权限与运维体系。二、运行环境与依赖准备PgVectorStorage的构造函数通过dependencies_required(psycopg, pgvector)装饰器实现在 camel/utils/commons.py在实例化时强制校验两个关键依赖缺少任一模块都会抛出ImportError。项目在 pyproject.toml 中对这两个依赖的版本约束为psycopg[binary]3.1.18,4, pgvector0.2.4,0.3,其中psycopg是 PostgreSQL 的 Python 驱动binary 版内置二进制依赖免编译pgvector则是 pgvector 扩展的 Python 适配层用于把List[float]与数据库的vector类型互转。安装方式pip install psycopg[binary]3.1.18,4 pgvector0.2.4,0.3除 Python 依赖外目标 PostgreSQL 实例本身需要启用 pgvector 扩展CREATE EXTENSION IF NOT EXISTS vector;三、初始化五个关键参数PgVectorStorage.__init__的签名如下def __init__( self, vector_dim: int, conn_info: Dict[str, Any], table_name: Optional[str] None, distance: VectorDistance VectorDistance.COSINE, **kwargs: Any ) - None:各参数含义与源码行为见 camel/storages/vectordb_storages/pgvector.py如下表参数类型默认值说明vector_dimint必填向量维度。源码在初始化时即校验vector_dim 0会抛出ValueError(vector_dim must be positive)且后续所有写入与查询的向量长度必须与之严格一致conn_infoDict[str, Any]必填透传给psycopg.connect(**conn_info)的连接参数如host、port、dbname、user、password等table_nameOptional[str]None存储向量的表名。为None时使用默认表名vectorsdistanceVectorDistanceVectorDistance.COSINE相似度距离度量取值来自 camel/types/enums.py 中的VectorDistance枚举**kwargsAny—预留扩展参数VectorDistance枚举提供三种距离度量class VectorDistance(Enum): DOT dot # 点积内积 COSINE cosine # 余弦相似度 EUCLIDEAN euclidean # 欧氏距离初始化过程的内部顺序源码第 68-86 行为建立psycopg.connect连接 → 调用register_vector(self._conn)注册 pgvector 类型适配 → 依次执行_ensure_table()与_ensure_index()自动建表建索引 → 任一环节失败则记录错误日志并向上抛出异常。典型初始化示例from camel.storages import PgVectorStorage from camel.types import VectorDistance storage PgVectorStorage( vector_dim1536, # 与你的 embedding 模型输出维度一致 conn_info{ host: localhost, port: 5432, dbname: camel_db, user: postgres, password: your_password, }, table_nameagent_vectors, distanceVectorDistance.COSINE, )四、表结构与索引的自动管理4.1_ensure_table幂等建表构造函数会自动执行建表逻辑源码第 88-110 行使用psycopg.sql.SQL组合参数化 SQL表名与维度均通过Identifier/Literal安全转义避免 SQL 注入CREATE TABLE IF NOT EXISTS {table} ( id VARCHAR PRIMARY KEY, vector vector({dim}), payload JSONB )可见每张向量表由三列构成id主键字符串类型对应VectorRecord.idvectorpgvector 的vector类型列维度在建表时固化payloadJSONB 类型用于存储任意元数据来源文本、标题、标签等查询时随结果一并返回。4.2_ensure_index自动创建 HNSW 索引建表后紧接着创建近似最近邻搜索索引源码第 112-132 行CREATE INDEX IF NOT EXISTS {table}_vector_idx ON {table} USING hnsw (vector vector_cosine_ops)需要说明的几点索引使用 HNSW分层可导航小世界图算法适合大规模向量的近似检索索引与distance参数存在耦合源码中_ensure_index固定使用vector_cosine_ops算子类因此当前实现更匹配默认的COSINE度量。若你在query阶段改用欧氏或点积度量从源码结构看索引算子类与度量之间可能不完全匹配建议按实际度量手工调整索引或在确定度量后保持配置一致与建表不同索引创建失败仅记录logger.warning而不会中断初始化建表失败则会抛出异常这是因为索引属于性能优化手段其缺失不应阻塞核心写入/查询能力。五、数据写入addadd(records: List[VectorRecord], **kwargs)用于新增或更新向量记录源码第 134-181 行行为要点空列表短路records为空时直接返回不产生任何 SQL 执行维度校验逐条检查len(rec.vector) ! self.vector_dim不一致立即抛出ValueError批量插入将记录组装成(id, vector, payload_json)元组列表payload 为None时写入None否则json.dumps序列化UPSERT 语义使用ON CONFLICT (id) DO UPDATE SET vectorEXCLUDED.vector, payloadEXCLUDED.payload因此重复写入相同id会覆盖旧向量与元数据天然支持增改合一事务管理批量执行executemany后统一commit()失败时rollback()并抛出异常。VectorRecord定义在 camel/storages/vectordb_storages/base.py是一个 Pydantic 模型vector: List[float]必填id缺省时自动生成随机 UUIDpayload: Optional[Dict[str, Any]]可选。写入示例from camel.storages import VectorRecord records [ VectorRecord( iddoc-001, vector[0.1, 0.2, 0.3, 0.4], # 长度必须等于 vector_dim payload{title: CAMEL 简介, source: docs/intro.md}, ), VectorRecord( vector[0.5, 0.6, 0.7, 0.8], # 未指定 id自动生成 UUID ), ] storage.add(records)六、数据删除deletedelete(ids: List[str], **kwargs)按 ID 批量删除源码第 183-204 行使用 PostgreSQL 数组参数化删除同样在空列表时短路DELETE FROM {table} WHERE id ANY(%s)调用方式storage.delete([doc-001, doc-002])删除失败会回滚事务并抛出异常保证数据一致性。七、相似性查询queryquery(query: VectorDBQuery, **kwargs)是检索核心源码第 206-287 行。VectorDBQuery封装了query_vector: List[float]与top_k: int默认 1两个字段。查询前会先校验查询向量维度不一致即抛ValueError。7.1 三种距离度量到 SQL 算子的映射VectorDistancepgvector 算子SQL 排序含义COSINEASC余弦距离越小越相似EUCLIDEAN-ASC欧氏距离越小越相似DOT#ASC负内积#返回负点积值越小越相似生成的查询 SQL 为SELECT id, vector, payload, (vector {metric} %s::vector) AS score FROM {table} ORDER BY score {order} LIMIT %s其中查询向量以参数形式绑定top_k控制返回条数。7.2 距离分数到相似度越高越好的换算数据库返回的是距离分数CAMEL 通过_score_to_similarity源码第 279-287 行统一转换为 0~1 区间的高分即相似方便上层 RAG 管线直接使用度量换算公式说明余弦similarity max(0, min(1, 1 - score))余弦距离 ∈ [0, 2]裁剪到 [0, 1]欧氏similarity 1 / (1 max(0, score))距离为 0 时相似度为 1距离越大越趋近 0点积similarity -score由于score本身就是负内积取负即还原为点积值7.3 返回结果查询返回List[VectorDBQueryResult]每个结果由record: VectorRecord含 id、原始向量、payload与similarity: float组成按相似度从高到低排序。完整查询示例from camel.storages import VectorDBQuery results storage.query( VectorDBQuery(query_vector[0.1, 0.2, 0.3, 0.4], top_k5) ) for r in results: print(r.record.id, r.record.payload, r.similarity)此外基类还提供了便捷方法get_payloads_by_vector(vector, top_k)它内部调用query并只返回非空 payload 列表适合只取元数据的检索场景。八、状态、清理与生命周期管理8.1status查询库内统计status()返回VectorDBStatus对象vector_dim与vector_count两个字段内部执行SELECT COUNT(*) FROM {table}例如status storage.status() print(status.vector_dim, status.vector_count)8.2clear清空全部数据clear()直接执行TRUNCATE TABLE {table}快速清空整张表注意TRUNCATE不可按条件筛选会删除该表全部向量随后提交事务。8.3load接口兼容的空操作load()为空操作源码第 332-337 行注释明确说明对于 PostgreSQL 本地/托管实例无需加载其存在仅是为了满足BaseVectorStorage的接口兼容性——这与面向云端集合的向量库如需要显式加载 collection 的实现形成对照。8.4close与__del__连接回收close()安全关闭底层 psycopg 连接带hasattr与异常防护析构函数__del__调用close()确保对象被销毁时连接自动回收。配合with上下文或显式storage.close()使用更佳。8.5client属性client是只读属性直接返回底层psycopg连接对象便于在需要原生 SQL 操作时透传访问raw_conn storage.client # psycopg.Connection九、与检索器的集成实践PgVectorStorage遵循BaseVectorStorage抽象因此可以直接注入 CAMEL 的VectorRetriever完成Embedding 向量检索的 RAG 闭环。参考 examples/agents/repo_agent.py 中 Qdrant 的接法替换为 pgvector 只需from camel.retrievers import VectorRetriever from camel.embeddings import OpenAIEmbedding from camel.storages import PgVectorStorage storage PgVectorStorage( vector_dim1536, conn_info{host: localhost, dbname: camel_db, user: postgres}, table_namerag_chunks, ) vr VectorRetriever( embedding_modelOpenAIEmbedding(), storagestorage, ) # vr.process(content, top_k3) # 完成内容切分、向量化并检索这样的组合让多智能体应用在保持关系型数据库统一管理的同时获得向量检索能力尤其适合已重度使用 PostgreSQL 的团队。十、测试用例验证仓库在 test/storages/vector_storages/test_pgvector.py 中通过 mock 连接对象对PgVectorStorage的每个方法进行了单测覆盖可作行为契约参考test_pgvector_init验证构造参数透传与register_vector、connect各被调用一次test_pgvector_add验证executemany批量插入被调用且事务提交test_pgvector_query给定返回行(1, [0.1,...], {a: 1}, 0.01)断言结果 id、vector、payload 正确且余弦距离 0.01 被换算为相似度0.99test_pgvector_score_to_similarity参数化验证三种度量的换算余弦1-01.0、余弦1-0.250.75、欧氏1/(11)0.5、点积-(-0.8)0.8test_pgvector_delete/test_pgvector_status/test_pgvector_clear分别验证删除执行、COUNT统计与清空提交test_pgvector_empty_add_delete验证空列表add/delete不产生任何 SQL 执行。结语PgVectorStorage将 pgvector 的能力封装进 CAMEL 统一的BaseVectorStorage抽象中自动建表建索引、UPSERT 批量写入、三种距离度量的一键切换、距离分数到相似度的标准化换算以及完备的连接生命周期管理。对于希望在 PostgreSQL 之上构建多智能体 RAG 检索、语义缓存等能力的开发者它是与现有数据库体系无缝衔接的轻量选择。进一步深入可阅读 camel/storages/vectordb_storages/pgvector.py 源码以及对比 camel/storages/vectordb_storages 目录下其他向量存储实现理解 CAMEL 如何在不同向量数据库之间保持一致的接入体验。【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考