AI SRE กับข้อมูลแท็กซี่ NYC

ยินดีต้อนรับสู่ playbook ของ ClickHouse BUILD Workshop ในเวลาสามชั่วโมงคุณจะนำแอป วิเคราะห์บริการเรียกรถแท็กซี่ NYC (ฟรอนต์เอนด์ React แบ็กเอนด์ FastAPI ฐานข้อมูลต้นทาง Postgres) มาตั้งขึ้นแบบครบวงจรบน ClickHouse Cloud โดยใช้เครื่องมือ agentic coding ของคุณเอง เป็นตัวสร้าง เมื่อจบคุณจะได้ change data capture แบบเรียลไทม์จาก Postgres แบบ managed, BI แบบสนทนาบนข้อมูลของคุณ, observability ครบถ้วน, เวิร์กโฟลว์ SRE ที่มี AI ช่วย, และแชท AI ในแอปที่ถูก trace ครบวงจร รวมถึงคุณจะได้ฝึก วินิจฉัยเหตุการณ์สดด้วย AI SRE

เวิร์กช็อปเดียวกันนี้รองรับทั้ง macOS และ Windows เลือกเครื่องของคุณที่หัวหน้า ของหน้าครั้งเดียว playbook จะแสดงขั้นตอนติดตั้งที่ถูกต้องให้เห็นทุกที่ Windows จะรัน ชุดเครื่องมือร่วมของเวิร์กช็อปภายใน Ubuntu บน WSL 2

คุณจะกลับไปพร้อมต้นแบบที่รันได้และ repo นี้เพื่อโชว์ทีมของคุณ ClickHouse แบบ managed, Postgres, ClickPipes, Agents และ artifact ของ ClickStack จะคงอยู่ตลอดช่วงทดลองใช้ ส่วน trace ของ Langfuse คงอยู่ใน Langfuse Cloud เมื่อกลับมาให้รีสตาร์ทแอปในเครื่องและตัวส่ง telemetry ด้วย Docker เมื่อจบคุณจะเดโมได้สดห้าอย่าง:

• แดชบอร์ดปฏิบัติการแบบเรียลไทม์บน ClickHouse Cloud,
• ไปป์ไลน์ change-data-capture ที่สตรีมจาก Postgres แบบ managed,
• BI แบบสนทนาบนข้อมูลของคุณด้วย ClickHouse Agents,
• แดชบอร์ดและการแจ้งเตือน SRE ที่ AI สร้างขึ้นบน telemetry ของคุณ,
• และแชท AI ในแอปที่ถูก trace ครบวงจรใน Langfuse

playbook นี้เป็นแบบสองแทร็ก แทร็กผู้เรียนคือบทเรียนที่คุณทำตามในห้อง ส่วน แทร็กผู้สอนเป็นคู่มือของผู้ดำเนินการสำหรับโมดูลเดียวกัน: เวลา แนวการพูด ปัญหาที่พบบ่อย และขั้นตอนรีเซ็ต

สำหรับผู้เรียน

คุณจะทำงานไปทีละโมดูล แต่ละโมดูลระบุจุดตรวจเริ่มต้น อธิบายว่าทำไมขั้นตอนนั้นสำคัญ ระบุเป้าหมายที่ชัดเจน พาคุณไปตามขั้นตอนที่มีหมายเลข และจบด้วยการตรวจสอบที่คุณเช็คได้เอง คุณไม่จำเป็นต้องตามให้ทันทั้งห้อง: ถ้าคุณตามไม่ทัน ส่วนจุดเริ่มต้นของแต่ละโมดูลจะบอก ชัดเจนว่าคุณต้องมีอะไรพร้อม เพื่อให้คุณตามเก็บจากจุดนั้นได้ในจังหวะของตัวเอง

สิ่งที่คุณต้องมีในวันนั้น:

• แล็ปท็อปที่ผ่านข้อกำหนดใน 00 การติดตั้ง
• เครื่องมือ agentic coding ของคุณเอง (Claude Code, Cursor, Codex CLI หรือ Windsurf) ที่ล็อกอิน แล้วและอยู่บนแพลนที่ใช้งานได้
• บัญชี ClickHouse Cloud ที่เห็นเครดิตทดลองใช้ (สร้างไว้ระหว่างงานเตรียมล่วงหน้า)
• repository ของแอปเวิร์กช็อปที่โคลนไว้ในเครื่อง พร้อม Docker ที่รันอยู่

