通过 Document Understanding API 使用模型

通过 Document Understanding 框架 API，使用基于标签或基于 ExtractorId 的提取端点，访问 IXP 非结构化复杂文档项目。

您可以通过同一 Document Understanding 框架 API 访问智能提取处理 (IXP) 非结构化复杂文档项目。智能提取处理 (IXP) 项目会以ProjectType: "IXP"的形式显示在“发现”中，并支持通过基于标签的端点和基于 extractorId 的端点进行提取。

相关文档：

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

先决条件

调用任何 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=<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) 专有的优化机制，不适用于 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进行路由。建议用于生产或暂存工作流。
• 基于 ExtractorId - 使用以下格式根据extractorId进行路由：gpt_ixp_[version]。例如，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=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。

基于 ExtractorId 的提取

使用与 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"，各字段则表示为表格列。所有值都表示为 Text (string)，无论其原始智能提取处理 (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类型。
• 即使是单值字段，也会包含在表格行结构中。
• TablesArray 包含实际的单元格值。

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 Array 被移除。字段组直接在Fields中返回。
• 各字段会保留其智能提取处理 (IXP) 数据类型，而不是统一表示为字符串。
• FieldId 采用点表示法，例如Default.Seller.Name）。

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

智能提取处理 (IXP) 项目通过标签和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) 用户界面中的“生产”或“暂存”标签。

调用 IXP 提取端点时，请考虑以下事项：

• 无需提示词：与 Document Understanding 生成式提取程序或分类器不同，IXP 提取架构是在 IXP 项目分类中预定义的。您未在 API 调用中传递prompts 。
• 标签 = 模型版本：使用与您要调用的生产或暂存版本对应的标签。
• DocumentTypeId：智能提取处理 (IXP) 项目通常使用单个默认文档类型 (00000000-0000-0000-0000-000000000000)。
• 页面上限：GPT-4o 每次调用最多 50 页，Gemini 每次调用最多 500 页。
• 计量：IXP 提取按以下方式收费，具体取决于您的定价计划：
  • Flex 计划：每页 1 个 AI Unit，或当上游已对页面进行分类时，每页 0.8 个 AI Unit（例如在 Document Understanding 新式项目中）。
  • Unified Pricing：每页 0.2 个 Platform Units。失败的请求不会消耗单元。
• 数据保留：数字化 7 天，提取 24 小时。

备注：

Document Understanding 和 IXP 许可证可以一起使用。有关更多详细信息，请参阅计量和计费逻辑（Flex 计划）和IXP Flex 定价计划。