Box AI抽出エージェント (強化) による抽出 (構造化) (Python)

Box AIが公開するインテリジェントな抽出機能により、開発者は、1回のAPIコールでドキュメントから自動的にキー/値ペアを抽出できます。抽出エージェント (強化) は、高度な推論モデルを使用して、複雑な非構造化ドキュメントのコンテンツを、手動によるデータ入力なしで実用的なメタデータに変換するため、請求書、フォーム、契約書などのビジネスドキュメントのドキュメント処理ワークフローが効率化されます。このクイックスタートでは、Box Python SDKを構成し、Box AIを使用して、Boxに保存されている株式購入契約書からデータを抽出する方法を紹介します。

Boxアプリケーションを作成して構成する

任意のBox Platform統合では、最初のステップとして、Boxアプリケーションを作成して構成します。

Box開発者コンソールに移動します。
このクイックスタートでは、アプリケーションの種類としてClient Credentials Grantを使用してアプリを作成します。
アプリが作成されたら、以下のスコープを有効にします。
- Boxに格納されているすべてのファイルとフォルダの読み取り
- Boxに格納されているすべてのファイルとフォルダへの書き込み
- AIを管理する

Boxアプリケーションの新規作成の詳細については、最初のアプリケーションの作成を参照してください。

テストファイルをアップロードする

テンプレートを準備したら、テストするファイルを選択します。このクイックスタートでは、こちらの株式購入契約書のサンプルを使用してください。

テスト用ドキュメントをダウンロードして、Boxアカウントにドラッグアンドドロップします。
ファイルIDを確認するには、Boxでファイルを開いてURLを調べます。パスの最後の部分がファイルIDです。たとえば、次のようなURLがあるとします: https://app.box.com/file/2064123286902 この場合、ファイルIDは2064123286902です。

環境を設定する

抽出を実行するために、開発環境を設定します。このクイックスタートでは、PythonとBox Python SDKバージョン10を使用します。お使いのマシンにPython 3.11以上がインストールされていることを確認してください。

プロジェクト用に新しいディレクトリを作成し、そのディレクトリに移動します。
仮想環境を作成します。
```
python3 -m venv .venv
source .venv/bin/activate
```
Box Python SDKをインストールします。
```
pip install "boxsdk~=10"
```
.envファイルから環境変数を読み込むためにpython-dotenvパッケージをインストールします。
```
pip install python-dotenv
```
プロジェクトディレクトリのルートに.envファイルを作成し、以下の環境変数を追加します。その際、プレースホルダの値を実際のBoxアプリの資格情報と前の手順で確認したIDに置き換えます。
```
 BOX_DEVELOPER_TOKEN=your_box_developer_token

 BOX_METADATA_TEMPLATE_KEY=your_metadata_template_key
 BOX_FILE_ID=your_box_file_id
```

開発者トークンを取得するには、Box開発者コンソールに移動します。アプリを開き、[構成] タブに移動します。

[開発者トークンを生成] をクリックして新しいトークンを作成します。

簡略化するために、このクイックスタートでは、有効期間の短い開発者トークンを使用します。実稼働環境では、開発者トークンではなく、お使いのアプリに設定された方法 (クライアント資格情報許可など) で認証する必要があります。

enhanced-extract.pyファイルを作成する

開発環境の準備ができました。Box AIを使用してドキュメントからデータを抽出するPythonスクリプトを作成できます。

プロジェクトディレクトリのルートにenhanced-extract.pyという名前の新しいファイルを作成し、以下のコードを追加します。

import os

from dotenv import load_dotenv

from box_sdk_gen import (
    AiAgentReference,
    AiAgentReferenceTypeField,
    AiItemBase,
    BoxClient,
    BoxDeveloperTokenAuth,
    CreateAiExtractStructuredFields,
    CreateAiExtractStructuredFieldsOptionsField
)

load_dotenv()

developer_token = os.getenv("BOX_DEVELOPER_TOKEN")
file_id = os.getenv("BOX_FILE_ID")

def get_box_client(token: str) -> BoxClient:
    
    if not developer_token:
        raise ValueError("BOX_DEVELOPER_TOKEN is not set in environment variables.")
    
    auth = BoxDeveloperTokenAuth(token=token)
    client = BoxClient(auth=auth)

    return client

def main():
    client = get_box_client(token=developer_token)

    me = client.users.get_user_me()
    print(f"My user ID is {me.id}")

