MongoDBと Agno フレームワークの統合

MongoDB は、マルチモーダルAIエージェントを構築するためのオープンソースPythonフレームワークである Agnore と統合できます。 Agno は 2 つのMongoDB統合を提供します。

エージェントの知識ベースを保存し、 MongoDB ベクトル検索で取得するベクトルデータベース。
MongoDBコレクション内のエージェントセッション、ユーザーメモリ、メトリクス、および評価の実行を保持するセッションおよびメモリデータベース。

統合は単独で使用することも、同じエージェントで両方を使用することもできます。

はじめる

MongoDB を使用するように Agno を構成するチュートリアルを完了するには、「 MongoDB Agno 統合を使い始める」を参照してください。

インストール

Agnos にはPython v3.9 以降が必要です。最新の Agno およびPyMongoバージョンをインストールするには、次のコマンドを実行します。

pip install agno pymongo

このページの例では、OpenAI モデルを使用します。このモデルではデフォルトでを使用します。 OpenAIクライアントライブラリをインストールするには、次のコマンドを実行します。

pip install openai

Custom configurationこのページのの例では、投票AI埋め込みを使用しています。 MongoDB AIクライアントライブラリをインストールするには、次のコマンドを実行します。

pip install voyageai

環境変数

このページの例を実行中前に、次の環境変数を設定してください。

接続文字列: MongoDBデプロイの接続文字列に MONGODB_URI を設定します。
モデルAPIキー: モデルプロバイダーのAPIキーに OPENAI_API_KEY または VOYAGE_API_KEY を設定します。

ベクトルデータベース

MongoVectorDbクラスは、 MongoDB ベクトル検索を持つ Agnoベクトルデータベースインターフェースを実装します。ドキュメントに対してエージェントセマンティック検索を実行するには、このクラスのインスタンスを Agno Knowledgeオブジェクトの vector_db パラメーターに渡し、そのオブジェクトをエージェントの knowledge パラメーターに渡します。

重要

MongoDBクラス名

Agnore は両方のMongoDBクラス MongoDb という名前を付けますが、それらは異なるモジュールからインポートします。 agno.vectordb.mongodb からベクトルデータベースクラスをインポートし、agno.db.mongo からデータベースクラスをインポートします。名前の競合を避けるために、Agnore はベクトルデータベースのクラスも MongoVectorDb としてエクスポートします。このページの例では、そのエイリアスを使用します。

Basic initialization最小構成の例を表示するには []タブを選択し、カスタム設定と統合を構成する方法を確認するにはCustom configuration []タブを選択します。

ベクトルデータベースを初期化するには、埋め込みとMongoDB接続文字列を保存するコレクションを指定します。次の例では、知識ベースを作成し、ドキュメントを追加し、エージェントにデータへのアクセス権を付与します。

import os
from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge
from 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)

次の例では、ハイブリッド検索を有効にし、OpenAI のデフォルトであるではなく、Voyage AIを使用して埋め込みを生成し、 MongoDB ベクトル検索インデックス名を指定しています。

import os
from agno.agent import Agent
from agno.knowledge.embedder.voyageai import VoyageAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.mongodb import MongoVectorDb
from 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 辞書はプロバイダー固有のキーワード引数を埋め込み呼び出しに渡します。投票AIの場合、output_dimension は変数次元をサポートするモデルの返されるベクトルのサイズを制御します。

Knowledgeオブジェクトを作成すると、Agnore はコレクションがすでに存在するかどうかを確認します。存在しない場合、Agnore はコレクションとMongoDB ベクトル検索インデックスを作成します。コレクションが存在する場合、インデックスを個別に削除した場合でも、Agnore はインデックスが存在するかどうかを確認しません。

インデックスを作成した後、Agnore はインデックスがコレクションに表示されるまで待機します。ただし、インデックスのステータスは確認されないため、インデックスの作成が完了する間は、その直後に実行されるクエリでは結果が返されません。

ベクトルデータベースパラメーター

これらのパラメーターを使用してベクトルデータベースを構成します。

MongoVectorDbクラスは次のパラメータを受け入れます。

