この手法は一般にテスト影響分析（test impact analysis）と呼ばれ、testmonはそれをPythonで無料で使える、オープンソースの手段です。gitにはまったく依存しません。比べる相手は前回の実行で見たコードで、コミット済みかどうかは関係ありません。

今週、私が作っているマーケットプレイスアプリのPythonのテストにこれを入れました。理由は、速さそのものではありません。

なぜ入れたのか

#

機能のリクエストは、たいてい小さなものです。画面が一つ、エンドポイントが一つ、挙動を変えたいルールが一つ。ところがテストスイートを丸ごと実行すると、そのどれもが実際より大きくなっていました。スイートはDjangoのテストが2,248件で、4プロセスで約3分半、1プロセスだと11分かかります。編集のたびにその全部を実行していましたが、そのほとんどはリクエストが一切触れていない部分を確認するものです。関係のないテストが落ちたり、単に実行に時間がかかったりするたびに、その機能は待たされました。機能リクエストとは関係のない事情で足止めされていて、足止めしていたのは自分のテストスイートだったわけです。

かといって、別のやり方がましだったわけでもありません。全体の実行は飛ばして、変更をカバーしていそうなテストファイルを当て推量で選び、ときどき外す。速くはありますが、正確ではありません。テストしていない変更をリリースすれば、その機能リクエストをもう一度やり直すことになります。

待つテストは、変更の届きうるテストとぴったり同じであるべきで、多すぎても少なすぎてもいけません。testmonはその集合を、推測ではなく記録から出してくれます。スイート全体は今もCIで実行していて、そこなら次に取りかかっている作業を止めることはありません。

何を実行するかの決め方

#

testmonは各Pythonファイルをブロックに分けます。モジュールのトップレベル、各クラス、各関数がそれぞれ一つのブロックで、ネストした関数の本体はそれを囲むブロックから切り離されます。保存するのは各ブロックのチェックサムだけで、コードそのものは保存しません。テストの実行中にcoverage.pyが実行された行を記録し、testmonはそれらの行がどのブロックに属するかを書き留めます。静的解析も、importからの推測もありません。テストが依存するのは、そのテストが実際に実行したブロックだけです。

たとえば、こんなモジュールがあるとします。

# pricing.py
def subtotal(items):
    return sum(item.price * item.quantity for item in items)

def discount(total, code):
    if code == "WELCOME10":
        return total * 0.9
    return total

subtotal()だけを呼ぶテストは、モジュールのトップレベルとsubtotalの本体に依存します。discount()をどう書き換えても、testmonはそのテストを再実行しません。そのテストはdiscountの行を一行も実行していないからです。逆にsubtotalの中を一文字でも変えれば、結果が変わりようのない変更でも再実行されます。testmonは副作用について賢く立ち回ろうとはしません。実行したブロックが変わったら、実行する。それだけです。

コードの周りにあるものも追跡します。記録にはPythonのバージョンと、インストール済みのパッケージとそのバージョンが含まれます。環境変数は見ていません。同じコードを二つの設定モジュールで動かすなら、--testmon-env（手順8）で名前を付けないと、一つの記録を共有してしまいます。Djangoをアップグレードすれば、Djangoに触れたものはすべてまた影響を受けます。Djangoアプリなら、それはつまり全部です。

見えないもの

#

testmonが追跡するのは、テストが実行するPythonのコードです。テストが読むそれ以外のファイル、つまりテンプレートやJSON、テキストなど、ディスク上にあるほかのものは追跡しません。ネットワーク越しに呼び出すサービスも追跡しません。そして、テストが始まる前に一度だけ実行されるものを、特定のテストに結びつけることもできません。

Djangoのプロジェクトでいえば、まずマイグレーションです。テスト用データベースを作るときに一度だけ実行されるので、どのテストの記録にも含まれません（後で紹介するラッパーは、新しいマイグレーションがあるとテスト用データベースを作り直します）。次に設定と起動時のコードで、pytestの起動中に実行されるので、どのテストにも属しません。そしてテンプレートとデータファイルです。テンプレートはPythonではないので、編集しても、それを描画するテストは一つも再実行されません。

私のスイートには、ほかにもいくつかあります。モバイルアプリのテストと共有しているフィクスチャのJSONファイルを読むテスト。ビルドしたWebのバンドルを確認するテスト。同じリポジトリで生成している静的サイトの出力を確認するテスト。どれを変えても、testmonは「何も実行する必要はありません」と平然と答えます。だから以下の手順では、testmonをスクリプトで包んで、こうしたファイルに気づき、どれかが変わっていたら全部を実行するようにしています。

Djangoのプロジェクトに入れる方法

#

ここではpytestとpytest-djangoを使い、依存関係はuvで管理している前提で書きます。pipを使っているなら、uv add --devをpip installに置き換え、uv runを外してください。

1. インストールする。

uv add --dev pytest-testmon

2. pytestでスイートを実行できるようにする。 testmonはpytestのプラグインなので、python manage.py testでは何もしません。pytest-djangoには、settingsモジュールと、テストが使っているファイル名のパターンを教える必要があります。

# pytest.ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings
python_files = tests.py test_*.py *_tests.py
python_classes = Test* *Tests *TestCase

これまでDjangoのランナーでしかスイートを実行したことがないなら、testmonを入れる前に一度pytestで実行し、違いが出たところを直しておきましょう。そうしないと、二つの問題を同時にデバッグする羽目になります。

3. 記録をgitに入れない。 testmonはpytestのルートディレクトリに.testmondataを書き出します。中身はSQLiteのデータベースなので、隣に-shmと-walのファイルもでき、さらに後で出てくるスクリプトがスタンプファイルを足します。パターン一つで全部まとめて除外できます。

# .gitignore
.testmondata*

4. 一度スイート全体を記録する。 testmonは、すべてのテストの実行を一度見るまで何も選べません。

uv run pytest --testmon

まっさらなチェックアウトでは、この最初の実行は1プロセスでのスイート全体の実行になります。私の環境では、2,248件のテストに約12分かかります。それ以降は、同じコマンドで影響を受けるテストだけが実行されます。何も変えていなければ、何も実行されません。

落とし穴が二つあります。一つ目に、testmon 2.2.0以前ではpytestのcacheプラグインが必要です。最初に試したときは-p no:cacheproviderを付けて実行していて、KeyError: 'lf'で落ちました（2.3.0では--lfがなければ未指定として扱われます）。二つ目に、Python 3.14以降では、記録する前にCOVERAGE_CORE=ctraceを設定してください。理由は、この後の「成功に見えたバグ」で説明します。以下のスクリプトで、いちばん大事な一行です。

追記（11月7日）：11月2日にリリースされたtestmon 2.3.0は、coverageのCトレーサーを自分で強制するようになったので、このバージョンではこのexportは念のためのものになります。2.2.0以前なら残してください。そして、わざと壊して確かめるチェックは、バージョンにかかわらず続けてください。

5. 見えないファイルのためにラップする。 毎日安心して使えるのは、この部分があるからです。スクリプトは、前回の実行が始まった時点のスタンプファイルを持っています。testmonが追跡できないファイルのどれかがスタンプより新しければ、全部を実行して記録し直します。新しいマイグレーションなら、テスト用データベースを作り直すだけです。そうでなければ、選ぶのはtestmonに任せます。削って例にしたものがこちらです。

#!/usr/bin/env bash
# scripts/test-changed.sh: the tests a change can affect, or all when in doubt.
#   scripts/test-changed.sh            # affected tests
#   scripts/test-changed.sh --all      # everything, re-recorded
#   scripts/test-changed.sh -k orders  # anything else goes to pytest
set -euo pipefail
cd "$(dirname "$0")/.."

# coverage's C tracer: from Python 3.14 coverage defaults to sys.monitoring,
# which reports a line only the first time a process runs it, so testmon
# would credit each line to one test. Changing this means --all.
export COVERAGE_CORE=ctrace

STAMP=.testmondata.started
full=false
rebuild=false
if [ "${1:-}" = "--all" ]; then
    full=true; shift
elif [ ! -f .testmondata ] || [ ! -f "$STAMP" ]; then
    echo "No record yet: running everything once."
    full=true
else
    # Changed since the last run started, and not traceable per test:
    # anything that isn't Python, plus settings and conftest.
    newer="$(find myapp myproject fixtures pytest.ini \
        -type f -newer "$STAMP" ! -path '*/migrations/*' \
        \( ! -name '*.py' -o -path 'myproject/settings*' -o -name 'conftest.py' \) \
        ! -path '*/__pycache__/*' | head -5)"
    if [ -n "$newer" ]; then
        echo "Changed, and not traceable per test:"; printf '  %s\n' $newer
        full=true
    fi
    # A new migration needs a fresh test database, not a full run.
    [ -n "$(find myapp -path '*/migrations/*.py' -newer "$STAMP" | head -1)" ] && rebuild=true
fi

# Stamp the start, so an edit made while the tests run counts next time.
started="$(mktemp .testmondata.run.XXXXXX)"
args=(--testmon --reuse-db)
# --create-db alone deletes the database when the run ends; with
# --reuse-db as well, the rebuilt one is kept for next time.
[ "$rebuild" = true ] && args=(--testmon --reuse-db --create-db)
[ "$full" = true ] && args=(--testmon-noselect --reuse-db --create-db)

status=0
uv run pytest "${args[@]}" -q "$@" || status=$?
# 0: passed, or nothing selected. 1: some failed (still recorded).
# 5: nothing collected at all.
case "$status" in 0|1|5) mv "$started" "$STAMP" ;; *) rm -f "$started" ;; esac
[ "$status" = 5 ] && exit 0
exit "$status"

この中で説明しておきたい点が二つあります。--reuse-dbは、テスト用データベースを実行の間で使い回すためのpytest-djangoのフラグです。一回の実行が数秒で済むようになると、これが効いてきます。毎回作り直していると、テストそのものより時間がかかることもあるからです。全体の実行や、新しいマイグレーションの後の実行では、データベースが現在のスキーマになるよう--create-dbを足します。そのときも--reuse-dbは外さないでください。--create-dbだけだと、pytest-djangoは実行の終わりにデータベースを削除してしまい、次の実行でまた一から作ることになります。

もう一つは終了コードです。testmonがすべてのテストを選択から外したとき、実行は0で終わるので、「何も変わっていない」は成功として扱われます。終了コード5はpytestの「テストが一つも収集されなかった」という意味で、スクリプトはこれも問題なしとして扱います。

リストに入っていないものにも注目してください。pyproject.tomlとロックファイルです。最初のバージョンはロックファイルが変わるたびに全部を実行していて、そのせいで遅いフォールバックがほぼ毎日発動し、入れる前より悪くなっていました。testmonはインストール済みのパッケージのバージョンを自分で追跡しているので、手助けはいりません。

6. 専用のデータベースとキャッシュを持たせる。 同じマシンでほかにもテストを実行するもの、たとえば二つ目のターミナルやコーディングエージェント、manage.py testなどがあるなら、スクリプトには専用のテスト用データベースと専用のキャッシュ番号を指定しておきます。そうすれば、使い回しているデータベースが他の誰かの実行と鉢合わせすることはありません。

export DATABASE_URL="postgresql://myapp:myapp@localhost:5432/myapp_changed"
export REDIS_URL="redis://localhost:6379/8"

7. 実行のたびにそのキャッシュを空にする。 これは痛い目を見て覚えました。一部だけを実行したときに、全体の実行では出ないKeyErrorが出るようになったのです。カテゴリのラベルの一部が有効期限なしでキャッシュされていて、ある実行から使い回したテスト用データベースが、それより前の実行で温まったままのキャッシュと出会っていました。スクリプトの冒頭でキャッシュをクリアしたら直りました。

