Pythonによるレンダーファームのアップロード自動化：paramiko・rsyncガイド

クラウドレンダリングで最も時間がかかるのは、レンダリングそのものではないことが多いです。マルチカメラのVFXショットや400 GBのHoudiniキャッシュを毎晩レンダーファームに送り続けるスタジオにとって、ボトルネックはバイトを移動すること――プロジェクトを確実にアップロードし、朝のスタッフが出社する前に完成フレームをダウンロードすることです。真夜中にプログレスバーを眺めながら手作業でこなすのは、スケールしません。スクリプトで自動化することが解決策です。

このガイドは、Pythonでそのファイル転送レイヤーを自動化することをテーマにしています。当社はフルマネージドのレンダーファームであるSuper Renders Farmを運営しており、「フルマネージド」という言葉には自動化において明確な意味があります。リモートマシンへのアクセス、ソフトウェアのインストール、ライセンスの管理は必要ありません。パイプラインのうちスクリプトで制御できる部分は、自分たちが所有する部分――アップロードするファイルとダウンロードするレンダリング結果です。転送面はSFTPを通じて完全にスクリプト化でき、Pythonはその最有力な選択肢です。当社の転送ドキュメントでは、Python の paramiko ライブラリがサポートされているクライアントとして、rsync over SSH および標準の sftp コマンドラインと並んで直接名指しされています。

今日Pythonから自動化できないことについても、同様に明確にお伝えします。存在しない機能に基づいて構築されたパイプラインは、最初の無人実行で必ず失敗するからです。「ヘッドレス」と「無人」の概念的な違い、コマンドラインレンダリングのためのシーン準備方法については、別のガイドで取り上げています。このガイドはコードレベルに絞り、転送レイヤーに集中します：paramiko、rsync、SSH鍵、リトライ処理、そしてスタジオの自動化に組み込めるナイトリー同期パターンです。

今日Pythonで自動化できること

コードを書く前に、境界線を明確にしておくことが重要です。マネージドレンダーファームでは、パイプラインの一部は完全にスクリプト化でき、一部は意図的にGUI経由となっており、中間に位置するものもあります。それぞれの性質を正確に把握することで、静かに壊れる自動化を防げます。

• プロジェクトのアップロード――完全スクリプト化可能。 paramiko によるSFTP、rsync、またはスクリプト化した sftp コマンドはすべて当社のSFTPサーバーに対して機能します。以下の内容の核心部分です。
• 完成フレームのダウンロード――完全スクリプト化可能。 出力はジョブごとのディレクトリに格納され、同じツールでダウンロードできます。
• ジョブ完了の検出――部分的。 ポーリング用の公開ステータスAPIはありません。できることは、SFTPの出力ディレクトリをポーリングしてフレームが現れて安定するのを待つことです。これは発見的手法であり、公式なシグナルではありません。以下でそのように扱います。
• レンダージョブの送信――現時点ではGUI。 送信はWebフォーム、SuperRenders Client App、またはDCCごとの送信プラグインを通じて行います。ジョブ送信、ステータスポーリング、出力取得のための公開REST APIはロードマップ上にありますが、現時点では直接統合のための公開APIエンドポイントは利用できません。パイプラインが送信APIで具体的にブロックされている場合は、サポートに連絡してユースケースをお知らせください――ロードマップは実際のパイプライン要件によって形成されます。
• アカウント、クレジット、課金の管理――GUI。 転送自動化の対象外です。

したがって、自動化可能な領域は転送です：プロジェクトをアップロードし、レンダリング結果をダウンロードし、出力ディレクトリを監視することでその間をつなぎます。送信ステップは意図的な引き渡しポイントとして残り、最終的なパイプラインでもそのように明示します。マネージドレンダリングが公開・非公開にしているものの全体像については、フルマネージドレンダーファームとは何かのガイドがそのモデルをカバーしています。新規アカウントは入門ウォークスルーから始められます。

前提条件：SFTPアクセス、SSH鍵、Pythonの環境

最初のスクリプトによるアップロードを行う前に、3つの準備が必要です。

