サーバー¶

YomiToku-Pro は REST API サーバーとして起動し、HTTP 経由でドキュメント解析を実行できます。

セットアップ¶

インストール¶

uv pip install -e ".[server]"

環境変数¶

変数名	必須	説明
`YOMITOKU_LICENSE_KEY`	Yes	ライセンスキー
`YOMITOKU_SECRET_KEY`	Yes	シークレットキー
`YOMITOKU_DEVICE_TOKEN`	No	オフライン認証用デバイストークンファイルパス
`YOMITOKU_ENV`	No	環境名

サーバー起動¶

Document Analyzer サーバー¶

yomitoku_server document_analyzer [--host 0.0.0.0] [--port 8000] [--device cuda]

Table Semantic Parser サーバー¶

yomitoku_server table_semantic_parser [--host 0.0.0.0] [--port 8000] [--device cuda]

オプション¶

オプション	デフォルト	説明
`--host`	`0.0.0.0`	バインドするホスト
`--port`	`8000`	バインドするポート
`--device`	自動検出	使用デバイス (`cuda`, `cpu`)
`-l`, `--lite`	-	軽量モデルを使用して高速に推論（CPU環境では自動的に有効）
`--request-timeout`	`600`	1リクエストあたりの処理タイムアウト（秒）。超過時は HTTP 504 を返却
`--max-pages`	無制限	1リクエストで処理可能な PDF ページ数の上限。超過時は HTTP 400 を返却
`--max-body-size-mb`	`100`	1リクエストのボディサイズ上限（MB）。超過時は HTTP 413 を返却
`--max-long-side`	無制限	1ページ/画像あたりの長辺の最大ピクセル数。超過時は HTTP 400 を返却
`--max-in-flight`	`8`	同時受付リクエスト数の上限。超過時は HTTP 503 を返却

並列実行とワーカー数について

GPU リソース競合を避けるため、サーバーは1プロセス内で asyncio.Lock を用いて推論処理を直列化しています。このロックはプロセスを跨がないため、サーバーは常に 1ワーカー（workers=1） で起動されます。スループットを上げる場合は、複数プロセス（複数 GPU またはコンテナ）で水平スケールしてください。

リクエストの公平性

GPU ロックは ページ単位で release/再取得 されるため、大規模 PDF 処理中でも後続の小さなリクエストが各ページの間に割り込めます（FIFO 順）。また --max-in-flight で同時受付数を制限することで、滞留メモリと待機時間の上限を制御できます。

HTTP ステータスコード¶

/invocations エンドポイントが返すステータスコード一覧:

コード	意味	発生条件
200	OK	解析成功
400	Bad Request	不正なファイル形式、`--max-pages` / `--max-long-side` 超過
413	Payload Too Large	リクエストボディが `--max-body-size-mb` を超過
500	Internal Server Error	サーバ内部エラー
503	Service Unavailable	同時受付数 (`--max-in-flight`) 超過
504	Gateway Timeout	処理時間が `--request-timeout` を超過
507	Insufficient Storage	GPU メモリ不足（エラーコード `5007 GPU_OUT_OF_MEMORY`）

API エンドポイント¶

`GET /ping`¶

ヘルスチェック用エンドポイント。

レスポンス:

{"status": "healthy", "message": "Service is running"}

`POST /invocations`¶

ドキュメント画像または PDF を解析します。

リクエスト:

Content-Type ヘッダーにファイル形式を指定
リクエストボディにバイナリデータを送信

サポートする Content-Type:

application/pdf
image/jpeg
image/png
image/tiff

リクエスト例:

curl -X POST http://localhost:8000/invocations \
     -H "Content-Type: image/jpeg" \
     --data-binary @sample.jpg

curl -X POST http://localhost:8000/invocations \
     -H "Content-Type: application/pdf" \
     --data-binary @document.pdf

クライアント CLI¶

yomitoku_client コマンドを使用すると、サーバーにファイルを送信し、処理結果を指定フォーマットでエクスポートできます。

使い方¶

yomitoku_client document_analyzer <入力ファイル> [オプション]
yomitoku_client table_semantic_parser <入力ファイル> [オプション]

オプション¶

