Box Developerドキュメント
ログイン

ファイルからメタデータを抽出する (自由形式)

ガイド Box AI Box AIのチュートリアル ファイルからメタデータを抽出する (自由形式)

ファイルからメタデータを抽出する (自由形式)

Endpoints related to metadata extraction are currently a beta feature offered subject to Box’s Main Beta Agreement, and the available capabilities may change. Box AI API is available to all Enterprise Plus and Enterprise Advanced customers.

Box AI APIを使用すると、ドキュメントを照会し、指定したプロンプトに基づいてメタデータを抽出できます。自由形式とは、JSONやXMLなどの形式の文字列化バージョン、またはプレーンテキストをプロンプトに含めることができるという意味です。

開始する前に

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

リクエストの送信

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

cURL
curl -i -L 'https://api.box.com/2.0/ai/extract' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <ACCESS_TOKEN>' \
     -d '{
        "prompt": "Extract data related to contract conditions",
        "items": [
              {
                  "type": "file",
                  "id": "1497741268097"
              }
        ],
        "ai_agent": {
          "type": "ai_agent_extract",
          "long_text": {
            "model": "azure__openai__gpt_4o_mini",
            "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
          },
          "basic_text": {
            "model": "azure__openai__gpt_4o_mini",
          }
        }
      }'
TypeScript Gen
await client.ai.createAiExtract({
  prompt: 'firstName, lastName, location, yearOfBirth, company',
  items: [new AiItemBase({ id: file.id })],
} satisfies AiExtract);
Python Gen
client.ai.create_ai_extract(
    "firstName, lastName, location, yearOfBirth, company",
    [AiItemBase(id=file.id)],
    ai_agent=ai_extract_agent_config,
)
.NET Gen
await client.Ai.CreateAiExtractAsync(requestBody: new AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})));
Java
BoxAIResponse response = BoxAI.extractMetadataFreeform(
    api,
    "firstName, lastName, location, yearOfBirth, company",
    Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE))
);

パラメータ

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

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

パラメータ説明例
promptBox AIに対するテキストの生成またはリファインのリクエスト。プロンプトの長さは10000文字以内にする必要があります。週1回の営業会議の議題を作成してください。
items.idドキュメントのBoxファイルID。IDは、拡張子が付いている実際のファイルを参照する必要があります。1233039227512
items.type指定した入力データのタイプ。file
items.content項目のコンテンツ (多くの場合はテキストレプリゼンテーション)。This article is about Box AI.
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エンドポイントを呼び出します。

  • クエリか、抽出するフィールドの構造化リストまたは非構造化リストを指定できるprompt。
  • データの抽出元となるファイルのtypeおよびid。

プロンプトの作成

ユースケースや詳細度に応じて、さまざまなプロンプトを作成できます。

プレーンテキストを使用する

このエンドポイントでは自由形式のプロンプトが許可されているため、プレーンテキストを使用して情報を取得できます。

curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
    "prompt": "find the document type (invoice or po), vendor, total, and po number",
    "items": [
        {
            "type": "file",
            "id": "1443721424754"
        }
    ]
}'

その場合、レスポンスは、テキストに含まれているキーワードに基づいて作成されます。

{
    "answer": "{\"Document Type\": \"Invoice\", \"Vendor\": \"Quasar Innovations\", \"Total\": \"$1,050\", \"PO Number\": \"003\"}",
    "created_at": "2024-05-31T10:30:51.223-07:00",
    "completion_reason": "done"
}

特定の用語を使用する

文全体を書かなくても、請求書に含まれることが予想される用語でプロンプトを構成できます。

curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: <ACCESS_TOKEN>' \
--data '{
    "prompt": "{\"vendor\",\"total\",\"doctype\",\"date\",\"PO\"}",
    "items": [
        {
            "type": "file",
            "id": "1443721424754"
        }
    ]
}'

このアプローチを使用すると、以下のように、リクエストで指定した用語のリストとその値が返されます。

{
    "answer": "{\"vendor\": \"Quasar Innovations\", \"total\": \"$1,050\", \"doctype\": \"Invoice\", \"PO\": \"003\"}",
    "created_at": "2024-05-31T10:28:51.906-07:00",
    "completion_reason": "done"
}

キー/値ペアを使用する

プロンプトには、Box AIがメタデータの構造を認識するのに役立つキー/値ペアのリストを指定することができます。このアプローチでは、fields配列内にキー/値ペアを列挙する必要があります。

curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
          "prompt": "{\"fields\":   [{\"key\":\"vendor\",\"displayName\":\"Vendor\",\"type\":\"string\",\"description\":\ "Vendorname\"},{\"key\":\"documentType\",\"displayName\":\"Type\",\"type\":\"string\",\"description\":\"\"}]}",
    "items": [
        {
            "type": "file",
            "id": "1443721424754"
        }
    ]
}'

レスポンスには、以下のように、ファイル内に存在するfieldsとその値が含まれます。

{
    "answer": "{\"vendor\": \"Quasar Innovations\", \"documentType\": \"Invoice\"}",
    "created_at": "2024-05-31T10:15:38.17-07:00",
    "completion_reason": "done"
}