เรียนด้วยตัวเอง? คุณทำเวิร์กช็อปทั้งหมดได้โดยไม่มีผู้สอน - เส้นทางหลัก เป็นแบบทำเองได้เต็มรูปแบบ ดู การทำเวิร์กช็อปนี้ด้วยตัวเอง เพื่อดูว่า อะไรเปลี่ยนไป จะใช้ coding agent ของคุณเป็นผู้สอนอย่างไร และ การแก้ปัญหา เป็นแหล่งอ้างอิงสำหรับทุกความล้มเหลวที่พบใน การทดสอบ

สำหรับผู้สอน

แทร็กผู้สอนสะท้อนแทร็กผู้เรียนแบบหนึ่งต่อหนึ่ง สำหรับทุกโมดูลคุณจะได้ งบเวลา แนวการพูด ความล้มเหลวที่เกิดขึ้นจริงในห้องและวิธีแก้ให้เดินต่อได้ และ ขั้นตอนรีเซ็ตที่แน่นอนเพื่อพาผู้เข้าร่วม (หรือทั้งห้อง) กลับสู่สถานะที่รู้ว่าใช้งานได้ อ่าน หน้าแรกของแทร็กผู้สอน ก่อน เพื่อดู ลำดับการดำเนินงานระดับห้องและเช็คลิสต์ทรัพยากรร่วม

ขอบเขตของเวิร์กช็อป

แอปที่คุณสร้างต่อยอด

แอปเวิร์กช็อปเป็นสแต็กวิเคราะห์แบบ "war room" ที่ครบในตัวสำหรับธุรกิจ เรียกรถแท็กซี่ NYC:

• ฟรอนต์เอนด์ — แอป React แบบหน้าเดียวที่มีสองแดชบอร์ด: แดชบอร์ด Ops (เมตริกปฏิบัติการสด) และแดชบอร์ด Historical (การรวมข้อมูลช่วงกว้างและการเจาะลึก) และยังเป็นที่อยู่ของแผงแชท AI ในแอปที่คุณต่อสายในโมดูล 08
• แบ็กเอนด์ — เซอร์วิส FastAPI ที่เปิดเอนด์พอยต์วิเคราะห์แบบปลอดภัยและรับพารามิเตอร์
• ฐานข้อมูลต้นทาง — Postgres ที่ ClickHouse จัดการให้ ทำหน้าที่เป็นแหล่งความจริงเชิงปฏิบัติการ และเป็นจุดกำเนิดของ change data capture เข้าสู่ ClickHouse
• คลังข้อมูลวิเคราะห์ — ClickHouse Cloud ที่คุณชี้แบ็กเอนด์ไปในโมดูล 01 และเป็นที่รับ CDC ข้อมูล observability และคิวรี BI

คุณไม่ได้สร้างแอปจากศูนย์ แอป React/FastAPI รันในเครื่อง ขณะที่ทุกเซอร์วิส ข้อมูลหรือผลิตภัณฑ์ที่มีสถานะถูกโฮสต์บนคลาวด์ตั้งแต่ต้น

แพลตฟอร์มที่คุณสร้างต่อยอด

ClickHouse Cloud เป็นแพลตฟอร์มเดียวที่ครอบคลุมสแต็กทั้งหมด — จากการนำข้อมูลเข้าที่ ชั้นล่าง ไปจนถึงการเก็บและวิเคราะห์ใน ClickHouse การสังเกตการณ์ และการวาง AI ทับด้านบน เวิร์กช็อปนี้คือทัวร์แบบมีไกด์ผ่านชิ้นส่วนเหล่านี้พอดี: คุณนำข้อมูลเข้าด้วย ClickPipes วิเคราะห์ใน ClickHouse และสังเกตการณ์ด้วย Managed ClickStack/HyperDX ส่วน Langfuse และ OpenAI เป็นเซอร์วิสโฮสต์แยกกัน

สถาปัตยกรรม (สถานะปลายทางที่ต้องการ)

ก่อนอื่น จัดกลุ่มชิ้นส่วนตามที่ที่มันรัน: แอปและเครื่องมือแบบไร้สถานะบนแล็ปท็อปของคุณ เซอร์วิสที่มีสถานะใน ClickHouse Cloud และเซอร์วิส AI ที่โฮสต์แยกกัน