SFTPアクセス（アカウントごとに有効化）。 SFTPはアカウントごとにリクエストで有効化されます。サインイン後、アカウント設定で「SFTPアクセス」を探してそこで認証情報を生成してください。表示されない場合はサポートに有効化を依頼してください。認証情報には、サーバーのホスト名（リージョンとストレージの割り当てによって異なるため、設定から読み取る値として扱い、ハードコードしないこと）、アカウントに紐づいたユーザー名、パスワードまたはSSH鍵、および標準のSFTPポート22が含まれます。重要なパスは2つあります：/uploads/<your-project-folder>/ が書き込み領域で、/output/<job-id>/ が完成したレンダリング結果が現れる場所です。

パスワードではなくSSH鍵を使用してください。 自動化するものには、SSH鍵認証が適切な選択です――スクリプトから秘密情報を排除し、インタラクティブなプロンプトなしで無人実行を維持します。モダンな鍵ペアを生成し、公開鍵をアカウントに登録してください：

ssh-keygen -t ed25519 -C "pipeline@yourstudio.example"
# ~/.ssh/id_ed25519.pub の内容を
# superrendersfarm.com -> Settings -> SFTP -> SSH Keys に追加してください

アカウントセキュリティに関する注意：現時点ではアカウントに2要素認証はサポートされていません。そのため、SFTPでの最強のセキュリティ強化は、鍵ファイルにパスフレーズを設定し、セッション中はSSHエージェントにアンロックされた鍵を保持させることです。鍵とそのパスフレーズの知識を組み合わせることで、第2要素に近い役割を果たします――所持と秘密の組み合わせです。

paramiko入りのPython環境。 以下の内容ではすべて、標準的な純PythonのSSH/SFTP実装であるparamikoを使用し、大規模な増分転送にはrsyncをシェル経由で呼び出します。

python3 -m venv .venv && source .venv/bin/activate
pip install paramiko

無人アップロードを乗り切るプロジェクトのパッケージング

失敗するレンダリングジョブのほとんどはエンジンのバグではなく、パッケージングの問題です。アーティストのワークステーションでレンダリングできるシーンが、新しいワーカーでは失敗するのは、テクスチャのパスがローカルドライブを指していたり、参照しているサブシーンがバンドルされていなかったりするためです。自動化はこれを増幅させます：壊れたパッケージの無人アップロードは、無人の失敗を生みます。2つのルールでパッケージをクリーンに保てます。

まず、相対パスでプロジェクトを自己完結させてください。DCCのcollect-and-packageコマンド（Archive、Collect Files、Save Project with Assets）を実行して、すべてのテクスチャ、プロキシ、キャッシュがプロジェクトルートからの相対パスで解決されるようにします。次に、アップロード前に圧縮する場合はアーカイブ形式に注意してください：tar、tar.gz、7zはサポートされていますが、.zipはサポートされていません――.tar.gzとして再パッケージするか、アーカイブをスキップしてフォルダツリーを rsync で転送してください。進行中のプロジェクトには後者の方が通常より良い選択です。実用的な上限として、1回のアップロードは約300 GB以下に抑えてください。それ以上の場合は再開機能付きのrsyncを使用し、単一の大規模転送を避けてください。

paramikoでプロジェクトをアップロードする

最初のビルディングブロックは再帰的なアップローダーです。鍵で接続し、ローカルのプロジェクトツリーを走査して/uploads/配下にディレクトリ構造を再現し、各ファイルをputします。RejectPolicyでホスト鍵を固定し、接続の詳細は環境変数から読み取るため、スクリプト内に機密情報は残りません。

import os
import paramiko

def connect():
    host = os.environ["SRF_SFTP_HOST"]
    user = os.environ["SRF_SFTP_USER"]
    key_path = os.environ["SRF_SFTP_KEY"]      # 秘密鍵のパス

    client = paramiko.SSHClient()
    client.load_system_host_keys()             # ~/.ssh/known_hosts のみ信頼
    client.set_missing_host_key_policy(paramiko.RejectPolicy())
    client.connect(hostname=host, port=22, username=user, key_filename=key_path)
    return client, client.open_sftp()

