Box Developerドキュメント

ファイルからメタデータを抽出する (構造化)

ガイド Box AI Box AIのチュートリアル ファイルからメタデータを抽出する (構造化)

ファイルからメタデータを抽出する (構造化)

メタデータ抽出に関連するエンドポイントは、現在、BoxのMain Beta Agreementに従い提供されるベータ機能のため、利用可能な機能が変更される可能性があります。Box AI APIは、Enterprise Plusをご利用のすべてのお客様が利用できます。

Box AI APIを使用すると、指定したファイルからメタデータを抽出し、結果をキー/値ペアの形式で取得することができます。入力には、fieldsパラメータを使用して構造を作成するか、すでに定義済みのメタデータテンプレートを使用できます。テンプレートの作成の詳細については、メタデータテンプレートのカスタマイズを参照するか、メタデータテンプレートAPIを使用してください。

開始する前に

カスタムアプリを作成して認証するには、Box AIの使い方に記載されている手順に従っていることを確認してください。

リクエストの送信

リクエストを送信するには、POST /2.0/ai/extract_structuredエンドポイントを使用します。

cURL
curl -i -L 'https://api.box.com/2.0/ai/extract_structured' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <ACCESS_TOKEN>' \
     -d '{
        "items": [
          {
            "id": "12345678",
            "type": "file",
            "content": "This is file content."
          }
        ],
        "metadata_template": {
            "template_key": "",
            "type": "metadata_template",
            "scope": ""
        },
        "fields": [
            {
              "key": "name",
              "description": "The name of the person.",
              "displayName": "Name",
              "prompt": "The name is the first and last name from the email address.",
              "type": "string",
              "options": [
                {
                  "key": "First Name"
                },
                {
                  "key": "Last Name"
                }
              ]
            }
        ],
        "ai_agent": {
          "type": "ai_agent_extract",
          "long_text": {
            "model": "azure__openai__gpt_4o_mini"
            },
          "basic_text": {
            "model": "azure__openai__gpt_4o_mini"
         }
      }
   }'
TypeScript Gen
await client.ai.createAiExtractStructured({
  metadataTemplate: {
    templateKey: templateKey,
    scope: 'enterprise',
  } satisfies AiExtractStructuredMetadataTemplateField,
  items: [new AiItemBase({ id: file.id })],
} satisfies AiExtractStructured);
Python Gen
client.ai.create_ai_extract_structured(
    [AiItemBase(id=file.id)],
    metadata_template=CreateAiExtractStructuredMetadataTemplate(
        template_key=template_key, scope="enterprise"
    ),
)
.NET Gen
await client.Ai.CreateAiExtractStructuredAsync(requestBody: new AiExtractStructured(items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})) { MetadataTemplate = new AiExtractStructuredMetadataTemplateField() { TemplateKey = templateKey, Scope = "enterprise" } });
Java
BoxAIExtractMetadataTemplate template = new BoxAIExtractMetadataTemplate("templateKey", "enterprise");
BoxAIExtractStructuredResponse result = BoxAI.extractMetadataStructured(
    api,
    Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE)),
    template
);
JsonObject sourceJson = result.getSourceJson();

パラメータ

コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは太字で示されています。

items配列に含めることができる要素は1つだけです。

