ノート:

請求書解決のためのマルチエージェント通信プロトコル・サーバーを使用したAIエージェントの構築

はじめに

流通業者、業界、小売チェーンなど、大量の製品を扱う企業は、多くの場合、不正確、不完全または多様なテキスト記述に基づいて製品を特定するという課題に直面しています。データが手動で入力される環境では、入力ミス、略語および商号が異なるため、エンタープライズ・リソース・プランニング(ERP)、顧客関係管理(CRM)およびeコマース・プラットフォームなどのシステムでアイテムを正しく識別することが困難になる場合があります。

このシナリオでは、次のことが可能なツールが一般的に必要になります。

このチュートリアルでは、顧客からの返品請求書の不整合の解決に特化したAIエージェントを作成する方法を学習します。エージェントは、ベクトル検索および請求書取得ツールを提供するMCPサーバーと対話できるため、エージェントは、顧客から提供された情報に基づいて会社の元の売掛金請求書を自動的に検索できます。

MCPサーバー(モデル・コンテキスト・プロトコル)は、メッセージおよびツールの標準化されたプロトコルを介してインテリジェント・エージェントと外部サービス間の通信を仲介するソフトウェア・コンポーネントです。これは、言語モデル(LLM)と既存のAPIの間のブリッジとして機能し、AIエージェントは、レガシー・システムの特定の機能に書き換えたり、直接適応したりすることなくアクセスできます。

使用方法

MCPサーバー:

レガシー・アプリケーションでの使用

レガシー・アプリケーションは、多くの場合、データベース、ファイルまたは内部APIを介して機能を提供します。MCPサーバーでは、次のことができます:

利点

このエージェントは、Oracle Cloud Infrastructure(OCI)生成AI言語モデルに基づいており、MCPサーバーによって管理される動的に宣言されたツールと統合されます。

次の2つのコンポーネント統合により、Oracle LLMに基づくエージェントが有効になります。

このモジュール設計により、請求書以外のドメインへのシステムの再利用性と容易な進化が可能になります。

目的

前提条件

requirements.txtを次のようにインストールします。

pip install -r requirements.txt

タスク1: Oracle Database 23aiの作成(Always Free)

このタスクでは、Oracle Database 23aiをAlways Freeモードでプロビジョニングする方法を学習します。このバージョンは、追加コストなしで開発、テスト、学習に最適なフルマネージド環境を提供します。

  1. OCIコンソールにログインし、「Oracle Database」、「Autonomous Database」に移動して、「Autonomous Databaseインスタンスの作成」をクリックします。

  2. 次の情報を入力します

    • データベース名:インスタンスの識別名を入力します。
    • ワークロード・タイプ:必要に応じて、「データ・ウェアハウス」または「トランザクション処理」を選択します。
    • コンパートメント:リソースを編成する適切なコンパートメントを選択します。

  3. 「Always Free」を選択して、インスタンスが無償でプロビジョニングされていることを確認します。

  4. データベースへのアクセスに使用されるADMINユーザーのセキュアなパスワードを作成します。

  5. 設定を確認し、「Autonomous Databaseの作成」をクリックします。インスタンスがプロビジョニングされ、使用可能になるまで数分待ちます。

タスク2: Autonomous Database表作成スクリプトの実行

ユース・ケースに合わせてデータベースを準備します。ここからSQLスクリプトをダウンロードして実行します: script.sql。このスクリプトは、請求書をAIエージェントと照合するシナリオ用に3つの重要な表(PRODUCTS、INVOICEおよびITEM_INVOICE)を作成します。

  1. OCIコンソールに移動し、「Oracle Database」、「Autonomous Database」に移動して、新しく作成されたインスタンスの名前をクリックします。

  2. 「データベース・アクション」および「SQL」をクリックして、ブラウザでSQLコンソールを開きます。

  3. script.sqlファイルをダウンロードしてローカルで開き、すべての内容をSQLコンソールエディタに貼り付けます。

  4. 「実行」をクリックするか、[Ctrl]を押しながら[Enter]を押します。コマンドが正常に実行されたことを確認するまで待ちます。

  5. 次のコマンドを実行して、表が作成されたことを確認します。

    SELECT table_name FROM user_tables;

タスク3: 表へのサンプル・データの挿入

AIエージェントの適用の実際のシナリオをシミュレートするダミー・データを挿入します。次の2つのSQLスクリプトを使用します。