def _ensure_remote_dir(sftp, remote_dir):
    # SFTP上のmkdir -p：パスを1セグメントずつ構築
    path = ""
    for segment in remote_dir.strip("/").split("/"):
        path += "/" + segment
        try:
            sftp.stat(path)
        except IOError:
            sftp.mkdir(path)

def upload_dir(sftp, local_dir, remote_dir):
    for root, _dirs, files in os.walk(local_dir):
        rel = os.path.relpath(root, local_dir)
        remote_root = remote_dir if rel == "." else f"{remote_dir}/{rel.replace(os.sep, '/')}"
        _ensure_remote_dir(sftp, remote_root)
        for name in files:
            local_path = os.path.join(root, name)
            remote_path = f"{remote_root}/{name}"
            sftp.put(local_path, remote_path)
            print(f"uploaded {remote_path}")

1つのプロジェクトで実行する方法：

client, sftp = connect()
try:
    upload_dir(sftp, "/local/projects/archviz-tower", "/uploads/archviz-tower-2026-06")
finally:
    sftp.close()
    client.close()

小中規模のプロジェクトにはこれで十分です。sftp.put は callback= 引数も受け付け、転送バイト数と合計バイト数を受け取れます。プログレスメーターやファイルごとのログ行に接続できます。ただし、スタジオ業務を特徴付ける大規模で繰り返しの転送には、rsync の方が優れたツールです。

rsync over SSHによる増分同期

レンダープロジェクトが1回だけアップロードされることはめったにありません。シェーダーを微調整し、シミュレーションを再キャッシュし、ライトを修正して再アップロードします。そのたびにフォルダ全体を送信するのは何時間も無駄にします。rsync は変更されたものだけを送信します。毎晩アップロードするスタジオにとって、これは転送レイヤーの中で最も大きな時間節約です。デルタのみを転送するためです。

標準的な呼び出し方：

rsync -avz --partial --progress \
  /local/projects/archviz-tower/ \
  "$SRF_SFTP_USER@$SRF_SFTP_HOST:/uploads/archviz-tower-2026-06/"

-a は構造とタイムスタンプを保持し、-z は転送中に圧縮し、--partial は部分転送されたファイルを保持することで接続が切れても最初からやり直さずに再開でき、--progress はファイルごとに進捗を報告します。変更後に同じコマンドを再実行すると、変更されたファイルのみが転送されます。自動化が目的なので、Pythonでラップして他のスクリプトと同じファイルに収め、終了コードに反応できるようにします：

import subprocess

def rsync_up(local_dir, remote_subdir):
    host = os.environ["SRF_SFTP_HOST"]
    user = os.environ["SRF_SFTP_USER"]
    dest = f"{user}@{host}:/uploads/{remote_subdir}/"
    cmd = ["rsync", "-avz", "--partial", "--progress",
           f"{local_dir.rstrip('/')}/", dest]
    subprocess.run(cmd, check=True)   # 失敗時はCalledProcessErrorを発生

無人実行するにはスケジュール設定します。作業ディレクトリを毎晩午前1時にレンダーファームにミラーリングするスタジオは、cronの1行で済みます：

0 1 * * *  cd /studio/pipeline && /usr/bin/python3 nightly_sync.py >> sync.log 2>&1

SSH経由のrsyncをプロンプトなしで認証するには、-e "ssh -i ~/.ssh/id_ed25519" で鍵を指定するか、SSHエージェントにセッション中アンロックされた鍵を保持させてください。

完成フレームの自動ダウンロード

ジョブが完了すると、出力フレームはSFTPサーバーの /output/<job-id>/ に書き込まれます。ダウンロード側はアップロード側を鏡写しにしています――paramikoによる再帰的な get、または rsync によるプル。paramikoのバージョンはリモートディレクトリを走査してローカルに再現します：

import stat

