コンテンツにスキップ

サーバー

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]

Studio複合APIサーバー

yomitoku_server studio [--host 127.0.0.1] [--port 8000] [--device cuda]

StudioサーバーはDocument AnalyzerとTable Semantic Parserの両パイプラインを保持します。Text DetectorとText Recognizerだけを共有し、document_analyzer・table_semantic_parserの各サーバーとは別プロセスで動作します。

オプション

オプション デフォルト 説明
--host 0.0.0.0 バインドするホスト
--port 8000 バインドするポート
--device 自動検出 使用デバイス (cuda, cpu)
-l, --lite - 軽量モデルを使用して高速に推論(CPU環境では自動的に有効)
--tr_name デフォルトモデル テキスト認識モデル名(例: parseqv5, parseqv5-tiny-dynw, parseqv4)。指定時はデフォルト/--lite の認識モデルより優先
--td_name デフォルトモデル テキスト検出モデル名(例: dbnetv2_1, dbnet)。指定時はデフォルトの検出モデルより優先
--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 を返却

次のオプションはstudioサブコマンドだけで使用できます。

オプション デフォルト 説明
--no-auth - Studio APIの認証を明示的に無効化
--api-key-file - 自動生成したStudio APIキーを新規0600ファイルへ出力
--cors-origin https://yomitoku-studio.mlism.com ブラウザからの接続を許可するOrigin。複数回指定可能

Studio接続用オプション、APIキー、CORSの詳細はStudio API 接続基盤を参照してください。

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

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"

Studio APIを起動する場合は、StudioからのBearer認証に使うAPIキーも設定します。APIキー本体は16文字以上で指定してください。

export YOMITOKU_STUDIO_API_KEYS="studio-user:replace-with-a-random-api-key"

docker/.envを使用する場合は次の形式で記載します。このファイルはGitへコミットしないでください。

YOMITOKU_LICENSE_KEY=your-license-key
YOMITOKU_SECRET_KEY=your-secret-key
YOMITOKU_STUDIO_API_KEYS=studio-user:replace-with-a-random-api-key
# Vercel Previewなど、公開版Studio以外から接続する場合だけ指定
YOMITOKU_CORS_ORIGINS=https://preview-name.vercel.app

YOMITOKU_STUDIO_API_KEYSはProのライセンスキーとは別の値です。キー形式とCORSの詳細はStudio API接続設定を参照してください。

3. ビルド & 起動

cd docker

各プラットフォームに対して Studio複合API (_studio)、Document Analyzer、Table Semantic Parser (_tsp) のサービスが用意されています。

サービス名 Dockerfile プラットフォーム Analyzer ポート
arm64_cpu_studio Dockerfile.cpu linux/arm64 Studio複合API 127.0.0.1:8000
arm64_cpu Dockerfile.cpu linux/arm64 Document Analyzer 8000
arm64_cpu_tsp Dockerfile.cpu linux/arm64 Table Semantic Parser 8001
amd64_cpu_studio Dockerfile.cpu linux/amd64 Studio複合API 127.0.0.1:8000
amd64_cpu Dockerfile.cpu linux/amd64 Document Analyzer 8000
amd64_cpu_tsp Dockerfile.cpu linux/amd64 Table Semantic Parser 8001
amd64_gpu_studio Dockerfile.gpu linux/amd64 Studio複合API 127.0.0.1:8000
amd64_gpu Dockerfile.gpu linux/amd64 Document Analyzer 8000
amd64_gpu_tsp Dockerfile.gpu linux/amd64 Table Semantic Parser 8001

Studio APIは安全のためホストの127.0.0.1にのみ公開されます。同一マシンのStudioから接続先をhttp://127.0.0.1:8000に設定して使用します。

Studio APIの起動

ARM64 CPU (Apple Silicon):

docker compose up --build arm64_cpu_studio

AMD64 CPU:

docker compose up --build amd64_cpu_studio

AMD64 GPU (NVIDIA):

docker compose up --build amd64_gpu_studio

初回ビルドではPythonパッケージと推論モデルを取得するため時間がかかります。2回目以降はDockerのビルドキャッシュが使用されます。

起動確認

別のターミナルでコンテナの状態とログを確認できます。以下はAMD64 CPUの例です。

docker compose ps amd64_cpu_studio
docker compose logs -f amd64_cpu_studio

ログには次のようにhttp://0.0.0.0:8000と表示されますが、これはコンテナ内部で全インターフェースからの接続を待ち受けていることを示します。Studioやホストのブラウザへ指定する接続先ではありません。

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

アクセスログの127.0.0.1はコンテナ内部のヘルスチェック、172.18.0.1のようなアドレスはDocker bridge経由のホストを示す場合があります。これらのログ上のアドレスにかかわらず、同一ホスト上のStudioからはhttp://127.0.0.1:8000へ接続してください。

モデルの初期化が完了したら、/pingとcapabilitiesを確認します。

curl http://127.0.0.1:8000/ping

curl http://127.0.0.1:8000/studio/v1/capabilities \
  -H "Authorization: Bearer replace-with-a-random-api-key"

Studioの接続設定には次の値を入力します。

項目 値
接続先URL http://127.0.0.1:8000
APIキー YOMITOKU_STUDIO_API_KEYSの:より後ろの値

停止と再起動

# 停止
docker compose stop amd64_cpu_studio

# 再起動
docker compose start amd64_cpu_studio

# コンテナとComposeネットワークを削除
docker compose down

他のプラットフォームではamd64_cpu_studioを起動したサービス名に置き換えてください。

従来APIの起動

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_studio, amd64_gpu, amd64_gpu_tsp) は NVIDIA CUDA ベースイメージを使用するため、AMD64 環境でのみ動作します。NVIDIA Container Toolkitが利用できない環境、ARM64、GPUなしの環境では CPU サービスを利用してください。

デバイストークンの設定(オフライン認証)

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

手順:

  1. デバイストークンファイル (device_token.txt) をリポジトリルートに配置します
  2. 使用する 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