NYC タクシーデータで学ぶ AI SRE

ClickHouse BUILD ワークショップのプレイブックへようこそ。3時間かけて、NYC タクシーの 配車分析アプリ（React フロントエンド、FastAPI バックエンド、Postgres ソースデータベース）を 題材に、自分のエージェント型コーディングツールで構築しながら ClickHouse Cloud 上に エンドツーエンドで立ち上げます。終わりには、マネージド Postgres からのリアルタイムな 変更データキャプチャ、自分のデータに対する対話型 BI、フルオブザーバビリティ、AI 支援の SRE ワークフロー、エンドツーエンドでトレースされたアプリ内 AI チャットが揃い、さらに AI SRE を使って実際のインシデントを診断する練習も済んでいます。

同じワークショップが macOS と Windows の両方に対応しています。ページヘッダーで 一度自分のマシンを選べば、プレイブックはどこでも正しいセットアップ手順を表示します。 Windows では、共通のワークショップツールチェーンを WSL 2 上の Ubuntu 内で実行します。

修了時には、動くプロトタイプとこのリポジトリが手元に残り、チームに見せられます。マネージドな ClickHouse、Postgres、ClickPipes、Agents、ClickStack の成果物はトライアル期間中は残り、 Langfuse のトレースは Langfuse Cloud に残ります。戻ってきたら、ローカルのアプリとテレメトリ フォワーダーを Docker で再起動してください。修了時には、次の5つをライブでデモできます。

• ClickHouse Cloud 上のリアルタイム運用ダッシュボード
• マネージド Postgres からストリーミングする変更データキャプチャ パイプライン
• ClickHouse Agents による自分のデータへの対話型 BI
• テレメトリをもとに AI が作った SRE ダッシュボードとアラート
• Langfuse でエンドツーエンドにトレースされたアプリ内 AI チャット

このプレイブックはデュアルトラックです。受講者トラックは会場で実際に進めるレッスン、 講師トラックは同じモジュールに対するファシリテーター向けの手引き（タイミング、トーク トラック、よくある失敗、リセット手順）です。

受講者の方へ

モジュールごとに進めていきます。各モジュールには、開始チェックポイント、その手順が重要な理由、 具体的なゴール、番号付きの手順、そして自分で確認できる検証項目があります。会場全体のペースに 合わせる必要はありません。遅れてしまっても、各モジュールの「開始時点」セクションに必要な状態が 正確に書かれているので、そこから自分のペースで追いつけます。

当日必要なもの:

• 00 セットアップ の前提条件を満たすノート PC。
• 自分のエージェント型コーディングツール（Claude Code、Cursor、Codex CLI、または Windsurf）。 サインイン済みで、有効なプランに加入していること。
• トライアルクレジットが表示されている ClickHouse Cloud アカウント（事前作業で作成済み）。
• ローカルにクローン済みのワークショップ アプリ リポジトリと、起動中の Docker。

自習で進めますか？ 講師なしでもワークショップ全体を完了できます — メインの経路は 完全にセルフサービスです。何が変わるか、コーディングエージェントを講師として使う方法は このワークショップを自習で進める を参照してください。また、 テストで確認されたすべての失敗については トラブルシューティング リファレンスがあります。

講師の方へ

講師トラックは受講者トラックと1対1で対応しています。各モジュールについて、時間配分、トーク トラック、実際に会場で起きる失敗とその解消方法、そして受講者（あるいは会場全体）を既知の 正常な状態に戻す具体的なリセット手順が揃っています。まずは 講師トラックのランディングページ を読んで、会場全体の進行と 共有リソースのチェックリストを確認してください。

ワークショップの範囲

題材となるアプリ

ワークショップ アプリは、NYC タクシーの配車ビジネス向けの自己完結型「ウォールーム」分析 スタックです。

• フロントエンド — 2つのダッシュボードを持つ React シングルページアプリ。Ops ダッシュ ボード（リアルタイムの運用メトリクス）と Historical ダッシュボード（広い期間の集計と ドリルダウン）です。モジュール 08 で接続するアプリ内 AI チャットパネルもここにあります。
• バックエンド — 安全でパラメータ化された分析エンドポイントを公開する FastAPI サービス。
• ソースデータベース — 運用上の信頼できる情報源としての ClickHouse マネージド Postgres。 ClickHouse への変更データキャプチャの起点になります。
• 分析ウェアハウス — ClickHouse Cloud。モジュール 01 でバックエンドの接続先として設定し、 CDC、オブザーバビリティ データ、BI クエリを受け取ります。

アプリをゼロから作るわけではありません。React/FastAPI のアプリはローカルで動き、状態を持つ データ／プロダクトサービスは最初からすべてクラウドでホストされています。

土台となるプラットフォーム

ClickHouse Cloud は、最下層のデータ取り込みから、ClickHouse での保存と分析、そのオブザーバ ビリティ、さらにその上に載る AI まで、スタック全体をカバーする単一のプラットフォームです。 このワークショップは、まさにこれらの構成要素をたどるガイドツアーです。ClickPipes で取り込み、 ClickHouse で分析し、Managed ClickStack/HyperDX で観測します。Langfuse と OpenAI は別の ホステッドサービスです。

アーキテクチャ（目標とする最終状態）

まず、それぞれの構成要素をどこで動くかで分類します。ステートレスなアプリとツールは自分の ノート PC、状態を持つサービスは ClickHouse Cloud、そして別途ホストされる AI サービスです。