Parameter	必要性	説明
`collection_name`	必須	ドキュメントとその埋め込みを保存するコレクションの名前。
`db_url`	任意	The connection string for your MongoDB deployment. Defaults to `mongodb://localhost:27017/`. To learn more about finding your connection string, see Connect to a Cluster via Client Libraries.
`client`	任意	既存の `MongoClient`インスタンス。このパラメータを指定すると、Agnore は `db_url` を無視します。
`database`	任意	コレクションを保持するデータベースの名前。デフォルトは `agno` です。
`embedder`	任意	Agno がドキュメントとクエリを埋め込むために使用する埋め込みモデル。デフォルトは `OpenAIEmbedder()` です。
`distance_metric`	任意	MongoDB ベクトル検索インデックスが使用する類似度関数。現在、デフォルト値の `Distance.cosine` のみがサポートされています。
`search_type`	任意	取得戦略。 `SearchType.vector` または `SearchType.hybrid` を受け入れます。デフォルトは `SearchType.vector` です。
`hybrid_vector_weight`	任意	ハイブリッド検索がセマンティック結果に適用する重み。デフォルトは `0.5` です。
`hybrid_keyword_weight`	任意	ハイブリッド検索がキーワード結果に適用する重み。デフォルトは `0.5` です。
`hybrid_rank_constant`	任意	ランク統合スコアを計算する前にハイブリッド検索が各ランクに追加する定数。デフォルトは `60` です。
`search_index_name`	任意	コレクションのMongoDB ベクトル検索インデックスの名前。デフォルトは `vector_index_1` です。
`wait_until_index_ready_in_seconds`	任意	Agno がMongoDB ベクトル検索インデックスの作成後、インデックス名がコレクションの検索インデックスに表示されるまで待機するかどうか。このパラメータを正の数に設定すると待機するか、`None` に設定して待機をスキップします。非同期メソッドは、値をタイムアウト（秒単位）として使用します。デフォルトは `3` です。
`wait_after_insert_in_seconds`	任意	Agno がドキュメントを挿入した後に待機する時間（秒単位）。デフォルトは `3` です。
`max_pool_size`	任意	ドライバー接続プール内の最大接続数。デフォルトは `100` です。
`retry_writes`	任意	ドライバーがサポートされている書込み操作を再試行するかどうか。デフォルトは `True` です。
`cosmos_compatibility`	任意	Agno がMongoDB ベクトル検索形式ではなくAzure Cosmos DB for MongoDB vCore形式でインデックスを作成するかどうか。デフォルトは `False` です。
`name`, `description`, `id`	任意	ベクトルデータベースインスタンスの識別メタデータ。 `id` を指定しない場合、Agnore は接続文字列、データベース名、コレクション名からそれを生成します。

ベクトルデータベースメソッド

Knowledgeクラスは、知識ベースにコンテンツを追加するとき、またはエージェントがそれを検索するときに次のメソッドを呼び出します。 Knowledgeオブジェクトの外部でドキュメントを管理する場合にのみ、これらのメソッドを直接呼び出します。

書込み操作または検索操作を1 人のユーザーのドキュメントに制限するには、操作メソッドに user_id 値を渡します。

方式	説明
`search(query, limit, filters, min_score, user_id)`	`query` を埋め込み、最大 `limit` の一致するドキュメントを返します。 `search_type` を `SearchType.hybrid` に設定すると、Agnore はキーワード検索も実行し、2 つの結果セットをマージします。 `filters` パラメータはメタデータフィルターの辞書を受け入れます。代わりに Agno フィルター式のリストを渡すと、 MongoDB統合ではフィルターがサポートされていないため、Agno は警告をログに記録し、フィルターを適用しません。
`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()`	コレクション内のドキュメントの数を返します。

Tip

非同期メソッド

前の表で説明されている次のメソッドには、それぞれに対応する非同期メソッドがあります。

search(): を使用する async_search()
insert(): Use async_insert()
upsert(): Use async_upsert()
drop(): Use async_drop()
exists(): Use async_exists()

セッションとメモリのデータベース

agno.db.mongo モジュールの MongoDbクラスはA Servicesデータベースインターフェースを実装します。 MongoDBでエージェントのセッション、ユーザーメモリ、メトリクス、評価の実行を永続化するには、このクラスのインスタンスを Agent、Team、または Workflowオブジェクトの db パラメータに渡します。

