Yabanin — Demo Satu Arahan
make demo membawa klon yang bersih ke tab pelayar yang menunjukkan perbelanjaan bukan sifar, kadar hit cache bukan sifar, taburan pengelas, dan angka penjimatan — dalam kira-kira 25 saat, tanpa langkah manual. Ia ialah aset jualan: ia mesti berjalan tanpa membaca sebarang dokumentasi lain.
Tiada masa untuk menjalankan apa-apa secara tempatan? Pendirian awam yang diuruskan oleh operator di
https://yabanin.ai menyediakan tindanan yang sama untuk penilaian — lihat
Pendirian awam. Selebihnya halaman ini ialah tentang demo tempatan satu arahan.
Demo ini menaikkan tindanan minimum (postgres, redis, migrasi, penyedia tiruan, penbenam tiruan, gerbang, logger, admin, papan pemuka) dan bukan bahagian yang berat (Prometheus, Grafana, Alertmanager, pengelas ML, LLM tempatan). Gerbang menghalakan ke penyedia tiruan dalam tindanan dan penbenam ialah penbenam tiruan, jadi tiada muat turun model dan tiada kelayakan penyedia yang sebenar.
Prasyarat
- Docker dengan Docker Compose v2 (
docker compose version) make(disertakan bersama Xcode Command Line Tools pada macOS)curldanshasum(kedua-duanya disertakan pada macOS; diperlukan oleh langkah main semula/benih)- ~2 GB memori Docker bebas untuk set kontena
- Klon bersih repositori (file
deploy/secrets/*mesti ada; ia ialah rahsia pembangunan tempatan, tidak dijejak oleh git)
Tiada psql, rantai alat Go, atau Node diperlukan pada hos — benih dijalankan melalui psql kontena postgres sendiri, dan imej perkhidmatan dibina oleh Docker.
Jalankan
make demo
Jika berjaya, arahan mencetak URL, kunci API demo, dan log masuk admin:
Demo is live.
Dashboard : http://localhost:3000
Admin : http://localhost:9091 (log in at /auth/login)
Gateway : http://localhost:8082 (POST /v1/chat/completions)
API key : demo-key-1234567890
Admin in : demo@local / demo-admin-123
Buka http://localhost:3000, log masuk di /auth/login dengan demo@local /
demo-admin-123, dan papan pemuka telah diisi.
Dengan mod bayang (make demo SHADOW=1)
Secara pilihan, cerminkan seluruh trafik demo ke model kedua supaya perbandingan utama berbanding bayang mempunyai data sebenar. Bayang dimatikan secara lalai dan meninggalkan respons klien tidak berubah (lihat shadow-mode.md):
make demo SHADOW=1
Apa yang berubah:
gerbang dimulakan dengan YABANIN_SHADOW_ENABLED=true dan mencerminkan setiap
permintaan demo bukan penstriman ke gpt-4o pada penyedia tiruan yang sama
(kadar sampel 1.0 untuk demo, had bajet harian 100 USD — ia tiruan, tiada
perbelanjaan sebenar);
selepas main semula, skrip mencetak kiraan baris bayang dan baris
kos purata setiap permintaan, utama berbanding bayang, daripada request_logs
(baris bayang membawa ab_group='shadow' dan request_id yang sama seperti
baris utama);
endpoint perbandingan kemudian menjawab dengan keputusan dan bukannya
insufficient_data:
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:9091/api/analytics/shadow?days=1"
# runtime kill switch (gateway admin listener, bearer-protected).
# The gateway admin listener (container :9090) is published on host
# :9092 — host :9090 is taken by Prometheus in this stack.
curl -H "Authorization: Bearer demo-shadow-key" \
http://localhost:9092/admin/shadow/status
curl -X POST -H "Authorization: Bearer demo-shadow-key" \
-d '{"enabled": false}' http://localhost:9092/admin/shadow/toggle
Papan pemuka bayang (pilihan, tindanan penuh)
Set demo minimum tidak termasuk Prometheus/Grafana. Untuk melihat metrik
yabanin_shadow_* secara langsung, naikkan perkhidmatan kebolehcerapan juga:
docker compose -f deploy/docker-compose.yml up -d prometheus grafana
Kemudian buka http://localhost:3001 (Grafana, admin / yabanin) dan pilih papan pemuka
Yabanin — Shadow Mode. Ia menunjukkan: keadaan bayang diaktifkan, kadar
perbelanjaan (USD/s), bajet yang dibelanjakan (24 jam), peristiwa bajet habis (1 jam), permintaan mengikut
hasil, langkaun mengikut sebab, kependaman P95 mengikut model, dan perbelanjaan mengikut model.
Dua amaran Prometheus mengiringi papan pemuka (deploy/prometheus/alert-rules.yml,
kumpulan yabanin-shadow):
- ShadowHighErrorRate (amaran) — >50% panggilan bayang gagal sepanjang 15 minit semasa trafik bayang mengalir; ralat yang berterusan bermakna sasaran salah konfigurasi atau tidak dapat dihubungi.
- ShadowBudgetBurn (maklumat) — had bajet harian menyekat panggilan bayang
yang baharu; laraskan
YABANIN_SHADOW_DAILY_BUDGET_USDatau kadar sampel.
Apa yang dijana
- 300 permintaan sembang dimainkan semula melalui gerbang: campuran gesaan mudah/sederhana/sukar, awalan sistem yang dikongsi, dan ulangan yang disengajakan supaya cache semantik menghasilkan hit yang tulen dan bukannya sifar yang rata.
- Organisasi demo + pasukan + kunci API + pengguna admin, serta dompet kredit dan bajet pasukan, supaya pengawal kredit dan penguat kuasa bajet gerbang membenarkan permintaan lalu.
- Data perbelanjaan, cache, pengelas, dan penjimatan ditulis ke pangkalan data oleh logger, yang dibaca oleh papan pemuka.
Keadaan skrin yang dijangka, halaman demi halaman
Selepas log masuk, setiap halaman menunjukkan data bukan sifar:
- Gambaran keseluruhan — jumlah permintaan (≈300), jumlah perbelanjaan ($ bukan sifar), dan angka penjimatan gabungan cache + penghalaan. Tunjuk pada kiraan permintaan dan jumlah perbelanjaan.
- Kos — pecahan perbelanjaan setiap model:
gpt-4odangpt-4o-mini, setiap satu dengan kiraan permintaan dan kos bukan sifar. Tunjuk pada baris model dan lajur dolar. - Cache — kiraan hit cache bukan sifar (gesaan yang diulang mengenai cache semantik) dan kadar hit. Tunjuk pada kiraan hit dan angka kos yang dielakkan.
- Pengelas — taburan mudah / sederhana / sukar bagi gesaan yang dimainkan semula. Tunjuk pada kiraan kelas.
API penjimatan di sebalik halaman ini ialah GET /api/analytics/savings?days=7; ia
memulangkan total_requests, actual_cost_usd, cache_hits, dan
top_models_by_cost, semuanya bukan sifar selepas main semula.
Tetapkan semula
Untuk menurunkan semuanya, termasuk volum (supaya make demo seterusnya bermula
daripada keadaan yang bersih):
make demo-down
Untuk menetapkan semula dan menjalankan semula dalam satu langkah:
make demo-down && make demo
Penyelesaian masalah
| Gejala | Punca yang mungkin | Pembaikan |
|---|---|---|
demo FAIL: <service> did not become ready ... within Ns | Perkhidmatan tidak bermula, atau port sudah digunakan. | Semak docker compose -f deploy/docker-compose.yml ps dan log perkhidmatan yang gagal (... logs <service>). Jika port (3000, 8082, 9091, 5432, 6379) diambil oleh proses lain, bebaskan port itu atau jalankan make demo-down dahulu. |
Kontena bermula tetapi gerbang memulangkan 502/unsupported protocol scheme | Gerbang tidak dapat mencapai penyedia tiruan. | Sahkan gerbang mempunyai YABANIN_PROVIDER_ADDR: http://mock-openai:8081 (ditetapkan dalam file compose) dan mock-openai sihat. |
demo FAIL: migrations did not create org_credits within 120s | Volum yang lapuk atau migrasi yang dijalankan separa. | make demo-down (membuang volum), kemudian make demo sekali lagi. |
Papan pemuka kosong / unauthorized | Tidak log masuk, atau sesi admin telah tamat. | Log masuk di /auth/login dengan demo@local / demo-admin-123. Demo menyemai semula pengguna admin secara idempoten, jadi kelayakan adalah stabil. |
| Docker kehabisan memori dan kontena OOM | Had memori Docker terlalu rendah untuk set kontena. | Naikkan peruntukan memori Docker Desktop kepada ≥ 4 GB, kemudian make demo-down && make demo. |
| Larian semula menunjukkan data lapuk atau pendua | Volum larian sebelumnya dikekalkan. | Sentiasa jalankan make demo-down (ia membuang volum) sebelum make demo untuk keadaan yang bersih. |
Merakam video demo
Rakam perkara ini, mengikut urutan ini, sambil menunjuk pada nombor yang dinamakan:
- Terminal —
make demosedang berjalan, kemudian blokDemo is live(tunjukkan URL dan kunci API). - Papan pemuka → Gambaran keseluruhan — kiraan permintaan keseluruhan dan jumlah perbelanjaan.
- Papan pemuka → Kos — baris setiap model (
gpt-4o,gpt-4o-mini) dan kosnya. - Papan pemuka → Cache — kiraan hit cache dan angka kos yang dielakkan.
- Papan pemuka → Pengelas — taburan mudah / sederhana / sukar.
- Terminal (pilihan) —
yb auditterhadap log permintaan untuk menunjukkan angka penjimatan gabungan penganalisis luar talian (lihatdocs/audit.md).
Jangan komit tangkapan skrin binari ke repositori; rakam ke dalam video atau stor aset luaran.