polaris-datainsight-doc-extract

Polaris AI DataInsight — 文档提取技能

使用 Polaris AI DataInsight 文档提取 API，从 Word、PowerPoint、Excel、HWP 和 HWPX 文件中提取文本、图像、表格、图表、形状、公式等内容，并将所有内容作为结构化的 unifiedSchema JSON 返回。只需调用一次 API，即可获取完整的文档结构，无需手动解析。

---

何时使用此技能

• 用户想从 DOCX、PPTX、XLSX、HWP 或 HWPX 文件中提取文本、表格、图表或图像
• 用户需要了解文档结构（页数、元素类型、位置数据等）
• 提取的数据将用于 RAG 流水线、数据分析工作流或自动化任务
• 表格数据需要转换为 CSV，或图表数据需要按系列和标签拆分
• 用户需要解析页眉、页脚、公式或形状等特殊元素

---

此技能的功能

1. 身份验证 — 通过 x-po-di-apikey 标头向 Polaris DataInsight API 进行身份验证。
2. 上传并提取 — 以 multipart/form-data POST 请求发送文件，并提取完整的文档结构。
3. 解析 ZIP 响应 — API 返回一个 ZIP 文件；将其解压并加载其中的 unifiedSchema JSON。
4. 提供结构化数据 — 返回按页面和元素类型（文本、表格、图表、图像、形状、公式等）组织的 JSON。
5. 支持多种使用模式 — 支持提取全文、将表格转换为 CSV、生成 RAG 分块等。

---

使用方法

前提条件

获取 API 密钥：在 https://datainsight.polarisoffice.com 注册并生成 API 密钥。

身份验证：在每个请求中将 API 密钥作为标头发送。

Header: x-po-di-apikey: $POLARIS_DATAINSIGHT_API_KEY

设置环境变量：

export POLARIS_DATAINSIGHT_API_KEY="your-api-key-here"

限制

项目	限制
支持的格式	HWP、HWPX、DOCX、PPTX、XLSX
文件大小上限	25 MB
超时时间	10 分钟
速率限制	每分钟 10 个请求

基本用法

端点：

POST https://datainsight-api.polarisoffice.com/api/v1/datainsight/doc-extract

使用 Python 提取文档：

import requests
import json
import zipfile
import io

def extract_document(file_path: str, api_key: str) -> dict:
    with open(file_path, "rb") as f:
        response = requests.post(
            "https://datainsight-api.polarisoffice.com/api/v1/datainsight/doc-extract",
            headers={"x-po-di-apikey": api_key},
            files={"file": f}
        )

    if response.status_code != 200:
        raise Exception(f"API error: {response.status_code} - {response.text}")

    # Response is a ZIP file
    zip_buffer = io.BytesIO(response.content)
    with zipfile.ZipFile(zip_buffer) as z:
        json_files = [name for name in z.namelist() if name.endswith('.json')]
        if json_files:
            with z.open(json_files[0]) as jf:
                return json.load(jf)

    raise Exception("No JSON found in ZIP")

# Example usage
import os
api_key = os.environ["POLARIS_DATAINSIGHT_API_KEY"]
schema = extract_document("report.docx", api_key)
print(f"Extracted {schema['totalPages']} pages")

使用 curl 提取：

curl -X POST "https://datainsight-api.polarisoffice.com/api/v1/datainsight/doc-extract" \
  -H "x-po-di-apikey: $POLARIS_DATAINSIGHT_API_KEY" \
  -F "[email protected]" \
  --output result.zip

