Document Understanding API 経由でモデルを利用する

タグベースまたは抽出器 ID ベースの抽出エンドポイントを使用して、Document Understanding フレームワーク API を介してフロー抽出ノードに構築された IXP モデルにアクセスします。

IXP の抽出ノードには、同じ Document Understanding フレームワークの API を介してアクセスできます。抽出ノードは Discovery に ProjectType: "IXP" として表示され、 抽出でタグベースのエンドポイント と 抽出器 ID ベースのエンドポイント の両方をサポートします。

関連ドキュメント:

• Document Understanding API の概要
• Document Understanding の外部アプリケーションを作成する
• 外部アプリケーションを管理する

注:

API v2 を使用してノードを 抽出 し、パブリック Document Understanding API の最新バージョンを使用します。このページの例では、API v2 (api-version=2) を使用します。

前提条件

Document Understanding または IXP API を呼び出す前に、Automation Cloud に登録されている外部アプリケーションが必要です。これにより、OAuth 認証に使用される AppID と AppSecret が提供されます。

外部アプリケーションを作成する

1. テナント レベルで Orchestrator に移動します。

2. [ アクセス権を管理]、[ アカウントとグループを管理] の順に選択します。

3. UiPath Administration のヘッダーから [外部アプリケーション] を選択します。

4. [アプリケーションを追加] を選択します。

5. [アプリケーション名] に入力します (例: DU API Client)。

6. アプリ シークレットを取得するために必要な [ 機密アプリケーション] を選択します。

7. [ リソース] で [ スコープを追加] を選択します。

   • [リソース] ドロップダウンから [Document Understanding] を選択します。
   • [ アプリケーション スコープ ] タブに切り替えます。
   • 必要なスコープを確認します。
     • Du.Digitization.Api - ドキュメントをデジタル化する
     • Du.Classification.Api - ドキュメントを分類する
     • Du.Extraction.Api - データを抽出
     • Du.Validation.Api - 検証タスクを作成
     • Du.DataDeletion.Api - ドキュメント データを削除
   • [保存] を選択します。

8. [追加] を選択して登録を作成します。

   注:

   [ アプリ シークレットを直ちにコピー] ポップアップは一度だけ表示され、回復することはできません。後で編集画面から新しい認証を生成できます。

アプリケーション ID は、[外部アプリケーション] ページにいつでも表示されます。

アクセス トークンを取得する

アプリ ID とアプリ シークレットを使用して、クライアント資格情報フローで OAuth トークンを要求します。

curl -X POST 'https://cloud.uipath.com/identity_/connect/token' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<APP_ID>' \
  -d 'client_secret=<your-client-secret>' \
  -d 'scope=Du.Digitization.Api Du.Extraction.Api'

応答:

{
  "access_token": "<your-access-token>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "Du.Digitization.Api Du.Extraction.Api"
}

トークンは 1 時間後に期限切れになります。これを、後続のすべての API 呼び出しの Authorization: Bearer <your-access-token> として使用します。

注:

アプリ シークレットを紛失した場合は、[ 管理] > [外部アプリケーション] に移動してアプリを編集し、[アプリ シークレット] の [ 新しく生成 ] を選択します。すべての連携を新しいシークレットで更新します。

主な違い

以下の表に、Document Understanding プロジェクトと IXP プロジェクトの主な違いを示します。

	Document Understanding (クラシックまたはモダン)	IXP
projectType	Classic OR Modern	IXP
分類	はい	いいえ (抽出のみ)
抽出ルーティング	tag + documentTypeId (推奨) または extractorId	tag + documentTypeId またはextractorId (gpt_ixp_[version])
抽出モデル	特殊または生成	生成 AI のみ (GPT-4o、Gemini)
スキーマ定義	プロジェクト内、またはプロンプト経由	IXP UI で定義 (タクソノミー)

IXP ワークフロー

1. プロジェクトとタグを検出する
2. ドキュメントをデジタル化し、デジタル化が完了するまでポーリングを行います。
3. 抽出し、抽出が完了するまでポーリングを行います。
4. 検証 (任意)。

注:

IXP は抽出データのみを処理するため、分類手順はありません。

手順 1: IXP プロジェクトを検出する

# List all projects - filter for type "IXP"
curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

応答から、IXP プロジェクトの id をメモします。

タグを取得する (パブリッシュ済みバージョン)

タグは、IXP のユーザー インターフェイスでステージングまたは運用としてマークされたパブリッシュ済みモデル バージョンに対応します。各タグには、関連する抽出器とドキュメントの種類が含まれます。タグを取得するには、次のコマンドを実行します。

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/tags?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

ドキュメントの種類を取得

ドキュメントの種類を取得するには、次のコマンドを実行します。

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/document-types?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

注:

プロジェクト ID、タグ、ドキュメントの種類 ID がわかれば、実行時に毎回検出呼び出しを実行する必要はありません。これらの値は、代わりにオートメーションで再利用してください。

手順 2: ドキュメントをデジタル化する

注:

デジタル化は必須の手順です。ドキュメントをデジタル化する前に、ドキュメントからデータを抽出することはできません。

Document Understanding と同様に、ファイルをアップロードして documentIdを取得します。

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf;type=application/pdf'

戻り値は { "documentId": "..." }です。

デジタル化結果のポーリング:

curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/result/<documentId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'

status がSucceededになるまでポーリングを行い、抽出を開始します。使用可能なステータスと応答については、「 Polling responses」をご覧ください。

ステップ 3: 抽出

IXP の抽出では、以下のルーティング アプローチがサポートされています。

