AI SRE với dữ liệu NYC Taxi

Chào mừng bạn đến với playbook của ClickHouse BUILD Workshop. Trong ba giờ, bạn sẽ lấy một ứng dụng phân tích dịch vụ gọi xe taxi NYC (front end React, back end FastAPI, Postgres làm database nguồn) và dựng nó lên hoàn chỉnh trên ClickHouse Cloud, dùng chính công cụ agentic coding của bạn để làm phần xây dựng. Đến cuối buổi, bạn sẽ có change data capture thời gian thực từ một Postgres được quản lý, BI hội thoại trên dữ liệu của mình, khả năng quan sát đầy đủ, một luồng làm việc SRE có AI hỗ trợ, và một AI chat trong ứng dụng được trace từ đầu đến cuối; bạn cũng sẽ thực hành chẩn đoán một sự cố đang xảy ra cùng một AI SRE.

Cùng một workshop này hỗ trợ cả macOS và Windows. Chỉ cần chọn máy tính của bạn ở phần header trang một lần; playbook sẽ luôn hiển thị đúng phần thiết lập ở mọi nơi. Trên Windows, bộ toolchain dùng chung của workshop chạy bên trong Ubuntu trên WSL 2.

Bạn ra về với một prototype đang chạy và repo này để trình bày cho đội của mình. ClickHouse, Postgres, ClickPipes, Agents được quản lý cùng các artifact ClickStack sẽ tồn tại suốt thời gian dùng thử; các trace Langfuse tồn tại trong Langfuse Cloud. Khi quay lại, hãy khởi động lại ứng dụng local và bộ chuyển tiếp telemetry bằng Docker. Đến cuối buổi, bạn có thể demo trực tiếp năm thứ:

• một dashboard vận hành thời gian thực trên ClickHouse Cloud,
• một pipeline change-data-capture stream từ Postgres được quản lý,
• BI hội thoại trên dữ liệu của bạn với ClickHouse Agents,
• một dashboard SRE và cảnh báo do AI dựng trên telemetry của bạn,
• và một AI chat trong ứng dụng được trace từ đầu đến cuối trong Langfuse.

Playbook này có hai lộ trình. Lộ trình Học viên là bài học bạn theo ngay tại lớp. Lộ trình Giảng viên là tài liệu đồng hành của người điều phối cho cùng module đó: thời lượng, mạch dẫn dắt, các lỗi thường gặp, và các bước reset.

Dành cho học viên

Bạn sẽ làm việc theo từng module. Mỗi module nêu rõ điểm khởi đầu, giải thích vì sao bước đó quan trọng, đặt ra một mục tiêu cụ thể, hướng dẫn bạn qua các bước được đánh số, và kết thúc bằng một phần kiểm chứng bạn có thể tự đối chiếu. Bạn không bao giờ phải theo kịp cả lớp: nếu bị tụt lại, phần Điểm khởi đầu của mỗi module nêu chính xác những gì cần có sẵn, để bạn có thể bắt kịp từ đó theo tốc độ của mình.

Những gì bạn cần trong ngày diễn ra workshop:

• Một laptop đáp ứng các yêu cầu tiên quyết trong 00 Thiết lập.
• Công cụ agentic coding của riêng bạn (Claude Code, Cursor, Codex CLI, hoặc Windsurf), đã đăng nhập và đang ở gói còn hiệu lực.
• Một tài khoản ClickHouse Cloud với tín dụng dùng thử hiển thị rõ (đã tạo trong phần chuẩn bị trước).
• Repository ứng dụng workshop đã clone về máy, với Docker đang chạy.

Tự học? Bạn có thể hoàn thành toàn bộ workshop mà không cần giảng viên - lộ trình chính hoàn toàn tự phục vụ. Xem Tự học workshop này để biết những gì thay đổi, cách dùng coding agent như một giảng viên, và tài liệu Xử lý sự cố cho mọi lỗi đã gặp khi kiểm thử.

Dành cho giảng viên

Lộ trình Giảng viên phản chiếu lộ trình Học viên theo tỉ lệ một-một. Với mỗi module, bạn có một ngân sách thời gian, một mạch dẫn dắt, những lỗi thực sự xảy ra tại lớp cùng cách tháo gỡ, và các bước reset chính xác để đưa một người tham dự (hoặc cả lớp) trở lại trạng thái đã biết là tốt. Hãy đọc trang giới thiệu lộ trình Giảng viên trước để nắm kịch bản chạy ở cấp độ cả lớp và danh sách kiểm tra tài nguyên dùng chung.

Phạm vi workshop

Ứng dụng bạn xây dựng trên đó

Ứng dụng workshop là một stack phân tích "war room" tự chứa cho một doanh nghiệp gọi xe taxi NYC:

• Front end — một single-page app React với hai dashboard: dashboard Ops (số liệu vận hành trực tiếp) và dashboard Historical (tổng hợp trên khoảng thời gian lớn và drilldown). Nó cũng chứa panel AI chat trong ứng dụng mà bạn đấu nối ở module 08.
• Back end — một service FastAPI phơi bày các endpoint phân tích an toàn, có tham số hóa.
• Database nguồn — Postgres do ClickHouse quản lý, làm nguồn sự thật vận hành, cũng là điểm khởi nguồn của change data capture vào ClickHouse.
• Kho phân tích — ClickHouse Cloud, nơi bạn trỏ back end tới ở module 01 và nơi nhận CDC, dữ liệu quan sát, cùng các truy vấn BI.