unzip result.zip -d result/
cat result/*.json | python -m json.tool

---

高级用法

响应结构（unifiedSchema）

根节点：

{
  "docName": "sample.docx",
  "totalPages": 3,
  "pages": [ ... ]
}

页面（pages[]）：

{
  "pageNum": 1,
  "pageWidth": 595.3,
  "pageHeight": 842.0,
  "extractionSummary": {
    "text": 5, "image": 2, "table": 1, "chart": 1
  },
  "elements": [ ... ]
}

元素类型（elements[].type）：

type	说明
text	文本块
image	图像
table	表格
chart	图表
shape	形状
equation	公式
header / footer	页眉 / 页脚

常见元素结构：

{
  "type": "text",
  "id": "te1",
  "boundaryBox": { "left": 40, "top": 80, "right": 300, "bottom": 120 },
  "content": { "text": "Body content here" }
}

表格内容：

{
  "content": {
    "html": "<table>...</table>",
    "csv": "Header1,Header2\nValue1,Value2",
    "json": [
      {
        "metrics": { "rowaddr": 0, "coladdr": 0, "rowspan": 1, "colspan": 1 },
        "para": [{ "content": [{ "text": "Cell content" }] }]
      }
    ]
  }
}

图表内容：

{
  "content": {
    "chart_type": "column",
    "title": "Annual Sales Comparison",
    "x_axis_labels": ["Q1", "Q2", "Q3", "Q4"],
    "series_names": ["2023", "2024"],
    "series_values": [[100, 200, 150, 300], [120, 220, 180, 320]],
    "csv": "Quarter,2023,2024\nQ1,100,120\nQ2,200,220"
  }
}

使用模式

提取所有文本：

def get_all_text(schema: dict) -> str:
    texts = []
    for page in schema.get("pages", []):
        for el in page.get("elements", []):
            if el["type"] == "text" and el.get("content", {}).get("text"):
                texts.append(el["content"]["text"])
    return "\n".join(texts)

将表格提取为 CSV：

def get_tables_as_csv(schema: dict) -> list:
    tables = []
    for page in schema.get("pages", []):
        for el in page.get("elements", []):
            if el["type"] == "table":
                csv_data = el.get("content", {}).get("csv", "")
                if csv_data:
                    tables.append(csv_data)
    return tables

生成 RAG 分块：

def make_rag_chunks(schema: dict) -> list:
    chunks = []
    doc_name = schema.get("docName", "")
    for page in schema.get("pages", []):
        for el in page.get("elements", []):
            text = el.get("content", {}).get("text") or el.get("content", {}).get("csv") or ""
            if text.strip():
                chunks.append({
                    "source": doc_name,
                    "page": page["pageNum"],
                    "type": el["type"],
                    "text": text.strip()
                })
    return chunks

---

示例

用户：“将这份 DOCX 报告中的所有表格数据提取为 CSV。”

输出：

import os
schema = extract_document("report.docx", os.environ["POLARIS_DATAINSIGHT_API_KEY"])
tables = get_tables_as_csv(schema)
for i, csv_data in enumerate(tables):
    print(f"=== Table {i+1} ===")
    print(csv_data)

=== Table 1 ===
Quarter,Revenue,Cost
Q1,1200,800
Q2,1500,900

=== Table 2 ===
Item,Amount
Labor,500
Operations,300

**灵感来源：**Polaris Office DataInsight API 文档和工作流。

---

提示

• 响应始终是一个 ZIP 文件。不要尝试直接将 response.content 解析为 JSON——应先使用 zipfile.ZipFile 将其解压。
• content.csv 适用于 table 和 chart 元素，是最便捷的数据提取格式。
• 速率限制为每分钟 10 个请求。处理多个文件时，请在调用之间添加延迟（例如 time.sleep(6)）。
• 使用 boundaryBox 确定每个元素在页面上的位置，这对布局分析很有用。
• 始终将 API 密钥存储在环境变量（POLARIS_DATAINSIGHT_API_KEY）中，切勿将其硬编码。

---

常见用例

• 文档搜索系统：提取全文并存储到向量数据库中，以进行语义搜索
• 自动化报告分析：从 PPTX/DOCX 报告中收集表格和图表数据，用于分析
• HWP 数字化：将 HWP/HWPX 文档转换为结构化、机器可读的数据
• RAG 流程搭建：将文档拆分成多个片段，用于基于大模型的问答系统
• 数据迁移：将旧版 Office 文档中的表格和图表数据迁移到数据库

---

许可证与条款

• 技能定义： 此 SKILL.md 文件采用 Apache 2.0 许可证提供。
• 服务访问： 使用 DataInsight API 需要有效的订阅或许可证密钥。
• 限制： 严禁未经授权重新分发 API 端点或绕过身份验证。
• 支持： 有关许可事宜，请访问 https://datainsight.polarisoffice.com。