データベースを初期化するには、 MongoDB接続文字列を指定します。次の例では、セッション履歴をMongoDBに保存し、その履歴をモデルコンテキストに含めるエージェントを作成します。

import os
from agno.agent import Agent
from agno.db.mongo import MongoDb
db = MongoDb(db_url=os.environ["MONGODB_URI"])
agent = Agent(db=db, add_history_to_context=True)

次の例では、データベース名と、セッション、メモリ、メトリクスを保存するコレクションの名前を指定します。

import os
from agno.agent import Agent
from 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 は、そのコレクションに初めて書込む、構成する各コレクションを作成します。

Database Parameters

これらのパラメーターを使用して、データベースを構成します。

MongoDbクラスは次のパラメータを受け入れます。

Parameter	必要性	説明
`db_url`	条件付き	MongoDBデプロイの接続文字列。 `db_client` を指定しない場合は必須です。
`db_client`	条件付き	既存の `MongoClient`インスタンス。 `db_url` を指定しない場合は必須です。両方を指定すると、Agnore は `db_url` を無視します。
`db_name`	任意	コレクションを保持するデータベースの名前。デフォルトは `agno` です。
`session_collection`	任意	エージェント、チーム、およびワークフローセッションを保存するコレクションの名前。デフォルトは `agno_sessions` です。
`runs_collection`	任意	実行ごとに 1 つのドキュメントを保存するコレクションの名前。デフォルトは `agno_runs` です。このパラメータを指定せずに `session_collection` を指定すると、Agnore はセッションコレクション名から名前を作成します（`agent_sessions_runs` など）。
`memory_collection`	任意	ユーザーのメモリを保存するコレクションの名前。デフォルトは `agno_memories` です。
`metrics_collection`	任意	集計された使用メトリクスを保存するコレクションの名前。デフォルトは `agno_metrics` です。
`eval_collection`	任意	評価の実行を保存するコレクションの名前。デフォルトは `agno_eval_runs` です。
`knowledge_collection`	任意	知識コンテンツメタデータを保存するコレクションの名前。デフォルトは `agno_knowledge` です。
`traces_collection`, `spans_collection`	任意	トレースと範囲を保存するコレクションの名前。デフォルトは `agno_traces` と `agno_spans` です。
`schedules_collection`, `schedule_runs_collection`	任意	スケジュールとスケジュールの実行を保存するコレクションの名前。デフォルトは `agno_schedules` と `agno_schedule_runs` です。
`learnings_collection`	任意	学習を保存するコレクションの名前。デフォルトは `agno_learnings` です。
`id`	任意	データベースインスタンスの識別子です。このパラメーターを指定しない場合、Agnore は接続文字列とデータベース名からそれを生成します。

エージェントが実行されると、Agnore は自動的にセッション、メモリ、メトリクスのコレクションから読み取りと書込みを行います。 Agno は各コレクションが初めて必要になったときに作成します。次のようなメソッドを MongoDbインスタンスで直接呼び出すこともできます。

upsert_session() および get_sessions() の読み取りおよび書込みセッション。
upsert_user_memory() は、単一のユーザーメモリを書込みます。
get_metrics() 集計された使用状況メトリクスを読み取ります。
upsert_sessions() と upsert_memories() は、既存のセッション履歴をMongoDBに移行する場合など、 1 つの操作で多くのレコードを書込みます。
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ベクトル検索の結果と結合します。

追加リソース

MongoDBで Agnos を使用する方法の詳細については、次のリソースを参照してください。

MongoDB Vector Store の参照を無視する
MongoDB Database の参照を無視する
Aggregation Query ドキュメント
GitHubリポジトリを無視する

戻る

マテリアライズド

はじめる

MongoDBと Agno フレームワークの統合

はじめる

インストール

環境変数

ベクトル データベース

重要

MongoDBクラス名

ベクトルデータベース パラメーター

ベクトルデータベース メソッド

Tip

非同期メソッド

セッションとメモリのデータベース

Database Parameters

検索インデックス

追加リソース

ベクトルデータベース

ベクトルデータベースパラメーター

ベクトルデータベースメソッド