このデータは、返品請求書の不整合を解決するためにAIエージェントによって使用されます。

  1. OCIコンソールに移動し、「Oracle Database」、「Autonomous Database」に移動して、新しく作成されたインスタンスの名前をクリックします。

  2. 「データベース・アクション」および「SQL」をクリックして、ブラウザでSQLコンソールを開きます。

  3. insert_products_books.sqlファイルの内容をダウンロードして開き、SQLエディタに貼り付けます。

  4. 「実行」をクリックするか、[Ctrl]を押しながら[Enter]を押します。

  5. ここで、invoice_data_insert.sqlファイルの内容をダウンロードして開き、エディタに貼り付けます。

  6. 「実行」をクリックするか、[Ctrl]を押しながら[Enter]を押します。

  7. 次のコマンドを実行してデータをチェックします。

    SELECT * FROM PRODUCTS;
SELECT * FROM INVOICE;
SELECT * FROM ITEM_INVOICE;

タスク4: データベースでの拡張検索機能の作成およびコンパイル

fn_advanced_searchというPL/SQLファンクションを作成します。このファンクションは、製品摘要のキーワードのインテリジェント検索を実行します。この関数は、resolve_eanツールの一部としてAIエージェントによって使用され、返品ノートで顧客から提供された説明に基づいて最も近いEANコードを検索できます。

この関数は何をしますか。

次の手順に従います。

  1. 完全なsimilarity_search.sqlスクリプトをコピーして、自律型データベースのSQLコンソールに貼り付けます。

    次のものが含まれます。

    • products表の作成(まだ実行されていない場合)。
    • テキスト索引の作成
    • product_resultおよびproduct_result_tabと入力します。
    • fn_advanced_searchファンクション。
    • オプション・テスト。

  2. スクリプト全体を実行します。結果は、Function createdおよびType createdである必要があります。

  3. 次の問合せを実行して、シミュレートされた説明で関数をテストします。

    SELECT *
FROM TABLE(fn_advanced_search('harry poter askaban'))
ORDER BY similarity DESC;

タスク5: AIによるセマンティック検索のための製品のベクトル化

このタスクでは、セマンティック・ベクトルに基づく新しいアプローチを使用して、高度なSQLベースの検索を補完します。これは、埋込み(フレーズの数値表現)を使用して製品記述間の類似性を比較するAIエージェントに特に役立ちます。これは、単語検索や音声検索よりも柔軟かつインテリジェントです。

これを行うには、Pythonスクリプト(process_vector_products.py)を使用します。このスクリプトは、Oracleデータベースに接続し、PRODUCTS表から製品を抽出し、その説明をベクトル(埋込み)に変換し、Oracleデータベース自体を使用してベクトル索引を作成します。

脚本は何をするのか。

ノート:埋込みは、BLOBとして格納されるnp.float32.tobytes()を使用してバイトに変換されます。ベクトルを取得するには、np.frombuffer(blob, dtype=np.float32)を使用します。

この形式では、SQLを使用して、またはnp.dot、cosine_similarityまたはLLMとの統合の操作のためにデータベースからベクトルをロードすることで、将来の類似性検索を実行できます。

このスクリプトは、製品のセマンティック埋込みを生成し、これらのベクトルをOracle 23aiデータベースに書き込みます。主なポイントは次のとおりです。

このスクリプトを実行します。

Oracle Walletをダウンロードして構成する必要があることに注意してください。端末で実行します。

python process_vector_products.py

完了!データベース内の製品はベクトル化されています。

なぜこれが重要なのですか?

ベクトル検索は、記述が主観的、不正確、または自然言語であっても、製品を見つけるのに非常に効果的です。

コードの理解: MCPサーバーを使用したLLMエージェント

このプロジェクトは3つの主要コンポーネントで構成されています。

各コンポーネントの機能を理解し、コードの最も重要な部分を詳細に説明します。

タスク6: MCPエージェントでのモデルおよび埋込みの構成

OCI生成AIサービスを使用して、MCPプロトコルに基づいて、会話型エージェントが使用する言語モデルと埋込みを構成します。

  1. 言語モデル(LLM)を設定します。

    言語モデルは、メッセージの解釈、応答の生成、エージェントのメイン・ブレインとしての役割を果たします。

    • main.pyファイルで構成します。

      from langchain_community.chat_models.oci_generative_ai import ChatOCIGenAI

llm = ChatOCIGenAI(
    model_id="cohere.command-r-08-2024",
    service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
    compartment_id="ocid1.compartment.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    auth_profile="DEFAULT",
    model_kwargs={"temperature": 0.1, "top_p": 0.75, "max_tokens": 2000}
)
      パラメータ 説明
      model_id 生成AIモデルID(例: cohere.command-r-08-2024)
      service_endpoint 生成AIサービスのリージョン・エンドポイント
      compartment_id OCIコンパートメントのOCID
      auth_profile ファイル~/.oci/configに構成されているプロファイルの名前
      model_kwargs 温度、top-pおよび応答サイズ

    • 使用可能なモデルをリストします。

      • OCI CLIの使用:

        oci generative-ai model list --compartment-id <seu_compartment_id>

      • Python SDKの使用:

        from oci.generative_ai import GenerativeAiClient
