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

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

メタデータを抽出 (自由形式) エンドポイントはOCRをサポートしていません。英語以外の言語の画像ファイル (TIFF、PNG、JPEG) またはドキュメントからメタデータを抽出するには、エンドポイントを使用してください。

開始する前に

Platformアプリを作成して認証するには、に記載されている手順に従っていることを確認してください。

リクエストの送信

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

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": "openai__gpt_5_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": "openai__gpt_5_mini",
          }
        }
      }'

await client.ai.createAiExtract({
  prompt: 'firstName, lastName, location, yearOfBirth, company',
  items: [new AiItemBase({ id: file.id })],
  aiAgent: agentIgnoringOverridingEmbeddingsModel,
} satisfies AiExtract);

client.ai.create_ai_extract(
    "firstName, lastName, location, yearOfBirth, company",
    [AiItemBase(id=file.id)],
    ai_agent=agent_ignoring_overriding_embeddings_model,
)

await client.Ai.CreateAiExtractAsync(requestBody: new AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})));

try await client.ai.createAiExtract(requestBody: AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: [AiItemBase(id: file.id)]))

client.getAi().createAiExtract(new AiExtract.Builder("firstName, lastName, location, yearOfBirth, company", Arrays.asList(new AiItemBase(file.getId()))).aiAgent(agentIgnoringOverridingEmbeddingsModel).build())

BoxAIResponse response = BoxAI.extractMetadataFreeform(
    api,
    "firstName, lastName, location, yearOfBirth, company",
    Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE))
);

パラメータ

コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは太字で示されています。 items配列には要素が1つだけ含まれている必要があります。プロンプトとファイルの制限については、を参照してください。

パラメータ	説明	例
`prompt`	Box AIに対するメタデータの抽出リクエスト。最大10,000文字。	週1回の営業会議のアジェンダを作成してください。
`items.id`	ドキュメントのBoxファイルID。IDは、拡張子が付いている実際のファイルを参照する必要があります。	`1233039227512`
`items.type`	指定した入力データのタイプ。	`file`
`items.content`	項目のコンテンツ (多くの場合はテキストレプリゼンテーション)。	`This article is about Box AI`.
`ai_agent`	デフォルトのモデル構成を上書きします。これにより、モデル、プロンプトテンプレート、システムメッセージ、またはLLMパラメータを変更できます。仕組みについてはを参照してください。また、使用例についてはを参照してください。

ユースケース

この例では、サンプル請求書からメタデータを抽出する方法を示します。

リクエストの作成

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

​開始する前に

​リクエストの送信

​パラメータ

​ユースケース

​リクエストの作成

​プロンプトの作成

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

​特定の用語を使用する

​キー/値ペアを使用する

開始する前に

リクエストの送信

パラメータ

ユースケース

リクエストの作成

プロンプトの作成

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

特定の用語を使用する

キー/値ペアを使用する