init

.dockerignore

@@ -0,0 +1,11 @@
+.git
+.venv
+__pycache__
+*.pyc
+.ruff_cache
+.pytest_cache
+archive
+tests
+docs
+*.md
+!README.md

.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+src/*.egg-info/
+dist/
+build/
+*.whl
+
+# Virtual environment
+.venv/
+
+# Build output
+node_modules/
+
+# Test
+test-results/
+playwright-report/
+.coverage
+htmlcov/
+coverage/
+
+# Logs
+logs/
+*.log
+archive/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+*.swp
+*.swo
+
+# Linter / Type checker cache
+.mypy_cache/
+.ruff_cache/
+
+# Environment variables
+.env
+.env.*
+
+# uv
+.python-version

DEVELOPMENT.md

@@ -0,0 +1,62 @@
+# 開発ガイド
+
+## セットアップ
+
+### Python
+
+```bash
+uv sync --dev
+```
+
+## ローカルでの起動
+
+コンテナや `Dockerfile` は不要です。リポジトリルートで依存関係を入れたうえで、`uvicorn` を直接起動します。
+
+1. **依存関係の同期**（未実施の場合）
+
+   ```bash
+   uv sync --dev
+   ```
+
+2. **Web サーバー起動**
+
+   ```bash
+   uv run uvicorn kuzushiji_ocr.web:app --reload --host 127.0.0.1 --port 8000
+   ```
+
+3. ブラウザで `http://127.0.0.1:8000` を開く。
+
+OCR 本体は Modal 上の Qwen2.5-VL（`vlm_app.py`）を呼び出すため、**初回から推論させるには**ローカルで `modal` にログイン済みであること、および `modal deploy src/kuzushiji_ocr/vlm_app.py` でアプリがデプロイ済みであることが必要です（詳細はルートの `README.md`）。
+
+Hugging Face Space 用の `Dockerfile` は、ローカル開発では使いません（Space 上での実行専用）。
+
+## リント・フォーマット
+
+[Ruff](https://docs.astral.sh/ruff/) を使用します（設定は `pyproject.toml` の `[tool.ruff]`）。
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+## テスト
+
+```bash
+uv run pytest
+```
+
+## ディレクトリ構成
+
+| パス | 内容 |
+|------|------|
+| `src/kuzushiji_ocr/` | Qwen2.5-VL ベースの本流（FastAPI `web.py`、`vlm_app.py`、テンプレート） |
+| `comparison/` | 別手法との比較用（PaddleOCR / GLM / NDL 古典籍OCR / Gemini などの Modal またはローカルスクリプト） |
+| `archive/pre-restructure-2026-04/` | 再編前のフラット構成のスナップショット |
+| `docs/` | 利用・設計メモ |
+| `tests/` | pytest |
+
+## Hugging Face Space
+
+ルートの `Dockerfile` で `kuzushiji_ocr.web:app` を `uvicorn` 起動します。Space の README に YAML フロントマターを含めているため、リポジトリをそのまま Docker Space に接続できます。
+
+**注意:** Space 上から Modal に接続するには、実行環境に `modal` の認証情報（トークン等）を安全に渡す必要があります。公開 Space ではシークレットの取り扱いに十分注意してください。

Dockerfile

@@ -0,0 +1,16 @@
+# Hugging Face Spaces（Docker SDK）用。ローカル開発は `uv run uvicorn ...` を参照。
+FROM python:3.12-slim-bookworm
+
+WORKDIR /app
+
+RUN pip install --no-cache-dir uv
+
+COPY pyproject.toml uv.lock ./
+COPY src ./src
+
+RUN uv sync --frozen --no-dev
+
+ENV PORT=7860
+EXPOSE 7860
+
+CMD ["uv", "run", "uvicorn", "kuzushiji_ocr.web:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

README.md

@@ -0,0 +1,60 @@
+---
+title: くずし字 OCR
+emoji: 📜
+colorFrom: gray
+colorTo: green
+sdk: docker
+pinned: false
+license: apache-2.0
+---
+
+# くずし字 OCR
+
+くずし字が含まれる画像をアップロードすると、Modal 上の Qwen2.5-VL により **bounding box 付き重畳画像** と **多段推論による解説テキスト** を返す Web アプリケーションです。
+
+## デモ（限定公開）
+
+Hugging Face Space でホストする場合は、このリポジトリを Space に接続し、**Docker** SDK でビルドしてください。ローカルと同様に `uvicorn` がポート **7860** で待ち受けます。
+
+## 要件
+
+- Python 3.10 以上
+- [uv](https://docs.astral.sh/uv/)（推奨）
+- Modal 利用時: アカウントと `modal` CLI、デプロイ済みの `src/kuzushiji_ocr/vlm_app.py`
+
+## ローカルでの起動
+
+依存関係のインストール:
+
+```bash
+uv sync --dev
+```
+
+Web サーバー:
+
+```bash
+uv run uvicorn kuzushiji_ocr.web:app --reload --port 8000
+```
+
+ブラウザで `http://127.0.0.1:8000` を開きます。
+
+## Modal（VLM 推論）
+
+事前に VLM アプリをデプロイしておきます。
+
+```bash
+modal deploy src/kuzushiji_ocr/vlm_app.py
+```
+
+詳細は `src/kuzushiji_ocr/vlm_app.py` のドキュメント文字列を参照してください。
+
+別モデル（PaddleOCR、GLM、NDL 古典籍OCR、Gemini など）で比較実験するスクリプトは `comparison/` にあります。
+
+## ドキュメント
+
+- [はじめに](docs/getting-started.md)
+- [開発者向け](DEVELOPMENT.md)
+
+## ライセンス
+
+Apache License 2.0 — [LICENSE](LICENSE)

comparison/Dockerfile.ndlkotenocr

@@ -0,0 +1,43 @@
+# NDL古典籍OCR (ndlkotenocr_cli) — Modal 用ビルド
+# 元: https://github.com/ndl-lab/ndlkotenocr_cli/blob/master/docker/Dockerfile
+# COPY の代わりにリポジトリを clone し、ビルドコンテキスト不要で再現可能にする
+
+FROM nvidia/cuda:12.1.1-cudnn8-devel-ubuntu22.04
+
+ENV PROJECT_DIR=/root/kotenocr_cli
+ENV FORCE_CUDA="1"
+ENV TORCH_CUDA_ARCH_LIST="7.5+PTX"
+ENV TORCH_NVCC_FLAGS="-Xfatbin -compress-all"
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN set -x \
+ && apt update \
+ && apt upgrade -y
+
+RUN set -x \
+ && apt update \
+ && apt -y install locales \
+ && locale-gen ja_JP.UTF-8
+ENV LANG ja_JP.UTF-8
+ENV LANGUAGE ja_JP:ja
+ENV LC_ALL ja_JP.UTF-8
+RUN localedef -f UTF-8 -i ja_JP ja_JP.utf8
+
+# Modal の関数ランタイムは PATH 上の `python` と `pip` を検出する（python3 / pip3 のみだと失敗する）
+RUN set -x && apt -y install libgl1-mesa-dev libglib2.0-0 zip git python3-pip wget python-is-python3 \
+ && ln -sf /usr/bin/pip3 /usr/bin/pip
+
+ARG NDLKOTEN_BRANCH=master
+RUN set -x && git clone --depth 1 --branch "${NDLKOTEN_BRANCH}" \
+    https://github.com/ndl-lab/ndlkotenocr_cli.git "${PROJECT_DIR}"
+
+RUN set -x && pip3 install --no-cache-dir torch==2.1.1 torchvision==0.16.1 torchaudio==2.1.1 torchtext==0.16.1 --index-url https://download.pytorch.org/whl/cu121
+RUN set -x \
+ && pip3 install --no-cache-dir -r ${PROJECT_DIR}/requirements.txt
+
+RUN set -x && wget -nc https://lab.ndl.go.jp/dataset/ndlkotensekiocr/trocr/model-ver2.zip -P ${PROJECT_DIR}/src/text_kotenseki_recognition/
+RUN set -x && wget -nc https://lab.ndl.go.jp/dataset/ndlkotensekiocr/layoutmodel/ndl_kotenseki_layout_ver3.pth -P ${PROJECT_DIR}/src/ndl_kotenseki_layout/models/
+RUN set -x && cd ${PROJECT_DIR}/src/text_kotenseki_recognition/ && unzip -o model-ver2.zip
+RUN set -x && pip3 install --no-cache-dir mmcv==2.1.0 -f https://download.openmmlab.com/mmcv/dist/cu121/torch2.1/index.html
+
+WORKDIR ${PROJECT_DIR}

comparison/glm_ocr_app.py

@@ -0,0 +1,272 @@
+"""
+GLM-OCR (0.9B) によるくずし字 OCR（Modal 上で実行）。
+
+特徴:
+  - わずか 0.9B パラメータで OmniDocBench v1.5 総合1位（94.62）
+  - T4 GPU（16GB VRAM）で動作可能（低コスト）
+
+前提:
+  - Modal アカウントと認証済み
+  - 初回はイメージビルドに時間がかかる（〜10 分）
+
+単一画像:
+  modal run comparison/glm_ocr_app.py --image-path ./sample.jpg
+
+ディレクトリ一括処理:
+  modal run comparison/glm_ocr_app.py --input-dir ./dataset/
+
+座標付き構造化出力（NDL OCR 互換 JSON）:
+  modal run comparison/glm_ocr_app.py --image-path ./sample.jpg --structured
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+import modal
+
+MODEL_ID = "zai-org/GLM-OCR"
+
+app = modal.App("kuzushiji-glm-ocr")
+
+hf_secret = modal.Secret.from_name("huggingface-secret")
+
+
+def _download_model():
+    from huggingface_hub import snapshot_download
+
+    snapshot_download(MODEL_ID)
+
+
+glm_image = (
+    modal.Image
+    .debian_slim(python_version="3.11")
+    .pip_install(
+        "torch>=2.5.0",
+        "torchvision>=0.20.0",
+        "transformers>=5.3.0",
+        "accelerate>=0.34.0",
+        "huggingface_hub",
+        "Pillow",
+    )
+    .run_function(_download_model, secrets=[hf_secret])
+)
+
+IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".tif", ".tiff", ".bmp", ".jp2"}
+
+DEFAULT_PROMPT = (
+    "この古典籍（くずし字）の画像に書かれている文字をすべて翻刻してください。\n"
+    "縦書きの場合は右から左の順で、行ごとに改行して出力してください。\n"
+    "読めない文字は□で示してください。翻刻テキストのみを出力し、説明は不要です。"
+)
+
+STRUCTURED_PROMPT = (
+    "この古典籍（くずし字）の画像に書かれている文字をすべて翻刻してください。\n"
+    "各テキスト行について、画像上のバウンディングボックス座標（ピクセル）と"
+    "翻刻テキストを以下の JSON 配列で出力してください。\n"
+    '形式: [[x1, y1, x2, y2, "翻刻テキスト"], ...]\n'
+    "座標は画像の左上を原点としたピクセル値です。\n"
+    "縦書きの場合は右の列から順に並べてください。読めない文字は□で示してください。\n"
+    "JSON のみを出力し、説明文は付けないでください。"
+)
+
+
+def _parse_structured_output(raw: str) -> list | None:
+    """VLM の生テキストから JSON を抽出し、NDL OCR 互換の
+    [[x1, y1, x2, y2, "text"], ...] 形式に正規化する。"""
+    match = re.search(r"\[.*\]", raw, re.DOTALL)
+    if not match:
+        return None
+    try:
+        data = json.loads(match.group())
+    except (json.JSONDecodeError, TypeError):
+        return None
+
+    result: list[list] = []
+    for item in data:
+        if isinstance(item, list) and len(item) >= 5:
+            result.append(item[:5])
+        elif isinstance(item, dict):
+            bbox = item.get("bbox", item.get("box", []))
+            text = item.get("text", item.get("content", ""))
+            if len(bbox) == 4:
+                result.append([*bbox, text])
+    return [result] if result else None
+
+
+MAX_SIDE = 1536
+
+
+def _fit_image(image, max_side: int = MAX_SIDE):
+    """長辺が max_side を超える場合にアスペクト比を維持してリサイズする。"""
+    w, h = image.size
+    if max(w, h) <= max_side:
+        return image
+    scale = max_side / max(w, h)
+    from PIL import Image as PILImage
+
+    return image.resize((int(w * scale), int(h * scale)), PILImage.LANCZOS)
+
+
+@app.cls(image=glm_image, gpu="A10G", timeout=60 * 60, memory=32768, secrets=[hf_secret])
+class GLMOCRInference:
+    @modal.enter()
+    def setup(self):
+        import torch
+        from transformers import AutoModelForImageTextToText, AutoProcessor
+
+        self.processor = AutoProcessor.from_pretrained(MODEL_ID, trust_remote_code=True)
+        self.model = AutoModelForImageTextToText.from_pretrained(
+            MODEL_ID,
+            dtype=torch.bfloat16,
+            device_map="auto",
+            trust_remote_code=True,
+        )
+
+    @modal.method()
+    def ocr_pages(
+        self,
+        pages: list[tuple[str, bytes]],
+        prompt: str = DEFAULT_PROMPT,
+        structured: bool = False,
+    ) -> dict[str, Any]:
+        import torch
+        from PIL import Image
+
+        effective_prompt = STRUCTURED_PROMPT if structured else prompt
+        max_tokens = 4096 if structured else 2048
+
+        texts: dict[str, str] = {}
+        jsons: dict[str, Any] = {}
+
+        for name, data in pages:
+            image = _fit_image(Image.open(io.BytesIO(data)).convert("RGB"))
+
+            messages = [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "image"},
+                        {"type": "text", "text": effective_prompt},
+                    ],
+                }
+            ]
+
+            text_input = self.processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+            inputs = self.processor(
+                text=[text_input],
+                images=[image],
+                return_tensors="pt",
+                padding=True,
+            ).to(self.model.device)
+
+            with torch.inference_mode():
+                output_ids = self.model.generate(**inputs, max_new_tokens=max_tokens)
+
+            trimmed = output_ids[0][inputs["input_ids"].shape[-1] :]
+            output = self.processor.decode(
+                trimmed,
+                skip_special_tokens=True,
+                clean_up_tokenization_spaces=False,
+            )
+
+            stem = Path(name).stem
+            texts[f"{stem}_main.txt"] = output
+
+            if structured:
+                parsed = _parse_structured_output(output)
+                if parsed is not None:
+                    jsons[f"{stem}.json"] = parsed
+
+        return {"txt": texts, "json": jsons}
+
+
+# ---------------------------------------------------------------------------
+# Local entrypoint
+# ---------------------------------------------------------------------------
+
+
+@app.local_entrypoint()
+def main(
+    image_path: str | None = None,
+    input_dir: str | None = None,
+    structured: bool = False,
+    prompt: str | None = None,
+) -> None:
+    """
+    例:
+      modal run comparison/glm_ocr_app.py --image-path ./page.jpg
+      modal run comparison/glm_ocr_app.py --input-dir ./dataset/
+      modal run comparison/glm_ocr_app.py --image-path ./page.jpg --structured
+    """
+    if input_dir:
+        _run_batch(input_dir, structured, prompt)
+    elif image_path:
+        _run_single(image_path, structured, prompt)
+    else:
+        print("用法:")
+        print("  modal run comparison/glm_ocr_app.py --image-path ./your.jpg")
+        print("  modal run comparison/glm_ocr_app.py --input-dir ./images/")
+        print("  modal run comparison/glm_ocr_app.py --image-path ./your.jpg --structured")
+
+
+def _run_single(image_path: str, structured: bool, prompt: str | None) -> None:
+    p = Path(image_path)
+    data = p.read_bytes()
+    print(f"推論中: {p.name} ({len(data)} bytes) [model={MODEL_ID}]")
+
+    inference = GLMOCRInference()
+    kwargs: dict[str, Any] = {"structured": structured}
+    if prompt:
+        kwargs["prompt"] = prompt
+    out = inference.ocr_pages.remote([(p.name, data)], **kwargs)
+    _print_results(out)
+
+
+def _run_batch(input_dir: str, structured: bool, prompt: str | None) -> None:
+    src = Path(input_dir)
+    if not src.is_dir():
+        print(f"ディレクトリが見つかりません: {input_dir}")
+        return
+
+    pages: list[tuple[str, bytes]] = []
+    for p in sorted(src.rglob("*")):
+        if p.is_file() and p.suffix.lower() in IMAGE_EXTS:
+            pages.append((p.name, p.read_bytes()))
+
+    if not pages:
+        print(f"画像が見つかりません: {input_dir}")
+        return
+
+    total_mb = sum(len(d) for _, d in pages) / 1024 / 1024
+    print(f"{len(pages)} 枚の画像を処理中 ({total_mb:.1f} MB) [model={MODEL_ID}] ...")
+
+    inference = GLMOCRInference()
+    kwargs: dict[str, Any] = {"structured": structured}
+    if prompt:
+        kwargs["prompt"] = prompt
+    out = inference.ocr_pages.remote(pages, **kwargs)
+    _print_results(out)
+
+
+def _print_results(out: dict[str, Any]) -> None:
+    texts = out.get("txt", {})
+    jsons = out.get("json", {})
+
+    if not texts and not jsons:
+        print("出力がありません。")
+        return
+
+    for name, text in texts.items():
+        print(f"--- {name} ---")
+        print(text[:2000] + ("..." if len(text) > 2000 else ""))
+
+    if jsons:
+        print("\n========== JSON 出力 ==========")
+        for name, obj in jsons.items():
+            print(f"--- {name} ---")
+            print(json.dumps(obj, ensure_ascii=False, indent=2)[:4000])

comparison/ndlkotenocr_app.py

@@ -0,0 +1,287 @@
+"""
+NDL古典籍OCR (ndlkotenocr_cli) を Modal 上で実行するアプリ。
+
+前提:
+  - Modal アカウントと `modal token new` などで認証済み
+
+デプロイ:
+  modal deploy comparison/ndlkotenocr_app.py
+
+ローカルから 1 枚試す:
+  modal run comparison/ndlkotenocr_app.py --image-path ./sample.jpg
+
+ディレクトリ一括処理（Volume 経由）:
+  modal run comparison/ndlkotenocr_app.py --input-dir ./dataset/
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+import modal
+
+DOCKERFILE = "Dockerfile.ndlkotenocr"
+
+app = modal.App("ndl-koten-ocr")
+
+# Dockerfile にローカル COPY が無いため、context は Dockerfile 所在ディレクトリで足りる
+koten_image = modal.Image.from_dockerfile(str(DOCKERFILE))
+
+vol = modal.Volume.from_name("ndl-koten-ocr-data", create_if_missing=True)
+VOL_PATH = "/data"
+IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".tif", ".tiff", ".bmp", ".jp2"}
+
+
+def _collect_outputs(
+    output_root: str,
+    input_basename: str,
+    layout_b: bool,
+) -> dict[str, Any]:
+    """output_root/<input_root名>/ 以下の txt / json を読み取る（-s b のときは各 bookid 配下）。"""
+    base = Path(output_root) / input_basename
+    texts: dict[str, str] = {}
+    jsons: dict[str, Any] = {}
+
+    def read_pair(txt_dir: Path, json_dir: Path, prefix: str) -> None:
+        if txt_dir.is_dir():
+            for p in sorted(txt_dir.glob("*.txt")):
+                key = f"{prefix}{p.name}" if prefix else p.name
+                texts[key] = p.read_text(encoding="utf-8", errors="replace")
+        if json_dir.is_dir():
+            for p in sorted(json_dir.glob("*.json")):
+                key = f"{prefix}{p.name}" if prefix else p.name
+                try:
+                    jsons[key] = json.loads(p.read_text(encoding="utf-8"))
+                except json.JSONDecodeError:
+                    jsons[key] = None
+
+    if layout_b:
+        for book_dir in sorted(base.iterdir()):
+            if not book_dir.is_dir():
+                continue
+            prefix = f"{book_dir.name}/"
+            read_pair(book_dir / "txt", book_dir / "json", prefix)
+    else:
+        read_pair(base / "txt", base / "json", "")
+
+    return {"txt": texts, "json": jsons}
+
+
+@app.function(volumes={VOL_PATH: vol})
+def upload_images(files: list[tuple[str, bytes]], input_subdir: str = "input") -> int:
+    """ローカルの画像を Volume にアップロードする。相対パスを維持する。"""
+    img_dir = Path(VOL_PATH) / input_subdir / "img"
+    img_dir.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for relpath, data in files:
+        dest = img_dir / relpath
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(data)
+        count += 1
+    vol.commit()
+    return count
+
+
+@app.function(
+    image=koten_image,
+    gpu="A10G",
+    timeout=60 * 60,
+    memory=32768,
+    volumes={VOL_PATH: vol},
+)
+def infer_from_volume(
+    input_subdir: str = "input",
+    output_subdir: str = "output",
+    input_structure: str = "s",
+    add_image_info: bool = False,
+) -> dict[str, Any]:
+    """Volume 上の画像に対して OCR 推論を実行し、結果も Volume に保存する。"""
+    vol.reload()
+    input_root = Path(VOL_PATH) / input_subdir
+    output_root = Path(VOL_PATH) / output_subdir
+
+    if output_root.exists():
+        shutil.rmtree(output_root)
+
+    cmd = [
+        "python3",
+        "main.py",
+        "infer",
+        str(input_root),
+        str(output_root),
+        "-s",
+        input_structure,
+    ]
+    if add_image_info:
+        cmd.append("-a")
+
+    subprocess.run(
+        cmd,
+        cwd="/root/kotenocr_cli",
+        env={**os.environ, "PYTHONUNBUFFERED": "1"},
+        check=True,
+    )
+
+    vol.commit()
+    return _collect_outputs(str(output_root), input_root.name, input_structure == "b")
+
+
+@app.function(
+    image=koten_image,
+    gpu="A10G",
+    timeout=60 * 60,
+    memory=32768,
+)
+def infer_pages(
+    pages: list[tuple[str, bytes]],
+    input_structure: str = "s",
+    add_image_info: bool = False,
+) -> dict[str, Any]:
+    """
+    複数ページを一度に推論する。
+
+    Args:
+        pages: (ファイル名, JPEG/PNG 等のバイト列) のリスト。構造 s のとき img 直下に並ぶ。
+        input_structure: ndlkotenocr_cli の -s と同じ（s=単一資料, b=複数 bookid）。
+        add_image_info: True のとき main.py に -a を付与（JSON 形式が変わる）。
+
+    Returns:
+        {"txt": {filename: text}, "json": {filename: object}}
+    """
+    if not pages:
+        return {"txt": {}, "json": {}}
+
+    work = Path("/tmp/ndl_koten_work")
+    input_root = work / "in"
+    output_root = work / "out"
+    if work.exists():
+        shutil.rmtree(work)
+    img_dir = input_root / "img"
+    img_dir.mkdir(parents=True)
+
+    for name, data in pages:
+        safe = Path(name).name
+        if not safe:
+            continue
+        (img_dir / safe).write_bytes(data)
+
+    layout_b = False
+    if input_structure == "b":
+        # 1 冊だけ: bookid フォルダを挟む（README の -s b 形式）
+        book = "book1"
+        nested = img_dir / book
+        nested.mkdir(parents=True)
+        for p in list(img_dir.iterdir()):
+            if p.is_file():
+                p.rename(nested / p.name)
+        input_structure_cli = "b"
+        layout_b = True
+    else:
+        input_structure_cli = input_structure
+
+    cmd = [
+        "python3",
+        "main.py",
+        "infer",
+        str(input_root),
+        str(output_root),
+        "-s",
+        input_structure_cli,
+    ]
+    if add_image_info:
+        cmd.append("-a")
+
+    subprocess.run(
+        cmd,
+        cwd="/root/kotenocr_cli",
+        env={**os.environ, "PYTHONUNBUFFERED": "1"},
+        check=True,
+    )
+
+    return _collect_outputs(str(output_root), input_root.name, layout_b)
+
+
+@app.local_entrypoint()
+def main(
+    image_path: str | None = None,
+    input_dir: str | None = None,
+    output_dir: str = "output",
+    structure: str = "s",
+) -> None:
+    """
+    例:
+      modal run comparison/ndlkotenocr_app.py --image-path ./page.jpg
+      modal run comparison/ndlkotenocr_app.py --input-dir ./dataset/
+    """
+    if input_dir:
+        _run_batch(input_dir, output_dir, structure)
+    elif image_path:
+        _run_single(image_path, structure)
+    else:
+        print("用法:")
+        print("  modal run comparison/ndlkotenocr_app.py --image-path ./your.jpg")
+        print("  modal run comparison/ndlkotenocr_app.py --input-dir ./images/")
+
+
+def _run_single(image_path: str, structure: str) -> None:
+    p = Path(image_path)
+    data = p.read_bytes()
+    print(f"推論中: {p.name} ({len(data)} bytes) ...")
+    out = infer_pages.remote([(p.name, data)], structure, add_image_info=False)
+    _print_results(out)
+
+
+def _run_batch(input_dir: str, output_dir: str, structure: str) -> None:
+    src = Path(input_dir)
+    if not src.is_dir():
+        print(f"ディレクトリが見つかりません: {input_dir}")
+        return
+
+    files: list[tuple[str, bytes]] = []
+    for p in sorted(src.rglob("*")):
+        if p.is_file() and p.suffix.lower() in IMAGE_EXTS:
+            relpath = str(p.relative_to(src))
+            files.append((relpath, p.read_bytes()))
+
+    if not files:
+        print(f"画像が見つかりません: {input_dir}")
+        return
+
+    total_mb = sum(len(d) for _, d in files) / 1024 / 1024
+    print(f"{len(files)} 枚の画像を Volume にアップロード中 ({total_mb:.1f} MB) ...")
+    count = upload_images.remote(files, input_subdir="input")
+    print(f"{count} 枚アップロード完了")
+
+    print("推論中 ...")
+    out = infer_from_volume.remote(
+        input_subdir="input",
+        output_subdir=output_dir,
+        input_structure=structure,
+    )
+    _print_results(out)
+    print(f"\n結果は Volume 'ndl-koten-ocr-data' の /{output_dir}/ にも保存済み")
+    print("  modal volume get ndl-koten-ocr-data <remote-path> <local-path>")
+
+
+def _print_results(out: dict[str, Any]) -> None:
+    texts = out.get("txt", {})
+    jsons = out.get("json", {})
+
+    if not texts and not jsons:
+        print("出力がありません。")
+        return
+
+    for name, text in texts.items():
+        print(f"--- {name} ---")
+        print(text[:2000] + ("..." if len(text) > 2000 else ""))
+
+    if jsons:
+        print("\n========== JSON 出力 ==========")
+        for name, obj in jsons.items():
+            print(f"--- {name} ---")
+            print(json.dumps(obj, ensure_ascii=False, indent=2)[:4000])

comparison/paddle_ocr_app.py

@@ -0,0 +1,277 @@
+"""
+PaddleOCR-VL-1.5 (0.9B) によるくずし字 OCR（Modal 上で実行）。
+
+特徴:
+  - 0.9B パラメータで OmniDocBench v1.5 スコア 94.5
+  - 109 言語対応（日本語含む）
+  - スキャン歪み・傾き・照明変動に強い（Real5-OmniDocBench 全5シナリオ1位）
+  - T4 GPU（16GB VRAM）で動作可能（低コスト）
+
+前提:
+  - Modal アカウントと認証済み
+  - 初回はイメージビルドに時間がかかる（〜10 分）
+
+単一画像:
+  modal run comparison/paddle_ocr_app.py --image-path ./sample.jpg
+
+ディレクトリ一括処理:
+  modal run comparison/paddle_ocr_app.py --input-dir ./dataset/
+
+座標付き構造化出力（NDL OCR 互換 JSON）:
+  modal run comparison/paddle_ocr_app.py --image-path ./sample.jpg --structured
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+import modal
+
+MODEL_ID = "PaddlePaddle/PaddleOCR-VL-1.5"
+
+app = modal.App("kuzushiji-paddle-ocr")
+
+hf_secret = modal.Secret.from_name("huggingface-secret")
+
+
+def _download_model():
+    from huggingface_hub import snapshot_download
+
+    snapshot_download(MODEL_ID)
+
+
+paddle_image = (
+    modal.Image
+    .debian_slim(python_version="3.11")
+    .pip_install(
+        "torch>=2.5.0",
+        "torchvision>=0.20.0",
+        "transformers>=4.49.0",
+        "accelerate>=0.34.0",
+        "qwen-vl-utils>=0.0.8",
+        "Pillow",
+        "huggingface_hub",
+    )
+    .run_function(_download_model, secrets=[hf_secret])
+)
+
+IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".tif", ".tiff", ".bmp", ".jp2"}
+
+_MIME_MAP = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+    ".bmp": "image/bmp",
+}
+
+DEFAULT_PROMPT = (
+    "この古典籍（くずし字）の画像に書かれている文字をすべて翻刻してください。\n"
+    "縦書きの場合は右から左の順で、行ごとに改行して出力してください。\n"
+    "読めない文字は□で示してください。翻刻テキストのみを出力し、説明は不要です。"
+)
+
+STRUCTURED_PROMPT = (
+    "この古典籍（くずし字）の画像に書かれている文字をすべて翻刻してください。\n"
+    "各テキスト行について、画像上のバウンディングボックス座標（ピクセル）と"
+    "翻刻テキストを以下の JSON 配列で出力してください。\n"
+    '形式: [[x1, y1, x2, y2, "翻刻テキスト"], ...]\n'
+    "座標は画像の左上を原点としたピクセル値です。\n"
+    "縦書きの場合は右の列から順に並べてください。読めない文字は□で示してください。\n"
+    "JSON のみを出力し、説明文は付けないでください。"
+)
+
+
+def _parse_structured_output(raw: str) -> list | None:
+    """VLM の生テキストから JSON を抽出し、NDL OCR 互換の
+    [[x1, y1, x2, y2, "text"], ...] 形式に正規化する。"""
+    match = re.search(r"\[.*\]", raw, re.DOTALL)
+    if not match:
+        return None
+    try:
+        data = json.loads(match.group())
+    except (json.JSONDecodeError, TypeError):
+        return None
+
+    result: list[list] = []
+    for item in data:
+        if isinstance(item, list) and len(item) >= 5:
+            result.append(item[:5])
+        elif isinstance(item, dict):
+            bbox = item.get("bbox", item.get("box", []))
+            text = item.get("text", item.get("content", ""))
+            if len(bbox) == 4:
+                result.append([*bbox, text])
+    return [result] if result else None
+
+
+@app.cls(image=paddle_image, gpu="T4", timeout=60 * 60, memory=16384, secrets=[hf_secret])
+class PaddleOCRInference:
+    @modal.enter()
+    def setup(self):
+        import torch
+        from transformers import AutoModelForImageTextToText, AutoProcessor
+
+        self.processor = AutoProcessor.from_pretrained(
+            MODEL_ID,
+            min_pixels=256 * 28 * 28,
+            max_pixels=1280 * 28 * 28,
+        )
+        self.model = AutoModelForImageTextToText.from_pretrained(
+            MODEL_ID,
+            dtype=torch.bfloat16,
+            device_map="auto",
+        )
+
+    @modal.method()
+    def ocr_pages(
+        self,
+        pages: list[tuple[str, bytes]],
+        prompt: str = DEFAULT_PROMPT,
+        structured: bool = False,
+    ) -> dict[str, Any]:
+        import torch
+        from qwen_vl_utils import process_vision_info
+
+        effective_prompt = STRUCTURED_PROMPT if structured else prompt
+        max_tokens = 4096 if structured else 2048
+
+        texts: dict[str, str] = {}
+        jsons: dict[str, Any] = {}
+
+        for name, data in pages:
+            b64 = base64.b64encode(data).decode()
+            suffix = Path(name).suffix.lower()
+            mime = _MIME_MAP.get(suffix, "image/jpeg")
+
+            messages = [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "image", "image": f"data:{mime};base64,{b64}"},
+                        {"type": "text", "text": effective_prompt},
+                    ],
+                }
+            ]
+
+            text_input = self.processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+            image_inputs, video_inputs = process_vision_info(messages)
+            inputs = self.processor(
+                text=[text_input],
+                images=image_inputs,
+                videos=video_inputs,
+                padding=True,
+                return_tensors="pt",
+            ).to(self.model.device)
+
+            with torch.inference_mode():
+                output_ids = self.model.generate(**inputs, max_new_tokens=max_tokens)
+
+            trimmed = output_ids[0][inputs["input_ids"].shape[-1] :]
+            output = self.processor.decode(
+                trimmed,
+                skip_special_tokens=True,
+                clean_up_tokenization_spaces=False,
+            )
+
+            stem = Path(name).stem
+            texts[f"{stem}_main.txt"] = output
+
+            if structured:
+                parsed = _parse_structured_output(output)
+                if parsed is not None:
+                    jsons[f"{stem}.json"] = parsed
+
+        return {"txt": texts, "json": jsons}
+
+
+# ---------------------------------------------------------------------------
+# Local entrypoint
+# ---------------------------------------------------------------------------
+
+
+@app.local_entrypoint()
+def main(
+    image_path: str | None = None,
+    input_dir: str | None = None,
+    structured: bool = False,
+    prompt: str | None = None,
+) -> None:
+    """
+    例:
+      modal run comparison/paddle_ocr_app.py --image-path ./page.jpg
+      modal run comparison/paddle_ocr_app.py --input-dir ./dataset/
+      modal run comparison/paddle_ocr_app.py --image-path ./page.jpg --structured
+    """
+    if input_dir:
+        _run_batch(input_dir, structured, prompt)
+    elif image_path:
+        _run_single(image_path, structured, prompt)
+    else:
+        print("用法:")
+        print("  modal run comparison/paddle_ocr_app.py --image-path ./your.jpg")
+        print("  modal run comparison/paddle_ocr_app.py --input-dir ./images/")
+        print("  modal run comparison/paddle_ocr_app.py --image-path ./your.jpg --structured")
+
+
+def _run_single(image_path: str, structured: bool, prompt: str | None) -> None:
+    p = Path(image_path)
+    data = p.read_bytes()
+    print(f"推論中: {p.name} ({len(data)} bytes) [model={MODEL_ID}]")
+
+    inference = PaddleOCRInference()
+    kwargs: dict[str, Any] = {"structured": structured}
+    if prompt:
+        kwargs["prompt"] = prompt
+    out = inference.ocr_pages.remote([(p.name, data)], **kwargs)
+    _print_results(out)
+
+
+def _run_batch(input_dir: str, structured: bool, prompt: str | None) -> None:
+    src = Path(input_dir)
+    if not src.is_dir():
+        print(f"ディレクトリが見つかりません: {input_dir}")
+        return
+
+    pages: list[tuple[str, bytes]] = []
+    for p in sorted(src.rglob("*")):
+        if p.is_file() and p.suffix.lower() in IMAGE_EXTS:
+            pages.append((p.name, p.read_bytes()))
+
+    if not pages:
+        print(f"画像が見つかりません: {input_dir}")
+        return
+
+    total_mb = sum(len(d) for _, d in pages) / 1024 / 1024
+    print(f"{len(pages)} 枚の画像を処理中 ({total_mb:.1f} MB) [model={MODEL_ID}] ...")
+
+    inference = PaddleOCRInference()
+    kwargs: dict[str, Any] = {"structured": structured}
+    if prompt:
+        kwargs["prompt"] = prompt
+    out = inference.ocr_pages.remote(pages, **kwargs)
+    _print_results(out)
+
+
+def _print_results(out: dict[str, Any]) -> None:
+    texts = out.get("txt", {})
+    jsons = out.get("json", {})
+
+    if not texts and not jsons:
+        print("出力がありません。")
+        return
+
+    for name, text in texts.items():
+        print(f"--- {name} ---")
+        print(text[:2000] + ("..." if len(text) > 2000 else ""))
+
+    if jsons:
+        print("\n========== JSON 出力 ==========")
+        for name, obj in jsons.items():
+            print(f"--- {name} ---")
+            print(json.dumps(obj, ensure_ascii=False, indent=2)[:4000])

comparison/vision_app.py

@@ -0,0 +1,139 @@
+"""
+Gemini API を使った古典籍 OCR（ローカル実行）。
+
+前提:
+  - Gemini API キーを取得済み（https://aistudio.google.com/apikey）
+  - 環境変数 GEMINI_API_KEY に設定:
+      export GEMINI_API_KEY='your-api-key'
+
+単一画像:
+  uv run python comparison/vision_app.py --image-path ./sample.jpg
+
+ディレクトリ一括処理:
+  uv run python comparison/vision_app.py --input-dir ./dataset/ --output-dir ./output/
+
+プロンプトのカスタマイズ:
+  uv run python comparison/vision_app.py --image-path ./sample.jpg --prompt "この画像の文字を読んでください"
+"""
+
+from __future__ import annotations
+
+import argparse
+import mimetypes
+import shutil
+from pathlib import Path
+
+from google import genai
+from google.genai import types
+
+IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".tif", ".tiff", ".bmp", ".jp2"}
+
+DEFAULT_PROMPT = (
+    "この古典籍（くずし字）の画像に書かれている文字をすべて翻刻してください。"
+    "縦書きの場合は右から左の順で、行ごとに改行して出力してください。"
+    "読めない文字は□で示してください。"
+)
+
+DEFAULT_MODEL = "gemini-3-flash-preview"
+
+
+def _get_client() -> genai.Client:
+    return genai.Client()
+
+
+def _get_mime_type(path: Path) -> str:
+    mt, _ = mimetypes.guess_type(str(path))
+    return mt or "image/jpeg"
+
+
+def ocr_image(
+    client: genai.Client,
+    image_bytes: bytes,
+    mime_type: str,
+    prompt: str,
+    model: str,
+) -> str:
+    """1 枚の画像を Gemini で OCR する。"""
+    response = client.models.generate_content(
+        model=model,
+        contents=[
+            prompt,
+            types.Part.from_bytes(data=image_bytes, mime_type=mime_type),
+        ],
+    )
+    return response.text or ""
+
+
+def run_single(
+    image_path: Path,
+    prompt: str,
+    model: str,
+) -> str:
+    """1 枚の画像を OCR してテキストを返す。"""
+    client = _get_client()
+    data = image_path.read_bytes()
+    mime = _get_mime_type(image_path)
+    print(f"OCR 中: {image_path.name} ({len(data)} bytes) [model={model}]")
+    return ocr_image(client, data, mime, prompt, model)
+
+
+def run_directory(
+    input_dir: Path,
+    output_dir: Path,
+    prompt: str,
+    model: str,
+) -> None:
+    """ディレクトリ内の画像を一括 OCR し、結果をファイルに保存する。"""
+    image_files = sorted(p for p in input_dir.rglob("*") if p.is_file() and p.suffix.lower() in IMAGE_EXTS)
+
+    if not image_files:
+        print(f"画像が見つかりません: {input_dir}")
+        return
+
+    if output_dir.exists():
+        shutil.rmtree(output_dir)
+    output_dir.mkdir(parents=True)
+
+    client = _get_client()
+    print(f"{len(image_files)} 枚の画像を処理中 [model={model}] ...")
+
+    for p in image_files:
+        relpath = p.relative_to(input_dir)
+        print(f"  OCR: {relpath}")
+
+        text = ocr_image(
+            client,
+            p.read_bytes(),
+            _get_mime_type(p),
+            prompt,
+            model,
+        )
+        (output_dir / f"{p.stem}.txt").write_text(text, encoding="utf-8")
+
+    print(f"\n完了: {len(image_files)} 枚処理済み")
+    print(f"出力: {output_dir}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Gemini API で古典籍画像を OCR する",
+    )
+    parser.add_argument("--image-path", type=str, help="単一画像のパス")
+    parser.add_argument("--input-dir", type=str, help="画像ディレクトリのパス（一括処理）")
+    parser.add_argument("--output-dir", type=str, default="output_vision", help="出力ディレクトリ（デフォルト: output_vision）")
+    parser.add_argument("--prompt", type=str, default=DEFAULT_PROMPT, help="OCR プロンプト")
+    parser.add_argument("--model", type=str, default=DEFAULT_MODEL, help=f"Gemini モデル名（デフォルト: {DEFAULT_MODEL}）")
+    args = parser.parse_args()
+
+    if args.input_dir:
+        run_directory(Path(args.input_dir), Path(args.output_dir), args.prompt, args.model)
+    elif args.image_path:
+        text = run_single(Path(args.image_path), args.prompt, args.model)
+        print("--- 翻刻結果 ---")
+        print(text)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kuzushiji-ocr"
+version = "0.1.0"
+description = "くずし字 OCR — Modal 上の VLM 推論と FastAPI Web UI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+dependencies = [
+    "google-genai>=1.0",
+    "modal>=0.62",
+    "fastapi>=0.115",
+    "uvicorn>=0.34",
+    "python-multipart>=0.0.20",
+    "Pillow>=11.0",
+    "jinja2>=3.1",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pytest-asyncio>=1.0.0",
+    "ruff>=0.14.10",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 160
+indent-width = 4
+target-version = "py310"
+extend-exclude = [".venv", "build", "dist", "archive"]
+src = ["src", "comparison"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B", "I"]
+extend-select = [
+    "C4",
+    "SIM",
+    "ERA",
+    "UP",
+]
+extend-ignore = ["SIM108"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+preview = true
+line-ending = "auto"
+docstring-code-format = true
+
+[tool.ruff.lint.isort]
+known-first-party = ["kuzushiji_ocr"]
+section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]

src/kuzushiji_ocr/__init__.py

@@ -0,0 +1,3 @@
+"""くずし字 OCR — Modal 上の VLM 推論と FastAPI Web UI。"""
+
+__version__ = "0.1.0"

src/kuzushiji_ocr/templates/index.html

@@ -0,0 +1,838 @@
+<!DOCTYPE html>
+<html lang="ja">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>くずし字 OCR</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Noto+Sans+JP:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <style>
+    /* ===== Aspara Design Tokens ===== */
+    :root {
+      --color-action: #2C2520;
+      --color-action-hover: #1a1512;
+      --color-accent: #CC785C;
+      --color-accent-hover: #B5654A;
+      --color-accent-light: #E8A892;
+      --color-base-bg: #F5F3F0;
+      --color-base-border: #E6E3E0;
+      --color-base-surface: #FDFCFB;
+      --color-text-primary: #2C2520;
+      --color-text-secondary: #6B5F55;
+      --color-text-muted: #9B8F85;
+      --color-status-error: #C84C3C;
+      --color-status-success: #5A8B6F;
+      --color-status-warning: #D4864E;
+      --font-sans: "Inter", "Noto Sans JP", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      --font-mono: "JetBrains Mono", Consolas, Monaco, monospace;
+      --radius: 0.5rem;
+    }
+
+    /* ===== Reset & Base ===== */
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      font-family: var(--font-sans);
+      background: var(--color-base-bg);
+      color: var(--color-text-primary);
+      line-height: 1.6;
+      letter-spacing: -0.01em;
+      min-height: 100vh;
+    }
+
+    /* ===== Layout ===== */
+    .app-header {
+      background: var(--color-base-surface);
+      border-bottom: 1px solid var(--color-base-border);
+      padding: 1rem 2rem;
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+    }
+    .app-header h1 {
+      font-size: 1.25rem;
+      font-weight: 700;
+      color: var(--color-text-primary);
+    }
+    .app-header .subtitle {
+      font-size: 0.8rem;
+      color: var(--color-text-muted);
+      font-weight: 400;
+    }
+
+    .container {
+      max-width: 1400px;
+      margin: 0 auto;
+      padding: 2rem;
+    }
+
+    /* ===== Card ===== */
+    .card {
+      background: var(--color-base-surface);
+      border: 1px solid var(--color-base-border);
+      border-radius: var(--radius);
+      padding: 1.5rem;
+      transition: border-color 150ms;
+    }
+    .card:hover { border-color: var(--color-accent); }
+
+    /* ===== Upload Zone ===== */
+    .upload-section { margin-bottom: 1.5rem; }
+
+    .drop-zone {
+      border: 2px dashed var(--color-base-border);
+      border-radius: var(--radius);
+      padding: 3rem 2rem;
+      text-align: center;
+      cursor: pointer;
+      transition: border-color 150ms, background 150ms;
+      background: var(--color-base-surface);
+      position: relative;
+    }
+    .drop-zone:hover,
+    .drop-zone.dragover {
+      border-color: var(--color-accent);
+      background: rgba(204, 120, 92, 0.04);
+    }
+    .drop-zone input[type="file"] {
+      position: absolute;
+      inset: 0;
+      opacity: 0;
+      cursor: pointer;
+    }
+    .drop-zone .icon {
+      width: 48px;
+      height: 48px;
+      margin: 0 auto 1rem;
+      color: var(--color-text-muted);
+    }
+    .drop-zone .label {
+      font-size: 0.95rem;
+      color: var(--color-text-secondary);
+      font-weight: 500;
+    }
+    .drop-zone .hint {
+      font-size: 0.8rem;
+      color: var(--color-text-muted);
+      margin-top: 0.25rem;
+    }
+
+    .preview-area {
+      display: none;
+      margin-top: 1rem;
+      position: relative;
+    }
+    .preview-area.visible { display: block; }
+    .preview-area img {
+      max-height: 200px;
+      max-width: 100%;
+      border-radius: var(--radius);
+      border: 1px solid var(--color-base-border);
+      object-fit: contain;
+    }
+    .preview-info {
+      margin-top: 0.5rem;
+      font-size: 0.8rem;
+      color: var(--color-text-muted);
+    }
+    .preview-clear {
+      position: absolute;
+      top: 0.5rem;
+      right: 0.5rem;
+      background: var(--color-action);
+      color: white;
+      border: none;
+      border-radius: 50%;
+      width: 28px;
+      height: 28px;
+      font-size: 1rem;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      opacity: 0.8;
+      transition: opacity 150ms;
+    }
+    .preview-clear:hover { opacity: 1; }
+
+    /* ===== Controls ===== */
+    .controls {
+      display: flex;
+      align-items: center;
+      gap: 2rem;
+      flex-wrap: wrap;
+      margin-bottom: 2rem;
+    }
+
+    .model-selector {
+      display: flex;
+      align-items: center;
+      gap: 1.25rem;
+    }
+    .model-selector .group-label {
+      font-size: 0.85rem;
+      font-weight: 600;
+      color: var(--color-text-secondary);
+    }
+    .radio-option {
+      display: flex;
+      align-items: center;
+      gap: 0.4rem;
+      cursor: pointer;
+      font-size: 0.85rem;
+      color: var(--color-text-primary);
+    }
+    .radio-option input[type="radio"] {
+      accent-color: var(--color-accent);
+      width: 16px;
+      height: 16px;
+      cursor: pointer;
+    }
+    .radio-option .tag {
+      font-size: 0.7rem;
+      padding: 0.1rem 0.4rem;
+      border-radius: 9999px;
+      font-weight: 500;
+    }
+    .tag-fast {
+      background: rgba(90, 139, 111, 0.12);
+      color: var(--color-status-success);
+    }
+    .tag-quality {
+      background: rgba(204, 120, 92, 0.12);
+      color: var(--color-accent);
+    }
+
+    .btn-run {
+      background: var(--color-accent);
+      color: white;
+      border: none;
+      padding: 0.6rem 1.5rem;
+      border-radius: var(--radius);
+      font-size: 0.9rem;
+      font-weight: 600;
+      cursor: pointer;
+      transition: background 150ms;
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      font-family: var(--font-sans);
+    }
+    .btn-run:hover:not(:disabled) { background: var(--color-accent-hover); }
+    .btn-run:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+
+    /* ===== Results ===== */
+    .results {
+      display: none;
+      gap: 1.5rem;
+    }
+    .results.visible {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+    }
+    @media (max-width: 900px) {
+      .results.visible { grid-template-columns: 1fr; }
+    }
+
+    .result-image-panel .card { padding: 1rem; }
+    .result-image-panel img {
+      width: 100%;
+      border-radius: calc(var(--radius) - 4px);
+      cursor: zoom-in;
+    }
+
+    .result-text-panel { display: flex; flex-direction: column; gap: 0.75rem; }
+
+    /* ===== Accordion ===== */
+    .accordion {
+      background: var(--color-base-surface);
+      border: 1px solid var(--color-base-border);
+      border-radius: var(--radius);
+      overflow: hidden;
+      transition: border-color 150ms;
+    }
+    .accordion:hover { border-color: var(--color-accent); }
+
+    .accordion-header {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      padding: 0.75rem 1rem;
+      cursor: pointer;
+      user-select: none;
+      background: none;
+      border: none;
+      width: 100%;
+      font-family: var(--font-sans);
+      font-size: 0.9rem;
+      font-weight: 600;
+      color: var(--color-text-primary);
+      text-align: left;
+    }
+    .accordion-header:hover { background: rgba(0, 0, 0, 0.02); }
+
+    .accordion-chevron {
+      width: 16px;
+      height: 16px;
+      transition: transform 200ms;
+      color: var(--color-text-muted);
+      flex-shrink: 0;
+    }
+    .accordion.open .accordion-chevron { transform: rotate(90deg); }
+
+    .accordion-badge {
+      font-size: 0.7rem;
+      padding: 0.1rem 0.5rem;
+      border-radius: 9999px;
+      font-weight: 500;
+      margin-left: auto;
+    }
+    .badge-observation { background: rgba(90, 139, 111, 0.12); color: var(--color-status-success); }
+    .badge-transcription { background: rgba(204, 120, 92, 0.12); color: var(--color-accent); }
+    .badge-review { background: rgba(44, 37, 32, 0.1); color: var(--color-text-secondary); }
+    .badge-bbox { background: rgba(212, 134, 78, 0.12); color: var(--color-status-warning); }
+
+    .accordion-body {
+      max-height: 0;
+      overflow: hidden;
+      transition: max-height 280ms ease;
+    }
+    /* 多段推論の長文（校訂・解説など）が 2000px 超で切れないよう、ビューポート基準で拡張し内部スクロール */
+    .accordion.open .accordion-body {
+      max-height: min(88vh, 32000px);
+      overflow-y: auto;
+      overflow-x: hidden;
+      -webkit-overflow-scrolling: touch;
+    }
+
+    .accordion-content {
+      padding: 0 1rem 1rem;
+      font-size: 0.85rem;
+      line-height: 1.8;
+      color: var(--color-text-primary);
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+    .accordion-content.mono {
+      font-family: var(--font-mono);
+      font-size: 0.75rem;
+      line-height: 1.5;
+      background: var(--color-base-bg);
+      margin: 0 1rem 1rem;
+      padding: 1rem;
+      border-radius: calc(var(--radius) - 2px);
+      max-height: 400px;
+      overflow-y: auto;
+    }
+
+    /* Markdown 本文（観察 / 翻刻 / 校訂・解説 など） */
+    .accordion-content.markdown-body {
+      white-space: normal;
+      overflow-x: auto;
+    }
+    .accordion-content.markdown-body > :first-child { margin-top: 0; }
+    .accordion-content.markdown-body > :last-child { margin-bottom: 0; }
+    .accordion-content.markdown-body h1,
+    .accordion-content.markdown-body h2,
+    .accordion-content.markdown-body h3,
+    .accordion-content.markdown-body h4 {
+      font-weight: 600;
+      color: var(--color-text-primary);
+      margin: 0.85rem 0 0.4rem;
+      line-height: 1.35;
+    }
+    .accordion-content.markdown-body h1 { font-size: 1.05rem; }
+    .accordion-content.markdown-body h2 { font-size: 1rem; }
+    .accordion-content.markdown-body h3 { font-size: 0.95rem; }
+    .accordion-content.markdown-body h4 { font-size: 0.9rem; }
+    .accordion-content.markdown-body p {
+      margin: 0.5rem 0;
+    }
+    .accordion-content.markdown-body ul,
+    .accordion-content.markdown-body ol {
+      margin: 0.45rem 0;
+      padding-left: 1.35rem;
+    }
+    .accordion-content.markdown-body li { margin: 0.2rem 0; }
+    .accordion-content.markdown-body li > p { margin: 0.25rem 0; }
+    .accordion-content.markdown-body blockquote {
+      margin: 0.6rem 0;
+      padding: 0.35rem 0 0.35rem 0.85rem;
+      border-left: 3px solid var(--color-base-border);
+      color: var(--color-text-secondary);
+    }
+    .accordion-content.markdown-body hr {
+      border: none;
+      border-top: 1px solid var(--color-base-border);
+      margin: 1rem 0;
+    }
+    .accordion-content.markdown-body a {
+      color: var(--color-accent);
+      text-decoration: underline;
+      text-underline-offset: 2px;
+    }
+    .accordion-content.markdown-body a:hover {
+      color: var(--color-accent-hover);
+    }
+    .accordion-content.markdown-body pre {
+      font-family: var(--font-mono);
+      font-size: 0.78rem;
+      line-height: 1.45;
+      background: var(--color-base-bg);
+      padding: 0.75rem 1rem;
+      border-radius: calc(var(--radius) - 2px);
+      overflow-x: auto;
+      margin: 0.55rem 0;
+    }
+    .accordion-content.markdown-body :not(pre) > code {
+      font-family: var(--font-mono);
+      font-size: 0.82em;
+      background: rgba(44, 37, 32, 0.07);
+      padding: 0.12em 0.4em;
+      border-radius: 4px;
+    }
+    .accordion-content.markdown-body table {
+      border-collapse: collapse;
+      width: 100%;
+      font-size: 0.82rem;
+      margin: 0.65rem 0;
+    }
+    .accordion-content.markdown-body th,
+    .accordion-content.markdown-body td {
+      border: 1px solid var(--color-base-border);
+      padding: 0.35rem 0.55rem;
+      text-align: left;
+    }
+    .accordion-content.markdown-body th {
+      background: rgba(44, 37, 32, 0.04);
+      font-weight: 600;
+    }
+
+    /* ===== Loading ===== */
+    .loading-overlay {
+      display: none;
+      position: fixed;
+      inset: 0;
+      background: rgba(245, 243, 240, 0.85);
+      z-index: 1000;
+      align-items: center;
+      justify-content: center;
+      backdrop-filter: blur(4px);
+    }
+    .loading-overlay.visible {
+      display: flex;
+    }
+    .loading-card {
+      background: var(--color-base-surface);
+      border: 1px solid var(--color-base-border);
+      border-radius: var(--radius);
+      padding: 2.5rem 3rem;
+      text-align: center;
+      max-width: 400px;
+    }
+    .spinner {
+      width: 40px;
+      height: 40px;
+      border: 3px solid var(--color-base-border);
+      border-top-color: var(--color-accent);
+      border-radius: 50%;
+      animation: spin 0.8s linear infinite;
+      margin: 0 auto 1.5rem;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+
+    .loading-title {
+      font-size: 1rem;
+      font-weight: 600;
+      color: var(--color-text-primary);
+      margin-bottom: 0.5rem;
+    }
+    .loading-stage {
+      font-size: 0.85rem;
+      color: var(--color-text-secondary);
+      margin-bottom: 0.25rem;
+    }
+    .loading-hint {
+      font-size: 0.75rem;
+      color: var(--color-text-muted);
+      margin-top: 0.75rem;
+    }
+
+    .progress-bar {
+      width: 100%;
+      height: 4px;
+      background: var(--color-base-border);
+      border-radius: 2px;
+      margin-top: 1rem;
+      overflow: hidden;
+    }
+    .progress-fill {
+      height: 100%;
+      background: var(--color-accent-light);
+      border-radius: 2px;
+      width: 0%;
+      animation: progress-pulse 2s ease-in-out infinite;
+    }
+    @keyframes progress-pulse {
+      0%, 100% { width: 20%; margin-left: 0; }
+      50% { width: 50%; margin-left: 25%; }
+    }
+
+    /* ===== Errors ===== */
+    .error-banner {
+      display: none;
+      background: rgba(200, 76, 60, 0.08);
+      border: 1px solid rgba(200, 76, 60, 0.25);
+      border-radius: var(--radius);
+      padding: 0.75rem 1rem;
+      margin-bottom: 1.5rem;
+      font-size: 0.85rem;
+      color: var(--color-status-error);
+    }
+    .error-banner.visible { display: block; }
+
+    /* ===== Model Info ===== */
+    .model-info {
+      font-size: 0.8rem;
+      color: var(--color-text-muted);
+      margin-bottom: 1rem;
+    }
+
+    /* ===== Lightbox ===== */
+    .lightbox {
+      display: none;
+      position: fixed;
+      inset: 0;
+      background: rgba(0, 0, 0, 0.8);
+      z-index: 2000;
+      align-items: center;
+      justify-content: center;
+      cursor: zoom-out;
+    }
+    .lightbox.visible { display: flex; }
+    .lightbox img {
+      max-width: 95vw;
+      max-height: 95vh;
+      object-fit: contain;
+      border-radius: var(--radius);
+    }
+
+    /* ===== Footer ===== */
+    .app-footer {
+      text-align: center;
+      padding: 2rem;
+      font-size: 0.75rem;
+      color: var(--color-text-muted);
+    }
+
+    /* ===== Accessibility ===== */
+    @media (prefers-reduced-motion: reduce) {
+      *, *::before, *::after {
+        animation-duration: 0.01ms !important;
+        transition-duration: 0.01ms !important;
+      }
+    }
+  </style>
+</head>
+<body>
+
+  <!-- Header -->
+  <header class="app-header">
+    <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/><polyline points="10 9 9 9 8 9"/></svg>
+    <h1>くずし字 OCR</h1>
+    <span class="subtitle">Qwen2.5-VL — 多段生成パイプライン</span>
+  </header>
+
+  <main class="container">
+    <!-- Upload -->
+    <section class="upload-section">
+      <div class="card">
+        <div class="drop-zone" id="dropZone">
+          <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="17 8 12 3 7 8"/><line x1="12" y1="3" x2="12" y2="15"/></svg>
+          <div class="label">画像をドラッグ＆ドロップ、またはクリックして選択</div>
+          <div class="hint">JPG, PNG, TIFF, BMP 対応</div>
+          <input type="file" id="fileInput" accept="image/*">
+        </div>
+        <div class="preview-area" id="previewArea">
+          <img id="previewImg" alt="プレビュー">
+          <button class="preview-clear" id="clearBtn" title="クリア">&times;</button>
+          <div class="preview-info" id="previewInfo"></div>
+        </div>
+      </div>
+    </section>
+
+    <!-- Controls -->
+    <section class="controls">
+      <div class="model-selector">
+        <span class="group-label">モデル:</span>
+        <label class="radio-option">
+          <input type="radio" name="model" value="7b" checked>
+          Qwen2.5-VL-7B
+          <span class="tag tag-fast">高速</span>
+        </label>
+        <label class="radio-option">
+          <input type="radio" name="model" value="32b">
+          Qwen2.5-VL-32B
+          <span class="tag tag-quality">高精度</span>
+        </label>
+      </div>
+      <button class="btn-run" id="runBtn" disabled>
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><polygon points="5 3 19 12 5 21 5 3"/></svg>
+        OCR 実行
+      </button>
+    </section>
+
+    <!-- Error -->
+    <div class="error-banner" id="errorBanner"></div>
+
+    <!-- Results -->
+    <div class="model-info" id="modelInfo"></div>
+    <section class="results" id="results">
+      <!-- Left: annotated image -->
+      <div class="result-image-panel">
+        <div class="card">
+          <img id="annotatedImg" alt="重畳画像">
+        </div>
+      </div>
+
+      <!-- Right: text panels -->
+      <div class="result-text-panel" id="textPanels"></div>
+    </section>
+  </main>
+
+  <!-- Loading -->
+  <div class="loading-overlay" id="loading">
+    <div class="loading-card">
+      <div class="spinner"></div>
+      <div class="loading-title">OCR 処理中...</div>
+      <div class="loading-stage" id="loadingStage">Modal GPU 上で推論を実行しています</div>
+      <div class="loading-hint">構造化 OCR と多段推論を並列実行中</div>
+      <div class="progress-bar"><div class="progress-fill"></div></div>
+    </div>
+  </div>
+
+  <!-- Lightbox -->
+  <div class="lightbox" id="lightbox">
+    <img id="lightboxImg" alt="拡大画像">
+  </div>
+
+  <footer class="app-footer">
+    Qwen2.5-VL on Modal — くずし字 OCR Viewer
+  </footer>
+
+  <script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" crossorigin="anonymous"></script>
+  <script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.7/dist/purify.min.js" crossorigin="anonymous"></script>
+  <script>
+    const $ = (sel) => document.querySelector(sel);
+    const dropZone = $('#dropZone');
+    const fileInput = $('#fileInput');
+    const previewArea = $('#previewArea');
+    const previewImg = $('#previewImg');
+    const previewInfo = $('#previewInfo');
+    const clearBtn = $('#clearBtn');
+    const runBtn = $('#runBtn');
+    const errorBanner = $('#errorBanner');
+    const results = $('#results');
+    const annotatedImg = $('#annotatedImg');
+    const textPanels = $('#textPanels');
+    const loading = $('#loading');
+    const loadingStage = $('#loadingStage');
+    const modelInfo = $('#modelInfo');
+    const lightbox = $('#lightbox');
+    const lightboxImg = $('#lightboxImg');
+
+    if (typeof marked !== 'undefined' && typeof marked.use === 'function') {
+      marked.use({ breaks: true, gfm: true });
+    }
+
+    let selectedFile = null;
+
+    /* --- Upload --- */
+
+    function handleFile(file) {
+      if (!file || !file.type.startsWith('image/')) return;
+      selectedFile = file;
+      const reader = new FileReader();
+      reader.onload = (e) => {
+        previewImg.src = e.target.result;
+        previewArea.classList.add('visible');
+        const sizeMB = (file.size / 1024 / 1024).toFixed(2);
+        previewInfo.textContent = `${file.name}  (${sizeMB} MB)`;
+      };
+      reader.readAsDataURL(file);
+      runBtn.disabled = false;
+      dropZone.style.display = 'none';
+    }
+
+    function clearFile() {
+      selectedFile = null;
+      previewImg.src = '';
+      previewArea.classList.remove('visible');
+      previewInfo.textContent = '';
+      runBtn.disabled = true;
+      dropZone.style.display = '';
+      fileInput.value = '';
+      results.classList.remove('visible');
+      errorBanner.classList.remove('visible');
+      modelInfo.textContent = '';
+    }
+
+    fileInput.addEventListener('change', (e) => {
+      if (e.target.files.length) handleFile(e.target.files[0]);
+    });
+
+    dropZone.addEventListener('dragover', (e) => {
+      e.preventDefault();
+      dropZone.classList.add('dragover');
+    });
+    dropZone.addEventListener('dragleave', () => dropZone.classList.remove('dragover'));
+    dropZone.addEventListener('drop', (e) => {
+      e.preventDefault();
+      dropZone.classList.remove('dragover');
+      if (e.dataTransfer.files.length) handleFile(e.dataTransfer.files[0]);
+    });
+
+    clearBtn.addEventListener('click', clearFile);
+
+    /* --- Lightbox --- */
+
+    annotatedImg.addEventListener('click', () => {
+      lightboxImg.src = annotatedImg.src;
+      lightbox.classList.add('visible');
+    });
+    lightbox.addEventListener('click', () => lightbox.classList.remove('visible'));
+
+    /* --- Accordion builder --- */
+
+    const STAGE_META = {
+      '観察':      { badge: 'badge-observation',   label: 'Stage 1' },
+      '翻刻':      { badge: 'badge-transcription',  label: 'Stage 2' },
+      '校訂・解説': { badge: 'badge-review',         label: 'Stage 3' },
+      'bbox':      { badge: 'badge-bbox',           label: 'Data' },
+      '出力':      { badge: 'badge-observation',    label: 'Output' },
+    };
+
+    function createAccordion(title, content, open, isMono) {
+      const meta = STAGE_META[title] || { badge: 'badge-observation', label: '' };
+      const div = document.createElement('div');
+      div.className = 'accordion' + (open ? ' open' : '');
+      const bodyHtml = isMono ? escapeHtml(content) : renderMarkdown(content);
+      const contentClass = isMono ? 'accordion-content mono' : 'accordion-content markdown-body';
+      div.innerHTML = `
+        <button class="accordion-header">
+          <svg class="accordion-chevron" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 18 15 12 9 6"/></svg>
+          ${escapeHtml(title)}
+          <span class="accordion-badge ${meta.badge}">${escapeHtml(meta.label)}</span>
+        </button>
+        <div class="accordion-body">
+          <div class="${contentClass}">${bodyHtml}</div>
+        </div>
+      `;
+      div.querySelector('.accordion-header').addEventListener('click', () => {
+        div.classList.toggle('open');
+      });
+      return div;
+    }
+
+    function escapeHtml(str) {
+      const d = document.createElement('div');
+      d.textContent = str == null ? '' : String(str);
+      return d.innerHTML;
+    }
+
+    function renderMarkdown(str) {
+      const raw = str == null ? '' : String(str);
+      if (typeof marked === 'undefined' || typeof DOMPurify === 'undefined') {
+        return escapeHtml(raw);
+      }
+      try {
+        const html = marked.parse(raw);
+        return DOMPurify.sanitize(html);
+      } catch (e) {
+        return escapeHtml(raw);
+      }
+    }
+
+    /* --- Run OCR --- */
+
+    runBtn.addEventListener('click', async () => {
+      if (!selectedFile) return;
+      const model = document.querySelector('input[name="model"]:checked').value;
+
+      errorBanner.classList.remove('visible');
+      results.classList.remove('visible');
+      modelInfo.textContent = '';
+      loading.classList.add('visible');
+      runBtn.disabled = true;
+
+      const stages = ['構造化 OCR + 多段推論を並列実行中...', 'Modal GPU 上で推論を実行しています'];
+      let si = 0;
+      const stageInterval = setInterval(() => {
+        si = (si + 1) % stages.length;
+        loadingStage.textContent = stages[si];
+      }, 3000);
+
+      try {
+        const formData = new FormData();
+        formData.append('image', selectedFile);
+        formData.append('model', model);
+
+        const resp = await fetch('/api/ocr', { method: 'POST', body: formData });
+        if (!resp.ok) {
+          const err = await resp.json().catch(() => ({ detail: resp.statusText }));
+          throw new Error(err.detail || `HTTP ${resp.status}`);
+        }
+
+        const data = await resp.json();
+
+        /* Errors */
+        if (data.errors && data.errors.length) {
+          errorBanner.textContent = data.errors.join('\n');
+          errorBanner.classList.add('visible');
+        }
+
+        /* Model info */
+        modelInfo.textContent = `使用モデル: ${data.model_used}`;
+
+        /* Annotated image */
+        annotatedImg.src = `data:image/png;base64,${data.annotated_image}`;
+
+        /* Text panels */
+        textPanels.innerHTML = '';
+        const stageOrder = ['観察', '翻刻', '校訂・解説'];
+        const renderedStages = new Set();
+
+        for (const name of stageOrder) {
+          if (data.stages[name]) {
+            textPanels.appendChild(createAccordion(name, data.stages[name], true, false));
+            renderedStages.add(name);
+          }
+        }
+        for (const [name, text] of Object.entries(data.stages)) {
+          if (!renderedStages.has(name)) {
+            textPanels.appendChild(createAccordion(name, text, true, false));
+          }
+        }
+
+        if (data.bboxes && data.bboxes.length) {
+          const bboxJson = JSON.stringify(data.bboxes, null, 2);
+          textPanels.appendChild(createAccordion('bbox', bboxJson, false, true));
+        }
+
+        results.classList.add('visible');
+      } catch (e) {
+        errorBanner.textContent = `エラー: ${e.message}`;
+        errorBanner.classList.add('visible');
+      } finally {
+        clearInterval(stageInterval);
+        loading.classList.remove('visible');
+        runBtn.disabled = !selectedFile;
+      }
+    });
+  </script>
+</body>
+</html>

src/kuzushiji_ocr/vlm_app.py

@@ -0,0 +1,638 @@
+"""
+Qwen2.5-VL によるくずし字 OCR（Modal 上で実行）。
+--model 7b / 32b でモデルサイズを選択可能。
+
+前提:
+  - Modal アカウントと `modal token new` などで認証済み
+  - 初回はイメージビルドにモデルダウンロード含め時間がかかる
+
+単一画像 (7B, 高速・低コスト):
+  modal run src/kuzushiji_ocr/vlm_app.py --image-path ./sample.jpg --model 7b
+
+単一画像 (32B, 高精度):
+  modal run src/kuzushiji_ocr/vlm_app.py --image-path ./sample.jpg --model 32b
+
+多段推論（専門家の思考プロセスで翻刻＋解説）:
+  modal run src/kuzushiji_ocr/vlm_app.py --image-path ./sample.jpg --deep-think
+
+ディレクトリ一括処理:
+  modal run src/kuzushiji_ocr/vlm_app.py --input-dir ./dataset/
+
+座標付き構造化出力（NDL OCR 互換 JSON）:
+  modal run src/kuzushiji_ocr/vlm_app.py --image-path ./sample.jpg --structured
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+import modal
+
+# ---------------------------------------------------------------------------
+# モデル構成: 7B / 32B
+# ---------------------------------------------------------------------------
+
+MODELS: dict[str, dict[str, Any]] = {
+    "7b": {
+        "id": "Qwen/Qwen2.5-VL-7B-Instruct",
+        "gpu": "A10G",
+        "memory": 32768,
+        "min_pixels": 256 * 28 * 28,
+        "max_pixels": 1280 * 28 * 28,
+    },
+    "32b": {
+        "id": "Qwen/Qwen2.5-VL-32B-Instruct",
+        "gpu": "A100-80GB:1",
+        "memory": 65536,
+        "min_pixels": 256 * 28 * 28,
+        "max_pixels": 768 * 28 * 28,
+    },
+}
+
+app = modal.App("kuzushiji-vlm-ocr")
+
+hf_secret = modal.Secret.from_name("huggingface-secret")
+
+model_cache = modal.Volume.from_name("kuzushiji-vlm-models", create_if_missing=True)
+CACHE_DIR = "/model-cache"
+
+vlm_image = modal.Image.debian_slim(python_version="3.11").pip_install(
+    "torch>=2.5.0",
+    "torchvision>=0.20.0",
+    "transformers>=4.49.0",
+    "accelerate>=0.34.0",
+    "qwen-vl-utils>=0.0.8",
+    "Pillow",
+    "huggingface_hub",
+)
+
+IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".tif", ".tiff", ".bmp", ".jp2"}
+
+_MIME_MAP = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+    ".bmp": "image/bmp",
+}
+
+DEFAULT_PROMPT = (
+    "この古典籍（くずし字）の画像に書かれている文字をすべて翻刻してください。\n"
+    "縦書きの場合は右から左の順で、行ごとに改行して出力してください。\n"
+    "読めない文字は□で示してください。翻刻テキストと説明を出力してください。"
+    "画像全体として何が写っているかも簡潔に説明してください。"
+)
+
+STRUCTURED_PROMPT = (
+    "この古典籍（くずし字）の画像に書かれている文字をすべて翻刻してください。\n"
+    "あわせて、文字以外の目立つ物体（挿絵・図・表・欄外の絵、蔵書印・印章、欄枠・見出し枠、"
+    "写真・貼り付け、表紙装飾など）も検出してください。\n"
+    "各要素について、画像上のバウンディングボックス座標（ピクセル）とラベルを"
+    "次の JSON 配列で出力してください。\n"
+    '- テキスト行: [x1, y1, x2, y2, "翻刻テキスト"]\n'
+    '- 文字以外の物体: [x1, y1, x2, y2, "簡潔な物体名・説明", "object"]\n'
+    "（6 番目の要素は必ず英語小文字の object とし、テキスト行には付けないこと）\n"
+    "座標は画像の左上を原点としたピクセル値です（VLM が入力に用いる解像度上の値でよい）。\n"
+    "縦書きテキストは右の列から順に並べてください。読めない文字は□で示してください。\n"
+    "JSON のみを出力し、説明文は付けないでください。"
+)
+
+# ---------------------------------------------------------------------------
+# 多段推論 — 多段生成パイプラインで専門家の思考プロセスを再現
+#
+# Stage 1（観察）— 画像を見て文書の種類・時代・書体・レイアウトを分析
+# Stage 2（翻刻）— Stage 1 の分析を踏まえて丁寧に翻刻
+# Stage 3（校訂・解説）— Stage 1+2 を踏まえて校訂し、内容を解説
+#
+# 各ステージの出力は会話履歴に追加され、次のステージのコンテキストになる。
+# ---------------------------------------------------------------------------
+
+DEEP_THINK_SYSTEM = """\
+あなたは日本の古典籍・くずし字を専門とする文献学者です。\
+数十年にわたり和古書・写本・版本を読み解いてきた経験を持ち、\
+書体の変遷、異体字、変体仮名、合字、踊り字に精通しています。"""
+
+DEEP_THINK_STAGES: list[tuple[str, str, int]] = [
+    # 各要素は ステージ名・プロンプト・max_new_tokens のタプル
+    (
+        "観察",
+        """\
+この画像を、くずし字の専門家として丁寧に観察・分析してください。
+以下の点を報告してください。
+
+1. 物体と文書の種類: 文字が書かれている物体は何か（紙・木箱・器・掛軸・石碑・屏風・扇・布など）を特定し、\
+文書としての種類（写本／版本／書状／日記／物語／公文書／商品ラベル／銘・落款など）を推定する
+2. 素材と保存状態: 素材の特徴（料紙・木材・陶磁器・漆器など）、装丁、損傷・虫食いの有無
+3. 時代の推定: 書風・紙質・印章・内容から推定される年代
+4. 挿絵・図・印: 挿絵、蔵書印、書き入れなどの有無と内容
+5. 書体の特徴: 楷書寄り／草書寄り／行書、筆の運び方の癖
+6. 変体仮名・異体字: 使われている変体仮名や異体字の傾向
+7. レイアウト: 縦書き行数、行間、丁付け、柱、振り仮名の有無
+
+まだ翻刻はしないでください。観察と分析のみを行ってください。""",
+        2048,
+    ),
+    (
+        "翻刻",
+        """\
+先ほどの観察結果を踏まえて、画像中のくずし字を翻刻してください。
+
+- 右から左、上から下の順で一行ずつ翻刻する
+- 読めない文字は□で示す
+- 推定できる読みは（　）で補う
+- 変体仮名は現行のひらがなに直し、原字が特定できる場合は注記する
+  （例: 「は」←「者」）
+- 踊り字（ゝ、〻、く等）は展開して示す
+- 行番号を付けて出力する
+
+翻刻テキストのみを出力してください。解説はまだ不要です。""",
+        4096,
+    ),
+    (
+        "校訂・解説",
+        """\
+観察結果と翻刻テキストを踏まえて、以下を行ってください。
+
+## 校訂
+- 文脈・文法から翻刻の読みが正しいか検証する
+- □の箇所を前後の文脈から埋められないか再検討する
+- 明らかな誤写・衍字・脱字があれば指摘する
+- 修正がある場合は、修正後の翻刻テキストを改めて出力する
+
+## 内容の解説
+- 翻刻した文章全体の現代語訳または要約
+- 文書の歴史的・文学的位置づけ（わかる範囲で）
+- 特筆すべき語彙・表現・文化的背景の注釈
+
+分量は読みやすい長さに抑え、解説は要点を箇条書きで簡潔に。冗長な前置きや繰り返しは避けてください。""",
+        4096,
+    ),
+]
+
+
+def _strip_markdown_code_fence(raw: str) -> str:
+    """先頭の ``` または ```json …（改行なしで `[` が続く場合を含む）を取り除き、閉じ ``` があればそこまで。"""
+    t = raw.strip()
+    if not t.startswith("```"):
+        return t
+    i = 3
+    while i < len(t) and t[i] in " \t":
+        i += 1
+    while i < len(t) and (t[i].isalpha() or t[i] == "-"):
+        i += 1
+    while i < len(t) and t[i] in " \t":
+        i += 1
+    if i < len(t) and t[i] == "\n":
+        i += 1
+    rest = t[i:]
+    end = rest.rfind("```")
+    if end != -1:
+        rest = rest[:end]
+    return rest.strip()
+
+
+def _extract_json_array_source(raw: str) -> str | None:
+    """```json ... ``` 内または先頭の JSON 配列 `[...]` を取り出す。
+
+    `` ```json [`` のようにフェンスと `[` が同一行の場合も扱う。
+    """
+    t = raw.strip()
+    if "```" in t:
+        t = _strip_markdown_code_fence(t[t.find("```") :])
+    t = t.strip()
+    if t.startswith("["):
+        return t
+    m = re.search(r"\[\s*\[", t)
+    if m:
+        return t[m.start() :]
+    m = re.search(r"\[", t)
+    return t[m.start() :] if m else None
+
+
+# 完成した 1 行 bbox のみマッチ（JSON が途中で切れても、閉じ `]` まで取れた行は拾える）
+_BBOX_LINE_RE = re.compile(
+    r"\[\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*"
+    r"(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*"
+    r'"((?:\\.|[^"\\])*)"\s*'
+    r'(?:,\s*"((?:\\.|[^"\\])*)"\s*)?'
+    r"\]",
+)
+
+
+def parse_bbox_rows_from_text(raw: str) -> list[list]:
+    """json.loads に失敗した VLM 生テキストから、完成した ``[x1,y1,x2,y2,"label"]`` 行だけを抽出する。"""
+    out: list[list] = []
+    for m in _BBOX_LINE_RE.finditer(raw or ""):
+        row: list = [
+            float(m.group(1)),
+            float(m.group(2)),
+            float(m.group(3)),
+            float(m.group(4)),
+            m.group(5),
+        ]
+        extra = m.group(6)
+        if extra is not None and extra.lower() in ("object", "obj"):
+            row.append("object")
+        out.append(row)
+    return out
+
+
+def _looks_like_flat_bbox_row(item: Any) -> bool:
+    """先頭4要素が数値座標の bbox 1 行か（行のリストと区別する）。"""
+    if not isinstance(item, list) or len(item) < 5:
+        return False
+    for i in range(4):
+        x = item[i]
+        if isinstance(x, bool) or not isinstance(x, (int, float)):
+            return False
+    return True
+
+
+def _normalize_structured_item(item: Any) -> list | None:
+    """VLM の検出1件を ``[x1,y1,x2,y2,label]`` または 6 要素（末尾 ``object``）に統一。"""
+    if isinstance(item, list) and len(item) >= 5 and _looks_like_flat_bbox_row(item):
+        row = list(item[:6])
+        if len(row) == 5:
+            return row
+        if len(row) >= 6:
+            tag = str(row[5]).lower()
+            if tag in ("object", "obj"):
+                return [*row[:5], "object"]
+            return row[:5]
+    if isinstance(item, dict):
+        inner = item.get("bbox_2d") or item.get("bbox") or item.get("box")
+        if isinstance(inner, (list, tuple)) and len(inner) >= 5:
+            x1, y1, x2, y2 = inner[0], inner[1], inner[2], inner[3]
+            label = str(inner[4])
+            obj_hint = str(item.get("object", item.get("type", item.get("category", "")))).lower()
+            if len(inner) >= 6:
+                six = str(inner[5]).lower()
+                if six in ("object", "obj"):
+                    return [x1, y1, x2, y2, label, "object"]
+            if obj_hint in ("object", "obj", "物体"):
+                return [x1, y1, x2, y2, label, "object"]
+            return [x1, y1, x2, y2, label]
+        if isinstance(inner, (list, tuple)) and len(inner) == 4:
+            bbox = list(inner)
+            text = item.get("text", item.get("content", item.get("label", "")))
+            typ = str(item.get("type", item.get("category", item.get("object", "text")))).lower()
+            if typ in ("object", "obj", "物体"):
+                return [*bbox, text, "object"]
+            return [*bbox, text]
+    return None
+
+
+def _parse_structured_output(raw: str) -> list | None:
+    """VLM の生テキストから JSON を抽出し、
+    [[x1, y1, x2, y2, "text"] または [x1, y1, x2, y2, "label", "object"], ...]
+    形式に正規化する。
+
+    Qwen 系の ``{"bbox_2d": [x1,y1,x2,y2,"ラベル"], "object": "テキスト行"}`` 形式にも対応する。
+
+    json.loads が失敗する（コードフェンス付き JSON・出力途中切れなど）場合は、完成行のみ正規表現で抽出する。
+    """
+    src = _extract_json_array_source(raw)
+    result: list[list] = []
+
+    if src:
+        try:
+            data = json.loads(src)
+        except (json.JSONDecodeError, TypeError):
+            data = None
+        else:
+            if isinstance(data, list):
+                for item in data:
+                    row = _normalize_structured_item(item)
+                    if row:
+                        result.append(row)
+                        continue
+                    if isinstance(item, list):
+                        for sub in item:
+                            if not isinstance(sub, list):
+                                continue
+                            row = _normalize_structured_item(sub)
+                            if row:
+                                result.append(row)
+
+    if result:
+        return [result]
+
+    rows = parse_bbox_rows_from_text(raw)
+    return [rows] if rows else None
+
+
+# ---------------------------------------------------------------------------
+# 共通推論ロジック（モジュールレベル関数）
+# ---------------------------------------------------------------------------
+
+
+def _generate(processor: Any, model: Any, messages: list[dict[str, Any]], max_new_tokens: int) -> str:
+    """メッセージから1回の生成を行い、テキストを返す。"""
+    import torch
+    from qwen_vl_utils import process_vision_info
+
+    text_input = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+    image_inputs, video_inputs = process_vision_info(messages)
+    inputs = processor(
+        text=[text_input],
+        images=image_inputs,
+        videos=video_inputs,
+        padding=True,
+        return_tensors="pt",
+    ).to(model.device)
+
+    with torch.inference_mode():
+        output_ids = model.generate(**inputs, max_new_tokens=max_new_tokens)
+
+    trimmed = output_ids[0][inputs.input_ids.shape[1] :]
+    return processor.decode(trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False)
+
+
+def _deep_think(processor: Any, model: Any, image_uri: str) -> dict[str, str]:
+    """多段生成パイプライン。各ステージを独立した1ターン生成で実行。"""
+    import time
+
+    stage_outputs: dict[str, str] = {}
+    context_so_far = ""
+
+    for i, (stage_name, prompt, max_tokens) in enumerate(DEEP_THINK_STAGES):
+        n = len(DEEP_THINK_STAGES)
+        print(f"[多段推論] Stage {i + 1}/{n}: {stage_name} ...")
+        t0 = time.time()
+
+        user_text = ""
+        if context_so_far:
+            user_text += f"これまでの分析結果:\n---\n{context_so_far}---\n\n"
+        user_text += prompt
+
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": DEEP_THINK_SYSTEM},
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": image_uri},
+                    {"type": "text", "text": user_text},
+                ],
+            },
+        ]
+
+        output = _generate(processor, model, messages, max_tokens)
+        stage_outputs[stage_name] = output
+
+        elapsed = time.time() - t0
+        print(f"[多段推論] Stage {i + 1}/{n}: {stage_name} 完了 ({elapsed:.1f}s)")
+
+        context_so_far += f"## {stage_name}\n{output}\n\n"
+
+    return stage_outputs
+
+
+def _run_ocr(
+    processor: Any,
+    model: Any,
+    pages: list[tuple[str, bytes]],
+    prompt: str,
+    structured: bool,
+    deep_think: bool,
+) -> dict[str, Any]:
+    """OCR 推論の本体。7B / 32B 共通。"""
+    texts: dict[str, str] = {}
+    jsons: dict[str, Any] = {}
+
+    for name, data in pages:
+        b64 = base64.b64encode(data).decode()
+        suffix = Path(name).suffix.lower()
+        mime = _MIME_MAP.get(suffix, "image/jpeg")
+        image_uri = f"data:{mime};base64,{b64}"
+
+        if deep_think:
+            stem = Path(name).stem
+            stage_outputs = _deep_think(processor, model, image_uri)
+            parts = []
+            for stage_name, output in stage_outputs.items():
+                parts.append(f"{'=' * 20} {stage_name} {'=' * 20}")
+                parts.append(output)
+                parts.append("")
+            texts[f"{stem}_main.txt"] = "\n".join(parts)
+            continue
+
+        effective_prompt = STRUCTURED_PROMPT if structured else prompt
+        max_tokens = 8192 if structured else 2048
+
+        messages: list[dict[str, Any]] = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": image_uri},
+                    {"type": "text", "text": effective_prompt},
+                ],
+            }
+        ]
+
+        output = _generate(processor, model, messages, max_tokens)
+        stem = Path(name).stem
+        texts[f"{stem}_main.txt"] = output
+
+        if structured:
+            parsed = _parse_structured_output(output)
+            if parsed is not None:
+                jsons[f"{stem}.json"] = parsed
+
+    return {"txt": texts, "json": jsons}
+
+
+# ---------------------------------------------------------------------------
+# Modal クラス: 7B / 32B
+# ---------------------------------------------------------------------------
+
+
+def _setup_model(model_key: str) -> tuple[Any, Any]:
+    """Volume 上のキャッシュからモデルを読み込む。未キャッシュなら自動DL。"""
+    import os
+    import time
+
+    import torch
+    from huggingface_hub import snapshot_download
+    from transformers import AutoProcessor, Qwen2_5_VLForConditionalGeneration
+
+    os.environ["HF_HOME"] = CACHE_DIR
+    cfg = MODELS[model_key]
+
+    print(f"モデル準備中: {cfg['id']} ...")
+    t0 = time.time()
+    snapshot_download(cfg["id"])
+    model_cache.commit()
+    dl = time.time() - t0
+    print(f"モデル準備完了 ({dl:.1f}s)")
+
+    processor = AutoProcessor.from_pretrained(
+        cfg["id"],
+        min_pixels=cfg["min_pixels"],
+        max_pixels=cfg["max_pixels"],
+    )
+    model = Qwen2_5_VLForConditionalGeneration.from_pretrained(
+        cfg["id"],
+        torch_dtype=torch.bfloat16,
+        device_map="auto",
+    )
+    return processor, model
+
+
+@app.cls(
+    image=vlm_image,
+    gpu="A10G",
+    timeout=60 * 60,
+    memory=32768,
+    secrets=[hf_secret],
+    volumes={CACHE_DIR: model_cache},
+)
+class VLMInference7B:
+    @modal.enter()
+    def setup(self):
+        self.processor, self.model = _setup_model("7b")
+
+    @modal.method()
+    def ocr_pages(
+        self,
+        pages: list[tuple[str, bytes]],
+        prompt: str = DEFAULT_PROMPT,
+        structured: bool = False,
+        deep_think: bool = False,
+    ) -> dict[str, Any]:
+        return _run_ocr(self.processor, self.model, pages, prompt, structured, deep_think)
+
+
+@app.cls(
+    image=vlm_image,
+    gpu="A100-80GB:1",
+    timeout=60 * 60,
+    memory=65536,
+    secrets=[hf_secret],
+    volumes={CACHE_DIR: model_cache},
+)
+class VLMInference32B:
+    @modal.enter()
+    def setup(self):
+        self.processor, self.model = _setup_model("32b")
+
+    @modal.method()
+    def ocr_pages(
+        self,
+        pages: list[tuple[str, bytes]],
+        prompt: str = DEFAULT_PROMPT,
+        structured: bool = False,
+        deep_think: bool = False,
+    ) -> dict[str, Any]:
+        return _run_ocr(self.processor, self.model, pages, prompt, structured, deep_think)
+
+
+# ---------------------------------------------------------------------------
+# Local entrypoint
+# ---------------------------------------------------------------------------
+
+
+def _get_inference(model: str) -> VLMInference7B | VLMInference32B:
+    if model == "32b":
+        return VLMInference32B()
+    return VLMInference7B()
+
+
+@app.local_entrypoint()
+def main(
+    image_path: str | None = None,
+    input_dir: str | None = None,
+    model: str = "7b",
+    structured: bool = False,
+    deep_think: bool = False,
+    prompt: str | None = None,
+) -> None:
+    """
+    例:
+      modal run src/kuzushiji_ocr/vlm_app.py --image-path ./page.jpg
+      modal run src/kuzushiji_ocr/vlm_app.py --image-path ./page.jpg --model 32b
+      modal run src/kuzushiji_ocr/vlm_app.py --image-path ./page.jpg --deep-think
+      modal run src/kuzushiji_ocr/vlm_app.py --input-dir ./dataset/
+      modal run src/kuzushiji_ocr/vlm_app.py --image-path ./page.jpg --structured
+    """
+    if model not in MODELS:
+        print(f"不明なモデル: {model}  (選択肢: {', '.join(MODELS)})")
+        return
+
+    if input_dir:
+        _run_batch(input_dir, model, structured, deep_think, prompt)
+    elif image_path:
+        _run_single(image_path, model, structured, deep_think, prompt)
+    else:
+        print("用法:")
+        print("  modal run src/kuzushiji_ocr/vlm_app.py --image-path ./your.jpg")
+        print("  modal run src/kuzushiji_ocr/vlm_app.py --image-path ./your.jpg --model 32b")
+        print("  modal run src/kuzushiji_ocr/vlm_app.py --image-path ./your.jpg --deep-think")
+        print("  modal run src/kuzushiji_ocr/vlm_app.py --input-dir ./images/")
+        print("  modal run src/kuzushiji_ocr/vlm_app.py --image-path ./your.jpg --structured")
+
+
+def _run_single(image_path: str, model: str, structured: bool, deep_think: bool, prompt: str | None) -> None:
+    p = Path(image_path)
+    data = p.read_bytes()
+    model_id = MODELS[model]["id"]
+    mode = "多段推論" if deep_think else "structured" if structured else "standard"
+    print(f"推論中: {p.name} ({len(data)} bytes) [model={model_id}] [mode={mode}]")
+
+    inference = _get_inference(model)
+    kwargs: dict[str, Any] = {"structured": structured, "deep_think": deep_think}
+    if prompt:
+        kwargs["prompt"] = prompt
+    out = inference.ocr_pages.remote([(p.name, data)], **kwargs)
+    _print_results(out)
+
+
+def _run_batch(input_dir: str, model: str, structured: bool, deep_think: bool, prompt: str | None) -> None:
+    src = Path(input_dir)
+    if not src.is_dir():
+        print(f"ディレクトリが見つかりません: {input_dir}")
+        return
+
+    pages: list[tuple[str, bytes]] = []
+    for p in sorted(src.rglob("*")):
+        if p.is_file() and p.suffix.lower() in IMAGE_EXTS:
+            pages.append((p.name, p.read_bytes()))
+
+    if not pages:
+        print(f"画像が見つかりません: {input_dir}")
+        return
+
+    total_mb = sum(len(d) for _, d in pages) / 1024 / 1024
+    model_id = MODELS[model]["id"]
+    mode = "多段推論" if deep_think else "structured" if structured else "standard"
+    print(f"{len(pages)} 枚の画像を処理中 ({total_mb:.1f} MB) [model={model_id}] [mode={mode}] ...")
+
+    inference = _get_inference(model)
+    kwargs: dict[str, Any] = {"structured": structured, "deep_think": deep_think}
+    if prompt:
+        kwargs["prompt"] = prompt
+    out = inference.ocr_pages.remote(pages, **kwargs)
+    _print_results(out)
+
+
+def _print_results(out: dict[str, Any]) -> None:
+    texts = out.get("txt", {})
+    jsons = out.get("json", {})
+
+    if not texts and not jsons:
+        print("出力がありません。")
+        return
+
+    for name, text in texts.items():
+        print(f"--- {name} ---")
+        print(text)
+
+    if jsons:
+        print("\n========== JSON 出力 ==========")
+        for name, obj in jsons.items():
+            print(f"--- {name} ---")
+            print(json.dumps(obj, ensure_ascii=False, indent=2)[:4000])