ข้อมูลไหลอย่างไร

ตอนนี้ตามการเดินทางสดหนึ่งเที่ยวจากตัวสร้างโหลดในเครื่องผ่าน Postgres แบบ managed และ ClickPipes เข้าสู่ default.realtime_trips และท้ายที่สุดเข้าสู่แดชบอร์ดของแอปพลิเคชัน

ไดอะแกรมด้านบนถูกสร้างจาก workshops/build_workshop/docs/diagrams/gen_diagrams.py (แก้สคริปต์แล้วรันใหม่เพื่อสร้าง SVG อีกครั้ง) — ดูลำดับโมดูลด้านล่าง

โมดูล

สิบโมดูลหลัก เรียงตามลำดับ แอปสมบูรณ์แล้วบน build-workshop-v1 ดังนั้นทุกโมดูลยกเว้น 07 ไม่ต้อง checkout ต่อโมดูล — คุณตั้งค่าและเชื่อมต่อเซอร์วิสมากกว่าจะแก้ โค้ดแอป การสลับ branch อย่างเดียวคือ fault branch ในโมดูล 07

เวลารวมกันประมาณ 2 ชั่วโมง 30 นาทีของการลงมือทำ ส่วนที่เหลือของ เซสชันสามชั่วโมงคือการเปิด การเปลี่ยนช่วง และเดโมปิดท้าย

วิธีทำไปตามลำดับ

Branch

แอปสมบูรณ์แล้วบน build-workshop-v1 เวิร์กช็อปนี้เกี่ยวกับการตั้งค่า และเชื่อมต่อเซอร์วิส — CDC เรียลไทม์, observability, agent, แชท — ไม่ใช่การแก้ โค้ดแอปพลิเคชัน จึงไม่มีอะไรต้องสร้างสะสมทีละ branch:

• โคลนแอปครั้งเดียวในโมดูล 00 สลับไป build-workshop-v1 และอยู่ที่นั่นยกเว้น ตอนรันสถานการณ์ความผิดพลาดในโมดูล 07
• ผู้ที่เข้าร่วมช้าไม่เคยติดค้าง: ทรัพยากรแบบ managed อยู่ฝั่งเซอร์วิส และแอป ในเครื่องที่สมบูรณ์รีสตาร์ทได้จาก branch ของเวิร์กช็อปบวก .env.workshop ไม่มี การ checkout ต่อโมดูลที่ต้องตามเก็บ
• การสลับ branch อย่างเดียวอยู่ในโมดูล 07 (ทำให้พังแล้วแก้) ซึ่งใช้ fault branch (fault/01-map-not-loading, fault/02-zone-stats-500, fault/03-slow-dashboard) คุณ checkout อันหนึ่ง วินิจฉัยความล้มเหลว แล้วเก็บรักษาการแก้ไขและกลับไปที่ build-workshop-v1 ด้วยการรีเซ็ตแบบ stash-and-switch ของโมดูล 07

ตัวแปรสภาพแวดล้อม

การตั้งค่าเวิร์กช็อปอยู่ในไฟล์ .env.workshop ไฟล์เดียวที่รากของ repository ของแอป ไฟล์ .env.workshop.example ที่ปลอดภัยถูก commit ไว้ ให้คัดลอกและกรอกเฉพาะ ค่าที่เป็นของคุณ:

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 คือชื่อโฮสต์เปล่า ไม่มี scheme และไม่มีพอร์ต
• 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 เป็นชื่อ env ของ 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 — observability ในส่วน ClickStack ของไฟล์ .env.workshop เดียวกัน (โมดูล 05)

ห้าม commit .env.workshop ที่กรอกแล้วของคุณ ไฟล์นี้ถูก git-ignore ไว้

โครงสร้าง repository

ทุกอย่างอยู่ใน repository เดียว (ClickHouse_Demos) บน branch build-workshop-v1 โค้ดแล็บของทุกเวิร์กช็อปอยู่ใต้ workshops/ ดังนั้นแอปที่คุณสร้างต่อยอด คือ workshops/build_workshop/ ส่วน playbook ที่เผยแพร่ซึ่งคุณกำลังอ่านอยู่ใน ไซต์ร่วมที่รากของ repository คือ 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

ไปต่อที่ไหน