オプション	デフォルト	説明
`--url`	`http://localhost:8000`	サーバーの URL
`-f`, `--format`	`json`	出力形式 (`json`, `csv`, `html`, `md`, `dict`)。カンマ区切りで複数指定可
`-o`, `--outdir`	`results`	出力ディレクトリ
`--encoding`	`utf-8`	出力ファイルのエンコーディング
`--combine`	-	PDF の全ページを1つのファイルにマージして出力
`--figure`	-	出力に図を含める
`--figure_letter`	-	図内の文字も出力に含める
`--figure_width`	`200`	出力する図の幅（ピクセル）
`--figure_dir`	`figures`	図画像の保存ディレクトリ
`-v`, `--vis`	-	解析結果の可視化画像（レイアウト・OCR）を保存
`--vis_dir`	`""`	可視化画像の保存サブディレクトリ（`--outdir` 配下）
`--font_path`	同梱フォント	OCR 可視化用フォントファイルのパス
`--ignore_line_break`	-	出力から改行を除去
`--dpi`	`200`	PDF 読み込み時の DPI
`--pages`	全ページ	処理するページ指定（例: `1,2,5-10`）

使用例¶

# Document Analyzer: JSON 形式でエクスポート
yomitoku_client document_analyzer sample.jpg -f json -o results

# Document Analyzer: Markdown と HTML を同時にエクスポート
yomitoku_client document_analyzer document.pdf -f md,html -o results

# Document Analyzer: PDF の全ページを1つの Markdown にマージ
yomitoku_client document_analyzer document.pdf -f md --combine -o results

# Document Analyzer: 図を含めて Markdown でエクスポート
yomitoku_client document_analyzer sample.jpg -f md --figure -o results

# Document Analyzer: 可視化画像（レイアウト・OCR）も保存
yomitoku_client document_analyzer sample.jpg -f json -v -o results

# Table Semantic Parser: JSON と dict でエクスポート
yomitoku_client table_semantic_parser form.jpg -f json,dict -o results

# 別のホスト・ポートに接続
yomitoku_client document_analyzer sample.jpg --url http://192.168.1.100:8080

Document Analyzer の出力形式¶

形式	説明
`json`	解析結果の完全な JSON
`csv`	表構造を CSV に変換
`html`	段落・表を含む HTML ドキュメント
`md`	Markdown 形式

Table Semantic Parser の出力形式¶

形式	説明
`json`	解析結果の完全な JSON
`dict`	テーブルのセルをキー・値の辞書形式に変換した JSON

クライアント CLI のエラーコード¶

コード	エラー名	説明	対処
7001	`CLIENT_FILE_NOT_FOUND`	入力ファイルが見つからない	ファイルパスを確認してください
7002	`CLIENT_UNSUPPORTED_INPUT_FORMAT`	対応していない入力ファイル形式	JPG, PNG, BMP, TIFF, PDF のいずれかを使用してください
7003	`CLIENT_UNSUPPORTED_FILE_FORMAT`	Content-Type にマッピングできない拡張子	対応する拡張子のファイルを使用してください
7004	`CLIENT_CONNECTION_ERROR`	サーバーに接続できない	サーバーが起動しているか、URL が正しいか確認してください
7005	`CLIENT_TIMEOUT`	サーバーからの応答がタイムアウト（60秒）	サーバーの負荷状況を確認してください
7006	`CLIENT_REQUEST_FAILED`	ネットワークエラーによりリクエスト失敗	ネットワーク接続を確認してください
7007	`CLIENT_SERVER_ERROR`	サーバーがエラーステータスを返した	サーバーのログを確認してください（400: リクエスト不正、500: 内部エラー）
7008	`CLIENT_INVALID_JSON_RESPONSE`	サーバーの応答が不正な JSON	サーバーのバージョン・状態を確認してください
7009	`CLIENT_EMPTY_RESULT`	サーバーの応答に解析結果が含まれていない	入力ファイルの内容やサーバーのログを確認してください

API ドキュメント¶

サーバー起動中は、以下の URL で API ドキュメントを参照できます。

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

サーバーを起動せずに静的な API リファレンスを確認する場合は以下を参照してください。

OpenAPI スキーマの再生成¶

API の定義を変更した場合は、以下のスクリプトで docs/ 配下の OpenAPI JSON を更新してください。

python scripts/generate_openapi.py --output-dir docs