if __name__ == "__main__":
    main()

このコードは、環境変数を.envファイルから読み込み、Box SDKクライアントを初期化し、現在のユーザーのIDを出力して、クライアントが正しく動作していることを確認します。

ターミナルで次のコマンドを使用してスクリプトを実行します。
```
python enhanced-extract.py
```
Box SDKクライアントが正しく設定されると、コンソールにはユーザーIDが表示されます。次に例を示します。
```
My user ID is 123456789
```

データを抽出する

Box SDKクライアントが動作を開始したら、Box AIを使用してドキュメントからデータを抽出するためのコードを追加できます。

get_box_client関数とmain関数の間に次の関数を追加します。

def extract_metadata(client: BoxClient, file_id: str) -> dict:

    enhanced_extract_config = AiAgentReference(
        id="enhanced_extract_agent",
        type=AiAgentReferenceTypeField.AI_AGENT_ID
    )

    fields=[
        CreateAiExtractStructuredFields(
            key="parties",
            display_name="Parties",
            description="The named parties involved",
            prompt="A comma separated list of the named parties involved",
            type="string",
        ),
        CreateAiExtractStructuredFields(
            key="effectiveDate",
            display_name="Effective date",
            description="The effective date of the contract",
            prompt="The effective date of the contract",
            type="date",
        ),
        CreateAiExtractStructuredFields(
            key="purchasePrice",
            display_name="Purchase price",
            description="The purchase price stated in the contract",
            prompt="The purchase price stated in the contract",
            type="float",
        ),
        CreateAiExtractStructuredFields(
            key="summary",
            display_name="Summary",
            description="A summary of the contract in 50 words or less",
            prompt="A summary of the contract in 50 words or less including key obligations",
            type="string",
        ),
        CreateAiExtractStructuredFields(
            key="recommendation",
            display_name="Recommendation",
            description="Should we make this purchase?",
            prompt="Given the financial details, would you recommend proceeding with the purchase? Answer Yes or No.",
            type="enum",
            options=[
                CreateAiExtractStructuredFieldsOptionsField(key="Yes"),
                CreateAiExtractStructuredFieldsOptionsField(key="No"),
            ],
        ),
    ]

    metadata = client.ai.create_ai_extract_structured(
        [ AiItemBase(id=file_id) ],
        fields=fields,
        ai_agent=enhanced_extract_config,
    )
    
    return metadata.to_dict()['answer']

この関数では、Box AIのcreate_ai_extract_structuredメソッドを使用して、指定したファイルからメタデータを抽出します。BoxClientとファイルIDは関数に送信され、この関数により、抽出されたメタデータがディクショナリとして返されます。

fieldsパラメータは、ドキュメントから抽出する特定のデータポイントを定義します。また、代わりにメタデータテンプレートキーを参照して、Boxメタデータテンプレートで定義されたフィールドを抽出することもできます。

main関数でメタデータを抽出する関数呼び出しを追加します。新しいmain関数に次のロジックが含まれていることを確認します。
```
def main():
    client = get_box_client(token=developer_token)

    me = client.users.get_user_me()
    print(f"My user ID is {me.id}")

    metadata = extract_metadata(client=client, file_id=file_id)

    print(f"\n\nExtracted Metadata: {metadata}")
```
SDKはBox AIへのAPIコールを処理し、抽出されたメタデータをAiExtractStructuredResponseオブジェクトとして返します。このクイックスタートでは、このコードによって、このオブジェクトがディクショナリに変換され、抽出されたキー/値ペアを含むanswerフィールドが返されます。

ターミナルで次のコマンドを実行して、抽出されたメタデータをコンソールに出力し、抽出が成功したかどうかを確認します。

python enhanced-extract.py

抽出が成功した場合、コンソールでは、ユーザーIDの後に、株式購入契約書から抽出されたメタデータが表示されます。

My user ID is 123456789

Extracted Metadata: {'parties': 'Argyle LLP, Suregood Family Trust', 'effectiveDate': '2023-03-31', 'purchasePrice': 231000000, 'summary': 'Argyle LLP agrees to purchase 51% of Erebor Life, Inc. from Suregood Family Trust for $231,000,000. The Seller must operate the business normally until closing, and the Buyer must pay the purchase price. The agreement is effective March 31, 2023.', 'recommendation': 'Yes'}

​リソース

リソース