uv run python -c "import os, redis; redis.Redis.from_url(os.environ['REDIS_URL']).flushdb()"

これはtestmonが、ドキュメントに書いてあるとおりのことをしているだけです。毎回違うサブセットを実行すると、前に何が実行されたかのおかげで通っていたにすぎないテストがあぶり出されます。直すべきはテストのセットアップで、testmonではありません。

8. 選択が間違っているときのためのフラグを知っておく。

• --testmon-noselectはすべてのテストを実行しますが、落ちそうなものを先に回します。-k、-m、--lfやテストのnode IDを一緒に渡すと、testmonは自動的にこれに切り替えます。
• --testmon-forceselectは、影響を受けるテストのうち、-kや-mにも一致するものだけを実行します。
• --testmon-nocollectは既存の記録を使いますが、記録には何も追加しません。デバッガの下で動かしているときや、coverageがすでに動いているときは、強制的にこれになります。
• --no-testmonは、一回の実行だけtestmonを無効にします。addoptsに入れているときに使います。
• --testmon-env=<name>は、一つのファイルの中に記録を別々に持ちます。二つのsettingsモジュールで実行するスイート向けです。

プロジェクトにJavaScriptの側もあるなら、Jestには同じような機能が最初から入っています。jest --changedSince=mainは、main以降に変わったものをimportしているテストを実行します。たどるのはcoverageではなくimportです。私はアプリのpackage.jsonにnpm run test:changedとして追加して、両側で同じ習慣が使えるようにしました。ユーティリティモジュールを一つ編集したときは、アプリの121個のテストファイルのうち7個が選ばれました。

どれだけ節約できるか

#

ラッパーを入れた後、次のセクションで書くバグを直してから、起動時間込みで計ってみました。

ふだんの編集なら並列実行のスイートより約25倍速く、何も変わっていなければ約200倍速くなります。

記録も、もっと広い範囲で同じことを示しています。スイートが実行する、テスト以外のPythonファイル307個のうち、中央値にあたるファイルを変えたときに届くのはテスト22件、テスト時間にして約8秒です。反対の端にはいくつかのコアモジュールがあります。ほぼすべてのテストがこれらを実行するので、変更すると約1,500件のテストに届き、testmonはスイートの大半を再実行します。これは失敗ではなく、正しい答えです。これらの数字はファイルごとの上限です。testmonはブロック単位で動くので、関数を一つ変えれば、その関数を実行したテストだけが選ばれます。

コストが表に出るのは、ラッパーがフォールバックしたときです。全体の実行は最初と同じ1プロセスでの記録なので約12分かかり、置き換える前の並列実行のスイートより遅くなります。1プロセスなのは、testmonをpytest-xdistと組み合わせてまだ試していないからです。xdistは1.4から対応しているので、次に測るべきはそこでしょう。だからこそ、フォールバックのきっかけになるファイルのリストは、正直でいられる範囲でできるだけ短くしておくべきです。

成功に見えたバグ

#

最初に出た数字は、これよりも良いものでした。一か所の編集でテスト6件、3.3秒。でもそれは間違っていて、画面のどこにもそうは書いてありませんでした。

Python 3.14から、coverage.pyはデフォルトで新しいコアを使います。インタプリタのsys.monitoringの上に作られたものです。このコアがある行を報告するのは、プロセスがその行を初めて実行したときだけです。testmonはどのテストがどの行を実行したかの記録をcoverageから作るので、各行は、たまたま最初にそれを実行したテスト一つだけのものとして記録され、ほかのどのテストにも結びつきませんでした。8件のテストが共有している行を編集しても、testmonはそのうち1件しか選びません。

気づいたのは、この仕組みをそのまま真似した、私の別の小さなプロジェクトでした。そちらに導入する作業の一環として、わざと一行を壊して結果を比べたところ、数字が合わなかったのです。こちらのスイートに戻って、同じ確認をしました。ホーム画面のバナーのコードで、スライドのタイトルの一行を壊します。素のpytestでは8件のテストが失敗しました。testmonが選んだのは4件です。壊れた残りの4件は一度も実行されず、出力のどこにも、それらが外されたことは書いてありませんでした。

直すのは一行で、export COVERAGE_CORE=ctraceです。これでcoverageは昔ながらのCトレーサーに戻ります。トレーサーが違えば記録も違うので、記録し直しました。2,248件のテストで12分3秒です。その後、同じように壊す編集をしたら、壊れた11件のテストがすべて実行されました。

追記（11月7日）：11月2日リリースのtestmon 2.3.0は、プロセス内でもサブプロセスでもCトレーサーを自分で設定するようになったので、新規に入れる場合はこのexportはもう要りません。次の段落のチェックは、今でも要ります。

この記事で何よりも先に伝えたい教訓はこれです。選ぶテストが少なすぎるテストセレクタは、成功とまったく同じに見えます。テストは少なく、実行は速く、すべて緑。だから導入するときは、共有されている何かをわざと壊し、素のスイートとセレクタの両方を実行して、同じテストが失敗するかを確かめてください。そして、Pythonやcoverage.pyのバージョンが変わるたびに、もう一度やってください。

コーディングエージェントの出番

#

そのリポジトリの変更を、もう全部自分でしているわけではありません。小さな変更の多くはコーディングエージェント（私の場合はClaude Code）がしていて、良いエージェントは編集のたびにテストを実行します。11分かかるスイートを前にすると、エージェントにも私と同じ二つの悪い選択肢しかありません。待つか、どのテストファイルが関係するかを当て推量するかです。

そこで、リポジトリのエージェント向けの指示に、作業中のテストはこのラッパースクリプトで実行するのを基本とし、全体を実行するときは--allを付ける、と書きました。エージェントも私と同じ正確なテストの集合を、編集のたびに数秒で得られます。ステップ6でスクリプトに専用のデータベースとキャッシュを持たせているのも、これが理由です。忙しい日には同じマシンで複数のセッションがテストを実行していて、使い回しているデータベースが他の誰かの実行と鉢合わせすることは、絶対にあってはなりません。

どれも、testmonにAI固有の何かを求めているわけではありません。同じ記録、同じ選択です。ただ、変更を加えているのが何であれ、その変更の数がとても多いと、それだけ効き目も大きくなります。

CIにはもっと粗いものを入れた理由

#

testmonにはCIモードがありません。ランナーの上でもノートPCの上と同じように動きます。作者は、CIのランナー間で.testmondataを共有したりキャッシュしたりするのは、自分たちのホスティングサービスであるtestmon.netに比べてずっと効果が薄いと書いています。キャッシュした記録は上で挙げた点でどれも見えないままですし、私のCIはDjangoのランナーを4プロセスで動かしてスイートを実行しています。なので、testmonは入れませんでした。

代わりにCIに入れたのは、同じ考え方をファイル単位にしたものです。チェックのワークフローはまず小さなジョブでpushの差分を取り、リポジトリのどちら側に触れたかを判断します。PythonのAPIか、モバイルアプリか、両方か、どちらでもないか。これまでCIは、ドキュメントだけのものも含めて、pushのたびにPythonとアプリの両方のジョブを実行していました。今は、ドキュメントだけのpushなら何も実行せず、アプリだけへのpushならDjangoのスイートを飛ばします。実際のコミット5件に対してこのジョブを試しに走らせてみたところ、ドキュメントだけのコミットでは何も実行されず、アプリだけのコミットではPythonのジョブが、バックエンドだけのコミットではアプリのジョブが飛ばされました。削って例にしたものがこちらです。

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      python: ${{ steps.diff.outputs.python }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - id: diff
        env:
          BEFORE: ${{ github.event.before }}
          HEAD: ${{ github.sha }}
        run: |
          FILES="$(git diff --name-only "$BEFORE" "$HEAD")"
          # Python's inputs include the non-Python files its tests read.
          PY='^(myapp/|myproject/|fixtures/shared\.json$|web/dist/|pyproject\.toml$|uv\.lock$)'
          if printf '%s\n' "$FILES" | grep -qE "$PY"; then
            echo "python=true" >> "$GITHUB_OUTPUT"
          else
            echo "python=false" >> "$GITHUB_OUTPUT"
          fi

  python:
    needs: changes
    if: needs.changes.outputs.python == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: uv run python manage.py test --parallel 4 --noinput

実際のワークフローでは、比べる範囲がないとき、つまり新しいブランチやforce push、手動実行のときにも全部を実行します。

盲点は、形を変えただけで同じものです。testmonにはJSONファイルが見えませんが、パスのフィルタも、リストに書かない限り見えません。そこでパターンには共有のフィクスチャ、ビルドしたバンドル、生成したサイトを明示的に書き、編集する人にはリストを実態に合わせておくよう頼むコメントを添えています。ファイル単位のやり方は大雑把ですが、失敗するときは安全な方向に失敗します。Python側で何かが変わっていれば、スイート全体が実行されます。

入れる価値はあるか

#

実行に数分かかるスイートなら、あります。本当のコストは見えないものの方で、ラッパースクリプトはそのためにあります。それでも、testmonが活きるのはノートPCでの開発ループです。CIはPython側が変わるたびに今もスイート全体を実行していて、デプロイの前に私が信頼しているのはその実行です。

GitHub ActionsでDocker Composeを動かす方法を探してここに来たなら、先に結論を。私はそれを2年やって、やめました。いまのCIは同じPostgresとValkeyのイメージをservices:として宣言し、同じuv run …とnpm run …をランナー上で直接実行します。Composeは開発者が手元で動かすものに戻りました。以下はその理由と、実際のファイルです。

2024年にCI/CDのロジックはプラットフォーム固有のYAMLではなくDocker Composeにという記事を書きました。ビルドのロジックはComposeに置き、CIツールにはそれを呼ぶことだけをさせる、という内容です。2年たって、実際にリリースに使っているリポジトリを全部見直しました。ワークフローがあるのは4つで、コミッターはどれも私一人です。そして、そのワークフローのうちdocker composeを呼んでいるものは、もう一つもありません。原則は残り、やり方は残りませんでした。以下はその代わりに入ったものです。ファイルを削って例にしたもの、GitHubが記録したステップごとの所要時間、そしてCI/CDの図が期待するほどには自動化されていない部分も書いています。

動かしているパイプラインを一つの表に

#

教科書の言葉でいえば、二つのHugoサイトは継続的デプロイメントで、アプリ（私が作っているマーケットプレイス兼コミュニティアプリ）は継続的インテグレーションにコマンド一つのリリースを足した継続的デリバリーです。チェックは何かがおかしいと教えてくれるだけで、デプロイを止めはしません。これは意図してそうしています。OTAアップデートは対象のバイナリバージョンを使っているすべての端末に届くので、マージの副作用ではなく判断であるべきです。そしてAPIはデータベースのマイグレーションが走る場所です。残り二つのDjangoアプリには、ワークフローがそもそもありません。

CIの側：ワークフロー一つ、ジョブ二つ

#

アプリのCIは.github/workflows/checks.ymlというファイル一つです。10月11日までは、これすらありませんでした。以下はその形を削って例にしたものです。

# Lint, types and tests on every push and pull request to main.
# Nothing here deploys.
name: Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: checks-${{ github.ref }}
  cancel-in-progress: true

jobs:
  python:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_USER: myapp
          POSTGRES_PASSWORD: myapp
          POSTGRES_DB: myapp
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U myapp"
          --health-interval 5s --health-timeout 5s --health-retries 20
      valkey:
        image: valkey/valkey:8-alpine
        ports: ["6379:6379"]
    env:
      DEBUG: "True"
      DATABASE_URL: postgresql://myapp:myapp@localhost:5432/myapp
      REDIS_URL: redis://localhost:6379
      PYTHON_JIT: "0"   # match production
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10
        with:
          enable-cache: true
          prune-cache: true
      - run: uv sync --locked
      - run: uv run ruff check .
      - run: uv run mypy myapp/
      - run: uv run python manage.py test --parallel 4 --noinput

  app:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        working-directory: frontend
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: frontend/package-lock.json
      - run: npm ci
      # Expo writes this on `expo start` and it is gitignored,
      # so a fresh checkout doesn't have it.
      - run: printf '/// <reference types="expo/types" />\n' > expo-env.d.ts
      - run: npm run typecheck
      - run: npx jest --ci

二つのジョブは並行して走ります。これまでに成功した35回の実行で、アプリのジョブの中央値は約7分、Pythonのジョブは約12分半です。

services:ブロックが、Composeファイルの移った先です。これは次の節で書きます。環境変数はいくつかとフラグ一つだけです。ほかはすべて開発者がdocker compose upで得る開発用のデフォルトに落ちるので、テストにシークレットは一つも要りません。本当にそうか確かめるために、まさにその環境だけで、ほかに何もない状態でテストの一部を走らせました。

CIは手元のノートPCや本番イメージと同じインタープリタ、つまりuv自身がビルドしたPython 3.15.0で動きます。uv syncが.python-versionを読み、まさにそのビルドをダウンロードするからです。（実際のファイルではsetup-uvにpython-version-fileという入力も渡していますが、これは何もしていません。setup-uv v6にはそんな入力がなく、毎回の実行にそういう警告が付いています。この記事を書いていて初めて気づきました。）

インタープリタを揃えた甲斐は、ワークフローを入れて8日後に出ました。10月19日に3.15のJITコンパイラを有効にしたところ、有効にして最初の実行でテストが一つ落ちたのです。アプリが保存のたびに通るコードパスのごく普通のyield fromが、AttributeError: 'list' object has no attribute 'send'を投げていました。同じコミットをJITなしで走らせると通ります。私のMacはarm64で一度もこれに当たらず、ランナーは本番マシンと同じx86_64です。JITはCIでもDockerfileでも再び無効にしてあり、このバグが本番に届くことはありませんでした。これはpython/cpython#155823で、3.15.0のリリース後の10月13日に上流で修正されています。

実は最初の実行も落ちていて、こちらの理由はもっと地味です。Expoはexpo startのときにexpo-env.d.tsを書き出し、このファイルはgitignoreされています。なので私が使ってきた作業コピーにはどれもあり、まっさらなチェックアウトにはありませんでした。TypeScriptは、ローカルでは一度も出たことのないエラーを五つ出しました。そのファイルを書き出すステップが対処です。

concurrencyは、同じブランチに新しいpushが来ると前の実行を取り消します。これまでに取り消された12回は、すべてこれによるものです。コミット前のフック（pre-commit）がリンターを走らせ、PythonかTypeScriptがステージされていれば型チェッカーも走らせるので、ミスの大半はpushまで行きません。

Docker Composeファイルはどこへ行ったか

#

アプリのdocker-compose.ymlのうち、CIに関係する部分を例にしたものです。実物にはもっと多くのサービスと、ずっと多くの環境変数があります。

services:
  valkey:
    image: valkey/valkey:8-alpine
    ports:
      - "6379:6379"

  # Host port 55432, not 5432, so it can't collide with a local Postgres.
  postgres:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=myapp
      - POSTGRES_PASSWORD=myapp
      - POSTGRES_DB=myapp
    ports:
      - "55432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp -d myapp"]
      interval: 5s
      retries: 10

  api:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://myapp:myapp@postgres:5432/myapp
      - REDIS_URL=redis://valkey:6379
    depends_on:
      postgres:
        condition: service_healthy
      valkey:
        condition: service_started

