Hands-on Track — AI Infrastructure for Real Business Problems
實作專題：解決真實商業問題的AI基礎架構 · 10 labs, one store, runnable code
A 10-lab, code-first track that complements the 12 modules of the main course. Every lab solves one problem for the same fictional store, Kettle & Kiln (an online tea-ware shop in Oakland), using one shared dataset. Each lab ships runnable Python 3.12 / FastAPI / Docker Compose code with tests.
How the Track Works — 課程運作方式
- One store, one dataset.
data/holds:- 30 products and 212 customers
- 288 orders / 412 order lines
- 20 reviews, 12 tickets and 7 wholesale leads
- 7 policy documents and a 15-question support eval set
data/generate_data.py regenerates the CSVs deterministically (seed 20261015; "today" in the data is 2026-10-15).
- One client for every model. labs/common (llmkit) talks to Ollama, llama.cpp, LM Studio, OpenAI or any OpenAI-compatible URL. Its offline mock provider makes every test suite run without a GPU or an API key.
- Each lesson has the same sections:
- business problem
- architecture (diagram)
- prerequisites
- step-by-step setup with exact commands
- how to test
- what was run on the build box
- cost & performance notes
- common failures
- stretch exercise
- deliverable checklist
- Honesty rules. Results quoted in the lessons are single observed runs on a CPU-only build box with small models (qwen2.5:0.5b/1.5b, nomic-embed-text). They are not benchmarks. No prices are quoted; you fill in labs/09/pricing.yaml from your provider's page. Anything not run on the build box is marked ⚠️ Not run.
Labs — 實作單元
| # | Lab | Business problem | Maps to module |
|---|---|---|---|
| 01 | Model Access: Local vs Cloud | Where may each request go? One client for all backends; PII stays local | M1, M10 |
| 02 | Prompts as Code + Evals | A prompt edit silently broke ticket routing | M2 |
| 03 | Product-Listing Generator Service | Bilingual listings without invented specs; Shopify CSV | M3 |
| 04 | Support Knowledge Base (RAG) | Answer only from policies, with citations, or refuse | M5 |
| 05 | Customer-Service Agent | Refunds by policy, identity checks, humans for safety | M6, M8 |
| 06 | n8n Automations | Reviews, tickets, leads triaged and routed automatically | M6 |
| 07 | Sales-Data Copilot | Plain-language analytics that can't modify data or invent numbers | M4 |
| 08 | Self-Hosting | 24/7 on a NAS/Mac: Compose, Caddy, Cloudflare Tunnel, GPU, TrueNAS | M10 |
| 09 | AI Gateway & Observability | Spend per feature, PII redaction, budgets, traces | M12 |
| 10 | Capstone Platform | Everything behind one gateway; smoke, load, production checklist | M11, Capstone |
Getting Started — 開始使用
cd hands-on/labs/01
uv venv --python 3.12 && source .venv/bin/activate
uv pip install -e ../common -r requirements.txt
LLM_PROVIDER=mock pytest -q # works offline
cp .env.example .env && python doctor.py
Test Status on the Build Box — 測試狀態
| Lab | Offline tests (mock) | Live run on build box (Ollama, CPU) |
|---|---|---|
| 01 | 8 passed, 1 skipped (live-only) | doctor / chat / compare / live test ✅ |
| 02 | 5 passed | eval reports saved (labs/02/reports/) |
| 03 | 8 passed | 4/4 drafts, 0 hard-rule failures, all needs_review |
| 04 | 8 passed (incl. pgvector) | hit@k 100%, cite_ok 87%, keywords 73%, grounded 100% (n=15) |
| 05 | 15 passed | 4 scenarios; discount-code incident → guard added |
| 06 | 9 passed | real n8n 2.43.7: 39/39 webhooks 200 (mock model); live-model replay not completed |
| 07 | 14 passed | golden 0/8 on 1.5B (3 wrong-but-verified) |
| 08 | validate.sh all OK (config only) |
⚠️ no Docker daemon: stack not started |
| 09 | 9 passed | redaction + restore via Ollama, report ✅ |
| 10 | 2 passed (full no-Docker smoke) | smoke 4/5 e2e on 1.5B (copilot failed) |
Not run anywhere on the build box: Docker builds / compose up, GPUs, cloud APIs, TrueNAS, a live Cloudflare Tunnel/Access, a Langfuse server, Slack, Open WebUI. See each lesson's "What was run" section.
Folder Layout — 目錄結構
hands-on/
README.md this page
NN-<slug>.md lessons 01–10
PROGRESS.md build log
data/ shared dataset (CSV + docs + eval)
labs/common/ llmkit shared client + mock
labs/01 … labs/10/ code, tests, Dockerfiles, compose, .env.example, README per lab