API経由でrokadocを利用する

本ページではrokadocをAPI経由で利用する方法について説明します。
APIを利用することで、文書変換からRAGまでの一連の処理を自動化し、任意のアプリケーションと接続することが可能になります。

前提

本チュートリアルではHTTPクライアントとしてcurlコマンドを利用します。もしご利用の環境でcurlコマンドが使えない場合は、任意のHTTPクライアントを利用してください。
変換対象のPDFファイルを用意してください。
APIキーを取得していることが前提です。APIキーの取得方法はこちらをご覧ください

1. ファイルを変換APIでアップロードする

rokadocの変換機能をAPI経由で利用することができます。以下ではcurlコマンドを使ってPDFファイルをアップロードし、変換ジョブを開始します。

ROKADOC_API_KEY="YOUR_API_KEY" # 確認したAPIキー

curl -X 'POST' \
'https://beta-api.rokadoc.ntt.com/v1/api/conversions' \
-H "api-key: $ROKADOC_API_KEY" \
-F 'upload_file=@sample.pdf'

正常にリクエストが完了すると以下のようなレスポンスが返ってきます。

{
    "code": 202,
    "status": "Pending",
    "conversion_id": "your_conversion_id_here"
}

conversion_idは後のステップで必要になるため保存してください。

2. 変換ステータスを確認する

変換は非同期で実行されるため、ステータス確認APIで処理状況を監視します。

CONVERSION_ID="your_conversion_id_here" # 1.で取得したconversion_id

curl -X 'GET' \
"https://beta-api.rokadoc.ntt.com/v1/user/conversions/${CONVERSION_ID}/status" \
-H "api-key: $ROKADOC_API_KEY" \
-H 'accept: application/json'

処理中の場合は以下のようなレスポンスが返ってきます：

{
    "code": 200,
    "data": {
        "status": "Running",
        "conversion_id": "your_conversion_id_here",
        "document_name": "sample.pdf"
    }
}

statusが"Succeeded"になるまで定期的に確認してください。

3. 変換結果を取得する

変換が完了したら、結果を取得します。

tips

coordinatesはページ上の要素の位置を示す左上基準の座標情報（[[xmin,ymin],[xmax,ymax]]）です。
widthとheightはPDFのページサイズを示します。

curl -X 'GET' \
"https://beta-api.rokadoc.ntt.com/v1/user/conversions/${CONVERSION_ID}/document" \
-H "api-key: $ROKADOC_API_KEY" \
-H 'accept: application/json'

正常に完了すると、変換されたテキストデータとレイアウト情報を含む詳細な結果が返ってきます：

{
    "code": 200,
    "data": {
        "conversion_id": "your_conversion_id_here",
        "document_name": "sample.pdf"
    },
    "roka_response": {
      "meta": {
        "separate_method": "page"
      },
      "units": [
        {
          "unit": 1,
          "title": "",
          "body": "",
          "elements": [
            {
              "type": "title",
              "coordinates": [[305.0, 254.0],[802.0, 343.0]],
              "text": "<ここにタイトルが入ります>",
              "page": 1,
              "reading_order": 1
            },
            {
              "type": "text",
              "coordinates": [[303.0, 522.0],[2044.0, 593.0]],
              "text": "<ここにテキストが入ります>",
              "page": 1,
              "reading_order": 2
            }
          ],
          "description": "<elementsが統合された全量テキスト>",
          "width": 2481,
          "height": 3508
      ]
    }
  }
}

4. RAGで対話的に質問する

変換したドキュメントに対してRAG（Retrieval-Augmented Generation）を使って質問することができます。

message=$(echo '[{"content":"NTTドコモビジネスに社名変更したのはいつですか"}]' | base64 -w 0)

curl -X POST \
"https://beta-api.rokadoc.ntt.com/v1/api/rag" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "api-key: $ROKADOC_API_KEY" \
--data-urlencode message=$message \
-d search_top_k=3

RAGの結果として、関連する文書片と共にLLMによる回答が返ってきます：

{
  "search_result": [
    {
      "context": "<チャンク化されたテキスト>",
      "unit": {
        "unit": 1,
        "title": "",
        "body": "",
        "elements": [
          {
            "type": "title",
            "coordinates": [[305.0,254.0],[802.0,343.0]],
            "text": "<ここにタイトルが入ります>",
            "page": 1,
            "reading_order": 1
          }],
        "description": "<elementsが統合されたチャンク化される前の全量テキスト>",
        "width": 2481,
        "height": 3508
      },
      "pdf_name": "sample.pdf",
      "page_number": 1,
      "roka_algorithm": null,
      "conversion_id": "xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "user_id": "xxxxxxxxxxxx",
      "tags": []
    }
  ],
  "chat_response": "<ここにAIの回答が入ります>",
  "chat_request": "<ここに質問内容が入ります>",
}

まとめ

以上でrokadocを使った文書変換からRAGまでの一連のAPI利用方法が完了しました。この流れを自動化することで、大量の文書を効率的に処理し、対話的に情報を取得することが可能になります。

API仕様の詳細についてはAPIリファレンスを参照ください。

API経由でrokadocを利用する

1. ファイルを変換APIでアップロードする​

2. 変換ステータスを確認する​

3. 変換結果を取得する​

4. RAGで対話的に質問する​

まとめ​

1. ファイルを変換APIでアップロードする

2. 変換ステータスを確認する

3. 変換結果を取得する

4. RAGで対話的に質問する

まとめ