name: extract-structured-data-from-document description: 結構化欄位抽取工具 - 基於使用者定義的schema從文件中抽取結構化欄位。schema定義要抽取的欄位及其語義描述，支援文本、表格、段落三種類型的欄位抽取。 metadata: {"openclaw": {"emoji": "🔍", "command-dispatch": "tool", "command-tool": "document_extract"}}

結構化欄位抽取工具 (extract_structured_data_from_document)

概述

extract_structured_data_from_document 是一個結構化欄位抽取工具，根據使用者定義的schema從文件中抽取結構化資料。

重要提示：此工具專注於從文件中提取結構化欄位，不適用於： - 文件摘要生成 - 通用問答 - 文件結構解析

如需解析文件結構，請使用 parse_document 工具。

適用場景

• 從PDF/Word/Excel等文件中提取結構化資料
• 財務報表資料抽取（如營收、利潤、資產負債表等）
• 合同關鍵條款提取
• 表單資料提取
• 任何需要從非結構化文件中提取結構化資訊的任務

不適用場景

• 文件結構解析（請使用 parse_document）
• 文件摘要或總結
• 通用問答任務
• 無明確抽取目標的探索性分析

輸入引數

document_url 既可以是公網可訪問的檔案 URL，也可以是本地檔案路徑。 當傳入本地路徑時，工具會先上傳到 DPA 文件裡指定的檔案服務，再呼叫欄位抽取介面。

環境變數

• DPA_ENV: sim 或 prod，預設 sim
• DPA_BASE_URL: 可選，自定義覆蓋解析服務地址
• DPA_UPLOAD_URL: 可選，自定義覆蓋檔案上傳地址

預設端點：

• 模擬環境：http://imsfz.gjzq.cn:18087/ismp/yx-dpa/document
• 模擬上傳：http://imsfz.gjzq.cn:18087/ismp/yx-gw/infras/file/file/v3/upload
• 生產環境：http://ims.gjzq.cn:18087/ismp/yx-dpa/document
• 生產上傳：http://ims.gjzq.cn:18087/ismp/yx-gw/infras/file/file/v3/upload

Schema結構

schema是一個JSON物件，支援三種欄位型別：

{
  "text": [
    {
      "keyName": "欄位名稱",
      "keyPrompt": "欄位的語義描述和抽取要求"
    }
  ],
  "table": [
    {
      "tableName": "表格名稱",
      "tableDescription": "表格的描述資訊",
      "tableColumn": [
        {
          "keyName": "列名稱",
          "keyPrompt": "列的語義描述和抽取要求"
        }
      ]
    }
  ],
  "paragraph": [
    {
      "keyName": "段落名稱",
      "keyPrompt": "段落的語義描述和抽取要求"
    }
  ]
}

關鍵使用規則

⚠️ 必須先構造Schema

如果使用者沒有提供schema，必須先根據使用者需求構造schema，然後再呼叫此工具。

LLM負責： 1. 理解使用者的抽取需求 2. 將需求轉換為符合格式的schema定義 3. 呼叫此工具執行抽取

Schema構造原則

1. keyName: 欄位的標識名稱，應簡潔明瞭
2. keyPrompt: 欄位的詳細描述，包含：
3. 欄位的含義
4. 資料格式要求（如"輸出純數字"、"帶單位"等）
5. 來源說明（如"從合併資產負債表提取"）
6. 特殊處理要求（如"取絕對值"、"單位轉換"等）

輸出格式

返回JSON格式的結構化抽取結果，包含： - 文本欄位的抽取值和溯源資訊 - 表格資料的二維陣列結構 - 段落內容的完整文本 - 每個抽取結果的來源頁碼和座標資訊

⚠️ 執行模式

此工具提交的是 DPA 文件規定的非同步欄位抽取任務：先呼叫 POST /parse 獲取 taskId，然後輪詢 GET /{taskId}/status，成功後再讀取 GET /{taskId}/result。

為了便於上層呼叫，工具預設會在本地幫你等待完成後直接返回結果（包含 data 中的 text、table、paragraph）。

注意：預設等待超時為 60 秒。如果文件較大、60 秒內未完成，工具會返回 taskId、當前 status 和提示資訊，供後續繼續查詢。

也可以傳入 async 模式立即返回 taskId，手動查詢結果。

步驟1：獲取 taskId（async模式）

工具返回格式：

{
  "taskId": "202603251633-8e44b4a2",
  "taskType": "extraction",
  "message": "欄位抽取任務已建立"
}

重要：請記錄返回的 taskId，用於後續查詢任務狀態和結果。

步驟2：查詢任務狀態

使用 document_get_result 工具查詢抽取結果：

{
  "tool": "document_get_result",
  "args": {
    "task_id": "202603251633-8e44b4a2"
  }
}

步驟3：解析結果

成功時返回的結構：