def download_dir(sftp, remote_dir, local_dir):
    os.makedirs(local_dir, exist_ok=True)
    for entry in sftp.listdir_attr(remote_dir):
        remote_path = f"{remote_dir}/{entry.filename}"
        local_path = os.path.join(local_dir, entry.filename)
        if stat.S_ISDIR(entry.st_mode):
            download_dir(sftp, remote_path, local_path)
        else:
            sftp.get(remote_path, local_path)
            print(f"downloaded {local_path}")

大規模な出力セットには、rsync プルの方が効率的で再開可能な選択肢です：

rsync -avz --progress \
  "$SRF_SFTP_USER@$SRF_SFTP_HOST:/output/<job-id>/" \
  /local/downloads/<job-id>/

無人パイプラインにとって重要な運用上の詳細があります：レンダリング済みの出力はジョブ完了後45日間保持され、その後自動的に削除されます。SFTPはその期間を延長しません。安全なパターンは、出力が現れた直後にローカルアーカイブにミラーリングするナイトリー同期です。そうすれば、保持期間がフレームを失う原因になることはありません。

ステータスAPIなしでジョブ完了を検出する

ここが、正直な境界線が具体的なエンジニアリングの選択になる部分です。「ジョブ12345は完了しましたか？」と尋ねる公開エンドポイントはありません――しかし、出力ディレクトリ自体はSFTP経由で観察できます。実用的なパターンは、/output/<job-id>/ をポーリングし、ファイル数をカウントして、期待するフレームの合計数に達したかつ連続するチェック間で安定するまで待つことです（書き込み中にダウンロードを開始しないように）。

import time

def wait_for_output(sftp, output_dir, expected_frames, poll=120, stable_checks=2):
    last_count, stable = -1, 0
    while True:
        try:
            files = sftp.listdir(output_dir)
        except IOError:
            files = []                      # フォルダがまだ作成されていない -> 未開始
        count = len(files)
        if count >= expected_frames and count == last_count:
            stable += 1
            if stable >= stable_checks:
                return files                # カウントが満たされ安定 -> 完了とみなす
        else:
            stable = 0
        last_count = count
        time.sleep(poll)

これが何であるかを明確に理解してください。フレームは増分的に現れるため、存在するだけでは完了ではありません。期待する合計数に対してカウントをチェックし、ポーリング間でそれが安定していることを確認することで、自動化に十分な信頼性が生まれます。これはディレクトリの発見的手法であり、契約ではありません。公開APIが公開されれば、この関数全体がステータスコールに置き換わります――それまでは、出力ディレクトリを監視することがギャップを埋める根拠のある方法であり、すでに存在する機能のみに依存しています。

まとめ：無人転送パイプライン

各部品は単一のナイトリースクリプトに組み合わさります。構成は：プロジェクトを同期してアップロードし、送信に引き渡し、出力が現れて安定するのを待ち、ダウンロードし、確認してアーカイブします。送信ステップは意図的なGUI引き渡しです――マネージドレンダーファームではWebフォーム、Client App、またはDCC送信プラグインを通じて送信します。各DCCプラグインは、送信がすでにスクリプト化しているツール内にある場合（MAXScript、DCC内のPython）、ホストアプリケーション独自のスクリプト環境から制御できます。APIが存在するかのように偽るのではなく、このステップを正直にマークします。

def nightly_pipeline(project_dir, remote_subdir, job_id, expected_frames):
    client, sftp = connect()
    try:
        # with_retries()（次のセクションで定義）は脆弱なネットワーク呼び出しをラップ
        with_retries(lambda: rsync_up(project_dir, remote_subdir))    # 1. デルタをアップロード
        # 2. 送信：GUI / Client App / DCCプラグイン -- 公開APIはまだ存在しない
        files = wait_for_output(                                      # 3. 出力ディレクトリを監視
            sftp, f"/output/{job_id}", expected_frames)
        with_retries(lambda:                                          # 4. 完成フレームをダウンロード
            download_dir(sftp, f"/output/{job_id}", f"/local/downloads/{job_id}"))
        print(f"job {job_id}: {len(files)} frames retrieved")
    finally:
        sftp.close()
        client.close()