volumes:
  postgres_data:

checks.ymlのservices:ブロックと並べると、同じイメージが二つです。Postgres 17（こちらはAlpine版、CIはDebian版）とvalkey/valkey:8-alpine。いまの関係はこうです。Composeファイルは開発者が動かすもの。CIは同じイメージをサービスコンテナとして宣言し、開発者が打つのと同じコマンド、uv run …とnpm run …をランナー上で直接実行します。

2024年の記事と比べると、いちばん大事にしていた部分は残りました。CIツールは薄く、チェックもデプロイも自分で実行できるコマンドです。残らなかったのは、CIからComposeを呼ぶやり方です。

アプリのCIはDockerイメージをまったくビルドしません。イメージはデプロイのときにFlyのビルダーが一度だけビルドし、CIはコードが大丈夫かどうかだけ答えればよく、ツールチェーンがキャッシュされていればそれは6秒のインストールで済みます。それにComposeファイルは作業コピーをバインドマウントし、データを投入しますが、それはテストの実行がすることではありません。CI用に別のComposeファイルが必要になっていたはずで、それは同じサービスの二つ目の定義を手で揃え続けるということです。

そして2024年の例には、当時気づかなかったバグがありました。docker compose buildはイメージをビルドするだけで、サービスのcommandは実行しません。なので、あのファイルのnpm testはCIで一度も走っておらず、ワークフローはテストが通ろうが落ちようが緑でした。

あの記事がいちばん心配していたリスク、つまりCIベンダーの乗り換えは、結局起きませんでした。実際に起きた移行は反対側でした。このブログとクライアントのサイトがホスティング先をCloudflare Pagesに移し、ブログのほうは45行のワークフローを一つ新しく書くだけで済みました。ビルドがもともとコマンド一つだったからです。それから、私が警告していた300行のワークフロー。一つあります。pyhtml2textのものです。wheelをLinux、macOS、Windowsのランナーで、それぞれ複数のアーキテクチャ向けにビルドしなければならないので長いのですが、だからこそプラットフォーム固有のYAMLが正しい道具になる唯一の仕事でもあります。

キャッシュ：まずステップの所要時間を読む

#

GitHubはすべてのステップの所要時間を記録していて、gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobsで取り出せます。以下は10月20日の、アプリで最新の成功した実行です。

依存関係のキャッシュは二つとも有効で、どちらも安い部分です。GitHubがこのリポジトリ用に保持しているuvのキャッシュは200KBほどで、setup-uvがダウンロードし直せば済むものを整理してしまうからです。npmのほうは400MB近くあります。時間がかかっているのはテストで、テストはすでに4並列で走っています。実行を速くしたいなら、キャッシュではなくテストスイートに手を入れます。

ブログは正反対です。Hugoが処理した画像はgitignoreされたresources/_genにあるので、新しいランナーのたびにカバー、本文の画像、プレースホルダーを全部エンコードし直していました。後で載せるワークフローはactions/cacheでこれを復元します。キーは画像そのもののハッシュで、合わなければいちばん新しい古いキャッシュで代用します。Hugoは足りない分しか処理しないからです。キャッシュ導入前の最後の8回では、ビルドのステップに33〜76秒かかっていました。導入後の26回は6〜20秒で、例外は94秒の一回だけ。しかも同じコミットでプレースホルダーと二つ目のカードサイズを追加したうえでの数字です。

アプリのイメージはFlyのビルダーでビルドされ、依存関係のファイルをコードより先にコピーし、uvのダウンロードキャッシュはBuildKitのキャッシュマウント（RUN --mount=type=cache,target=/root/.cache/uv）に置いています。ただ、もっと大きな改善はキャッシュではありませんでした。以前の.dockerignoreはブロックリストで、追加のgit worktreeを置いたフォルダーを漏らしていました。それぞれが自分の依存関係とビルド成果物を抱えています。そのせいで27万7千ファイル、7.7GBが、デプロイのたびにビルダーへ送られていました。許可リストに書き直したいま、ビルドコンテキストは40MBほどです。パターンの例はこうです。

# Exclude everything, then let back in only what the Dockerfile COPYs.
*

!pyproject.toml
!uv.lock
!manage.py
!myapp
!static

