PythonでのBox AIを使用した構造化データの抽出

Box AIは、構造化されたキー/値ペアを単一のAPIコールでドキュメントから自動的に抽出できる、インテリジェントな抽出機能を開発者向けに備えています。この強力な機能により、データの手動入力なしに、非構造化ドキュメントコンテンツがすぐに使用可能なメタデータに変換され、請求書、フォーム、契約書などのビジネスドキュメントのドキュメント処理ワークフローが効率化されます。このクイックスタートでは、Box Python SDKを構成して、メタデータテンプレートを作成し、Box AIを使用して請求書データを抽出し、それを検索可能なメタデータとしてBoxに保存する方法を説明します。

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

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

Box開発者コンソールに移動します。
このクイックスタートでは、アプリケーションの種類としてClient Credentials Grantを使用してアプリを作成します。
アプリが作成されたら、以下のスコープを有効にします。

Boxに格納されているすべてのファイルとフォルダの読み取り
Boxに格納されているすべてのファイルとフォルダへの書き込み
AIを管理する

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

Boxメタデータテンプレートを作成する

この手順では、管理者がBox Enterpriseにアクセスできる必要があります。現在の環境でアクセス権限がない場合は、Box管理者に連絡してください。

Box AIを使用すると、いくつかの方法でドキュメントからデータを抽出できます。

型	説明	ユースケース
抽出 (自由形式)	文字列のプロンプトを使用できます。	自然言語のプロンプトを入力します。
テンプレートを使用した抽出 (構造化)	Boxメタデータテンプレートキーを使用できます。	フィールドとデータ型を1回定義します。そうすると、メタデータとしてBoxに戻す処理がシンプルになります。
フィールドを使用した抽出 (構造化)	フィールドのJSON配列を使用できます。	テンプレートを作成せず、1回限りの抽出を実行します。
抽出エージェント (強化)	推論モデルを備えた専任エージェントを使用します。	複雑なドキュメントや、複雑かつ繊細な抽出に適しており、構造化されたテンプレートやフィールドで動作します。

このクイックスタートでは、ドキュメントから抽出するフィールドを定義するためのBoxメタデータテンプレートを作成します。Box管理コンソールでBoxメタデータテンプレートを作成する手順の詳細な説明については、メタデータテンプレートのカスタマイズを参照してください。

テンプレートに名前を付けます (例: Box AI extract quick start)。

以下のフィールドを作成します。

フィールド名	型	説明
クライアント名	テキスト	請求書を受け取るクライアントの名前
請求書の金額	数字	税および手数料徴収後の請求書の総額
製品	テキスト	請求書記載の納品された製品名 (コンマ区切りの文字列として返されます)

フィールドの説明は、正しいデータが抽出されるように、LLMへのプロンプトの補完情報としてBox AIによって使用されます。

[保存] をクリックしてテンプレートを作成します。テンプレートキーは後で使用できるようにメモしておきます。

テンプレートを保存すると、テンプレートのリストが表示されます。テンプレートキーを確認するには、先ほど作成したテンプレートを開き、URLを調べます。パスの最後の部分がテンプレートキーです。たとえば、次のようなURLがあるとします: https://app.box.com/master/metadata/templates/boxAiExtractquick startこの場合、テンプレートキーはboxAiExtractquick startです。

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

テンプレートを準備できたら、テストするファイルを選択します。このクイックスタートでは、こちらのサンプル請求書のドキュメントを使用します。

テスト用ドキュメントをダウンロードして、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開発者コンソールに移動します。アプリを開き、[構成] タブに移動します。

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

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

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

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

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

import os

from dotenv import load_dotenv

from box_sdk_gen import (
    AiItemBase,
    BoxClient,
    BoxDeveloperTokenAuth,
    CreateAiExtractStructuredMetadataTemplate,
    CreateAiExtractStructuredMetadataTemplateTypeField,
    CreateFileMetadataByIdScope
)

load_dotenv()

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

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 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, template_key: str) -> dict:
    metadata = client.ai.create_ai_extract_structured(
        [AiItemBase(id=file_id)],
        metadata_template=CreateAiExtractStructuredMetadataTemplate(
            template_key=template_key,
            type=CreateAiExtractStructuredMetadataTemplateTypeField.METADATA_TEMPLATE,
            scope="enterprise",
        ),
    )
    
    return metadata.to_dict()['answer']

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

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, template_key=template_key)

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

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

python extract.py

抽出が成功した場合、コンソールでは、ユーザーIDの後に請求書ドキュメントから抽出されたメタデータが表示されます。

My user ID is 123456789