{
  "code": 200,
  "message": "檢索成功，召回內容已返回。",
  "data": {
    "text": [
      {
        "keyName": "本期營業收入",
        "keyValue": "500億元",
        "source": {
          "docUrl": "https://example.com/report.pdf",
          "pageNum": 3,
          "bbox": [100, 200, 300, 250]
        }
      }
    ],
    "table": [...],
    "paragraph": [...]
  }
}

完整呼叫流程示例

1. 呼叫 extract_structured_data：

輸入: /path/to/document.pdf, schema={...}
返回: {"taskId": "202603251633-abc123", "taskType": "extraction", "message": "欄位抽取任務已建立"}

1. 查詢結果：

輸入: task_id="202603251633-abc123"
返回: {"code": 200, "data": {"text": [...], "table": [...], "paragraph": [...]}}

返回欄位說明

呼叫示例

示例1：使用者直接給抽取需求（無schema）

使用者請求：

請從這份年報中提取公司的營業收入、去年同期營業收入、本期營業費用等資訊
小蔥技能站7w4.net，專業的AI技能分享平臺。

LLM首先構造Schema：

{
  "text": [
    {
      "keyName": "本期營業收入",
      "keyPrompt": "輸出純數字，且取絕對值。必須帶上單位。若專案值單位是百萬元，需要轉換為億元"
    },
    {
      "keyName": "去年同期營業收入",
      "keyPrompt": "輸出純數字，且取絕對值。必須帶上單位。若專案值單位是百萬元，需要轉換為億元"
    },
    {
      "keyName": "本期營業費用",
      "keyPrompt": "輸出純數字，且取絕對值。必須帶上單位。若專案值單位是百萬元，需要轉換為億元"
    },
    {
      "keyName": "去年同期營業費用",
      "keyPrompt": "輸出純數字，且取絕對值。必須帶上單位。若專案值單位是百萬元，需要轉換為億元"
    }
  ],
  "table": [],
  "paragraph": []
}

然後呼叫工具：

{
  "tool": "extract_structured_data_from_document",
  "args": {
    "document_url": "https://example.com/annual_report_2024.pdf",
    "schema": {
      "text": [
        {
          "keyName": "本期營業收入",
          "keyPrompt": "輸出純數字，且取絕對值。必須帶上單位。若專案值單位是百萬元，需要轉換為億元"
        },
        {
          "keyName": "去年同期營業收入",
          "keyPrompt": "輸出純數字，且取絕對值。必須帶上單位。若專案值單位是百萬元，需要轉換為億元"
        },
        {
          "keyName": "本期營業費用",
          "keyPrompt": "輸出純數字，且取絕對值。必須帶上單位。若專案值單位是百萬元，需要轉換為億元"
        },
        {
          "keyName": "去年同期營業費用",
          "keyPrompt": "輸出純數字，且取絕對值。必須帶上單位。若專案值單位是百萬元，需要轉換為億元"
        }
      ],
      "table": [],
      "paragraph": []
    }
  }
}

工具返回：

{
  "text": [
    {
      "keyName": "本期營業收入",
      "keyValue": "500億元",
      "source": {
        "docUrl": "https://example.com/annual_report_2024.pdf",
        "pageNum": 3,
        "bbox": [100, 200, 300, 250]
      }
    },
    {
      "keyName": "去年同期營業收入",
      "keyValue": "420億元",
      "source": {
        "docUrl": "https://example.com/annual_report_2024.pdf",
        "pageNum": 3,
        "bbox": [100, 260, 300, 310]
      }
    }
  ],
  "table": [],
  "paragraph": []
}

示例2：複雜文件 - 表格資料抽取

使用者請求：

從這份銀行資產負債表中提取同業存放的資料，包括本期和去年年底的數值

LLM構造Schema：

{
  "text": [],
  "table": [
    {
      "tableName": "合併及銀行資產負債表",
      "tableDescription": "銀行合併及本身的資產負債表",
      "tableColumn": [
        {
          "keyName": "序號",
          "keyPrompt": "依據表格順序增加序號，如1,2,3,4"
        },
        {
          "keyName": "專案",
          "keyPrompt": "僅採集下述專案：同業存放"
        },
        {
          "keyName": "專案值",
          "keyPrompt": "不同年份的專案值按照年份緊鄰排列，如果某一年為空值也按空值輸出，輸出純數字，且取絕對值"
        },
        {
          "keyName": "所屬時期",
          "keyPrompt": "從下述選擇專案所屬時期：本期、去年同期、前年同期、去年年底、前年年底"
        },
        {
          "keyName": "年份",
          "keyPrompt": "專案值對應時間，包括年份、月份、日期等"
        },
        {
          "keyName": "單位",
          "keyPrompt": "專案單位，比如：億元、百萬元、元等"
        }
      ]
    }
  ],
  "paragraph": []
}

呼叫工具：