パラメータ説明
metadata_template抽出するフィールドを含むメタデータテンプレート。リクエストを機能させるには、metadata_templateまたはfieldsを指定する必要がありますが、両方を指定することはできません。
metadata_template.typeメタデータテンプレートのタイプ。metadata_template
metadata_template.scopeメタデータテンプレートのスコープ。globalまたはenterpriseのいずれかになります。globalテンプレートは、任意のBox Enterpriseで利用できますが、enterpriseテンプレートは特定のEnterpriseに関連付けられます。metadata_template
metadata_template.template_keyメタデータテンプレートの名前。invoice
items.idドキュメントのBoxファイルID。IDは、拡張子が付いている実際のファイルを参照する必要があります。1233039227512
items.type指定した入力データのタイプ。file
items.content項目のコンテンツ (多くの場合はテキストレプリゼンテーション)。This article is about Box AI.
fields.typeフィールドのタイプ。これには、stringfloatdateenummultiSelectが含まれますが、これらに限定されるものではありません。string
fields.descriptionフィールドの説明。The person's name.
fields.displayNameフィールドの表示名。Name
fields.keyフィールドの一意の識別子。name
fields.optionsこのフィールドのオプションのリスト。ほとんどの場合、enumおよびmultiSelectフィールドタイプと組み合わせて使用します。[{"key":"First Name"},{"key":"Last Name"}]
fields.options.keyフィールドの一意の識別子。First Name
fields.promptキー (識別子) に関する追加のコンテキスト。キーの確認方法や形式を含めることができます。Name is the first and last name from the email address
ai_agentデフォルトのエージェント構成を上書きするために使用されるAIエージェント。このパラメータを使用すると、たとえば、modelパラメータを使用してデフォルトのLLMをカスタムのLLMに置き換えたり、よりカスタマイズされたユーザーエクスペリエンスを実現できるようにベースとなるpromptを微調整したり、temperatureなどのLLMパラメータを変更して結果の創造性を調整したりすることができます。ai_agentパラメータを使用する前に、GET 2.0/ai_agent_defaultリクエストを使用してデフォルト構成を取得できます。具体的なユースケースについては、AIモデルの上書きに関するチュートリアルを参照してください。

ユースケース

この例では、サンプル請求書から構造化された形でメタデータを抽出する方法を示します。ベンダー名、請求書番号などの詳細情報を抽出する必要があるとします。

�サンプル請求書

リクエストの作成

Box AIから応答を取得するには、以下のパラメータを使用して、POST /2.0/ai/extract_structuredエンドポイントを呼び出します。

  • items.typeおよびitems.id: データの抽出元となるファイルを指定します。
  • fields: 指定したファイルから抽出するデータを指定します。
  • metadata_template: 既存のメタデータテンプレートを指定します。

fieldsmetadata_templateのどちらかを使用して、構造を指定できます。両方を使用することはできません。

fieldsパラメータの使用

fieldsパラメータを使用すると、抽出するデータを指定できます。各fieldsオブジェクトにはパラメータのサブセットがあり、それを使用して、検索対象のデータに関する情報を追加できます。たとえば、フィールドのタイプや説明、さらには追加のコンテキストを含めたプロンプトを追加することができます。

curl --location 'https://api.box.com/2.0/ai/extract_structured' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'' \
--data '{
    "items": [
        {
            "id": "1517628697289",
            "type": "file"
        }
    ],
    "fields": [
        {
            "key": "document_type",
            "type": "enum",
            "prompt": "what type of document is this?",
            "options": [
                {
                    "key": "Invoice"
                },
                {
                    "key": "Purchase Order"
                },
                {
                    "key": "Unknown"
                }
            ]
        },
        {
            "key": "document_date",
            "type": "date"
        },
        {
            "key": "vendor",
            "description": "The name of the entity.",
            "prompt": "Which vendor is sending this document.",
            "type": "string"
        },
        {
            "key": "document_total",
            "type": "float"
        }
    ]
  }'

応答には、以下のように、指定したフィールドとその値が示されます。

{
    "document_date": "2024-02-13",
    "vendor": "Quasar Innovations",
    "document_total": $1050,
    "document_type": "Purchase Order"
}

メタデータテンプレートの使用

メタデータテンプレートを使用する場合は、そのtemplate_keytypescopeを指定します。

curl --location 'https://api.box.com/2.0/ai/extract_structured' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
    "items": [
        {
            "id": "1517628697289",
            "type": "file"
        }
    ],
    "metadata_template": {
        "template_key": "rbInvoicePO",
        "type": "metadata_template",
        "scope": "enterprise_1134207681"
    }
}'

応答には、以下のように、メタデータテンプレートに含まれているフィールドとその値が示されます。

{
  "documentDate": "February 13, 2024",
  "total": "$1050",
  "documentType": "Purchase Order",
  "vendor": "Quasar Innovations",
  "purchaseOrderNumber": "003"
}