polaris-datainsight-doc-extract

Polaris AI DataInsight — Doc Extract スキル

Polaris AI DataInsight Doc Extract API を使用して、Word、PowerPoint、Excel、HWP、HWPX ファイルからテキスト、画像、表、グラフ、図形、数式などを抽出し、すべてを構造化された unifiedSchema JSON として返します。API を 1 回呼び出すだけで、手動で解析することなく、ドキュメント全体の構造を取得できます。

---

このスキルを使う場面

• 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 分
レート制限	1 分あたり 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 を使って展開してください。
• table と chart の要素では content.csv を利用できるため、データ抽出に最も便利な形式です。
• レート制限は 1 分あたり 10 リクエストです。複数のファイルを処理する場合は、呼び出しの間に遅延（例：time.sleep(6)）を入れてください。
• boundaryBox を使うと、ページ上で各要素が配置されている場所を特定できます。レイアウト分析に役立ちます。
• API キーは必ず環境変数（POLARIS_DATAINSIGHT_API_KEY）に保存し、コードに直接記述しないでください。

---

一般的なユースケース

• ドキュメント検索システム：全文を抽出してベクトルデータベースに保存し、セマンティック検索に利用します
• レポート分析の自動化：PPTX/DOCX レポートから表やグラフのデータを収集して分析します
• HWP のデジタル化：HWP/HWPX ドキュメントを構造化された機械可読データに変換します
• RAG パイプラインの構築：ドキュメントを分割し、LLM ベースの質疑応答システムで利用します
• データ移行：従来の Office ドキュメントから表やグラフのデータをデータベースに移行します

---

ライセンスと利用規約

• スキル定義： この SKILL.md ファイルは、Apache 2.0 ライセンスの下で提供されています。
• サービスへのアクセス： DataInsight API を利用するには、有効なサブスクリプションまたはライセンスキーが必要です。
• 制限事項： API エンドポイントの無許可の再配布や認証の回避は固く禁じられています。
• サポート： ライセンスに関するお問い合わせは、https://datainsight.polarisoffice.com をご覧ください。