Docker での利用¶

Docker を利用する場合は、まずリポジトリを clone してください。

1. リポジトリの clone¶

git clone https://github.com/MLism-Inc/yomitoku-pro.git
cd yomitoku-pro

2. 環境変数の設定¶

.env ファイルを docker/ ディレクトリに作成するか、環境変数を直接設定します。

export YOMITOKU_LICENSE_KEY="your-license-key"
export YOMITOKU_SECRET_KEY="your-secret-key"

3. ビルド & 起動¶

cd docker

各プラットフォームに対して Document Analyzer (_da なし) と Table Semantic Parser (_tsp) のサービスが用意されています。

サービス名	Dockerfile	プラットフォーム	Analyzer	ポート
`arm64_cpu`	`Dockerfile.cpu`	linux/arm64	Document Analyzer	8000
`arm64_cpu_tsp`	`Dockerfile.cpu`	linux/arm64	Table Semantic Parser	8001
`amd64_cpu`	`Dockerfile.cpu`	linux/amd64	Document Analyzer	8000
`amd64_cpu_tsp`	`Dockerfile.cpu`	linux/amd64	Table Semantic Parser	8001
`amd64_gpu`	`Dockerfile.gpu`	linux/amd64	Document Analyzer	8000
`amd64_gpu_tsp`	`Dockerfile.gpu`	linux/amd64	Table Semantic Parser	8001

ARM64 CPU (Apple Silicon):

# Document Analyzer のみ
docker compose up arm64_cpu --build

# Table Semantic Parser のみ
docker compose up arm64_cpu_tsp --build

# 両方同時起動
docker compose up arm64_cpu arm64_cpu_tsp --build

AMD64 CPU:

docker compose up amd64_cpu --build
docker compose up amd64_cpu_tsp --build

AMD64 GPU (NVIDIA):

docker compose up amd64_gpu --build
docker compose up amd64_gpu_tsp --build

Note

GPU サービス (amd64_gpu, amd64_gpu_tsp) は NVIDIA CUDA ベースイメージを使用するため、AMD64 環境でのみ動作します。ARM64 や GPU なしの環境では CPU サービスを利用してください。

デバイストークンの設定（オフライン認証）¶

オフライン環境でデバイストークンを使用して認証する場合は、Dockerfile を直接編集する必要があります。

手順:

デバイストークンファイル (device_token.txt) をリポジトリルートに配置します
使用する Dockerfile (docker/Dockerfile.gpu または docker/Dockerfile.cpu) を開き、末尾付近のコメントアウトされた行を有効化します

# 変更前（コメントアウト状態）
#COPY device_token.txt ${server_dir}/device_token.txt
#ENV YOMITOKU_DEVICE_TOKEN=${server_dir}/device_token.txt
#ENV YOMITOKU_ENV=${ENVIRONMENT}

# 変更後（コメントを外す）
COPY device_token.txt ${server_dir}/device_token.txt
ENV YOMITOKU_DEVICE_TOKEN=${server_dir}/device_token.txt
ENV YOMITOKU_ENV=production

YOMITOKU_ENV には使用する環境名を設定してください。

カスタムコマンド¶

ANALYZER_TYPE ビルド引数を使って、ビルド時に Analyzer の種類を切り替えることもできます。

# Table Semantic Parser として直接ビルド
docker build --build-arg ANALYZER_TYPE=table_semantic_parser -f docker/Dockerfile.gpu -t yomitoku-server:tsp .
docker run yomitoku-server:tsp

サーバー¶

セットアップ¶

インストール¶

環境変数¶

サーバー起動¶

Document Analyzer サーバー¶

Table Semantic Parser サーバー¶

オプション¶

HTTP ステータスコード¶

API エンドポイント¶

GET /ping¶

POST /invocations¶

クライアント CLI¶

使い方¶

オプション¶

使用例¶

Document Analyzer の出力形式¶

Table Semantic Parser の出力形式¶

クライアント CLI のエラーコード¶

API ドキュメント¶

OpenAPI スキーマの再生成¶

Docker での利用¶

1. リポジトリの clone¶

2. 環境変数の設定¶

3. ビルド & 起動¶

デバイストークンの設定（オフライン認証）¶

カスタムコマンド¶

`GET /ping`¶

`POST /invocations`¶