src/kuzushiji_ocr/web.py

@@ -0,0 +1,629 @@
+"""
+くずし字 OCR Web アプリケーション。
+
+Modal 上の Qwen2.5-VL (7B/32B) で OCR を実行し、
+bounding box 重畳画像と多段生成テキストを返す。
+
+起動:
+  uv run uvicorn kuzushiji_ocr.web:app --reload --port 8000
+"""
+
+from __future__ import annotations
+
+import ast
+import asyncio
+import base64
+import io
+import json
+import logging
+import math
+import re
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Any
+
+import modal
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+from fastapi.responses import HTMLResponse
+from PIL import Image, ImageDraw, ImageFont, ImageOps
+
+from kuzushiji_ocr.vlm_app import (
+    MODELS,
+    _looks_like_flat_bbox_row,
+    _normalize_structured_item,
+    _parse_structured_output,
+    parse_bbox_rows_from_text,
+)
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)s [%(name)s] %(message)s")
+logger = logging.getLogger("kuzushiji-ocr")
+
+APP_DIR = Path(__file__).resolve().parent
+TEMPLATES_DIR = APP_DIR / "templates"
+
+app = FastAPI(title="くずし字 OCR")
+_executor = ThreadPoolExecutor(max_workers=4)
+
+# ---------------------------------------------------------------------------
+# フォント解決
+# ---------------------------------------------------------------------------
+
+_FONT_SEARCH_PATHS = [
+    "/System/Library/Fonts/ヒラギノ角ゴシック W3.ttc",
+    "/System/Library/Fonts/Supplemental/Arial Unicode.ttf",
+    "/Library/Fonts/Arial Unicode.ttf",
+    "/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
+    "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
+    "/usr/share/fonts/truetype/fonts-japanese-gothic.ttf",
+]
+
+
+def _resolve_font(size: int = 14) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
+    for p in _FONT_SEARCH_PATHS:
+        if Path(p).exists():
+            try:
+                return ImageFont.truetype(p, size)
+            except OSError:
+                continue
+    return ImageFont.load_default()
+
+
+# ---------------------------------------------------------------------------
+# 多段推論テキストパーサー
+# ---------------------------------------------------------------------------
+
+_STAGE_RE = re.compile(r"={10,}\s+(.+?)\s+={10,}")
+
+
+def _parse_stages(text: str) -> dict[str, str]:
+    """多段推論の出力を ``{"観察": "...", "翻刻": "...", ...}`` に分解する。"""
+    headers = list(_STAGE_RE.finditer(text))
+    if not headers:
+        return {"出力": text.strip()}
+
+    stages: dict[str, str] = {}
+    for i, m in enumerate(headers):
+        name = m.group(1).strip()
+        start = m.end()
+        end = headers[i + 1].start() if i + 1 < len(headers) else len(text)
+        stages[name] = text[start:end].strip()
+    return stages
+
+
+# ---------------------------------------------------------------------------
+# 画像読み込み（EXIF Orientation）
+# ---------------------------------------------------------------------------
+
+
+def _image_bytes_exif_aligned(data: bytes) -> bytes:
+    """EXIF Orientation を適用した画像を PNG バイト列にする。
+
+    ブラウザ表示と同じ向き・寸法のラスタにそろえ、VLM 入力と bbox 重畳で
+    同一のピクセル格子を使う（推論はこのバイト列を送る）。
+    """
+    img = Image.open(io.BytesIO(data))
+    img = ImageOps.exif_transpose(img)
+    buf = io.BytesIO()
+    img.convert("RGB").save(buf, format="PNG", optimize=True)
+    return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Qwen VL 入力解像度（qwen_vl_utils.smart_resize と同一式）
+#
+# AutoProcessor の min_pixels / max_pixels に合わせて画像が縮小される。
+# プロンプトの「ピクセル」はこの解像度上の値であることが多く、
+# そのまま元画像幅で 0-1000 扱いするとずれる。
+# ---------------------------------------------------------------------------
+
+_QWEN_PATCH_FACTOR = 28  # image_patch_size(14) * SPATIAL_MERGE_SIZE(2)
+
+
+def _round_by_factor(number: float, factor: int) -> int:
+    return int(round(number / factor) * factor)
+
+
+def _floor_by_factor(number: float, factor: int) -> int:
+    return int(math.floor(number / factor) * factor)
+
+
+def _ceil_by_factor(number: float, factor: int) -> int:
+    return int(math.ceil(number / factor) * factor)
+
+
+def _smart_resize_like_qwen(
+    height: int,
+    width: int,
+    min_pixels: int,
+    max_pixels: int,
+    factor: int = _QWEN_PATCH_FACTOR,
+) -> tuple[int, int]:
+    """qwen_vl_utils.vision_process.smart_resize と同じ (h_bar, w_bar) を返す。"""
+    assert max_pixels >= min_pixels, "max_pixels must be >= min_pixels"
+    h_bar = max(factor, _round_by_factor(height, factor))
+    w_bar = max(factor, _round_by_factor(width, factor))
+    if h_bar * w_bar > max_pixels:
+        beta = math.sqrt((height * width) / max_pixels)
+        h_bar = _floor_by_factor(height / beta, factor)
+        w_bar = _floor_by_factor(width / beta, factor)
+    elif h_bar * w_bar < min_pixels:
+        beta = math.sqrt(min_pixels / (height * width))
+        h_bar = _ceil_by_factor(height * beta, factor)
+        w_bar = _ceil_by_factor(width * beta, factor)
+    return h_bar, w_bar
+
+
+def _vision_input_size_px(img_w: int, img_h: int, model_key: str) -> tuple[int, int]:
+    """VLM が実際にリサイズして見る (proc_h, proc_w)。vlm_app MODELS と一致させる。"""
+    cfg = MODELS[model_key]
+    return _smart_resize_like_qwen(
+        img_h,
+        img_w,
+        cfg["min_pixels"],
+        cfg["max_pixels"],
+    )
+
+
+def _bboxes_within_proc_pixels(bboxes: list[list], proc_w: int, proc_h: int, tol: float = 1.5) -> bool:
+    """全角が VLM 入力リサイズ後の幅・高さに収まるなら proc 空間のピクセルとみなせる。"""
+    for b in bboxes:
+        if len(b) < 4:
+            continue
+        x1, y1, x2, y2 = b[0], b[1], b[2], b[3]
+        if min(x1, x2) < -tol or min(y1, y2) < -tol:
+            return False
+        if max(x1, x2) > proc_w + tol or max(y1, y2) > proc_h + tol:
+            return False
+    return True
+
+
+def _map_proc_pixel_bboxes_to_original(bboxes: list[list], proc_w: int, proc_h: int, img_w: int, img_h: int) -> list[list]:
+    sx = img_w / proc_w
+    sy = img_h / proc_h
+    out: list[list] = []
+    for b in bboxes:
+        if len(b) < 4:
+            out.append(b)
+            continue
+        out.append([b[0] * sx, b[1] * sy, b[2] * sx, b[3] * sy, *b[4:]])
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Bounding Box 正規化
+# ---------------------------------------------------------------------------
+
+
+def _normalize_bboxes(bboxes: list[list], img_w: int, img_h: int, model_key: str = "7b") -> list[list]:
+    """Qwen2.5-VL が返す座標を元画像のピクセル座標に変換する。
+
+    優先:
+      1. 値が VLM 入力リサイズ後の解像度に収まる → proc 上のピクセルとみなし線形拡大
+      2. それ以外 → 従来の 0-1000 / フル解像度ピクセル推定
+    """
+    if not bboxes:
+        return bboxes
+
+    proc_h, proc_w = _vision_input_size_px(img_w, img_h, model_key)
+    if _bboxes_within_proc_pixels(bboxes, proc_w, proc_h):
+        scaled = _map_proc_pixel_bboxes_to_original(bboxes, proc_w, proc_h, img_w, img_h)
+        logger.info(
+            "bbox 座標変換 (VLM 入力リサイズ空間 → 元画像):\n"
+            "  元画像       : %d x %d\n"
+            "  推論時解像度: %d x %d (smart_resize, model=%s)\n"
+            "  先頭 (変換前): %s\n"
+            "  先頭 (変換後): %s",
+            img_w,
+            img_h,
+            proc_w,
+            proc_h,
+            model_key,
+            bboxes[0][:5] if bboxes else "[]",
+            [round(v, 1) if isinstance(v, float) else v for v in scaled[0][:5]] if scaled else "[]",
+        )
+        return scaled
+
+    return _normalize_bboxes_heuristic(bboxes, img_w, img_h)
+
+
+def _normalize_bboxes_heuristic(bboxes: list[list], img_w: int, img_h: int) -> list[list]:
+    """proc 空間に収まらない場合の座標系推定（0-1000 / フル解像度ピクセル）。"""
+    coords = []
+    for b in bboxes:
+        if len(b) >= 4:
+            coords.extend([b[0], b[1], b[2], b[3]])
+    if not coords:
+        return bboxes
+
+    max_coord = max(coords)
+    img_max = max(img_w, img_h)
+
+    if max_coord <= 1.0:
+        mode = "0-1"
+        scale_x, scale_y = img_w, img_h
+    elif max_coord > 1100:
+        # Qwen の 0-1000 正規化では通常 1100 を超えない → 実ピクセルとみなす
+        mode = "pixel (>1100)"
+        logger.info(
+            "bbox 座標変換なし (max_coord>1100 → ピクセルと判定):\n  画像サイズ : %d x %d\n  max_coord  : %.1f\n  先頭       : %s",
+            img_w,
+            img_h,
+            max_coord,
+            bboxes[0][:5] if bboxes else "[]",
+        )
+        return bboxes
+    elif max_coord <= 1100 and img_max > 1100:
+        # 座標が ~1000 範囲で画像がそれより大きい → 0-1000 正規化
+        mode = "0-1000"
+        scale_x, scale_y = img_w / 1000, img_h / 1000
+    elif 0.8 < max_coord / img_max < 1.2:
+        # 座標範囲が画像サイズと近い → ピクセル座標
+        mode = "pixel"
+        logger.info(
+            "bbox 座標変換なし (ピクセル座標):\n  画像サイズ : %d x %d\n  max_coord  : %.1f\n  先頭       : %s",
+            img_w,
+            img_h,
+            max_coord,
+            bboxes[0][:5] if bboxes else "[]",
+        )
+        return bboxes
+    else:
+        # 判断がつかない場合は 0-1000 と仮定（Qwen2.5-VL のデフォルト）
+        mode = "0-1000 (fallback)"
+        scale_x, scale_y = img_w / 1000, img_h / 1000
+
+    scaled = [[b[0] * scale_x, b[1] * scale_y, b[2] * scale_x, b[3] * scale_y, *b[4:]] for b in bboxes]
+    logger.info(
+        "bbox 座標変換 (ヒューリスティック):\n"
+        "  画像サイズ : %d x %d\n"
+        "  座標モード : %s (max_coord=%.1f)\n"
+        "  スケール   : x=%.4f, y=%.4f\n"
+        "  変換前 (先頭): %s\n"
+        "  変換後 (先頭): %s",
+        img_w,
+        img_h,
+        mode,
+        max_coord,
+        scale_x,
+        scale_y,
+        bboxes[0][:5] if bboxes else "[]",
+        [round(v, 1) if isinstance(v, float) else v for v in scaled[0][:5]] if scaled else "[]",
+    )
+    return scaled
+
+
+# ---------------------------------------------------------------------------
+# 画像重畳
+# ---------------------------------------------------------------------------
+
+_COLOR_TEXT = (204, 120, 92)  # --color-accent
+_FILL_TEXT = (204, 120, 92, 35)
+_COLOR_OBJ = (90, 139, 111)  # --color-status-success
+_FILL_OBJ = (90, 139, 111, 35)
+
+
+def _rect_intersects(a: tuple[int, int, int, int], b: tuple[int, int, int, int]) -> bool:
+    """軸平行矩形 a, b = (x1, y1, x2, y2) が重なるか。"""
+    return not (a[2] <= b[0] or a[0] >= b[2] or a[3] <= b[1] or a[1] >= b[3])
+
+
+def _place_label_background(
+    x1: int,
+    y1: int,
+    lw: int,
+    lh: int,
+    img_w: int,
+    img_h: int,
+    placed: list[tuple[int, int, int, int]],
+) -> tuple[int, int]:
+    """ラベル背景矩形の左上 (lx, ly)。既に配置したラベル矩形と重ならない位置を探す。"""
+    if lw <= 0 or lh <= 0:
+        return 0, 0
+    lw = min(lw, img_w)
+    lh = min(lh, img_h)
+
+    def free(lx: int, ly: int) -> bool:
+        r = (lx, ly, lx + lw, ly + lh)
+        if r[0] < 0 or r[1] < 0 or r[2] > img_w or r[3] > img_h:
+            return False
+        return not any(_rect_intersects(r, p) for p in placed)
+
+    base_lx = max(0, min(int(x1), img_w - lw))
+    y_start = max(0, y1 - lh)
+    for ly in range(y_start, img_h - lh + 1, 2):
+        if free(base_lx, ly):
+            return base_lx, ly
+    for ly in range(0, min(y_start, img_h - lh + 1), 2):
+        if free(base_lx, ly):
+            return base_lx, ly
+    for lx in range(0, img_w - lw + 1, 6):
+        for ly in range(0, img_h - lh + 1, 2):
+            if free(lx, ly):
+                return lx, ly
+    return base_lx, max(0, min(y1 - lh, img_h - lh))
+
+
+def _draw_overlays(image_bytes: bytes, bboxes: list[list], model_key: str = "7b") -> bytes:
+    """元画像に bounding box + ラベルを重畳して PNG bytes を返す。"""
+    img = Image.open(io.BytesIO(image_bytes)).convert("RGBA")
+    bboxes = _normalize_bboxes(bboxes, img.width, img.height, model_key)
+
+    overlay = Image.new("RGBA", img.size, (0, 0, 0, 0))
+    draw = ImageDraw.Draw(overlay)
+    font_size = max(14, min(img.width, img.height) // 50)
+    font = _resolve_font(font_size)
+    pad = 4
+    img_w, img_h = img.width, img.height
+
+    # 物体 bbox を先に描画し、テキストラベルは後から重ならない位置へ
+    def _is_object_box(box: list) -> bool:
+        return len(box) >= 6 and str(box[5]).lower() in ("object", "obj")
+
+    sorted_boxes = sorted(bboxes, key=lambda b: (0 if _is_object_box(b) else 1,))
+
+    for box in sorted_boxes:
+        if len(box) < 5:
+            continue
+        x1, y1, x2, y2 = int(box[0]), int(box[1]), int(box[2]), int(box[3])
+        is_obj = _is_object_box(box)
+        color = _COLOR_OBJ if is_obj else _COLOR_TEXT
+        fill = _FILL_OBJ if is_obj else _FILL_TEXT
+        draw.rectangle([x1, y1, x2, y2], outline=color, width=2, fill=fill)
+
+    placed_labels: list[tuple[int, int, int, int]] = []
+
+    for box in sorted_boxes:
+        if len(box) < 5:
+            continue
+        x1, y1, x2, y2 = int(box[0]), int(box[1]), int(box[2]), int(box[3])
+        label = str(box[4])
+        if not label:
+            continue
+        is_obj = _is_object_box(box)
+        color = _COLOR_OBJ if is_obj else _COLOR_TEXT
+        tb = draw.textbbox((0, 0), label, font=font)
+        tw, th = tb[2] - tb[0], tb[3] - tb[1]
+        lw, lh = tw + pad * 2, th + pad * 2
+        lx, ly = _place_label_background(x1, y1, lw, lh, img_w, img_h, placed_labels)
+        placed_labels.append((lx, ly, lx + lw, ly + lh))
+        draw.rectangle(
+            [lx, ly, lx + tw + pad * 2, ly + th + pad * 2],
+            fill=(*color, 230),
+        )
+        draw.text((lx + pad, ly + pad), label, fill=(255, 255, 255, 255), font=font)
+
+    result = Image.alpha_composite(img, overlay).convert("RGB")
+    buf = io.BytesIO()
+    result.save(buf, format="PNG", optimize=True)
+    return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Modal 呼び出しヘルパー
+#
+# デプロイ済みアプリに対して modal.Cls.lookup() で接続する。
+# 事前に `modal deploy src/kuzushiji_ocr/vlm_app.py` が必要。
+# ---------------------------------------------------------------------------
+
+_MODAL_APP_NAME = "kuzushiji-vlm-ocr"
+
+
+def _get_inference(model_key: str) -> Any:
+    cls_name = "VLMInference32B" if model_key == "32b" else "VLMInference7B"
+    cls = modal.Cls.from_name(_MODAL_APP_NAME, cls_name)
+    return cls()
+
+
+def _call_structured(inference: Any, pages: list[tuple[str, bytes]]) -> dict[str, Any]:
+    return inference.ocr_pages.remote(pages, structured=True)
+
+
+def _call_deep_think(inference: Any, pages: list[tuple[str, bytes]]) -> dict[str, Any]:
+    return inference.ocr_pages.remote(pages, deep_think=True)
+
+
+def _collect_bboxes_from_modal_json(json_data: Any) -> list[list]:
+    """Modal / VLM の JSON 配列から bbox 行を集める。
+
+    次のどちらにも対応する:
+    - ``[[x1,y1,x2,y2,label], ...]`` — bbox のフラットな配列
+    - ``[[[x1,...], ...]]`` — 1 段ラップ（ページ相当）
+
+    誤って ``extend`` して座標をばらすことはしない。
+    """
+    out: list[list] = []
+    if not isinstance(json_data, list):
+        return out
+    for item in json_data:
+        if not isinstance(item, list) or not item:
+            continue
+        if _looks_like_flat_bbox_row(item):
+            row = _normalize_structured_item(item)
+            if row:
+                out.append(row)
+            continue
+        for sub in item:
+            if not isinstance(sub, list):
+                continue
+            row = _normalize_structured_item(sub)
+            if row:
+                out.append(row)
+    return out
+
+
+def _extract_bboxes(structured_result: dict[str, Any]) -> tuple[list[list], str]:
+    """structured 出力から bbox リストをフラットに取り出す。
+
+    Returns:
+        (bboxes, raw_text) — raw_text はデバッグ用の生テキスト。
+    """
+    raw_text = ""
+    for txt in structured_result.get("txt", {}).values():
+        raw_text = txt
+        break
+
+    # 1) Modal 側でパース済みの JSON を使う
+    bboxes: list[list] = []
+    for json_data in structured_result.get("json", {}).values():
+        bboxes.extend(_collect_bboxes_from_modal_json(json_data))
+
+    if bboxes:
+        logger.info(
+            "bbox %d 件取得（Modal パース済み JSON）:\n%s",
+            len(bboxes),
+            "\n".join(f"  [{i}] {b}" for i, b in enumerate(bboxes)),
+        )
+        return bboxes, raw_text
+
+    # 2) JSON が空の場合、生テキストを Web サーバー側で再パースする
+    if raw_text:
+        logger.info("Modal 側 JSON が空 — 生テキストを再パース:\n  %s", raw_text[:300])
+
+        # 2a) vlm_app の標準パーサー（json.loads — ダブルクォートのみ対応）
+        parsed = _parse_structured_output(raw_text)
+        if parsed:
+            for chunk in parsed:
+                if isinstance(chunk, list):
+                    bboxes.extend(_collect_bboxes_from_modal_json(chunk))
+
+        # 2b) VLM がシングルクォートで出力した場合のフォールバック
+        if not bboxes:
+            bboxes = _parse_bbox_lenient(raw_text)
+
+        if bboxes:
+            logger.info(
+                "bbox %d 件取得（Web サーバー側再パース）:\n%s",
+                len(bboxes),
+                "\n".join(f"  [{i}] {b}" for i, b in enumerate(bboxes)),
+            )
+            return bboxes, raw_text
+
+    logger.warning("bbox 取得失敗 — VLM 生テキスト:\n  %s", raw_text[:500] if raw_text else "(空)")
+    return [], raw_text
+
+
+def _parse_bbox_lenient(raw: str) -> list[list]:
+    """VLM がシングルクォートや Python リテラルで出力した場合に対応する。"""
+    row_scan = parse_bbox_rows_from_text(raw)
+    if row_scan:
+        return row_scan
+
+    match = re.search(r"\[.*\]", raw, re.DOTALL)
+    if not match:
+        return []
+
+    text = match.group()
+
+    # シングルクォートをダブルクォートに置換して json.loads
+    try:
+        data = json.loads(text.replace("'", '"'))
+    except (json.JSONDecodeError, TypeError):
+        pass
+    else:
+        return _flatten_bbox_list(data)
+
+    # ast.literal_eval で Python リテラルとしてパース
+    try:
+        data = ast.literal_eval(text)
+    except (ValueError, SyntaxError):
+        return []
+
+    return _flatten_bbox_list(data)
+
+
+def _flatten_bbox_list(data: Any) -> list[list]:
+    """パース済み JSON 配列を ``[[x1,y1,x2,y2,label], ...]`` にフラット化する。
+
+    ``bbox_2d`` 付きオブジェクト形式も ``vlm_app._normalize_structured_item`` で扱う。
+    """
+    if not isinstance(data, list):
+        return []
+
+    result: list[list] = []
+    for item in data:
+        row = _normalize_structured_item(item)
+        if row:
+            result.append(row)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# ルーティング
+# ---------------------------------------------------------------------------
+
+
+@app.get("/", response_class=HTMLResponse)
+async def index() -> HTMLResponse:
+    html = (TEMPLATES_DIR / "index.html").read_text(encoding="utf-8")
+    return HTMLResponse(html)
+
+
+@app.post("/api/ocr")
+async def ocr(
+    image: UploadFile = File(...),  # noqa: B008
+    model: str = Form("7b"),
+) -> dict[str, Any]:
+    if model not in MODELS:
+        raise HTTPException(400, f"不明なモデル: {model}  (選択肢: {', '.join(MODELS)})")
+
+    data = await image.read()
+    filename = image.filename or "upload.jpg"
+
+    try:
+        img = Image.open(io.BytesIO(data))
+        img.verify()
+    except Exception:
+        raise HTTPException(400, "無効な画像ファイルです") from None
+
+    try:
+        aligned = _image_bytes_exif_aligned(data)
+    except Exception:
+        raise HTTPException(400, "無効な画像ファイルです") from None
+
+    # Modal の MIME は拡張子で決まるため、実体が PNG なら .png に合わせる
+    aligned_name = f"{Path(filename).stem}.png"
+    pages: list[tuple[str, bytes]] = [(aligned_name, aligned)]
+    inference = _get_inference(model)
+    loop = asyncio.get_event_loop()
+
+    structured_fut = loop.run_in_executor(_executor, _call_structured, inference, pages)
+    deep_think_fut = loop.run_in_executor(_executor, _call_deep_think, inference, pages)
+
+    structured_result, deep_think_result = await asyncio.gather(structured_fut, deep_think_fut, return_exceptions=True)
+
+    # --- bbox ---
+    bboxes: list[list] = []
+    structured_raw = ""
+    if isinstance(structured_result, dict):
+        bboxes, structured_raw = _extract_bboxes(structured_result)
+
+    # --- 重畳画像（VLM に渡したのと同一の aligned ラスタに描画） ---
+    if bboxes:
+        annotated_bytes = _draw_overlays(aligned, bboxes, model)
+    else:
+        annotated_bytes = aligned
+    annotated_b64 = base64.b64encode(annotated_bytes).decode()
+
+    # --- ステージテキスト ---
+    stages: dict[str, str] = {}
+    if isinstance(deep_think_result, dict):
+        for text in deep_think_result.get("txt", {}).values():
+            stages = _parse_stages(text)
+            break
+
+    # --- エラー情報 ---
+    errors: list[str] = []
+    if isinstance(structured_result, Exception):
+        errors.append(f"構造化 OCR エラー: {structured_result}")
+    if isinstance(deep_think_result, Exception):
+        errors.append(f"多段推論エラー: {deep_think_result}")
+    if isinstance(structured_result, dict) and not bboxes:
+        errors.append(f"構造化 OCR は完了しましたが、bounding box を抽出できませんでした。 VLM 生テキスト: {structured_raw[:300]}")
+
+    return {
+        "annotated_image": annotated_b64,
+        "stages": stages,
+        "bboxes": bboxes,
+        "model_used": MODELS[model]["id"],
+        "errors": errors,
+    }

tests/test_imports.py

@@ -0,0 +1,10 @@
+from kuzushiji_ocr import __version__
+from kuzushiji_ocr.web import app
+
+
+def test_app_title() -> None:
+    assert app.title == "くずし字 OCR"
+
+
+def test_version() -> None:
+    assert __version__ == "0.1.0"