YomiToku インストールマニュアル¶
本マニュアルでは、YomiToku のライセンス種別（サブスクリプション版・買い切りオンライン認証版・買い切りオフライン認証版）に応じたインストール手順を説明します。不明な点がございましたら、support@mlism.comまでお問い合わせください。
🚩 事前準備¶
以下を事前に準備してください。
- Python 3.10 以上
- PyTorch（ご自身の GPU 環境に合わせてインストール。GPU 環境は VRAM 8GB 以上推奨）
GITHUB_PERSONAL_TOKEN（ライセンス文書に記載）YOMITOKU_LICENSE_KEY（ライセンス文書に記載）YOMITOKU_SECRET_KEY（ライセンス文書に記載。2025/6/2 以降の v1.2.5 以降にサポート）
📌 GitHub 経由で YomiToku-Pro をインストール¶
バージョンを指定する場合¶
pip install git+https://${GITHUB_PERSONAL_TOKEN}@github.com/MLism-Inc/yomitoku-pro.git@${YOMITOKU_VERSION}
- バージョン指定は任意
リポジトリをクローンする場合¶
※ソースコードの内容を確認するためにリポジトリをクローンすることも可能です。
📌 認証方式について¶
| ライセンス種別 | 認証方式 | 機器の変更 |
|---|---|---|
| サブスクリプション | ライセンスサーバーとの HTTPS 通信によるオンライン認証 | 自由に変更可 |
| 買い切り（オンライン） | ライセンスサーバーに機器情報を事前登録後、HTTPS 通信でオンライン機器認証 | 自由に変更可 |
| 買い切り（オフライン） | ライセンスサーバーに機器情報を事前登録後、サーバー発行の認証トークンによるローカル認証 | MLism への依頼が必要 |
オンライン機器認証（買い切りオンライン）¶
導入先サーバーからライセンスサーバーへの HTTPS 通信が可能な場合に使用します。
- 機器情報の取得：
get_device_infoコマンドで導入先サーバーのハードウェア情報を収集し、暗号化して保存します。 - 機器情報の登録：
set_device_infoコマンドでライセンスサーバーに機器フィンガープリントを登録します。 - 機器認証：YomiToku 実行時に自動でライセンスサーバーへ機器情報を送信し、登録済みフィンガープリントと照合します。
代理機器認証 / オフライン機器認証（買い切りオフライン）¶
導入先サーバーがライセンスサーバーと直接通信できない場合に使用します。インターネット接続可能な代理機器を介してトークンを取得し、ローカルで認証します。
- 機器情報の取得：導入先サーバーで
get_device_infoを実行し、機器情報ファイルを取得します。 - 機器情報の登録とトークン取得：機器情報ファイルをインターネット接続可能な代理機器へ転送し、
set_device_info --get_tokenでライセンスサーバーに登録後、認証トークンを受け取ります。 - 機器認証：認証トークンファイルを導入先サーバーへ転送し、
YOMITOKU_DEVICE_TOKEN環境変数に設定します。YomiToku 実行時にトークン内の情報と機器フィンガープリントをローカルで照合します（ライセンスサーバーへの通信は不要）。
クラウドインスタンス（VM）の機器認証¶
AWS EC2 などのクラウドインスタンスで買い切りライセンスを使用する場合、IMDS（Instance Metadata Service）からインスタンスのメタ情報を取得して機器フィンガープリントを生成します。
- 機器情報の取得：
get_device_infoコマンドが IMDS（IMDSv2）に問い合わせ、インスタンス ID・AMI ID・インスタンスタイプなどのメタ情報を取得します。 - 機器情報の登録：
set_device_infoでライセンスサーバーに登録し、認証トークンを受け取ります。 - 機器認証：YomiToku 実行時に IMDS から再度メタ情報を取得し、トークン情報と照合します。
機器フィンガープリントについて¶
機器フィンガープリントは、YOMITOKU_ENV 環境変数の値に応じて収集されたハードウェア情報の SHA-256 ハッシュです。登録時と実行時で同じ情報が生成されることを確認することで機器を認証します。
YOMITOKU_ENV |
収集される機器情報 |
|---|---|
on-premise |
ホスト名・OS 情報・CPU 種別／アーキテクチャ／コア数（CUDA が利用可能な場合は GPU UUID） |
aws / aws-ec2 |
EC2 インスタンス ID・AMI ID・インスタンスタイプ・プライベート IP アドレス（IMDSv2 経由） |
aws-ecs |
ECS タスク ARN・コンテナ ARN（ECS Task Metadata Endpoint v4 経由。環境変数 ECS_CONTAINER_METADATA_URI_V4 が必要） |
🔧 環境変数設定の例¶
Linux / macOS¶
export YOMITOKU_LICENSE_KEY="あなたのライセンスキー"
export YOMITOKU_SECRET_KEY="あなたのシークレットキー"
export YOMITOKU_ENV="aws" # 買い切り版のみ(on-premise, aws, aws-ec2, aws-ecs, azureのいずれか)
Windows (PowerShell)¶
$env:YOMITOKU_LICENSE_KEY = "あなたのライセンスキー"
$env:YOMITOKU_SECRET_KEY = "あなたのシークレットキー"
$env:YOMITOKU_ENV = "aws" # 買い切り版のみ(on-premise, aws, aws-ec2, aws-ecs, azureのいずれか)
📥 ライセンス別インストール手順¶
🟢 サブスクリプションライセンス¶
サブスクリプションライセンスでは追加の設定は不要です。環境変数を設定し、以下の手順でインストールを進めてください。
🔵 買い切りオンライン認証ライセンス¶
① デバイス情報の取得¶
| オプション | 必須 | 説明 |
|---|---|---|
-o |
✔ | デバイス情報を保存するディレクトリ |
② デバイス情報の登録¶
set_device_info -k ${YOMITOKU_LICENSE_KEY} -s ${YOMITOKU_SECRET_KEY} -f ./device_info/device_info_*.txt
| オプション | 必須 | 説明 |
|---|---|---|
-k |
✔ | ライセンスキー |
-s |
シークレットキー | |
-f |
✔ | 取得したデバイス情報ファイルのパス |
🔴 買い切りオフライン認証ライセンス¶
① デバイス情報の取得（YomiToku を実行する PC で実行）¶
| オプション | 必須 | 説明 |
|---|---|---|
-o |
✔ | デバイス情報を保存するディレクトリ |
② デバイス情報の登録とトークン取得（インターネット接続可能な PC で実行）¶
set_device_info -k ${YOMITOKU_LICENSE_KEY} -s ${YOMITOKU_SECRET_KEY} -f ./device_info/device_info_*.txt -o ./token_dir --get_token
| オプション | 必須 | 説明 |
|---|---|---|
-k |
✔ | ライセンスキー |
-s |
シークレットキー | |
-f |
✔ | 取得したデバイス情報ファイルのパス |
-o |
✔ | トークン保存ディレクトリ |
--get_token |
✔ | 認証トークン取得 |
③ トークンを導入先サーバーに配置し、環境変数を設定¶
④ トークンの有効期限の確認と再取得¶
Warning
update_token コマンドは、有効期限付きのデバイストークンを用いた機器認証ライセンス (買い切りオフライン認証ライセンスなど) でのみ使用できます。サブスクリプションライセンスや、有効期限のないトークンを使用するライセンスでは本コマンドを実行する必要はありません。
デバイストークンには有効期限が埋め込まれており、期限切れが近づいた場合はトークンを再取得する必要があります。update_token コマンドは、既存トークンの有効期限を確認し、残り日数が閾値以下の場合のみライセンスサーバーからトークンを再取得します。
| オプション | 必須 | 説明 |
|---|---|---|
--license_key |
ライセンスキー (省略時は環境変数 YOMITOKU_LICENSE_KEY を使用) |
|
--secret_key |
シークレットキー (省略時は環境変数 YOMITOKU_SECRET_KEY を使用) |
|
--token_path |
有効期限を確認する既存トークンファイルのパス (省略時は環境変数 YOMITOKU_DEVICE_TOKEN を使用) |
|
--out |
新しいトークンを保存するディレクトリパス (省略時は YOMITOKU_DEVICE_TOKEN の親ディレクトリ、さらに未設定時は .) |
|
--threshold_days |
残り有効日数がこの値以下になった場合に再取得する (デフォルト: 7) |
|
--force |
有効期限に関わらずトークンを再取得する | |
--check_only |
有効期限の確認のみ行い、トークンの再取得は行わない |
Note
YOMITOKU_DEVICE_TOKEN が設定されている状態で update_token を引数なしで実行すると、現在使用中のトークンを同じディレクトリに上書き保存します。
使用例¶
① 有効期限のみを確認する（再取得は行わない）
現在のトークンの有効期限と残り日数をログに表示するだけで、トークンの再取得は行いません。運用開始前の動作確認や、残り日数のモニタリングに利用できます。
② 残り日数が閾値以下の場合のみ再取得する
環境変数 YOMITOKU_LICENSE_KEY / YOMITOKU_SECRET_KEY / YOMITOKU_DEVICE_TOKEN が設定されている状態で実行すると、現在のトークンの残り有効日数を確認し、7 日以下の場合のみライセンスサーバーから新しいトークンを取得して既存トークンと同じディレクトリに上書き保存します。
③ 有効期限に関わらず強制的に再取得する
機器構成を変更した直後など、有効期限に関係なくトークンを取り直したい場合に使用します。
④ 取得したトークンの保存先を明示する
デフォルトでは YOMITOKU_DEVICE_TOKEN の親ディレクトリにトークンが保存されますが、--out で任意のディレクトリを指定することも可能です。
⑤ 環境変数を使用せず引数ですべて指定する
環境変数を使いたくない場合は、ライセンスキー・シークレットキー・既存トークンのパスをすべてコマンドライン引数で指定できます。
update_token \
--license_key "あなたのライセンスキー" \
--secret_key "あなたのシークレットキー" \
--token_path /path/to/device_token.txt \
--out /path/to/token_dir \
--threshold_days 7
マルチGPU環境で特定のGPUを認証キーに指定する¶
複数のGPUが搭載されたマシンでは、デフォルトではすべてのGPU情報をまとめて機器認証に使用します。特定の単一GPUの情報のみを認証キーとして使用したい場合は、以下の手順で YOMITOKU_GPU_UUID を設定したうえで、上記①〜③の手順を実施してください。
Note
YOMITOKU_GPU_UUID は認証に使用するGPUを指定するだけであり、他のGPUが推論に使用できなくなるわけではありません。すべてのGPUは引き続き推論に利用可能です。
1. GPU一覧の取得
get_device_list コマンドを実行して、搭載されているGPUの情報を確認します。
以下のように、各GPUのインデックス、UUID、デバイス名が表示されます。
[{'index': 0, 'name': 'NVIDIA A100-SXM4-40GB', 'uuid': 'GPU-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'},
{'index': 1, 'name': 'NVIDIA A100-SXM4-40GB', 'uuid': 'GPU-yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy'}]
2. 環境変数にUUIDを設定
認証に使用するGPUのUUIDを環境変数 YOMITOKU_GPU_UUID に設定します。
Linux / macOS:
Windows (PowerShell):
3. デバイス情報の取得と登録
環境変数を設定した状態で、上記①〜③の手順を実行してください。指定したGPUの情報のみが機器情報として使用されます。
📦 モデルの事前準備（インターネット非接続環境向け）¶
インターネット接続可能な環境でモデルを事前にダウンロードします。MLism/フォルダにモデルがダウンロードされるので、実行時のカレントディレクトリの直下にMLism/を配置してください。
モデルの指定 以下のオプションを利用して、特定のモデルファイルのみをダウンロードできます。
| オプション | 必須 | 説明 |
|---|---|---|
--hf_hub_repo |
ダウンロード対象のモデルレポジトリ（指定がない場合は全モデル） |
| モデルの種類 | モデルのリポジトリ | 採用バージョン | 備考 |
|---|---|---|---|
| 文字列検出モデル | MLism/yomitoku-text-detector-dbnet-v1 | v1.0.0 ~ v1.1.0 | 手書き文字非対応 |
| 文字列検出モデル | MLism/yomitoku-text-detector-dbnet-v2 | v1.2.0 ~ | |
| 文字列認識モデル | MLism/yomitoku-text-recognizer-parseq-small-v1 | v1.0.0 ~ | 手書き文字非対応 |
| 文字列認識モデル | MLism/yomitoku-text-recognizer-parseq-small-v4 | v1.4.0 ~ | |
| 文字列認識モデル | MLism/yomitoku-text-recognizer-parseq-middle-v1 | v1.0.0 ~ v1.1.0 | 手書き文字非対応 |
| 文字列認識モデル | MLism/yomitoku-text-recognizer-parseq-middle-v2 | v1.2.0 ~ v1.2.7 | |
| 文字列認識モデル | MLism/yomitoku-text-recognizer-parseq-middle-v3 | v1.3.0 ~ | |
| 文字列認識モデル | MLism/yomitoku-text-recognizer-parseq-middle-v4 | v1.4.0 ~ | |
| 文字列認識モデル | MLism/yomitoku-text-recognizer-parseq-short-v4 | v1.4.0 ~ | |
| 文字列認識モデル | MLism/yomitoku-text-recognizer-parseq-tiny-v4 | v1.4.0 ~ | |
| レイアウト解析モデル | MLism/yomitoku-layout-parser-rtdtrv2-v1 | v1.0.0 ~ v1.1.0 | 6 クラス |
| レイアウト解析モデル | MLism/yomitoku-layout-parser-rtdtrv2-v2 | v1.2.0 ~ v1.2.7 | 6 クラス |
| レイアウト解析モデル | MLism/yomitoku-layout-parser-rtdtrv2-v3 | v1.3.0 ~ | 15 クラス(詳細解析) |
| テーブル解析モデル | MLism/yomitoku-table-structure-recognizer-rtdtrv2-v1 | v1.0.0 ~ | |
| テーブルセル解析モデル | MLism/yomitoku-cell_detector_rtdtrv2-beta | v1.5.0 ~ | TableSemanticParser用 |
| 回転補正モデル | MLism/yomitoku-rotate-detector-efficientnetbo-v1 | v1.2.4 ~ |
📌 uv でのインストール¶
GPU を利用する場合:
🐳 Docker での実行¶
リポジトリを clone した上で、ローカルビルドを行います。
イメージのビルド¶
GPU 版 (AMD64 + NVIDIA CUDA)¶
CPU 版¶
コンテナ起動¶
GPU 版¶
docker run -it --gpus all \
-e YOMITOKU_LICENSE_KEY=${YOMITOKU_LICENSE_KEY} \
-e YOMITOKU_SECRET_KEY=${YOMITOKU_SECRET_KEY} \
-v $(pwd):/workspace \
yomitoku-pro:gpu /bin/bash
CPU 版¶
docker run -it \
-e YOMITOKU_LICENSE_KEY=${YOMITOKU_LICENSE_KEY} \
-e YOMITOKU_SECRET_KEY=${YOMITOKU_SECRET_KEY} \
-v $(pwd):/workspace \
yomitoku-pro:cpu /bin/bash
デバイストークンの設定（オフライン認証）¶
オフライン環境でデバイストークンを使用して認証する場合は、Dockerfile を直接編集する必要があります。
- デバイストークンファイル (
device_token.txt) をリポジトリルートに配置します - 使用する Dockerfile (
dockerfile.gpuまたは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 には使用する環境名を設定してください。
Note
API サーバーとして利用する場合は サーバー ページを参照してください。docker/ ディレクトリにサーバー専用の Dockerfile が用意されています。