# Rules match the whole relative path and the last match wins,
# so these re-excludes apply inside the allowed directories too.
**/__pycache__/
**/*.pyc
**/.DS_Store
**/*.log

シークレットはできるだけ少ない場所に

#

シークレットは三か所にあります。GitHub Actionsのシークレットはワークフローがすることのためのもので、二つのHugoリポジトリにはそれぞれCLOUDFLARE_API_TOKENが一つあるだけです。Flyのシークレットはアプリの実行時設定で、flyctl secrets setで入れ、Actionsを経由することはありません。そしてノートPCのgitignoreされた.envに、デプロイスクリプトがCloudflareのキャッシュを消すときに使うトークンがあります。

PyPIにはシークレットがそもそも要りません。pyhtml2textはトラステッドパブリッシングを使っています。GitHubがワークフローに発行する短命のOIDCトークンをPyPIが受け付けるので、リリースのジョブはid-token: writeを求めるだけで、リポジトリのシークレットのページは空です。漏れるものも、ローテーションするものもありません。

トークンには必要な分だけを与えます。GitHubにあるアプリのFlyトークンは、マシンの一覧を取るだけの定期チェック用なので、fly tokens create readonlyで作っています。Pagesのデプロイが求めるのはcontents: readとdeployments: writeだけで、それ以上はありません。

入力は直接スクリプトに入れず、必ずenv:を通します。OTAのワークフローは自由記述のリリースノートを受け取ります。これをrun:の中に${{ inputs.notes }}と書くと、bashが読む前にテキストがスクリプトにそのまま貼り込まれるので、引用符とセミコロンを含むノートはコードになってしまいます。環境変数として渡せば、データのままです。パターンの例です。

      - name: Publish
        env:
          OTA_API_TOKEN: ${{ secrets.OTA_API_TOKEN }}
          INPUT_PLATFORM: ${{ inputs.platform }}
          INPUT_ROLLOUT: ${{ inputs.rollout }}
          INPUT_NOTES: ${{ inputs.notes }}
        run: |
          args=("$INPUT_PLATFORM")
          [ -n "$INPUT_ROLLOUT" ] && args+=(--rollout "$INPUT_ROLLOUT")
          [ -n "$INPUT_NOTES" ] && args+=(--notes "$INPUT_NOTES")
          ./scripts/publish-ota.sh "${args[@]}"

GitHubの外に置いたままのキーもあります。ある定期レポートには、アプリのサインイン基盤に対する管理者権限を持つキーが必要です。なのでそのレポートは定期ワークフローから、Mac上の定期ジョブに移しました。ワークフローは手動の予備として残してあり、そのキーが要るセクションを除いて投稿します。

デプロイ：pushごとに、スクリプトで、タグで

#

Hugoサイトはpushのたびにデプロイ

#

ブログのワークフローを例にしたものです。初回だけPagesのプロジェクトを作るステップは省いています。

name: Deploy to Cloudflare Pages

on:
  push:
  workflow_dispatch:

env:
  HUGO_VERSION: "0.165.0"
  PAGES_PROJECT: my-site

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v7
        with:
          submodules: true

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      # Processed images are gitignored; restore them so Hugo only
      # re-encodes what is new. An older cache still helps.
      - uses: actions/cache@v6
        with:
          path: resources/_gen
          key: hugo-resources-${{ hashFiles('content/**/*.jpg', 'content/**/*.png', 'assets/img/**') }}
          restore-keys: |
            hugo-resources-

      # A multilingual site has no root 404.html; without one, Pages
      # answers unknown paths with index.html and a 200.
      - name: Build
        run: |
          hugo --gc
          cp public/en/404.html public/404.html

      # ...

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy public --project-name=${{ env.PAGES_PROJECT }} --branch=${{ github.ref_name }}

--branch=${{ github.ref_name }}によってmainが本番になり、ほかのブランチはどれもプレビューURLを得ます。クライアントのサイトのワークフローはこれと同じ形で、ビルドの前にrm -rf publicが一行加わっています。あちらはpublic/がコミットされているので、そうしないと削除したページがアップロードに残り続けるからです。

Hugoのバージョンはここでだけ固定しています。10月にパッケージマネージャーのアップグレードでノートPCのHugoが0.168に上がりましたが、これはテーマが対応する最新版より一つ新しいものです。デプロイは0.165のままで、何も起きませんでした。

そして、ビルドそのものがテストです。9月14日、あるブランチのプレビューデプロイが3回続けて失敗しました。そのブランチの記事が、Hugoのrefでまだ下書きの記事を指していたのです。CIは本番と同じように下書きを除いてビルドするので、リンク先は存在せず、HugoはREF_NOT_FOUNDで止まりました。その間もmainは普通にデプロイされ続けていました。

アプリのAPIはスクリプトでデプロイ

#

デプロイスクリプトの中心部分を例にしたものです。

IMAGE_LABEL="deploy-$(git rev-parse --short HEAD)-$(date +%Y%m%d%H%M%S)"

# Build first, then wake a spare machine, then roll out exactly that image.
flyctl deploy --config fly.toml --build-only --push --image-label "$IMAGE_LABEL"
curl -fsS --retry 5 https://myapp.fly.dev/health > /dev/null
flyctl deploy --config fly.toml --image "registry.fly.io/myapp:$IMAGE_LABEL"

そしてfly.tomlの対応する部分です。

[deploy]
  # max_unavailable only counts machines that are running,
  # which is why the script wakes one first.
  strategy = "rolling"
  max_unavailable = 1

イメージは一度だけビルドし、コミットと時刻からなるラベルを付けてFlyのレジストリに送り、そのラベルでデプロイします。なので、ロールアウトされるのはビルドしたものそのものです。

ゼロダウンタイムを実現しているのは、先に予備のマシンを起こしておくことです。max_unavailable = 1が数えるのは動いているマシンだけですが、アプリは暇なときに動いているマシンを一台も置きません（サスペンドしたマシンは1秒ほどで復帰します）。そのため、起きていた一台が寝ているマシンと同じバッチで置き換えられ、後ろに温まったマシンが一台もない、ということが起きていました。9月28日にオリジンへプローブを送り続けて測ったところ、素のflyctl deployではタイムアウトが7回と7.3秒の空白があり、先にビルドしてロールアウト開始時にはマシンを一台起こしておくスクリプトのデプロイでは、2,514リクエストで失敗はゼロでした。

スクリプトの残りは、エラーの通知が届くチームのチャットチャンネルにデプロイの印を残します。エラーが固まって出たとき、直前に何が変わったかと照らし合わせられるようにです。それからCloudflareのキャッシュを消し、マシンを温めておきます。Webフロントエンドはイメージをまったく通りません。それはフロントエンドとバックエンドを別々にデプロイするに書きました。

マイグレーションはパイプラインのステップではありません。Flyのrelease_commandが私の環境では固まってしまったので、新しいイメージで最初に起動したマシンがロックを取ってマイグレーションし、ほかのマシンは待ちます。そのため、どのマイグレーションもまだ動いているコードと両立しなければなりません。カラムはあるデプロイで追加し、次のデプロイで使うのをやめ、三回目のデプロイで削除します。

このスクリプトに、私のノートPCでなければならない部分は特にありません。ただ、ノートPCにしかないファイルがいくつかあって、それが縛りになっています。Cloudflareの認証情報と、最後に何をデプロイしたかの記録で、まっさらなランナーにはこれがありません。コミットしていない変更もデプロイしてしまい、チャットでそう知らせますが、Webのリリース用スクリプトは汚れた作業ツリーを拒否します。

ブランチごとのプレビュー環境で私は、これを手でやるのは自分一人なら構わないが、二人目の開発者からはgitで何かが起きたから起きるようにしなければならない、と書きました。アプリの開発者はまだ一人です。あの記事のブランチ環境のワークフローは、作ったときのブランチにそのまま置いてあります。

OTAのワークフローは手動専用です。公開は判断であるべきですし、アップデートのサービスは部分ロールアウトが開いている間は新しいリリースを拒むので、pushトリガーではカナリアのたびに引っかかってしまいます。このワークフローは一度も実行されたことがありません。これまでのOTAアップデートはすべてノートPCから、ワークフローが呼ぶのと同じスクリプトで出しています。薄いワークフローにする理由は一言でこれです。リリースをどう始めても、同じスクリプトです。

pyhtml2textはタグでリリース

#

リリースのジョブです。パッケージ名は一般的なものにしてあります。

  release:
    runs-on: ubuntu-latest
    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
    needs: [linux, macos, windows, sdist]
    environment:
      name: pypi
      url: https://pypi.org/p/mypackage
    permissions:
      id-token: write       # trusted publishing and signing
      contents: write
      attestations: write
    steps:
      - uses: actions/download-artifact@v8
      - uses: actions/attest@v4
        with:
          subject-path: 'wheels-*/*'
      - uses: astral-sh/setup-uv@v10
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        with:
          prune-cache: true
      - name: Publish to PyPI
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        run: uv publish --trusted-publishing always 'wheels-*/*'

リリースのジョブはすべてのビルドジョブを待ち、実際に公開するのはタグのときだけです。手動実行はビルドとアテステーションまではしますが、何もアップロードしません。actions/attestはどのワークフローが各wheelをビルドしたかを記録し、uv publish --trusted-publishing alwaysはパスワードの代わりにOIDCトークンでアップロードします。パッケージそのものについては閉じられたプルリクエスト、フォーク、そしてPyPIパッケージに書きました。

定期ワークフローはベストエフォート

#

アプリには定期ワークフローが一つあります。Flyがベースラインより多くのマシンを起動していないかを見るチェックで、放っておけば請求書で初めて気づくことです。通知はわざと失敗することで行います。定期実行が失敗すると、GitHubが所有者にメールを送るからです。

設定はcron: '*/15 * * * *'、1日96回です。ところがこの2週間は1日3〜8回しか動いておらず、実行間隔の中央値は3時間40分ほどでした。GitHubのドキュメントが挙げる理由は負荷だけです。Actionsが混んでいると定期実行は遅れることがあり、混み具合によっては落とされることもある、と。持続的なスケールアウトを見るなら数時間で十分です。数分以内に鳴らなければならないものにとって、GitHubのcronは監視ではありません。

パイプラインに投げかけたい質問

#

これから作る人も、すでにあるものを見直している人も：

1. GitHub Actionsが丸一日止まったら、それでもリリースできますか？ できないなら、リリースのロジックがYAMLの中にあるということで、2024年の記事がまだ当てはまります。
2. CIは本番と同じインタープリタ、同じCPUアーキテクチャ、同じデータベースのメジャーバージョンで動いていますか？ 私のCIがコンパイラのバグを捕まえられたのは、ランナーと本番がどちらもx86_64で、ノートPCがそうではなかったからです。
3. まっさらなチェックアウトで通りますか？ 通らないとしたら、たいていは生成されてgitignoreされたファイルのせいです。
4. 実行時間は実際どこに使われていますか？ キャッシュを足す前に、ステップの所要時間を読んでください。
5. シークレットはそれぞれ何か所にありますか？ そして本当にGitHubに置く必要がありますか？

pip install pyhtml2text

from pyhtml2text import html2markdown

html = """<h2>Before you start</h2>
<p>Read the <a href="setup.html">setup guide</a> and <b>back up</b> your data.</p>
<img src="https://jared.lynskey.co.nz/img/diagram.png" alt="How it fits together">
<table><tr><th>Plan</th><th>Price</th></tr><tr><td>Basic</td><td>Free</td></tr></table>"""

print(html2markdown(html, base_url="https://example.com/docs/intro.html"))

## Before you start