ステップ1・3・4は完全に自動化されています。ステップ2が引き渡しポイントです。公開の送信APIが登場すれば、ステップ2と3はAPIコールになり、ディレクトリポーリングは不要になります。アーキテクチャは変わりません――送信とステータスのレグがGUIと発見的手法からエンドポイントに移行するだけです。

エラー処理、リトライ、再開可能な転送

無人実行とは、転送がヒックアップした際に誰も監視していないことを意味します。そのため、スクリプト自体が回復しなければなりません。3つの習慣でほとんどの障害をカバーできます。

バックオフ付きのリトライで一時的な障害を処理してください。 ネットワークの瞬断や短い切断は、長時間の転送中には正常です。上記の nightly_pipeline のように脆弱な呼び出しをラップして、単一の切断で実行が終了しないようにします。特定の一時的エラーをキャッチしてください：paramikoの SSHException、ソケット用の OSError ファミリー、失敗した rsync の CalledProcessError。

def with_retries(fn, attempts=3, backoff=5):
    transient = (paramiko.SSHException, OSError, subprocess.CalledProcessError)
    for i in range(1, attempts + 1):
        try:
            return fn()
        except transient:                  # SSH/ネットワーク/rsyncのヒックアップをリトライ
            if i == attempts:
                raise
            time.sleep(backoff * i)        # バックオフ：5秒、10秒、15秒

再開可能性を活用してください。 rsync --partial はすでに中断されたファイルを再開し、rsync を再実行することは冪等です――不足しているものだけを送信するため、リトライした同期は安価であり、再スタートではありません。paramikoの転送では、リトライに加えて再走査することで同じ効果が得られます。既に存在するファイルはほぼ瞬時に転送されるためです。

ホスト鍵と接続エラーを明示的に処理してください。 「host key verification failed」エラーは、~/.ssh/known_hosts のキャッシュされた鍵がサーバーの鍵と一致しなくなったことを意味します――稀なホスト鍵のローテーション後に最も多く発生します。エラーが示す古い行を削除して再接続し、新しい鍵を承認してください。接続の拒否またはタイムアウトは通常、スタジオのファイアウォールがアウトバウンドTCPポート22をブロックしていることを意味します。許可するかサポートに代替案を尋ねてください。スループットがリンク速度を大幅に下回る場合、長距離リンクではSFTPのパケットごとのオーバーヘッドが原因です――並列セグメントを使った lftp や複数の同時SFTPセッションでほとんどのギャップを取り戻せます。

まとめ：何を自動化するか、そしてその方法

転送レイヤーはマネージドファームパイプラインにおいてコードで所有できる部分であり、Pythonはそのすべてをカバーします。

タスク	Pythonで自動化可能か	ツール	備考
プロジェクトのアップロード	可	paramiko または rsync	大規模・繰り返しには rsync；--partial で再開
増分再アップロード	可	rsync over SSH	変更されたファイルのみ転送
完成フレームのダウンロード	可	paramiko get / rsync プル	ナイトリーにミラーリング――45日保持
完了の検出	部分的	/output/<job-id>/ をポーリング	カウント+安定性の発見的手法、ステータスAPIなし
レンダージョブの送信	不可（現時点）	Web / Client App / DCCプラグイン	公開APIはロードマップ上
認証	可	SSH鍵（ed25519）	鍵+パスフレーズ；シークレットをハードコードしない

アップロードを自動化し、ダウンロードを自動化し、出力ディレクトリを監視することで中間をつなぎ、送信の引き渡しを明示的に保ってください。これにより、継ぎ目について正直で、だからこそ信頼性の高いナイトリーパイプラインが構築されます。転送の信頼性が最も重要な大規模シミュレーション重視のプロジェクト――マルチテラバイトのHoudiniキャッシュなど――でもSuper Renders Farmで同じパターンが直接スケールします。そのワークロードについてはHoudiniクラウドレンダーファームページで詳しく説明しています。

FAQ

