site iconKoei's Digital Garden

Archive

Self-hosted Deployments

6 min read

Self-hosted Deployments

参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ

What（何についてか）

LiveKit Cloudのマネージドデプロイではなく、自前のコンテナオーケストレーション環境（Kubernetes、Render等）でAgentを運用する際に必要な知識。アーキテクチャ設計、リソースサイジング、ロールアウト戦略、オートスケーリングの設定指針をまとめている。

Why（なぜ必要か）

本番運用では、コストやセキュリティ要件、既存インフラとの統合などの理由で自前環境へのデプロイが求められる。LiveKit Agentはコンテナベースでほぼどこでも動くが、Voice AI特有の長時間セッションやリアルタイム性を考慮した設計判断が必要になる。

How（どう動くか）

アーキテクチャ概要

AgentはWorker Pool Modelで動作する。1台のAgentサーバーマシン上でAgentサーバープロセス（Worker）が起動し、LiveKit Server（SFU）にWebSocketで外向き接続してジョブの割り当てを待機する。各ジョブは独立したサブプロセスとして実行され、1ジョブが1ユーザーとのセッションに対応する。

graph TD
    LS["LiveKit Server - SFU"]
    LS -->|"ジョブ割り当て - round-robin"| AS1["Agentサーバーマシン1"]
    LS -->|"ジョブ割り当て"| AS2["Agentサーバーマシン2"]
    LS -->|"WebRTC - 音声/映像"| U["ユーザー - ブラウザ"]
    AS1 -->|"WebRTC"| LS
    AS2 -->|"WebRTC"| LS
    AS1 --> J1["Job1 - sub-process"]
    AS1 --> J2["Job2 - sub-process"]
    AS2 --> J3["Job3 - sub-process"]

ネットワーク

AgentサーバーはWebSocketでLiveKit Serverに外向き接続するだけのため、inboundポートを公開する必要がない。これはセキュリティ面で大きな利点である。オプションでヘルスチェックエンドポイント（デフォルト http://0.0.0.0:8081/）を公開できるが、通常運用では必須ではない。

プロジェクトセットアップ

DockerfileでAgentサーバーをビルドし、コンテナオーケストレータにデプロイする。公式starterプロジェクト（Python: agent-starter-python、Node.js: agent-starter-node）にDockerfileとCI設定が含まれている。

環境変数と環境分離

APIキーは環境変数で管理する。staging/production/developmentで別々のLiveKitプロジェクト（インスタンス）を使うことで、開発中の本番トラフィックへの影響を防ぐ。

リソース要件

推奨スペックは4コア/8GBで、同時10〜25ジョブを処理できる。公式ロードテストでは、30エージェント（Silero VAD使用）を1台の4コア/8GBマシンで稼働させ、CPU約3.8コア、メモリ約2.8GBという結果を記録している。ストレージはDockerイメージ込みで10GBのephemeral storageで十分である。

ロールアウトとGrace Period

デプロイ時にPodが SIGTERM を受け取ると、新規ジョブの受付を停止し、実行中のジョブは最後まで実行を続ける。Voice AIでは会話が10分以上続くことがあるため、Grace Periodを十分に長く設定する必要がある（Kubernetesでは terminationGracePeriodSeconds で指定）。

ロードバランシング

LiveKit Serverが内蔵のラウンドロビン分散を行う。単一割り当て原則により1ジョブは1台のサーバーにだけ割り当てられ、タイムアウト時は別サーバーにフォールバックする。LiveKit Cloudでは地理的アフィニティにより、ユーザーに最も近いAgentサーバーが優先される。

Agentサーバーの可用性制御

load_fnc（サーバーの負荷を0〜1で返す関数）と load_threshold（受付停止の閾値、デフォルト0.7）でジョブの受付可否を制御する。負荷が閾値を超えると新ジョブの受付を停止し、LiveKit Serverは別のサーバーにジョブを割り当てる。

オートスケーリング設計

スケールアップ閾値は load_threshold より低く設定する（例: load_threshold=0.7 に対してスケールアップ閾値は0.5）。これにより、既存サーバーが満杯になる前に新しいサーバーが追加される。

Voice Agentは長時間実行タスクのため、負荷のスパイクが持続的であるという特徴がある。スケールアップ時はクールダウンを短く（急いでサーバーを増やす）、スケールダウン時はクールダウンを長く（ジョブのドレインに時間がかかるため）設定する。

ジョブクラッシュの分離

ジョブプロセスがクラッシュしてもAgentサーバーや他のジョブには影響しない。しかしAgentサーバー自体がクラッシュした場合、そのサーバー上の全ジョブが終了する。クラッシュ情報はAgentサーバーのログに記録される。

Key Concepts

用語説明
Agentサーバーマシン1台の物理/VMサーバー。Agentサーバープロセスが動く
Agentサーバー (Worker)マシン上の1プロセス。LiveKit ServerにWebSocketで接続
ジョブ (Job)1ユーザーセッションを処理するサブプロセス
load_fncサーバー負荷を0〜1で返す関数（デフォルト: CPU使用率）
load_thresholdジョブ受付停止の閾値（デフォルト: 0.7）
Grace Periodロールアウト時に実行中ジョブの完了を待つ猶予期間
Geographic AffinityLiveKit Cloud機能。ユーザーと物理的に近いサーバーを優先割り当て

Graph View

Backlinks