Box Developerドキュメント

BoxWorks 2024でコンテンツと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 customers.

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

リクエストの送信

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

アプリを承認するための開発者トークンを生成済みであることを確認します。詳細については、Box AIを使用するための前提条件を確認してください。

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_3_5_turbo_16k",
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "embeddings": {
              "model": "openai__text_embedding_ada_002",
              "strategy": {
                "id": "basic",
                "num_tokens_per_chunk": 64
              }
            }
          },
          "basic_text": {
            "model": "azure__openai__gpt_3_5_turbo_16k",
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            }
          }
        }
      }'
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: <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がメタデータの構造を認識するのに役立つキー/値ペアのリストを指定することができます。

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"
        }
    ]
}'

応答には、以下のように、ファイル内に存在するフィールドとその値が含まれます。

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

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

以下のように、プレーンテキストを使用することもできます。

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"
}