对于 AI 代理:可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

将 MongoDB 与 Agno 框架集成

您可以将 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)

当您创建一个 Knowledge 对象时,Agno 会验证集合是否已经存在。如果没有这样,Agno 将创建集合和 MongoDB 向量搜索索引。如果集合存在,Agno 不会检查索引是否存在,即使您单独删除了它。

创建索引后,Agno 等待直到索引出现在集合中。但是,它不验证索引状态,因此索引在完成构建期间,紧随其后运行的查询可能会返回空结果。

当您向知识库添加内容或代理搜索知识库时,Knowledge 类会调用以下方法。仅当您在 Knowledge 对象之外管理文档时,才直接调用这些方法。

为了将写入或搜索操作限制为单个用户的文档,请向操作方法传递 user_id 值。

方法
说明

search(query, limit, filters, min_score, user_id)

嵌入 query 并返回最多 limit 个匹配的文档。如果将 search_type 设置为 SearchType.hybrid,Agno 还会运行关键字搜索并合并这两个结果集。filters 参数接受一个元数据过滤器字典。如果改为传递 Agno 过滤器表达式列表,Agno 会记录一条警告日志,且不会应用任何过滤器,因为 MongoDB 集成不支持这些表达式。

insert(content_hash, documents, filters, user_id)

将 documents 中的每个文档嵌入并插入到您的集合中。Agno 从文档内容的哈希中派生每个文档的 _id 值。

upsert(content_hash, documents, filters, user_id)

替换共享 content_hash 的文档,然后插入 documents 中的文档。使用此方法更新内容已更改的文档。

delete()

从集合中删除每个文档,但保留集合及其 MongoDB 向量搜索索引。

delete_by_id(id)

删除具有指定 _id 值的文档。

delete_by_name(name)

删除具有指定 name 值的文档。

delete_by_metadata(metadata)

删除 meta_data 字段与指定键值对匹配的文档。

drop()

删除您的集合及其 MongoDB 向量搜索索引。

exists()

如果您的集合存在,则返回 True。

get_count()

返回集合中的文档数量。

提示

异步方法

上表中描述的以下每种方法都有一个对应的异步方法:

  • 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)

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 结合使用的更多信息,请参阅以下资源: