通过 Document Understanding API 使用模型

可以通过相同的 Document Understanding 框架 API 访问 IXP 非结构化复杂文档项目。IXP 项目在发现中显示为ProjectType: "IXP" ，并支持基于标签的端点和基于提取程序 ID 的提取端点。相关文档：

• Document Understanding API 概述
• 为 Document Understanding 创建外部应用程序
• 管理外部应用程序

先决条件

在调用任何 Document Understanding 或 IXP API 之前，您需要一个在 Automation Cloud 中注册的外部应用程序。这提供了用于 OAuth 身份验证的AppID和AppSecret 。

创建外部应用程序

1. 在租户级别导航到Orchestrator 。
2. 选择“管理访问权限” ，然后选择“管理帐户和组” 。
3. 从“UiPath 管理”标头中，选择“外部应用程序” 。
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=<APP_SECRET>' \
  -d 'scope=Du.Digitization.Api Du.Extraction.Api'

响应：

{
  "access_token": "eyJh...CRaKrg",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "Du.Digitization.Api Du.Extraction.Api"
}

令牌将在 1 小时后过期。在所有后续 API 调用中将其用作Authorization: Bearer <token> 。

备注：

如果您丢失了应用程序密码，请转到“管理员” ，然后转到“外部应用程序” ，编辑应用程序，然后选择“应用程序密码”下的“生成新的” 。使用新密码更新所有集成。

主要差异

下表显示了 Document Understanding 和 IXP 项目之间的主要区别：

	Document Understanding（传统或新式）	IXP (智能提取处理)
项目类型	Classic 或者 Modern	IXP
分类	是	否（仅提取）
提取路由	通过tag + documentTypeId （推荐）或extractorId	按tag + documentTypeId或extractorId ( gpt_ixp_[version] )
版本控制	提取程序/分类器	标签（暂存、生产）
提取模型	专用或生成式	仅限生成式（GPT-4o、Gemini）
架构定义	项目内执行或通过提示执行	在 IXP 用户界面（分类）中定义

IXP 工作流

1. 发现项目和标签。
2. 数字化和提取（并行）。
3. 验证（可选）。

备注：

没有分类步骤，因为 IXP 仅处理提取。

并行数字化和提取（仅限 IXP）

对于 IXP 项目，您可以跳过对数字化结果的轮询，并在提交数字化后立即开始提取。后端并行运行这两个操作。数字化和 IXP 提取并发进行，只有在两者完成后才会返回最终提取结果。这是一项特定于 IXP 的优化，不适用于 Document Understanding 传统或新式项目，在这些项目中，您必须等待数字化完成，然后才能调用提取。优化后的流程：

# 1. Start digitization (fire and forget — do not poll for result).
POST /projects/{projectId}/digitization/start
# → returns { "documentId": "..." }
# 2. Immediately start extraction with the documentId (no need to wait).
POST /projects/{projectId}/{tag}/document-types/{documentTypeId}/extraction/start
# → returns { "operationId": "..." }
# 3. Poll extraction result only — it waits for both digitization and extraction.
GET /projects/{projectId}/{tag}/document-types/{documentTypeId}/extraction/result/{operationId}

此流程消除了数字化和提取之间的空闲时间，从而减少了总延迟。

步骤 1：发现 IXP 项目

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

从响应中，记下 IXP 项目的id 。

获取标签（已发布版本）

标签与在 IXP 用户界面中标记为“暂存”或“生产”的已发布模型版本相对应。每个标签都包含其关联的提取程序和文档类型。要获取标签，请运行以下命令：

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

获取文档类型

要获取文档类型，请运行以下命令：

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

步骤 2：将文档数字化

与 Document Understanding 类似，上传文件以获取documentId ：

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

返回{ "documentId": "..." } 。

步骤 3：提取

IXP 提取支持以下路由方法：

• 基于标签- 按tag和documentTypeId路由。建议对 Production 或暂存工作流这样做。
• 基于提取程序 ID - 由extractorId使用gpt_ixp_[version]格式进行路由。例如， gpt_ixp_67 ），与 Document Understanding 传统或新式项目相同。

基于标签的提取

将基于标签的路径与“发现”中的documentTypeId一起使用。

同步（最多 5 页）

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction?api-version=1' \
  -H 'Authorization: Bearer <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=1' \
  -H 'Authorization: Bearer <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=1' \
  -H 'Authorization: Bearer <TOKEN>'

轮询直到status为Succeeded或Failed 。

基于 Extractor ID 的提取

使用与 Document Understanding 经典或新式相同的基于提取程序的端点。IXP 的 ExtractorId 遵循gpt_ixp_[version]格式，可在发现响应中查看。同步（最多 5 页）：

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction?api-version=1' \
  -H 'Authorization: Bearer <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=1' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

步骤 4：验证（可选）

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/validation/start?api-version=1' \
  -H 'Authorization: Bearer <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": { }
  }'

IXP 提取响应结构

API v1 或 v1.1

在 v1 和 v1.1 中，IXP 字段组映射到响应中的FieldType: "Table" ，将单个字段映射为表格列。所有值都表示为文本（字符串），无论其原始 IXP 数据类型如何：

{
  "extractionResult": {
    "DocumentId": "...",
    "ResultsDocument": {
      "DocumentTypeId": "00000000-0000-0000-0000-000000000000",
      "DocumentTypeName": "Default",
      "Fields": [
        {
          "FieldId": "Fleet member transaction details",
          "FieldName": "Fleet member transaction details",
          "FieldType": "Table",
          "Values": []
        }
      ],
      "Tables": [
        {
          "FieldId": "Fleet member transaction details",
          "FieldName": "Fleet member transaction details",
          "Values": [
            {
              "Cells": [
                { "FieldId": "Fleet Code", "Value": "FL-7892", "Confidence": 0.95 },
                { "FieldId": "Fuel type", "Value": "Diesel", "Confidence": 0.97 }
              ]
            }
          ]
        }
      ]
    }
  }
}

与 Document Understanding（v1 或 v1.1）的主要结构差异：

• 所有字段都属于字段组，在响应中显示为Table类型。
• 即使是单值字段也会包含在表格行结构中。
• Tables数组包含实际的单元格值。

API v2

在 v2 中，IXP 字段组映射到FieldType: "FieldGroup"而不是Table 。这是 IXP 字段组概念的精确映射。每个字段都保留其实际的 IXP 数据类型，例如 Text、Number、Date、MonetaryQuantity，而不是将所有内容表示为字符串。有关更多详细信息，请参阅从 API v1 迁移到 v2 。

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

与 v1 的主要区别：

• FieldType: "FieldGroup"替换FieldType: "Table" 。
• Tables数组已删除。字段组直接在Fields中返回。
• 各个字段保留其 IXP 数据类型，而不是全部是字符串。
• 字段 ID 使用点符号，例如Default.Seller.Name ）。

智能提取处理 (IXP) 发现响应结构

IXP 项目通过Tags和projectVersions公开版本控制：

{
  "id": "044fedbc-40a6-8078-8f06-02a0d362ab44",
  "name": "Transcom Invoices - Andras",
  "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 用户界面中的“生产”或“临时”标签。

备注：

• 需要无提示词：与 DU 生成式提取程序/分类器不同，IXP 提取架构是在 IXP 项目分类中预定义的。您未在 API 调用中传递prompts 。
• “标签 = 模型版本” ：使用与要调用的 Production 或暂存版本对应的标签。
• DocumentTypeId ：IXP 项目通常使用单个默认文档类型（ 00000000-0000-0000-0000-000000000000 ）。
• 页面限制：每次调用 GPT-4o 最多 50 页，Gemini 最多 500 页。
• 计量：每页 1 个 AI Unit（Flex 计划）或每页 0.2 个 Platform Unit（统一定价）。失败的请求不会消耗单元。
• 数据保留：数字化 7 天，提取 24 小时。