データの流れ

次に、1件のライブな乗車データが、ローカルの負荷生成器からマネージド Postgres と ClickPipes を 通り、default.realtime_trips に入り、最後にアプリのダッシュボードへ届くまでを追います。

上記の図は workshops/build_workshop/docs/diagrams/gen_diagrams.py から生成されています （スクリプトを編集して再実行すると SVG が再生成されます） — 以下のモジュールフローも参照してください。

モジュール

コアモジュールは10個、順番どおりに進めます。アプリは build-workshop-v1 上で完成しているため、 07 以外のモジュールではモジュールごとのチェックアウトは不要です — アプリコードを変更するのでは なく、サービスを設定して接続していきます。ブランチを切り替えるのはモジュール 07 の fault ブランチだけです。

合計するとハンズオン作業は約2時間30分です。3時間セッションの残りは、オープニング、 モジュール間の移行、そして最後のデモに使います。

進め方

ブランチ

アプリは build-workshop-v1 上ですでに完成しています。このワークショップは、アプリコードを 編集することではなく、サービス（リアルタイム CDC、オブザーバビリティ、エージェント、チャット）を 設定して接続することが主題なので、ブランチごとに積み上げていくものは何もありません。

• モジュール 00 でアプリを一度クローンし、build-workshop-v1 に切り替えて、モジュール 07 で 障害シナリオを実行するとき以外はそこに留まります。
• 遅れて参加しても取り残されることはありません。マネージドなリソースはサービス側にあり、 完成済みのローカルアプリはワークショップブランチと .env.workshop があれば再起動できます。 追いつくためのモジュールごとのチェックアウトはありません。
• ブランチを切り替えるのはモジュール 07（故障と修復）だけで、ここでは fault ブランチ （fault/01-map-not-loading、fault/02-zone-stats-500、fault/03-slow-dashboard）を使います。 1つをチェックアウトして障害を診断し、その後モジュール 07 の stash-and-switch リセットで 修正を保持しつつ build-workshop-v1 に戻ります。

環境変数

ワークショップの設定は、アプリリポジトリのルートにある1つの .env.workshop ファイルに まとまっています。安全な .env.workshop.example がコミットされているので、それをコピーして 自分固有の値だけを埋めてください。

cp .env.workshop.example .env.workshop

スタックは --env-file で明示的にこのファイルを読み込みます。

docker compose --env-file .env.workshop -f docker-compose.workshop.yml up -d

値はモジュール 00 のセットアップ中に埋めます。ただし ClickStack のブロックだけは モジュール 05 で追加します。

• CLICKHOUSE_HOST、CLICKHOUSE_PASSWORD（さらに CLICKHOUSE_PORT=8443、 CLICKHOUSE_USER=default、CLICKHOUSE_DATABASE=nyc_tlc_data、CLICKHOUSE_SECURE=true） — 自分の Cloud サービス（モジュール 00）。CLICKHOUSE_HOST はスキームもポートも付けない ホスト名のみです。
• OPENAI_API_KEY、LLM_MODEL=gpt-5.4-mini、LLM_BASE_URL — アプリ内チャット用の ランタイム LLM（モジュール 00）。
• LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_BASE_URL — 自分の Langfuse プロジェクト（モジュール 00）。LANGFUSE_BASE_URL は Langfuse v4 の環境変数名です。 https://us.cloud.langfuse.com（US）または https://cloud.langfuse.com（EU）を使います。
• OTLP_AUTH_TOKEN、CLICKSTACK_DATABASE=otel、OTEL_SERVICE_NAME=nyc-taxi-backend — オブザーバビリティ用で、同じ .env.workshop の ClickStack セクションにあります（モジュール 05）。

値を埋めた .env.workshop は絶対にコミットしないでください。git-ignore されています。

リポジトリ構成

すべてが1つのリポジトリ（ClickHouse_Demos）の build-workshop-v1 ブランチにあります。 各ワークショップのラボコードは workshops/ 以下にあるので、題材となるアプリは workshops/build_workshop/ です。いま読んでいる公開プレイブックは、リポジトリルートの共有 サイト site/ にあり、このサイトは Agent Arena ワークショップと静的な RTA ガイドも配信しています。

site/                           # the shared Next.js + Fumadocs site (all workshops)
  content/docs/build-workshop/  # this playbook (the site you are reading)
    index.mdx                   # this overview
    learner/                    # self-paced guide, the lessons 00-setup ... 09-wrap-up,
                                #   and a troubleshooting reference
    instructor/                 # facilitator notes: 00-setup ... 09-wrap-up
  src/                          # Next.js + Fumadocs app
  README.md                     # run, build, deploy, and authoring guide

workshops/build_workshop/
  app/                         # the NYC-taxi app you build on (cloned in module 00)
    frontend/                  # React SPA (Ops + Historical dashboards, chat panel)
    backend/                   # FastAPI analytics API + AI chat
    db/cloud/001_cloud_schema.sql   # maintainer fixture; Module 01 contains the copyable SQL
    docker-compose.workshop.yml     # the workshop stack (Cloud + ClickPipes)
    docker-compose.otel.yml         # the ClickStack observability overlay (module 05)
    .env.workshop.example      # single env template (Cloud + chat + observability);
                               #   copy to .env.workshop and fill in your values

次に進む先