• タグベース - tag と documentTypeIdによるルーティングこれは、運用ワークフローまたはステージング ワークフローに推奨されます。
• 抽出器 ID ベース - gpt_ixp_[version]の形式を使用してextractorIdでルーティングします。たとえば、 gpt_ixp_67です。これは、Document Understanding のクラシック プロジェクトまたはモダン プロジェクトの場合と同じです。

タグベースの抽出

Discovery からの documentTypeId でタグベースのパスを使用します。

同期 (最大 5 ページ)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

非同期 (複数ページ)

開始：

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

戻り値は { "operationId": "..." }です。結果のポーリング:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/result/<operationId>?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

statusがSucceededまたはFailedになるまでポーリング。使用可能なステータスと応答については、「 Polling responses」をご覧ください。

抽出器 ID ベースの抽出

Document Understanding のクラシックまたはモダンと同じ抽出器ベースのエンドポイントを使用します。IXP の抽出器 ID は、検出の応答に表示される形式 gpt_ixp_[version]に従います。同期 (最大 5 ページ):

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

非同期 (複数ページ):

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

戻り値は { "operationId": "..." }です。結果のポーリング:

curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/result/<operationId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'

statusがSucceededまたはFailedになるまでポーリング。使用可能なステータスと応答については、「 Polling responses」をご覧ください。

手順 4: 検証 (任意)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/validation/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "documentId": "<documentId>",
    "actionTitle": "Review IXP extraction",
    "actionPriority": "Medium",
    "actionCatalog": "default_du_actions",
    "actionFolder": "Shared",
    "storageBucketName": "du_storage_bucket",
    "storageBucketDirectoryPath": "du_storage_bucket",
    "extractionResult": { }
  }'

回答をポーリングする

手順 2 の非同期デジタル化呼び出しと手順 3 の非同期抽出呼び出しは、ポーリングを介して結果を返します。各ポーリングの回答には、次のいずれかの statusが含まれます。

• NotStarted - ジョブは作成され、処理を待機しています。
• Running - ジョブはピックアップされ、処理中です。
• Succeeded - ジョブは正常に完了しました。応答には resultが含まれます。
• Failed - ジョブはエラーで終了しました。応答には errorが含まれます。

ステータスが [ NotStarted ] または [ Running] の間、ポーリングを続けます。

ジョブの処理中は、応答にはジョブのステータスとタイムスタンプが含まれます。

{
  "status": "Running",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>"
}

ジョブが成功すると、応答には resultも含まれます。抽出の場合、結果は result.extractionResultです。その構造については、「 IXP の抽出応答の構造」をご覧ください。

{
  "status": "Succeeded",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>",
  "result": {
    "extractionResult": {
      "documentId": "<documentId>"
    }
  }
}

ジョブが失敗すると、応答には次の詳細情報を含む error オブジェクトが含まれます。

• message - エラーの説明です。
• severity - エラーの重大度です (通常は Errorです。
• code - エラーの種類を識別するコードです。
• parameters - エラーに関する追加情報です (該当する場合)。

詳しくは、『Document Understanding API ガイド』の「 要求の応答スキーマ 」をご覧ください。

IXP の抽出応答の構造

API v2 では、IXP によって報告されるすべてのフィールドと値は、IXP のフィールド グループと子フィールドの定義が正確にマッピングされて、正しいフィールドの種類 (フィールド グループと子フィールドを含む) が使用されています。

{
  "extractionResult": {
    "ResultsDocument": {
      "Fields": [
        {
          "FieldId": "Default.Seller",
          "FieldName": "Seller",
          "FieldType": "FieldGroup",
          "IsMissing": false,
          "DataSource": "Automatic",
          "Values": [
            {
              "Components": [
                {
                  "FieldId": "Default.Seller.Name",
                  "FieldName": "Name",
                  "FieldType": "Text",
                  "Values": [
                    {
                      "Value": "John Doe",
                      "Confidence": 0.9999834
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

注:

IXP プロジェクトのフィールド グループとフィールドの種類と報告される結果は 1 対 1 でマッピングされるため、IXP の消費には API v2 を使用することをお勧めします。

IXP 検出の応答構造

IXP プロジェクトでは、 タグ と projectVersion を使用してバージョン管理を公開しています。

{
  "id": "044fedbc-40a6-8078-8f06-02a0d362ab44",
  "name": "Invoices",
  "type": "IXP",
  "properties": ["SupportsTags", "SupportsVersions"],
  "extractors": [
    {
      "id": "gpt_ixp_67",
      "documentTypeId": "00000000-0000-0000-0000-000000000000",
      "projectVersion": 67
    }
  ],
  "projectVersions": [
    { "version": 67, "tag": "live", "deployed": true }
  ],
  "classifiers": []
}

タグ名 (例: live) は、IXP のユーザー インターフェイスの「運用」または「ステージング」ラベルにマップされます。

IXP の抽出エンドポイントを呼び出す際には、以下の点に留意してください。

• タグ = モデル バージョン: 呼び出す運用バージョンまたはステージング バージョンに対応するタグを使用します。
• DocumentTypeId: IXP プロジェクトでは通常、1 つの既定のドキュメントの種類 (00000000-0000-0000-0000-000000000000) が使用されます。
• ページの制限: ページとトークンの制限については、「 ドキュメント処理の制限」をご覧ください。
• 使用状況の測定: IXP の抽出の課金方法について詳しくは、「 IXP フレックス プライシング プラン」、「 ユニファイド プライシング」、「使用 状況の測定と請求ロジック (フレックス プラン)」をご覧ください。
• データの保持: デジタル化と抽出結果の保持期間について詳しくは、「 Document Understanding API の概要」をご覧ください。