Extracted Metadata: {'clientName': 'ACME Inc', 'invoiceAmount': 1106.06, 'products': 'Polyol, Diisocyanate, 
Carbon Dioxide, Laser, Lens, Oleic Acid, Glycerine, Sodium Tallowate, Paint Base, Polypropylene, Rubber, 
Additive, Pigment, Aluminum Silicate, Magnesium Silicate, Zinc Oxide, Distilled Solvent, Petroleum Distillate, 
Sulfur Dioxide, Sodium Benzoate, Dust cap, Ferrite cap, Cone and coil assembly, Cleaner, Polypropylene pellets, 
Polypropylene chips, Polypropylene blocks, Polypropylene slag, Parts Wash Solvent, Jar, 
Plastic Bottle - 15.2 FL Oz (450 ml), Polymer'}

ファイルにBoxメタデータを追加する

ドキュメントからメタデータを抽出できました。これで、データベースへのプッシュ、CRMとの統合、エージェントへの処理用フィード、自動化ワークフローの開始などの目的で、キー/値ペアを自分のアプリケーションで使用できるようになります。このクイックスタートでは、抽出されたデータをファイルのメタデータとしてBoxに戻す方法を説明します。Boxのメタデータ管理機能では、強力なフィルタ機能と検索機能をコンテンツ全体で使用できます。たとえば、過去30日間の500ドルを超える請求書を全件照会したり、Box Appsでダッシュボードを作成したり、ドキュメントの主なインサイトをBoxウェブアプリに直接表示したりできます。

次の関数をextract_metadata関数とmain関数の間に追加して、抽出されたメタデータをBoxに戻します。
```
def push_metadata(client: BoxClient, file_id: str, metadata: dict, template_key: str) -> dict:
    attached_metadata = client.file_metadata.create_file_metadata_by_id(
        file_id,
        CreateFileMetadataByIdScope.ENTERPRISE,
        template_key,
        metadata,
    )
    return attached_metadata.to_dict()
```
この関数ではcreate_file_metadata_by_idメソッドを使用して、指定されたファイルにメタデータを追加し、BoxClient、ファイルID、メタデータディクショナリ、テンプレートキーを処理します。API自体はMetadataFullオブジェクトを返します。この関数によって、このオブジェクトがディクショナリに変換され、返されます。

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, template_key=template_key)

    print(f"Extracted Metadata: {metadata}")

    attached_metadata = push_metadata(client=client, file_id=file_id, metadata=metadata, template_key=template_key)

    print(f"Attached Metadata: {attached_metadata}")

ターミナルで次のコマンドを実行します。

python extract.py

スクリプトが成功すると、コンソールには、ユーザーID、抽出されたメタデータ、Boxから追加されたメタデータレスポンスが表示されます。次に例を示します。

My user ID is 123456789

Extracted Metadata: {'clientName': 'ACME Inc', 'invoiceAmount': 1106.06, 'products': 'Polyol, Diisocyanate,
Carbon Dioxide, Laser, Lens, Oleic Acid, Glycerine, Sodium Tallowate, Paint Base, Polypropylene, Rubber,
Additive, Pigment, Aluminum Silicate, Magnesium Silicate, Zinc Oxide, Distilled Solvent, Petroleum Distillate,
Sulfur Dioxide, Sodium Benzoate, Dust cap, Ferrite cap, Cone and coil assembly, Cleaner, Polypropylene pellets,
Polypropylene chips, Polypropylene blocks, Polypropylene slag, Parts Wash Solvent, Jar,
Plastic Bottle - 15.2 FL Oz (450 ml), Polymer'}

Attached Metadata: {'invoiceAmount': 1106.06, 'products': 'Polyol, Diisocyanate, Carbon Dioxide, Laser, Lens, 
Oleic Acid, Glycerine, Sodium Tallowate, Paint Base, Polypropylene, Rubber, Additive, Pigment, Aluminum Silicate, 
Magnesium Silicate, Zinc Oxide, Distilled Solvent, Petroleum Distillate, Sulfur Dioxide, Sodium Benzoate, Dust cap, 
Ferrite cap, Cone and coil assembly, Cleaner, Polypropylene pellets, Polypropylene chips, Polypropylene blocks, 
Polypropylene slag, Parts Wash Solvent, Jar, Plastic Bottle - 15.2 FL Oz (450 ml), Polymer', 
'clientName': 'ACME Inc', '$parent': 'file_1956534287859', '$template': 'boxAiExtractquick start', 
'$scope': 'enterprise_899905961', '$version': 0, '$canEdit': True, '$id': '4d4f0b55-d45a-4ba4-9ff6-1241182cb76a', 
'$type': 'boxAiExtractquick start-c4024235-2384-49f4-9286-ada6d68fd6a9', '$typeVersion': 0, 'extra_data': 
{'invoiceAmount': 1106.06, 'products': 'Polyol, Diisocyanate, Carbon Dioxide, Laser, Lens, Oleic Acid, Glycerine, 
Sodium Tallowate, Paint Base, Polypropylene, Rubber, Additive, Pigment, Aluminum Silicate, Magnesium Silicate, 
Zinc Oxide, Distilled Solvent, Petroleum Distillate, Sulfur Dioxide, Sodium Benzoate, Dust cap, Ferrite cap, 
Cone and coil assembly, Cleaner, Polypropylene pellets, Polypropylene chips, Polypropylene blocks, Polypropylene slag, 
Parts Wash Solvent, Jar, Plastic Bottle - 15.2 FL Oz (450 ml), Polymer', 'clientName': 'ACME Inc'}}

​リソース

リソース