from oci.config import from_file

config = from_file(profile_name="DEFAULT")
client = GenerativeAiClient(config)

models = client.list_models(compartment_id=config["compartment_id"])
for model in models.data:
    print(model.display_name, model.model_id)

  2. セマンティック検索の埋込みを構成します。

    類似製品またはコンテキスト情報を検索するには、ベクトル埋込みに依存します。

    エージェントでの使用例:

    @mcp.tool()
def search_vectorized_product(description: str) -> dict:
    """
        Searches for a product by description using embeddings.
    """
    return sercher.search_similar_products(description)

    次に示すように、パラメータ(product_search.py)を変更します。

    
class SimilarProductSearch:
    def __init__(
            self,
            top_k=5,
            minimum_distance=1.0,
            model_id="cohere.embed-english-light-v3.0",
            service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
            compartment_id="ocid1.compartment.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
            auth_profile="DEFAULT",
            wallet_path="/WALLET_PATH/Wallet_oradb23ai",
            db_alias="oradb23ai_high",
            username="USER",
            password="Password"
    ):
    パラメータ 説明
    top_k 返された提案数。
    minimum_distance 関連する結果を考慮する最大距離。
    model_id OCIの埋込みモデルのID (cohere.embed-english-light-v3.0など)。
    service_endpoint OCI Generative AIのリージョン・エンドポイント。
    compartment_id コンパートメントOCID。
    auth_profile ~/.oci/configファイルのプロファイル名。
    wallet_path Oracle Database 23aiウォレットへのパス。
    db_alias データベース別名
    username データベース・ユーザー
    password データベースのパスワード。

    MCPサーバーを構成します。

    process_vector_products.pyコードの実行時と同様に、Oracle Database 23aiデータベース用にOracle Walletを構成する必要があります。

    設定に従ってパラメータを変更します。

    import os

# Oracle Wallet settings
WALLET_PATH = "/path/to/Wallet"
DB_ALIAS = "oradb23ai_high"
USERNAME = "admin"
PASSWORD = "..."

# Define the environment variable required for the Oracle client
os.environ["TNS_ADMIN"] = WALLET_PATH

    次に、process_vector_products.pyを実行して、製品をOracle Database 23aiにベクトル化します。

    python process_vector_products.py

これにより、LLMモデルおよび埋込みは、LangGraphおよびLangChainでMCPエージェントが使用できるようになります。

  1. 次のコマンドを使用して、main.pyファイルを実行します。

    python main.py

  2. [ユーザー]プロンプトが表示されたら、次のステートメントを入力します。

    { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "SP"}

    ノート: Harry PotterおよびAzkabanというブックの名前は間違っていますが、エンジンは問題なく見つけることができます。

    img.png

    img_1.png

    サービスが実行されていることに注意してください。

    fetch_vectorized_product
resolve_ean
search_invoices_by_criteria

  3. ここで、次の文を入力します。

    { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26}

    請求書レコードが見つかりません。これは、場所が請求書の検索の鍵となるためです。

    img_2.png

  4. ここで、次の文を入力します。

    { "customer": "Customer 108",  "description": "Harry Poter", "location": "SP"}

    今回は場所を入力しますが、単価は省略します。

    img_3.png

    さらに、請求書が見つかりました。これは、価格が基本的ではないためですが、より断固として格差を埋めるのに役立ちます。

    テストの例を次に示します。

     { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "SP"}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "location": "SP"}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "RJ"}

 { "customer": "Customer 125",  "description": "Harry Potter Chamber", "price": 79.16, "location": "SP"}

 { "customer": "Customer 125",  "description": "Harry Potter Chamber", "price": 79.15, "location": "SP"}

タスク8: フェニックスによる可観測性の表示

ブラウザにhttp://localhost:6006/と入力して、フェニックスとの可観測性を表示します。

img.png

img.png

img.png

確認

その他の学習リソース

docs.oracle.com/learnで他のラボを確認するか、Oracle Learning YouTubeチャネルで無料のラーニング・コンテンツにアクセスしてください。また、education.oracle.com/learning-explorerにアクセスして、Oracle Learning Explorerになります。

製品ドキュメントについては、Oracle Help Centerを参照してください。