Q: レンダーファームへのアップロードにどのPythonライブラリを使うべきですか？ A: paramiko が標準的な選択肢であり、当社のSFTPドキュメントでサポートされているクライアントとして直接名指しされています。純Pythonで、SFTPをクリーンに処理し、アップロードとダウンロードのロジックに適しています。非常に大規模または頻繁に繰り返される転送には、Pythonから subprocess で rsync over SSH を呼び出してください――変更されたファイルのみを送信し、中断されたものを再開します。paramiko はネイティブにはこれを行いません。

Q: PythonパイプラインからレンダージョブをサブミットするためのパブリックAPIはありますか？ A: 現時点ではありません。サブミット、ステータスポーリング、出力取得のための公開REST APIはロードマップ上にありますが、現時点では公開エンドポイントはありません。現在のプログラム的なサブミット手段は、SuperRenders Client AppとDCCごとの送信プラグインです。後者はMAXScriptやDCC内Pythonなどのホストアプリケーションのスクリプティング環境と統合されています。パイプラインが具体的に公開サブミットAPIでブロックされている場合は、サポートに連絡してユースケースをお知らせください――ロードマップは実際のパイプライン要件によって形成されます。

Q: ステータスAPIがない場合、レンダージョブの完了をどのように検出しますか？ A: ジョブのSFTP出力ディレクトリ /output/<job-id>/ をポーリングし、フレーム数を監視してください。期待する合計数に達し、かつ連続するチェック間で安定している場合にのみジョブを完了とみなします。フレームがまだ書き込まれている間にダウンロードを開始しないためです。これはディレクトリの発見的手法であり、公式のステータスシグナルではありませんが、今日すでに存在する機能のみに依存しています。

Q: 自動転送にはSSH鍵とパスワードのどちらを使うべきですか？ A: SSH鍵を使用してください。スクリプトにパスワードをハードコードするのはセキュリティリスクであり、鍵認証はインタラクティブなプロンプトなしで無人実行できます。ed25519鍵を生成し、Settings → SFTP → SSH Keys に公開鍵を登録し、SSHエージェントに保持させたパスフレーズで秘密鍵を保護してください。現時点ではアカウントに2要素認証がサポートされていないため、鍵とそのパスフレーズの組み合わせがSFTPアクセスに対して最も強力な実用的セキュリティ強化です。

Q: スクリプトから .zip アーカイブをアップロードできますか？ A: いいえ――.zip アーカイブはサポートされていません。.tar.gz（または .tar / .7z）として再パッケージするか、アーカイブをスキップして rsync でフォルダツリーを直接転送してください。アップロード間で変更されるプロジェクトには後者が通常より良い選択です。1回のアップロードは約300 GB以下に抑え、それ以上のものには rsync --partial を使って接続が切れても再スタートではなく再開されるようにしてください。

Q: この方法でどれくらいの大きさのプロジェクトを転送できますか？ A: SFTP経由でのマルチテラバイト転送はサポートされています。実際の制限はレンダーファームが設けた上限ではなく、自身のアップロード帯域幅です。100 Mbpsで1 TBのアップロードには約1日かかるため、リンク速度に合わせて計画を立ててください。太い回線や長距離回線での最大スループットには、単一のSFTPストリームはパケットごとのオーバーヘッドによって制限されるため、並列セグメントを使った lftp や複数の同時SFTPセッションを使用してください。

Q: レンダリング済みのフレームはどのくらいダウンロード可能ですか？ A: 出力はジョブ完了後45日間保持され、その後自動的に削除されます。SFTPはその期間を延長しません。無人パイプラインには、出力が現れた直後にローカルアーカイブにミラーリングしてください――/output/<job-id>/ のナイトリー rsync プルにより、保持期間がフレームを失う原因になることはありません。

Q: ヘッドレス・無人ワークフローガイドとこのガイドの違いは何ですか？ A: あちらのガイドは概念的な地図です――ヘッドレスレンダリングの意味、コマンドラインレンダリングのためのシーン準備方法、マネージドレンダーファームにおける無人ループの全体像。このガイドはコードレベルのガイドであり、転送レイヤーに焦点を当てています：プロジェクトをアップロードしフレームをダウンロードするために実際に書く paramiko と rsync。形を理解するにはワークフローガイドを、実装にはこのガイドを参照してください。