Bạn không xây ứng dụng từ đầu. Ứng dụng React/FastAPI chạy local, còn mọi service dữ liệu hoặc sản phẩm có trạng thái đều được host trên cloud ngay từ đầu.

Nền tảng bạn xây dựng trên đó

ClickHouse Cloud là một nền tảng duy nhất trải khắp toàn bộ stack — từ nạp dữ liệu ở dưới cùng, tới lưu trữ và phân tích trong ClickHouse, tới quan sát nó và xếp AI lên trên. Workshop này là một chuyến tham quan có dẫn đường qua đúng những mảnh ghép đó: bạn nạp dữ liệu bằng ClickPipes, phân tích trong ClickHouse, và quan sát bằng Managed ClickStack/HyperDX. Langfuse và OpenAI là các service được host riêng.

Kiến trúc (trạng thái đích cuối cùng)

Trước tiên, hãy nhóm các mảnh ghép theo nơi chúng chạy: ứng dụng không trạng thái và các công cụ trên laptop của bạn, các service có trạng thái trong ClickHouse Cloud, và các service AI được host riêng.

Dữ liệu chảy như thế nào

Giờ hãy theo dấu một chuyến xe trực tiếp từ bộ sinh tải local qua Postgres được quản lý và ClickPipes, vào default.realtime_trips, và cuối cùng vào các dashboard của ứng dụng.

Các sơ đồ ở trên được sinh ra từ workshops/build_workshop/docs/diagrams/gen_diagrams.py (sửa script rồi chạy lại để sinh lại các SVG) — xem luồng module bên dưới.

Các module

Mười module cốt lõi, theo thứ tự. Ứng dụng đã hoàn chỉnh trên build-workshop-v1, nên mọi module trừ 07 đều không cần checkout riêng — bạn cấu hình và kết nối các service thay vì thay đổi code ứng dụng. Lần chuyển branch duy nhất là các fault branch ở module 07.

Tổng thời lượng cộng lại khoảng 2 giờ 30 phút làm việc thực hành; phần còn lại của buổi ba giờ là phần mở đầu, các đoạn chuyển tiếp, và các demo kết thúc.

Cách làm việc qua các module

Branch

Ứng dụng đã hoàn chỉnh trên build-workshop-v1. Workshop này nói về việc cấu hình và kết nối các service — CDC thời gian thực, khả năng quan sát, agent, chat — chứ không phải sửa code ứng dụng, nên không có gì phải dựng dần theo từng branch:

• Clone ứng dụng một lần ở module 00, chuyển sang build-workshop-v1, và ở đó suốt, trừ lúc chạy các tình huống lỗi ở module 07.
• Người vào muộn không bao giờ bị bỏ rơi: các tài nguyên được quản lý nằm ở phía service, và ứng dụng local hoàn chỉnh khởi động lại từ branch của workshop cộng với .env.workshop. Không có checkout theo từng module nào phải bắt kịp.
• Lần chuyển branch duy nhất là ở module 07 (Làm hỏng và sửa), nơi dùng các fault branch (fault/01-map-not-loading, fault/02-zone-stats-500, fault/03-slow-dashboard). Bạn checkout một branch, chẩn đoán lỗi, sau đó giữ lại bản sửa và trở về build-workshop-v1 bằng bước reset stash-and-switch của module 07.

Biến môi trường

Cấu hình của workshop nằm trong một file .env.workshop duy nhất ở gốc repository ứng dụng. Một file .env.workshop.example an toàn đã được commit; hãy copy nó và chỉ điền các giá trị thuộc về bạn:

cp .env.workshop.example .env.workshop

Stack đọc nó một cách tường minh qua --env-file:

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

Bạn điền các giá trị trong phần thiết lập ở module 00, trừ khối ClickStack mà bạn sẽ thêm ở module 05:

• CLICKHOUSE_HOST, CLICKHOUSE_PASSWORD (cùng với CLICKHOUSE_PORT=8443, CLICKHOUSE_USER=default, CLICKHOUSE_DATABASE=nyc_tlc_data, CLICKHOUSE_SECURE=true) — service Cloud của bạn (module 00). CLICKHOUSE_HOST là hostname trần, không có scheme và không có port.
• OPENAI_API_KEY, LLM_MODEL=gpt-5.4-mini, LLM_BASE_URL — LLM chạy runtime cho chat trong ứng dụng (module 00).
• LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL — project Langfuse của bạn (module 00). LANGFUSE_BASE_URL là tên biến môi trường của Langfuse v4; dùng https://us.cloud.langfuse.com (US) hoặc https://cloud.langfuse.com (EU).
• OTLP_AUTH_TOKEN, CLICKSTACK_DATABASE=otel, OTEL_SERVICE_NAME=nyc-taxi-backend — khả năng quan sát, trong phần ClickStack của cùng file .env.workshop (module 05).

Đừng bao giờ commit file .env.workshop đã điền của bạn; nó đã được git-ignore.

Bố cục repository

Mọi thứ nằm trong một repository duy nhất (ClickHouse_Demos), trên branch build-workshop-v1. Code lab của mọi workshop nằm dưới workshops/, nên ứng dụng bạn xây dựng trên đó là workshops/build_workshop/; playbook đã công bố mà bạn đang đọc nằm trong site dùng chung ở gốc repository, site/, nơi cũng phục vụ workshop Agent Arena và hướng dẫn RTA tĩnh.

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

Đi đâu tiếp