Read the [setup guide](https://example.com/docs/setup.html) and **back up** your data.

![How it fits together](https://example.com/img/diagram.png)

| Plan | Price |
| --- | --- |
| Basic | Free |

始まりはrust-html2textへのプルリクエストでした。メンテナーはLLMで書かれたという理由でそれをクローズしたので、pyhtml2textはフォークの上で動いています。この記事では、その経緯、フォークとパッケージの中身、そしてMarkdownが正しいことをどう確かめたかを書きます。

なぜ必要だったのか

#

私が作っているマーケットプレイス兼コミュニティアプリは、Accept: text/markdown のリクエストに、HTMLの代わりにMarkdownを返します。ナビゲーションバーやフッターをかき分けて読みたくないAIエージェントやLLMクライアントのためです。エッジ側の話はクローラーとキャッシュについての記事に書きました。アプリのデータから作るページはHTMLが空のJavaScriptシェルなので、Markdownを直接組み立てています。それ以外は静的なHTML（マーケティング、規約、ブログのページ）で、こちらは変換しています。

変換するうえで問題になるのはリンクです。静的サイトのページには /en/posts/... や ../setup/ のようなリンクがたくさんあります。ブラウザなら元のページが分かっているので問題ありません。でもMarkdownを読むエージェントにはその文脈がないので、/login をたどれません。必要なのは https://example.com/login です。

純粋なPythonで書かれたhtml2textにはこのための baseurl オプションがあり、最初はそれを使っていました。ただ遅いうえに、Markdownの出力にも問題があります（後で説明します）。rust-html2textは高速でテストもしっかりしていましたが、リンクを解決する手段がありませんでした。

まずは上流に相談

#

8月29日にissue #287を立て、ユースケースと求める挙動を書きました。RFC 3986に従って解決し、絶対URLや mailto:、data:、#fragment のリンクはそのままにする、というものです。その数分後にプルリクエスト #288を出しました。Config::base_url(...) というオプションを追加する変更で、issueには「たたき台のつもりなので、メンテナーが別のアプローチを取りたければそれでも構わない」と書き添えました。

10月11日、メンテナーはPRをクローズしました。

Thanks for the contribution, but I’m unable to accept this as it appears to be LLM generated. (I have now added a brief policy to the README.md - it wasn’t previously stated)

訳：「貢献ありがとうございます。ただ、LLMで生成されたもののように見えるため、受け入れることができません（README.mdに簡単なポリシーを追加しました。これまでは明記していませんでした）。」

issueにも返信がありました。

Hi - this is a reasonable feature request, thanks! I have closed the PR as it appears to be LLM-written which I can’t accept, but thanks for the attempt.

A short HTML sample and expected output would definitely help get the feature implemented!

訳：「こんにちは。妥当な機能リクエストですね、ありがとうございます！ PRはLLMで書かれたように見え、それは受け入れられないのでクローズしましたが、取り組んでくれてありがとうございます。短いHTMLのサンプルと期待される出力があれば、機能を実装するうえで間違いなく助けになります！」

READMEには現在、次のポリシーが書かれています。

At this time, this project is not able to accept code contributions produced with generative AI/LLMs due to the uncertain copyright status.

訳：「現時点では、著作権上の位置づけが不確かであるため、このプロジェクトは生成AIやLLMで作られたコードの貢献を受け入れることができません。」

その見立ては正しく、あのコードは私がAIコーディングツールで書いたものです。ポリシー自体も不当だとは思いません。LLMの出力の著作権上の扱いはまだ定まっていませんし、ほかのプロジェクトが依存しているMITライセンスのクレートにそれをマージするリスクを負うのはメンテナーです。メンテナーのプロジェクトですし、返信も丁寧でした。機能リクエストは今もオープンのままです。

それでも、私にはこの機能が必要でした。かといって、メンテナー自身の貢献ポリシーについて言い争うのは、機能を手に入れる良い方法ではありません。そこで変更はフォークに残し、その上にPythonパッケージを作りました。どちらにも、上流のものではないとはっきり書いてあります。

フォークの中身

#

フォークは私のrust-html2textフォークのpyhtml2text-perf ブランチです。上流にきれいにリベースできるよう、小さなコミット3つだけにとどめています。中心はPRで出した Config::base_url オプションで、相対リンクをRFC 3986 §5.3に従って解決します。base URLを渡さなければ出力は変わりません。もうひとつは、呼び出しのたびにスタイルルールを作り直さないようにした変更で、短いスニペットで7.3 µsが5.6 µsになりました。大きなページでは誤差ですが、数千回呼べば効いてきます。最後のひとつは、後述のMarkdownコンバーターがクレートから必要とする部分を公開しているだけです。

Pythonパッケージ

#

pyhtml2textはPyO3とmaturinで作っていて、関数は2つです。

from pyhtml2text import html2text, html2markdown

html2text(html, width=80, *, base_url=None, decorate=True, link_footnotes=True,
          table_borders=True, wrap_links=True, max_wrap_width=None, raw=False)

html2markdown(html, *, base_url=None)

html2text はrust-html2textのプレーンテキストレンダラーで、ターミナルやメールの text/plain パート向けに作られています。

print(html2text('<p>Please <a href="https://jared.lynskey.co.nz/login">sign in</a> first.</p>',
                base_url="https://example.com/docs/page.html"))

Please [sign in][1] first.

[1]: https://example.com/login

バインディングについて、すぐには分からないかもしれない点をいくつか挙げます。

• どちらの関数も str かUTF-8の bytes を受け付けます。 なので、response.content をデコードせずにそのまま渡せます。入力はコピーせずに借用します。
• 変換中はGILを解放します。 最初から最後まで純粋なRustなので、スレッドは複数のコアにスケールします。モジュールはGILを必要としないことも宣言しているので、フリースレッド版のPython 3.14tでも、インポート時にGILが再び有効になることはありません。
• パニックは ValueError として返ります。 PyO3はデフォルトで PanicException を送出しますが、これは except Exception では捕まえられません。変換エラーは処理済みのつもりのWebワーカーがそれで落ちてしまうので、バインディング側で捕まえて ValueError として送出し直しています。
• wheelは30個あります。 CPython 3.10以降向けのabi3 wheelと、フリースレッド版3.14t向けのwheelを、Linux（glibcとmusl）、macOS、Windowsについて、maturinのCIがビルドできるすべてのアーキテクチャ向けに用意しています。なので、インストールにRustのツールチェーンは必要ありません。

高速化

#

バージョン0.2.0は、実際のページで0.1.0の1.5〜1.7倍、短いスニペットでは2倍速くなり、出力はバイト単位で同じでした。大半はプロファイルガイド最適化（PGO）によるものです。CIで計測用のwheelをビルドし、ドキュメントのページとRFCからなる学習用セットで動かして、そのプロファイルを使って本番のwheelをビルドします。学習用セットに含まれないページで約25%速くなります。CIで計測用ビルドをネイティブに実行できるプラットフォームでだけ有効にしています。残りは、小さなメモリ確保が大量にあっても強いmimallocアロケーターへの切り替えと、フォークで入れたスタイルルールの変更によるものです。

高速化で何も変わっていないことを確かめるため、実際のページを集めたコーパスをすべてのオプションの組み合わせで変換し、その出力のハッシュを記録しました。空の入力や非常に深いネストといったエッジケースも含めています。どの変更も、ハッシュをひとつも変えないことが条件でした。

以下はApple SiliconのMacで計測した中央値です。まずMarkdownへの変換です。

次にプレーンテキストへの変換です。

深くネストしたHTMLとhtml5everへのパッチ

#

40,000階層のリストを手で書く人はいません。でも、自分が書いていないページを変換していれば、いずれ悪意のあるものや壊れたものが送られてきます。標準のパーサーでは、40,000階層にネストした <ul><li> のパースに6秒かかりました。たった1つのリクエストでワーカーが止まってしまうということです。

原因は、rust-html2textが使っているHTML5パーサーのhtml5everにありました。ほとんどのブロックレベルの開始タグは、開いている <p> 要素が「button scope内」にあるかを確認する必要があり、html5everはそのたびに開いている要素のスタック全体をたどっていました。ネストが深くなるほどタグ1つあたりの時間が延び、全体の時間は深さの2乗で増えていったわけです。

パッケージには、パッチを1つ当てたhtml5ever 0.39.0を同梱しています。要素が開いたり閉じたりするたびにその答えを更新しておくので、確認にかかる時間がネストの深さに左右されなくなりました。同じ文書のパースは0.14秒になりました。パッチがほかに何も変えていないことを確かめるため、html5libのツリー構築テストすべて、実際のページ約20件、ランダムなタグスープ文書300,000件で、元のパーサーとパッチ版のDOMを比較し、すべて一致しました。

Markdownコンバーターにも、同じ理由で上限を設けています。どんな入力でもスレッドのスタックをあふれさせることはなく、引用やリストは32階層を超えるとそれ以上インデントしないので、出力が2乗で膨らむこともありません。展開したグリッドが100,000セルを超える表は、セルの中身だけを書き出します。

html2markdown

#

バージョン0.3.0で html2markdown を追加しました。パッケージの作業の大半はこれに費やしています。rust-html2textのレンダラーはMarkdownに見えるテキストを作りますが、ターミナル向けに折り返されていて、パースされることは想定していません。そこで html2markdown はパーサーだけを借りて、出力は自前でCommonMarkに、GitHub形式のパイプテーブルと ~~strikethrough~~ を加えた形で書き出します。

• # の見出し、- の箇条書き、_emphasis_ と **strong**。
• インラインのリンクと画像。base_url を指定すれば絶対URLになります。中身がアイコンだけのリンクは、aria-label か title をリンクテキストとして使います。
• フェンス付きのコードブロック。ページが言語を指定していれば（class="language-python"）、その言語を付けます。
• パイプテーブル。行や列をまたぐセルは空のセルになり、ヘッダー行のない表には空のヘッダー行が付き、ページのレイアウトに使われている表は段落として書き出します。
• 行の折り返しはしません。隠しコンテンツ（hidden、aria-hidden、display: none）、スクリプト、スタイル、フォームのコントロールは除外します。

必要なところだけエスケープする

#

HTMLからMarkdownへの変換ライブラリの中には、Markdownの構文になりうる文字をすべてエスケープするものがあります。たとえばmarkdownifyは、デフォルトで _ と * をすべてエスケープします。出力は正しいのですが、snake\_case や 5 \* 3 だらけになり、人間には読みにくく、モデルにとってはトークンの無駄です。pyhtml2textは、CommonMarkのパーサーが構文として読んでしまう場所でだけ文字をエスケープします。

html2markdown('<p>Use <code>snake_case</code>, 5 * 3, $5 and '
              '<a href="../setup.html">setup</a></p>',
              base_url="https://example.com/docs/intro.html")

Use `snake_case`, 5 * 3, $5 and [setup](https://example.com/setup.html)

韓国語の助詞の前の太字

#

これは私のアプリ自身のページで見つかった問題です。韓国語では、文法上の助詞がスペースなしで名詞の直後に付きます。そのため、括弧を含む語を太字にするとこうなります。

<p><b>타이타닉(Titanic)</b>의 감독</p>

素直にMarkdownにすると **타이타닉(Titanic)**의 で、markdownifyもこう書き出しますが、これは機能しません。CommonMarkのフランキング（flanking）ルールでは、** が句読点の直後で閉じるには、その後ろにスペースか別の句読点が続く必要があります。의 は文字なので、アスタリスクはそのまま文字として残ってしまいます。純粋なPythonのhtml2textは、スペースを入れてこれを回避します。

**타이타닉(Titanic)** 의 감독

これで太字にはなりますが、韓国語が変わってしまいます。助詞が独立した単語になり、綴りの誤りになるのです。pyhtml2textは代わりに、句読点をマーカーの外に出します。

**타이타닉(Titanic**)의 감독

閉じ括弧は太字ではなくなりますが、強調は正しくパースされ、元の文字はすべて残ります。

日本語でも同じことが起きます。日本語の助詞（の、を、は）も、韓国語と同じく前の語にスペースなしで付きます。全角の括弧もCommonMarkでは句読点として扱われるので、**タイタニック（Titanic）**の のような書き方では太字になりません。中国語をはじめ、後ろに続く語の前にスペースを置かない言語ならどれも同じです。

読み戻して出力を確かめる

#

ユニットテストが通るからといって、変換ライブラリを信用はしません。Markdownの出力のバグは、誰もテストを書こうと思わなかった組み合わせに潜んでいるからです。そこで、出力を読み戻して確かめています。

変換中は、段落ごとにCommonMarkとしてもう一度パースし、強調が意図どおりに読めるかを確認します。読めなければ、もう一方の強調スタイル（_ の代わりに *、またはその逆）で書き直し、どちらもだめならテキスト、リンク、コードは残して書式だけを落とすので、単語が失われることはありません。テストスイートでは、別のMarkdownパーサーで往復チェックをして、表示される単語、リンク先、画像のソースをすべて元のHTMLと比較します。エスケープされなかった構文に飲み込まれたテキスト、パースされなかったリンク、紛れ込んだ * などは、すべて差分として現れます。実際のページと何万件ものランダムなドキュメントで実行していて、失敗したら最小のケースまで縮めてくれます。

本番環境で

#

私のアプリのMarkdownネゴシエーションは、0.3.0が出たその日に、純粋なPythonのhtml2textからpyhtml2textに切り替えました。ガイドページのひとつでは、変換が4.2 msから0.36 msになり、約12倍高速になりました。リンクは絶対URLになり、表は本物のパイプテーブルになり、韓国語の太字は助詞がくっついたままです。abi3 wheelがx86_64とarm64のPython 3.14をすでにカバーしているので、コンテナイメージにはインストールのために何も追加する必要がありませんでした。

クレジットとバグ報告先

#

プレーンテキストのレンダリングは、Chris EmersonさんによるMITライセンスのrust-html2textです。pyhtml2textは、そのフォーク、パッチを当てたhtml5ever（MIT/Apache-2.0）、そしてMarkdownコンバーターを加えたものです。このパッケージはどちらのプロジェクトとも提携しておらず、承認も受けていません。なので、問題は上流ではなくpyhtml2textのissueトラッカーに報告してください。このコードのバグを直すのは私の役目ですし、上流のメンテナーが受け入れを断ったコードについての報告を受けるべきではありません。

PythonでHTMLを変換していて、とくにモデルに読ませる用途なら、ぜひ試してみてください。

pip install pyhtml2text

ソースはGitHubにあり、0.1.0から0.3.0までの変更はすべてchangelogにまとめてあります。

私は現在、個人開発者として2つのプロダクトを運用しています。ひとつは現場で見積もりを出す職人向けの現場見積もりアプリ、もうひとつは出品とリアルタイムメッセージングを備えたマーケットプレイス兼コミュニティアプリです。

プロダクトもユーザーも全く違いますが、技術スタックはほぼ同一です。そしてどちらも、Fly.ioの最安ティアであるshared-cpu-1xマシンだけで動いています。この制約は意図的なものです。ピーク負荷に合わせてサーバーを大きくするのではなく、小さなマシン1台から絞り出せる性能を最大化し、どこで崩壊するかを正確に測定し、その実測された限界を軸にFlyのオートスケーラーにマシンの追加と削除を任せます。この記事では、それを可能にしている最適化、閾値の根拠となった負荷テストの数値、そしてFly.ioでスケールアップ/ダウンが実際にどう動くのかを紹介します。

哲学：1台を測定し、それを掛け算する

#

両アプリともスケーリング戦略は同じ3ステップです。

1. 小さなマシン1台を、合理的な範囲で可能な限り速くする。
2. 壊れるまで負荷テストを行い、レイテンシが崩壊する同時実行数を記録する。
3. その直前で2台目のマシンが起動するようFlyのオートスケーラーを設定し、トラフィックが減ったらアイドルマシンを停止させる。

こうすればキャパシティはマシン数にほぼ線形に比例し、ベースラインコストはアプリごとに小さなVM 1台です。以下の内容はすべて、この3ステップのいずれかのためにあります。

小さなマシン1台を速くする

#

Granian：APIはWSGI、WebSocketはuvloop ASGI

#

両バックエンドともDjango 6 + Django REST Frameworkです。APIはRustベースのサーバーGranianがサービングしますが、ASGIではなくブロッキングスレッドプールを使うWSGIで動かしています。

granian --interface wsgi myapp.wsgi:application \
    --workers 1 --blocking-threads 16 \
    --workers-max-rss 1400 \
    --workers-kill-timeout 15 --respawn-failed-workers

最初は--interface asgi --loop uvloopで始めましたが、誤った選択でした。これらのアプリのHTTPビューはすべて同期（sync）で、DjangoのASGIハンドラは同期ビューをthread_sensitiveで—ワーカーあたり一度に1つずつ—実行します。つまりASGIは、ワーカーあたりの同時リクエストを実質1つに絞りながら、asyncio/uvloop/Channelsのスタック一式をただメモリに載せていただけでした。--blocking-threadsを使うWSGIは、同じ同期ビューを本物のスレッドプールで走らせます。ワーカー1つ × スレッド16 = I/Oバウンドなリクエスト（DB読み取り、S3のプリサイン）16件を同時に、非同期スタックより低い常駐メモリでさばきます。

なぜワーカーが1つなのか？VMがshared-cpu-1x—1コアだからです。2つ目のワーカーは1コアではPythonを並列に走らせられない（GIL + 1コア）くせに、常駐するDjangoプロセスをまるごと1つ余分に食います。Granianはまさにこの点を警告します。ワーカー1つにスレッド16が、I/Oバウンドな処理における1 vCPUマシンの正直な上限です。--workers-max-rss 1400はワーカーがメモリ上限を超えると再生成するので、暴走したPDFや画像処理がマシンをOOMへ引きずっていく代わりにリサイクルされます。

WebSocketは自前のGranianプロセスに切り出しました。uvloopと--wsを使うASGIアプリで、長寿命コネクションのためにワーカー1つで動かします。同期APIにはASGIの経路はまったく不要です。ビューがソケットへプッシュしたいときはRedis経由でasync_to_sync(channel_layer.group_send)を呼ぶので、メッセージは変わらずWebSocketプロセスへ渡ります。2つのサーバーが、それぞれ本当に得意なインターフェースを走らせているわけです。ローカルのDockerも同じWSGIスレッドプールで動かしているため、テスト時は私のラップトップがプロダクションマシン1台の近似になります。

ホットパスにはRust

#

PythonのホットパスにRustベースの代替があれば、必ず採用します。

• orjson（drf-orjson-renderer経由）— すべてのAPIレスポンスが標準ライブラリのJSONエンコーダーではなくRustでシリアライズされます。
• blurhash-rs — 画像プレースホルダーをアップロード時に計算。
• uuid-utils — RustによるUUID生成。
• psycopg 3 (binary) — Cで高速化されたPostgresドライバー。

これらはアーキテクチャを変えません。2台目のマシンが必要になる前に、1 vCPUがこなせる上限を引き上げるだけです。

隠れたレイテンシ税を潰す

#

どちらのコードベースでも最大の改善はアルゴリズムではなく、コネクションの再利用でした。Granianのスレッドプールでは、新しいスレッドごとにboto3のS3クライアントを作り直しており、写真やPDFを返すすべてのエンドポイントがそのコストを払っていました。小さなカスタムストレージクラスでクライアントをプロセス単位にキャッシュするようにしたところ：

新規スレッドでの署名付きURL生成が約150msから約1msになりました。

同じ教訓はデータベースにも当てはまります。FlyのPostgresはPgBouncerの背後にあるので、アプリはconn_max_age=0にしてコネクション再利用をプーラーに任せ、古くなったSSLコネクションでワーカーが固まらないようconnect_timeoutを5秒にして素早く失敗させます。

本当のボトルネックの前にキャッシュを置く

#

マーケットプレイスの負荷テストで、覚えておく価値のある事実が判明しました。天井はCPUではなくPostgresのコネクションだったのです。閲覧トラフィックは圧倒的に匿名でユーザー間で同一であり、負荷がかかると、その同一のリストクエリ群がCPUは暇なままコネクションプールを飽和させます。

対策は匿名リストページ用のRedisキャッシュです。無効化はネームスペースごとのバージョンカウンターで行います。書き込みが起きたらカウンターをひとつ進めるだけで（O(1)、キーの管理は不要）、そのリソースのキャッシュ済みページはすべて即座に無効になります。短いTTLが取りこぼしをカバーします。閲覧ページをRedisから直接返すことで本当のボトルネックが消え、小さなマシンはコネクションをログイン済みトラフィックに使えるようになります。

ブローカーなしのバックグラウンド処理

#

両アプリともCeleryではなく、Djangoのデータベースバックエンドのタスクフレームワークdjango-tasks-dbを使っています。独立したdb_workerプロセスがデータベースをポーリングし、画像処理、PDF生成、機械翻訳、リマインダーといったジョブを処理します。ブローカーはなく、サイズを見積もって監視すべき追加サービスもなく、APIプロセスが重い処理でブロックされることもありません。さらにワーカーはPgBouncerをバイパスしてPostgresに直接接続します。長時間走るジョブはトランザクションプーリングと相性が悪いからです。

メモリ：jemallocとスワップのクッション

#

画像とPDFの処理は、定常状態ベースの見積もりでは予測できないメモリスパイクを起こします。安上がりな緩和策が2つ。Dockerイメージにjemallocをプリロードして断片化を抑えること、そして全マシンにスワップを持たせることです（APIマシンに2GB、WebSocketマシンに1GB）。スパイクが来てもプロセスがOOMで殺される代わりにディスクへスワップされます。スワップは性能のための機能ではなく、メモリ割り当てを小さく保つための保険です。

Djangoの負荷テスト：膝（knee）を見つける

#

閾値の根拠として通用するのは、実測した値だけです。プロジェクトごとに専用のハーネスがあります。

• 見積もりアプリには、同時実行数を掃引してRPS、p50/p95/p99、エラー率を報告する小さなPythonのストレステストスクリプトがあります。生成した数百件のサンプルデータに対して実行するので、リスト系エンドポイントは現実的なデータ量でクエリされます。
• マーケットプレイスはLocustで30秒刻みのステップ負荷により50 → 500ユーザーまでランプして飽和点を探し、実際の閲覧中心トラフィックに合わせたエンドポイント重み付けを使っています。さらに別建ての小さなテストスイートが、仮想ユーザー5 → 50をp95 < 2秒の閾値付きでプロダクションに対してランプします。

見積もりアプリのスイープの代表的な数値です（Granianワーカー1 × ブロッキングスレッド16、開発マシン上のDocker）：

そして他のすべてを決める数字が、shared-cpu-1xマシン1台でマーケットプレイスを負荷テストした結果から出てきます。旧来のASGIビルドでは、これが固い壁でした。同期ビューが実質3スロットほどに直列化されるため、p95は同時リクエスト約5までは300ms未満を保ち、すべてがthread_sensitiveのロックの後ろに並ぶことで約8〜10を超えると崩壊していました。この膝を外側へ押し出したのが、APIをWSGIスレッドプールへ移したことです—マシンあたりの実質同時スロットが約3ではなく16になり、この新しい天井がオートスケーリング設定全体の根拠です。

Fly.ioでのスケーリングの仕組み

#

Flyのモデルはシンプルです。アプリはプロキシの背後にある同一マシンの集合で、プロキシがマシンごとの負荷を数えます。宣言するのは2つの数字だけです。

[http_service.concurrency]
  type = 'requests'
  soft_limit = 12   # これを超えたら別のマシンを起動
  hard_limit = 24   # これを超えたらキューイングせず負荷を遮断

auto_stop_machines = 'stop'
auto_start_machines = true
min_machines_running = 1

スケールアップ： あるマシンの処理中（in-flight）リクエストがsoft limitを超えると、プロキシは停止中のマシンを起動し、新しいトラフィックをそちらへ流します。WSGIスレッドプールによってマシンあたり実質16の同時スロットがあるので、soft limitは12—プールの約75%で、ユーザーが数秒のレイテンシを体験した後ではなく、スレッドにまだ余裕があるうちに2台目が起動します。hard limitの24（プールの1.5倍）はサーキットブレーカーです。短いバーストはスレッド上でキューイングされ、それを超えたら、1台のマシンが溶け落ちるのを許すのではなく、プロキシが負荷を遮断します。（旧来のASGIビルドは実質スロットが約3で8/20でした。プールを広げたことで両方の数字を引き上げられたのです。）

スケールダウン： トラフィックが減ると、Flyはアイドルマシンを自動的に停止し、min_machines_running = 1まで縮小します。停止中のマシンはコンピューティング費用がかからず rootfs のストレージ分だけなので、各アプリのベースラインコストは文字通り小さなVM 1台で、バースト用のキャパシティは常に待機しています。

私はここに、停止中のマシンは「1秒未満でコールドスタートする」と書いていました。それは間違いで、しかも高くつく間違いでした。想定ではなく実際に計測したところ、コールドスタートには25〜33秒かかっていて、まだ起動中のマシンに振られたリクエストはその時間をまるごと待たされます。当初は、ヘルスチェックがずっと緑のままCDNのダッシュボードに出ていた22パーセントの失敗率を、このコールドスタートのせいだと考えていました。ところがその数字は、CDN自身のEarly Hintsのプローブがオリジンで失敗していたもので、実際のクライアントが受け取った504はひとつもありませんでした。それでも、コールドスタートそのものは本物でした。

対処は上のスケーリングの数値にはありません。あの数値は問題ないのです。マシンが立ち上がる途中で何をしているか、そして Fly にマシンを停止ではなくサスペンドさせるかどうかにあります。そうすれば復帰は約3秒のメモリ復元になります。別記事にまとめました。ゼロスケールと、再起動のたびに起きる30秒の障害で、診断の過程と変更すべき点を扱っています。auto_stop_machines を使って Fly で何かを動かしているなら、この段落を信じる前にそちらを読んでください。

ひとつ微妙なポイント：同時実行のタイプがconnectionsではなくrequestsであることです。現代のクライアントはkeep-aliveコネクションを開きっぱなしにするため、コネクションを数えても実負荷でほとんど変動せず、オートスケーラーが発火しません。処理中リクエストを数えることで、実際の仕事量が追跡できます。

WebSocketは別の軸でスケールする

#

マーケットプレイスはWebSocketサーバーを、同じDockerイメージを共有する2つ目のFlyアプリに分離しています。APIアプリはWSGIでワーカー1つ × ブロッキングスレッド16を動かし、リクエストを数えます（soft limit 12）。WebSocketアプリは512MBのマシンでASGIでuvloopとともにワーカー1つを動かし、コネクションを数えます。

[http_service.concurrency]
  type = 'connections'
  soft_limit = 1500
  hard_limit = 2000

長寿命のソケットは維持コストこそほぼゼロですが、スロットを何時間も占有します。一方HTTPリクエストがスロットを占有するのはミリ秒単位です。同じオートスケーリングシグナルで両方を賄うことはできません。分離すれば各フリートがそれぞれに正直なメトリクスでスケールし、アイドル状態のWebSocketキャパシティのコストは2GBではなく512MBで済みます。Channels側では、Redisレイヤーをcapacity: 1500、メッセージ有効期限60秒で動かし、30秒ごとにソケットのkeepaliveを送ります。FlyのRedisプロキシが、Channelsの依存する長寿命のBRPOPソケットをアイドルと見なして切断してしまうからです。

コンピューティングをエッジとクライアントへオフロードする

#

最も安いサーバー処理は、サーバーが一切やらない処理です。

• 静的ファイルとメディアはFlyのS3互換オブジェクトストレージに置き、非公開メディアは署名付きURLでCDN経由配信します。画像のバイト列はDjangoマシンを一切通りません。
• AI推論はユーザーのスマートフォン上で動きます。 両アプリとも小さなローカルLLM（量子化された4Bモデル、約2.7GB）を組み込み、端末上で動かしています。サーバー側の推論コストはゼロで、オフラインでも動作します。
• オフラインファーストのモバイル（端末上のSQLiteと、リトライ付きの同期キュー）のおかげで、アプリはキー入力のたびに細かなリクエストでAPIを叩くのではなく、書き込みをまとめて送り、電波の届かない場所でも動き続けます。

残りのスタックを手短に

#

認証はホスティング型のIDプロバイダーとWebAuthnパスキーで、WebSocketコネクションはアップグレード完了前に認証します。プロダクションはPostgres、開発はSQLite。管理画面と監査履歴には既製のDjangoパッケージをいくつか使っています。モバイルはExpo上のReact NativeとTypeScriptにExpo RouterとTailwindを組み合わせ、OTAアップデートはセルフホストのExpo Updatesサーバーから配信し、アプリ内課金はサブスクリプション管理サービスに任せています。品質ゲートはバックエンドがpytestとmypy、クライアントがユニットテストとE2Eテストです。

持ち帰ってほしいもの

#

移植できるアイデアは特定のライブラリではなく、ループそのものです。安いマシン1台を本当に速くする（Rustのホットパス、コネクション再利用、本当のボトルネックの前のキャッシュ、CDNとクライアントへのオフロード）。どの同時実行数で壊れるかを特定できるまで負荷テストする。オートスケーラーのsoft limitをその膝に置き、アイドルマシンは停止させ、最小フリートは1に保つ。プロダクションアプリ2つ、リアルタイム機能、AIアシスタント — それでも定常時の請求額は、プラットフォームで最安のVM数台分です。

ここ数週間、関連する2つのプロジェクトに取り組んでいました。1つ目は、2024年に Scientific Reports に載った Lee et al. の論文 “Social signals predict contemporary art prices better than visual features, particularly in emerging markets” の再現です。存命作家590人、34,200件のオークション記録でXGBoostモデルを学習させる内容です。2つ目はアートのプラットフォーム作りで、作家・所有者・オークション記録をつなぐナレッジグラフが中心にあります。要するに、ああいうモデルで何か意味のあることをしようと思ったときに必要になるデータの配管です。

どちらのプロジェクトも、結局同じ問いに戻ってきました。作品がいくらで売れるかは本当に予測できるのか？答えは「できる」です。ただし、作品を見ても無理です。効く特徴量はほぼすべて社会的なものでした。

アートの値付けが難しい理由

#

コードを書く前に、鑑定士やオークションハウスが実際どう値付けしているのかを数日かけて読み込みました。考慮する要素は多く、そのほとんどはきれいに数値化できません。来歴（誰が所有し、どこで展示され、どのカタログに載ったか）。帰属と真贋──作家の財団が本物と認めた作品は、「〜の作と伝えられる」だけの作品より桁違いに高くなります。個展、ビエンナーレ、美術館収蔵、批評で積み上がる作家の評判。それに保存状態と修復履歴、作家の作品群の中での稀少性、媒体（キャンバスの油彩は紙の作品より、紙の作品は版画より高く売れる傾向があります）。大きな美術館が所蔵していれば、2次市場が信頼するお墨付きになります。タイミングも効きます。5年前の比較事例はもう古いのです。

オークションハウスの専門家は「感情価値」の話もします。コレクターの欲望、入札合戦の力学、個人的な思い入れ。これらは合理的な見積もりをはるかに超えてハンマープライスを押し上げることがあります。直接モデル化はできませんが、オークションハウスの事前予想額を通じて間接的にその輪郭を捉えることはできます。

実務で主流の評価手法は比較売買分析です。同じ作家の類似作品の直近のオークション結果を探して、差分を調整する。XGBoostがやっているのも本質的には同じことで、ただ人間の鑑定士が手で追える範囲をはるかに超えた規模と特徴量でやっているだけです。

論文の中心的主張

#

Lee et al. の主張は直感に反します。作品の視覚的内容は、価格をほとんど説明しないというのです。視覚的特徴のみ（色、構図、エッジ密度、ResNet18の埋め込み）を使ったモデルはR²約0.055。平均値を答えるより少しマシな程度です。

一方、作家レベルの「社会的」特徴のみ（キャリアステージ、展示歴、過去のオークション価格、ArtFactsランキング）を使ったモデルはR² ≈ 0.73に達します。さらにオークションハウスの事前予想額を特徴量に加えると0.92まで上がります。

つまり、作品そのものはほとんど関係ないのです。重要なのは誰が作ったか、そして市場がその人物についてすでに何を語っているかです。

論文のもう一つの主張は、この差が新興市場でさらに開くというものです。新興市場とは、確立された中核であるアメリカ・イギリス・フランス・ドイツ以外のすべてを指します。そうした市場では社会的シグナルの効きが強まり、専門家の予想額の精度は下がるため、アルゴリズム予測が価値を出せる余地が大きくなります。

論文を再現する

#

依頼内容はシンプルでした。1人開発のMVPとして論文を再現する。本番デプロイなし、ライブのデータパイプラインなし。忠実な再実装と、プロトタイプ品質のコードと、所見をまとめたレポートです。

データ

#

論文は補足資料としてクリーニング済みのCSVを提供しています。

全部で約5 GB。RAMに余裕で収まりますし、この規模のデータセットならXGBoostの学習はラップトップのCPUで5分もかかりません。コアモデルにGPUは不要です。この規模の表形式データに対する勾配ブースティング木は、学習コストがほぼタダみたいなものです。ニューラルネットの世界に数年浸かっていると、つい忘れてしまいますが。

特徴量

#

モデルは38個の特徴量を3カテゴリに分けて使います。

作家について（30個）：

• 属性: 年齢、性別、学歴、トップスクール出身フラグ。
• キャリア: ArtFactsランキング、個展、グループ展、ビエンナーレ参加、受賞。
• 収蔵: 個人・公的コレクションの数。
• 価格履歴: 直近5回・10回の販売の平均、中央値、最高、最低。
• サイズ調整済み価格履歴（平方インチあたり価格）。
• 地理: 作家の活動・居住地を国フラグとしてエンコード。
• マッチフラグ: 作品のジャンルは作家の通常のジャンルと一致するか？販売国は一致するか？

市場について（8個）：

• オークションハウスのティア（1–4）。
• その年の国・地域の価格水準（最小、平均、中央値、最大）。

作品そのものについて（視覚以外）：

• 幅、高さ、平方インチ換算の面積。
• 媒体カテゴリ（絵画、版画、写真、彫刻、その他）。

このリストに欠けているのは、作品の実際の視覚的内容に関するものです。それは別立てのアブレーション実験としてしか登場しません。

学習/テストの分割

#

ランダムではなく時系列です。2011年5月より前を学習用（約80%、約27,360件）、それ以降をテスト用（約20%、約6,840件）に回します。ランダムに分割すると、作家の価格履歴特徴量を通じて未来の情報がリークするからです。同じ作家のレコードを学習とテストにばらまくと、テスト行はローリングウィンドウ越しにお互いの価格をすでに「見て」いる状態になり、R²が人為的に膨らみます。

一度気づけば当たり前なのに、最初に組むときには見落としやすい類のものです。

モデル

#

XGBoost回帰で、log10(price_usd)を予測します。検証用スライスに対してmax_depthとlearning_rateのハイパーパラメータ探索。モデルの変種は2つです。

1. 専門家予想額なし。 目標R² ≈ 0.73。
2. 専門家予想額あり。 目標R² ≈ 0.92。

「予想額あり」の変種は、オークションハウスの事前予想額の下限と上限を追加の特徴量として使います。実はこの2つだけを単独で使ってもR² ≈ 0.90が出ます。その上に社会的特徴を載せて、さらに0.02。絶対値としては小さいですが、専門家がすでに知っていることの先で、実際に予測の仕事をしている部分がここです。

どこまで狙ったか

#

論文を超えるつもりはありませんでした。全条件で論文のR²値の±0.03以内に収めるのが目標です。ヘッドラインの数値（メタデータのみで約0.73、予想額込みで約0.92）は再現性が高いはずです。XGBoostはシードを固定すれば決定論的ですし、特徴量の定義も明確です。ズレを予想したのは2か所。PCAの次元数や画像前処理のわずかな差で結果が動く視覚特徴のアブレーションと、4,346件しかなくノイズフロアが高い新興市場の分割です。

視覚特徴がほとんど効かない理由

#

私にとっては、これが一番面白い結果でした。論文の視覚パイプラインは、画像1枚から8,971個の数値を抽出します。

• GISTディスクリプタ（960次元）: 全体的な空間レイアウト。
• 方向勾配ヒストグラム（HOG）（2,915次元）: エッジ構造。
• カラーヒストグラム（4,096次元）: パレットの内訳。
• ResNet18特徴（1,000次元）: 事前学習済みの高次埋め込み。
• カラフルネス（1次元）: 鮮やかさのスカラー。
• 複雑度（1次元）: エッジ密度のスカラー。

これをPCAで圧縮してXGBoostに入れると、R² ≈ 0.055。色だけで0.056、エッジ構造で0.029、ニューラルネット埋め込みに至っては0.009、実質ゼロです。

すっきりした説明はこうです。オークション価格は個々の作品ではなく、作家のレベルで決まる。同じ作家の絵は、キャンバスに何が描かれていようと似た値段で売れます。値付けされているのは署名だからです。

オークションカタログの解説を読んだことがあれば、腑に落ちるはずです。あの文章は来歴と展示歴と比較売買にほとんどの言葉を費やしていて、作品そのものの描写はごくわずかです。

この5%という数字を真に受けるなら、作品の美的内容は市場価値からほぼ切り離されています。市場が報いているものが何であれ、それはキャンバスの上にはありません。ピクセルレベルでアートを理解するモデルは、作家の経歴しか知らないモデルより価格予測が下手になる、ということです。

Phase 3は条件付きだった

#

論文の画像リンク列が指すURLは2012年時点で有効だったもので、2026年にはほとんど死んでいます。私が書いた計画では8日目にこのリスクを検証することにしていました。ランダムに100本URLを引いて、何本生きているか確かめる。半分以上死んでいたら視覚フェーズは丸ごとスキップして、理由を文書に残す。

そもそも視覚特徴が説明する価格分散は5%程度です。その程度の数字を確認するためにリンク切れと2週間格闘するのは、割に合いません。リンク切れの調査結果をレポートに書いて先へ進むほうがましです。

既存市場 vs 新興市場

#

論文は既存市場（アメリカ、イギリス、フランス、ドイツ）と新興市場（それ以外の19か国）で別々のモデルを学習させています。中心的な結果はこうです。

目を引く点は2つ。まず、社会的シグナルは新興市場のほうが効きます。データが豊富な既存市場のほうが社会特徴の性能も高いだろうと思っていたのですが、逆でした。

次に、新興市場では専門家予想額の精度が落ちます。予想額を加えたときの0.916対0.859の差がそれです。既存市場でのアルゴリズム予測は、数十年分の比較売買データを背負った大手オークションハウスの専門家と競うことになります。新興市場ではその専門家の持ちデータが薄く、アルゴリズムが価値を出せる余地が広がります。

このモデルを商売にするなら、稼ぎ場所は新興市場でしょう。

明記しておくべき制約

#

これは論文の再現であって、本番システムではありません。ライブのデータパイプラインはなく、モデルは1996–2012年のオークションデータで学習したきり更新されません。デプロイもなし。成果物はノートブックとレポートで、予測APIではありません。ドリフト検出もないので、学習後のモデルは市場が変わったことに気づけません。データセットは凍結されていて、クリプトアートもNFTもコロナ後の市場変動も学習データには存在しません。韓国のオークションハウスの価格を予測したければ、オークションハウス固有の特徴量と、おそらく韓国市場専用のモデルが要りますが、そこまでの特化はしていません。

モデルは過去のパターンを映すものでもあります。現代美術市場が2015年前後に構造的に変わったのだとしたら（アートフェアが1次市場の主要な場になり、新しい世代のコレクターが参入したという議論があります）、1996–2012年のパターンは一般化しないかもしれません。

論文からプラットフォームへ

#

論文を読んだことで、2つ目のプロジェクトの見方が変わりました。このプラットフォームはもともと、アート展覧会のクラウドファンディング・マーケットプレイスとして構想していました。作家はこれからの展覧会の資金を確保し、投資家はオークション市場が通常許すより早い段階で新興作家へのエクスポージャーを得る、というものです。

プロダクトとしての機能は、意図的にシンプルにしています。作家は資金が必要な展覧会を投稿します（会場、日程、出展予定作品）。投資家は特定のショーを段階別の金額（$100、$500、$1k、$5k）で支援し、作品が売れたら上振れ分を分け合います。作家と投資家のチャットの大部分はAIエージェントが受け持つので、どちらかがオフラインでも会話は止まりません。韓国のギャラリーが14時間の時差を挟んでアメリカのコレクターと話しているときには、これが特に効きます。

資産は作品ではなく作家だ、ということが腹に落ちると、データモデルもそれに合わせて変わります。押さえるべきは、各作品を誰が所有してきたか、どこで展示されてきたか、比較作品がいくらで売れたか、そして同じ作家の作品をほかに誰が持っているか。所有の連鎖、機関による承認、オークションの比較事例、コレクターのネットワーク──ナレッジグラフの出番です。

データモデルはあえて小さくしています。作家、作品、オークション記録、所有期間、そしてデータそのものの来歴ログ。これで、どのレコードもどこからスクレイピングしたのかまでさかのぼれます。最後のものは帳簿付けのように聞こえますが、スクレイピングしたデータを扱うなら、これがあって初めてグラフを信用できます。

モバイルアプリは、これら全部をforce-directedグラフとして描画します。タイムレンジスライダーで年をスクラブすると、ネットワークが育っていく様子が見えます。どのコレクターがいつ入ってきたか、どの作家がどの美術館に拾われたか、2008年の下落局面でどの作品が持ち主を変えたか。

エンティティの種類ごとに形と色を分けています。作家はダイヤ、作品は角丸長方形、オークションハウスは六角形、コレクター・ディーラー・美術館・遺産といった所有者は色違いの円です。

形は飾りではありません。数百ノードまでズームアウトしたとき、ラベルの描画を待たなくてもシルエットだけでエンティティの種類が分かります。円に囲まれたダイヤは、コレクターネットワークを持つ作家。多くのダイヤとつながる六角形は、作家を多数抱えるオークションハウス。市場の構造がひと目で読めます。

2つ目のタブでは、同じデータをタイムラインで見せます。所有期間は水平バー、売買は点イベント。同じグラフを別のレンズで見る形です。ある時点のネットワークの形ではなく、誰が何をどの順で持っていたかを見たいときに便利です。

このプラットフォーム自体は価格予測ツールではありません。その下に敷くデータレイヤーです。凍結された2012年のCSVではなく、生きた最新データをLee et al. のようなモデルに供給したいなら、必要になるのはこういう構造です。

価値評価をゲームにする

#

まだ作っていないけれど一番興味があるのが、アート評価のゲーム化です。

Lee et al. の論文はオークションハウスの事前予想額を特徴量として使い、R²を大きく引き上げています。あの予想額に価値があるのは、何千件もの比較作品を見てきて、結果に責任を負う訓練された専門家たちの、集約された判断だからです。しかしオークションハウスの専門家は、狭くて高価なリソースです。世界に数百人しかおらず、特定の委託案件にしか関わらず、まだ誰も委託していない作家のロングテールには手が届きません。

私が何度も戻ってくる問いはこれです。もっと広くて安い判断のプールから、同等のシグナルを合成できないか？

ざっくりした設計はこうです。

• ユーザーに作品を見せる。画像、寸法、制作年、作家名、簡単な経歴。
• オークションでいくらで売れるかを尋ねる。
• 価格帯を選ばせるか、ハンマープライスを直接当てさせる。
• 回答を確定した後で、実際の落札価格を明かす。
• Brierスコア方式の精度レーティングを時間をかけて付ける。
• リーダーボード、デイリーストリーク、連続的中バッジを用意する。
• 各ユーザーの今後の予測を、過去の精度で重み付けする。

アート価格の予測市場を、当てっこゲームの形にしたものです。ループは地理当てゲームやオンラインチェスのパズルレーティングと同じ。繰り返せて、採点できて、フィードバックを頼りに腕を磨けます。よく当てる人はリーダーボードを上がり、その人の今後の予測は集約シグナルの中でより重くなります。

これが本当に役立つのはモデル側です。重み付き集約された推測は、社会的シグナルと並べてXGBoostに入れられる特徴量になります。群衆の精度加重中央値がハンマープライスとよく相関するなら、本物の予想額が付いていない作品についても、合成オークションハウス予想額に近いものが手に入る。それこそ、Lee et al. のモデルが一番助けを必要としている作家ロングテールの穴です。

コールドスタートの観点もあります。モデルは価格履歴が豊富な作家ではよく学習できて、販売実績が3件しかない作家では苦しみます。販売3件＋群衆の推測1,000件なら、少なくとも扱える材料にはなります。クラウドソーシングによる評価は、元データがカバーしていないケースのための学習シグナルを生成する手段なのです。

ここでゲーム化が重要なのは、群衆を信頼できるものにする唯一の方法が、参加を楽しくしてたくさんやってもらうことだからです。一問きりのフォームでは、一度クリックして通り過ぎた人たちのノイズだらけのデータしか得られません。デイリーストリークとリーダーボードとキャリブレーションバッジがあれば、同じ人が1年かけて500回、真剣に考えた予測をしてくれます。量に自己選別（当てられる人は残り、当てられない人は飽きる）が掛かって、ノイズではなくシグナルになります。

作る前に解いておくべき設計上の問題もいくつかあります。ユーザーに何をどこまで見せるか──画像と経歴だけか、文脈として比較売買も出すか。文脈が多いほど推測の質は上がりますが、行きすぎるとユーザーはこちらが見せたものを反芻しているだけになります。価格フィードバックの粒度はどうするか。落札額そのままか、レンジか、±20%以内だったかどうかだけか。細かすぎると特定の数字にアンカーする癖を付けてしまい、曖昧すぎるとキャリブレーションができません。リーダーボードの攻略問題もあります。プレイヤーは知っている作家に流れますし、Banksyの推測は実力というよりほぼ雑学です。おそらく語学アプリがレッスンを選ぶような強制ランダムサンプリングと、作家名を伏せた「ブラインド」ラウンド用の別ランキングが現実解でしょう。そして後知恵バイアスは避けられません。バスキアが1億1千万ドルで売れたと知ってしまったら、知らなかった状態には戻れない。ループの誠実さを保つのは、まだ誰も見ていない作品の供給で、その供給は週あたり有限です。

ゲーム化という枠組みは、プラットフォームの両半分をつなぐ役目も果たします。クラウドファンディング側はショーが財務的に成功したときに投資家に報い、当てっこゲーム側は、投資家であろうとなかろうと、価格を当てるのがうまい人に報います。どちらも同じアイデアの変奏です。群衆の集合的判断を、取引可能なシグナルに変える。一方は資本を、もう一方は注意を取引します。本物の腕を磨いたプレイヤーは、検証可能な価格予測の実績を引っ提げて、いずれ投資家側に「卒業」できるかもしれません。「いい画商を知っていた」よりよほどまともなフィルタです。

持ち帰ったこと

#

事前予想額は非常に優秀です。オークションハウスは不透明な値付けだと叩かれがちですが、あの予想額だけで価格分散の90%近くを捉えます。専門家が何をやっているにせよ、上手にやっている。その一方で、作品そのものは統計的にほとんど意味を持ちません。美的な理由でアートが好きな人間には居心地の悪い結論です。市場が値段を付けているのは目の前の作品ではなく、ほかの人たちが隣の作品にすでに払った金額なのです。

モデリング面で効いた習慣は2つ。時系列分割は価格モデルを評価する唯一の正直な方法で、ランダム分割が返すのは本番投入に耐えない見栄えのいいR²です。そして勾配ブースティング木は今でも正しい道具です。論文中でXGBoostはすべてのニューラルベースラインに勝っていて、この規模・この作り込まれた特徴構造の表形式データでトランスフォーマーに手を伸ばす理由はありません。

商売の観点では、面白い機会は新興市場にあります。専門家の値付けが最も薄く、アルゴリズム予測が埋められる差が最も大きい場所だからです。それから、群衆は使われていないデータソースです。Lee et al. のモデルで最大の単一特徴量はオークションハウスの事前予想額でした。キャリブレーションされた群衆が作家ロングテールについて同等のシグナルを作れるなら、それはモデル入力としても、それ自体プロダクトとしても、本物の商機です。

2つのプロジェクトは、当初の計画以上に補完的になりました。論文の再現は何が価格を予測するのかを教えてくれて、プラットフォームの作業はその知識を使うのに必要なデータ構造を教えてくれました。そしてゲーム化のアイデアが両者をつなぎます。ナレッジグラフが作品と過去の販売を供給し、当てっこゲームが群衆由来の予想額特徴を生成し、モデルがそれを社会的シグナルと並べて消費して、このままではモデルから見えない作家たちについても予測を出す。

どれも完成はしていません。論文の再現はレポート付きの動くプロトタイプ、プラットフォームはシードデータ入りのデモ、クラウドソーシングのゲームはいま読んでもらった設計メモの中にしかありません。それでも、通底する筋は十分一貫していて、あるべき形はそれなりにはっきり見えていると思います。作品ではなく作家に値を付ける。専門家だけに頼らず群衆を集約する。評価を、専門家が上から手渡すものではなく、市場が集合的に作り出すものとして扱う。

時間さえ作れれば、次に作るのはこのバージョンです。