{
  "tool": "extract_structured_data_from_document",
  "args": {
    "document_url": "https://example.com/bank_balance_sheet.pdf",
    "schema": {
      "table": [
        {
          "tableName": "合併及銀行資產負債表",
          "tableDescription": "銀行合併及本身的資產負債表",
          "tableColumn": [
            {"keyName": "序號", "keyPrompt": "依據表格順序增加序號，如1,2,3,4"},
            {"keyName": "專案", "keyPrompt": "僅採集下述專案：同業存放"},
            {"keyName": "專案值", "keyPrompt": "輸出純數字，且取絕對值"},
            {"keyName": "所屬時期", "keyPrompt": "從下述選擇：本期、去年同期、前年同期、去年年底"},
            {"keyName": "年份", "keyPrompt": "專案值對應時間"},
            {"keyName": "單位", "keyPrompt": "專案單位"}
          ]
        }
      ]
    }
  }
}

示例3：使用者已提供Schema

使用者請求：

請使用以下schema從文件中提取資料：
- 本期營業收入（單位：億元）
- 去年同期營業收入（單位：億元）
- 董事會制度（段落內容）

由於使用者已提供schema，直接呼叫：

{
  "tool": "extract_structured_data_from_document",
  "args": {
    "document_url": "https://example.com/company_report.pdf",
    "schema": {
      "text": [
        {
          "keyName": "本期營業收入",
          "keyPrompt": "輸出純數字，單位億元"
        },
        {
          "keyName": "去年同期營業收入",
          "keyPrompt": "輸出純數字，單位億元"
        }
      ],
      "paragraph": [
        {
          "keyName": "董事會制度",
          "keyPrompt": "公司的董事會制度相關資訊"
        }
      ],
      "table": []
    }
  }
}

完整Schema示例

以下是一個完整的schema示例，涵蓋文本、表格和段落三種類型：

{
  "paragraph": [
    {
      "keyName": "財務會計制度、利潤分配和審計",
      "keyPrompt": "公司的財務會計制度、利潤分配和審計相關資訊"
    },
    {
      "keyName": "董事會制度",
      "keyPrompt": "公司的董事會制度相關資訊"
    }
  ],
  "text": [
    {
      "keyPrompt": "輸出純數字，且取絕對值。必須帶上單位。若專案值單位是百萬元，需要轉換為億元",
      "keyName": "本期營業收入"
    },
    {
      "keyPrompt": "輸出純數字，且取絕對值。必須帶上單位。若專案值單位是百萬元，需要轉換為億元",
      "keyName": "去年同期營業收入"
    },
    {
      "keyPrompt": "輸出純數字，且取絕對值。必須帶上單位。若專案值單位是百萬元，需要轉換為億元",
      "keyName": "本期營業費用"
    }
  ],
  "table": [
    {
      "tableName": "合併及銀行資產負債表",
      "tableDescription": "",
      "tableColumn": [
        {
          "keyPrompt": "依據表格順序增加序號，如1,2,3,4",
          "keyName": "序號"
        },
        {
          "keyPrompt": "僅採集下述專案：同業存放",
          "keyName": "專案"
        },
        {
          "keyPrompt": "輸出純數字，且取絕對值",
          "keyName": "專案值"
        },
        {
          "keyPrompt": "從下述選擇：本期、去年同期、前年同期、去年年底",
          "keyName": "所屬時期"
        },
        {
          "keyPrompt": "專案值對應時間",
          "keyName": "年份"
        },
        {
          "keyPrompt": "專案單位",
          "keyName": "單位"
        }
      ]
    }
  ]
}

工具定義

{
  "name": "extract_structured_data_from_document",
  "description": "結構化欄位抽取工具 - 基於schema從文件中抽取結構化欄位，支援文本、表格、段落三種類型",
  "parameters": {
    "type": "object",
    "properties": {
      "document_url": {
        "type": "string",
        "description": "文件的URL地址，支援PDF、Word、Excel、圖片等格式"
      },
      "schema": {
        "type": "object",
        "description": "抽取規則定義，必須包含text、table、paragraph三個欄位，每個欄位都是陣列",
        "properties": {
          "text": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "keyName": {"type": "string"},
                "keyPrompt": {"type": "string"}
              },
              "required": ["keyName", "keyPrompt"]
            }
          },
          "table": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tableName": {"type": "string"},
                "tableDescription": {"type": "string"},
                "tableColumn": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "keyName": {"type": "string"},
                      "keyPrompt": {"type": "string"}
                    },
                    "required": ["keyName", "keyPrompt"]
                  }
                }
              },
              "required": ["tableName", "tableDescription", "tableColumn"]
            }
          },
          "paragraph": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "keyName": {"type": "string"},
                "keyPrompt": {"type": "string"}
              },
              "required": ["keyName", "keyPrompt"]
            }
          }
        },
        "required": ["text", "table", "paragraph"]
      }
    },
    "required": ["document_url", "schema"]
  }
}

這個Skill質量中規中矩，整體可用。文件寫得比較清晰，對工具的功能和使用方法說明得比較詳細，示例也比較豐富。但美中不足的是缺少FAQ和常見問題解答，遇到問題時可能找不到答案；也沒有錯誤處理的說明，不知道出問題了該怎麼辦。功能本身比較專一，就是從文件裡提取結構化資料，對於有這個需求的使用者來說比較實用。