您可以将 MongoDB 与 Agno 集成,这是一个用于构建多模态 AI 代理的开源 Python 框架。Agno 提供了两种 MongoDB 集成:
矢量数据库,用于存储代理的知识库,并使用 MongoDB 向量搜索进行检索。
会话和内存数据库,用于在您的 MongoDB 集合中持久保存代理会话、用户记忆、指标和评估运行。
您可以单独使用其中任何一个集成,也可以在同一个代理中同时使用两者。
开始体验
要完成配置 Agno 以使用 MongoDB 的教程,请参阅 MongoDB Agno 集成入门。
安装
Agno 需要 Python 3.9 或更高版本。要安装最新版本的 Agno 和 PyMongo,运行以下命令:
pip install agno pymongo此页上的示例使用 OpenAI 模型,这些模型是 Agno 默认使用的。要安装 OpenAI 客户端库,请运行以下命令:
pip install openai本页面上的 Custom configuration 示例使用 Voyage AI 嵌入。要安装 Voyage AI 客户端库,请运行以下命令:
pip install voyageai环境变量
在运行本页上的示例之前,请设置以下环境变量:
连接字符串:将
MONGODB_URI设置为您的 MongoDB 部署的连接字符串。模型 API key:将
OPENAI_API_KEY或VOYAGE_API_KEY设置为您的模型提供商的 API key。
向量数据库
MongoVectorDb 类使用 MongoDB 向量搜索实现 Agno 矢量数据库接口。要让代理对您的文档进行语义搜索,请将此类的实例传递给 Agno Knowledge 对象的 vector_db 参数,然后将该对象传递给代理的 knowledge 参数。
重要
MongoDB 类名
Agno 将两个 MongoDB 类都命名为 MongoDb,但从不同的模块导入它们。从 agno.vectordb.mongodb 导入矢量数据库类,从 agno.db.mongo 导入数据库类。为了避免名称冲突,Agno 还将矢量数据库类导出为 MongoVectorDb。本页上的示例使用了该别名。
选择 Basic initialization 标签页以查看最小配置示例,或选择 Custom configuration 标签页以查看如何使用自定义设置配置集成。
要初始化矢量数据库,请指定存储嵌入的集合和您的 MongoDB 连接字符串。以下示例创建了一个知识库,添加了一个文档,并允许代理访问该数据:
import osfrom agno.agent import Agentfrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.mongodb import MongoVectorDb
vector_db = MongoVectorDb( collection_name="agent_knowledge", db_url=os.environ["MONGODB_URI"], database="agno",)
knowledge = Knowledge(vector_db=vector_db)knowledge.insert( name="Recipes", url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",)
agent = Agent(knowledge=knowledge, search_knowledge=True)以下示例启用了混合搜索,使用 Voyage AI 生成嵌入(而不是 OpenAI 默认嵌入),并指定了 MongoDB Vector Search 索引名称:
import osfrom agno.agent import Agentfrom agno.knowledge.embedder.voyageai import VoyageAIEmbedderfrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.mongodb import MongoVectorDbfrom agno.vectordb.search import SearchType
embedder = VoyageAIEmbedder( id="voyage-4-large", dimensions=1024, api_key=os.environ["VOYAGE_API_KEY"], request_params={"output_dimension": 1024},)
vector_db = MongoVectorDb( collection_name="agent_knowledge", db_url=os.environ["MONGODB_URI"], database="agno", embedder=embedder, search_type=SearchType.hybrid, hybrid_vector_weight=0.7, hybrid_keyword_weight=0.3, search_index_name="agno_vector_index",)
knowledge = Knowledge(vector_db=vector_db)agent = Agent(knowledge=knowledge, search_knowledge=True)如果您指定了嵌入器,Agno 会在创建 MongoDB 向量搜索 索引时使用该嵌入器生成的维度数量。request_params 字典将特定于提供商的关键字参数传递给嵌入调用。对于 Voyage AI,output_dimension 控制支持可变维度的模型返回的向量大小。
当您创建一个 Knowledge 对象时,Agno 会验证集合是否已经存在。如果没有这样,Agno 将创建集合和 MongoDB 向量搜索索引。如果集合存在,Agno 不会检查索引是否存在,即使您单独删除了它。
创建索引后,Agno 等待直到索引出现在集合中。但是,它不验证索引状态,因此索引在完成构建期间,紧随其后运行的查询可能会返回空结果。
矢量数据库方法
当您向知识库添加内容或代理搜索知识库时,Knowledge 类会调用以下方法。仅当您在 Knowledge 对象之外管理文档时,才直接调用这些方法。
为了将写入或搜索操作限制为单个用户的文档,请向操作方法传递 user_id 值。
方法 | 说明 |
|---|---|
| 嵌入 |
| 将 |
| 替换共享 |
| 从集合中删除每个文档,但保留集合及其 MongoDB 向量搜索索引。 |
| 删除具有指定 |
| 删除具有指定 |
| 删除 |
| 删除您的集合及其 MongoDB 向量搜索索引。 |
| 如果您的集合存在,则返回 |
| 返回集合中的文档数量。 |
提示
异步方法
上表中描述的以下每种方法都有一个对应的异步方法:
search():使用async_search()insert():使用async_insert()upsert():使用async_upsert()drop():使用async_drop()exists():使用async_exists()
会话和内存数据库
agno.db.mongo 模块中的 MongoDb 类实现了 Agno 数据库接口。要将代理的会话、用户记忆、指标和评估运行持久化到 MongoDB 中,请将此类的一个实例传递给 db、Agent、Team 或 Workflow 对象的 参数。
选择 Basic initialization 标签页以查看最小配置示例,或选择 Custom configuration 标签页以查看如何使用自定义设置配置集成。
要初始化数据库,请指定 MongoDB 连接字符串。以下示例创建一个代理,该代理将其会话历史存储在 MongoDB 中,并将该历史包含在模型上下文中:
import osfrom agno.agent import Agentfrom agno.db.mongo import MongoDb
db = MongoDb(db_url=os.environ["MONGODB_URI"])
agent = Agent(db=db, add_history_to_context=True)以下示例指定了数据库名称以及存储会话、记忆和指标的集合名称:
import osfrom agno.agent import Agentfrom agno.db.mongo import MongoDb
db = MongoDb( db_url=os.environ["MONGODB_URI"], db_name="agno_prod", session_collection="agent_sessions", memory_collection="agent_memories", metrics_collection="agent_metrics",)
agent = Agent(db=db, add_history_to_context=True)Agno 会在首次写入时创建您配置的每个集合。
当您的代理运行时,Agno 会自动读取本节中描述的会话、内存和指标集合,并向其写入数据。Agno 会在首次需要时创建每个集合。您还可以直接在 MongoDb 实例上调用方法,例如:
upsert_session()以及get_sessions()读取和写入会话。upsert_user_memory()写入单个用户内存。get_metrics()读取聚合的使用指标。upsert_sessions()upsert_memories()以及在单个操作中写入多条记录,例如将现有会话历史记录迁移到 MongoDB 时。close()释放客户端连接。在应用程序关闭时调用此方法。
搜索索引
当 Agno 首次创建您的向量集合时,它也会在集合上创建一个 MongoDB 向量搜索索引。索引名称是 search_index_name 参数的值,默认为 vector_index_1。您也可以手动创建或检查此索引。要了解更多信息,请参阅 创建 MongoDB 向量搜索索引。
该索引使用以下定义,其中 numDimensions 匹配您的嵌入器生成的维度数量,similarity 匹配您的 distance_metric 值:
{ "fields": [ { "type": "vector", "path": "embedding", "numDimensions": 1536, "similarity": "cosine" }, { "type": "filter", "path": "user_id" } ]}Agno 将 user_id 字段索引为过滤器字段,以便将搜索范围限定为单个最终用户的文档。
混合搜索不需要 MongoDB Search 索引。Agno 将其关键字搜索作为 content 字段上的正则表达式查询运行,然后使用倒数排名融合将这些结果与 MongoDB 向量搜索结果相结合。
其他资源
要了解有关将 Agno 与 MongoDB 结合使用的更多信息,请参阅以下资源:
Agno Github 存储库