Yabanin — Mod Bayang (v9)
Mod bayang menjawab soalan penghalaan dengan data pengeluaran sebenar dan bukannya simulasi: pecahan tersampel permintaan sebenar yang telah dilayan dihantar semula secara senyap ke model/penyedia calon, dan kos serta kependaman sebenar calon direkodkan di sebelah baris permintaan utama. Perbandingan itu tidak lagi menjadi anggaran.
Ia ialah ciri gerbang. Ia dimatikan secara lalai, ia menelan wang sebenar semasa dihidupkan, dan ia dibina supaya tiada apa-apa tentangnya boleh menjejaskan respons klien.
Tiga invarian
- Laluan terus wajib. Respons klien ditulis sepenuhnya ke wayar sebelum panggilan bayang dilepaskan. Ralat bayang, tamat masa, panik dan penyedia bayang yang mati sepenuhnya tidak kelihatan kepada klien, bait demi bait. Suit ujian membuktikan ini (kes ralat bayang / tamat masa / panik semuanya menegaskan respons utama tidak berubah).
- Lalai gagal selamat. Dimatikan secara lalai. Melangkau organisasi yang disemat residensi, melangkau permintaan yang sudah menuju ke model bayang. Disampel, dihadkan keserentakan, dihadkan tamat masa, secara pilihan dihadkan bajet. Suis pemadaman masa jalan. (Utama penstriman DICERMINKAN — lihat Pendirian penstriman.)
- Perakaunan jujur. Kos bayang ialah perbelanjaan sebenar pada penyedia
bayang. Ia disimpan sebagai baris
request_logstersendiri (ab_group='shadow',request_idyang sama seperti utama), dikecualikan daripada setiap agregat perbelanjaan yang kelihatan kepada klien, dan tidak pernah ditolak daripada kredit klien.
Cara ia berfungsi
client ──POST /v1/chat/completions──▶ gateway
│
├─ primary upstream call ──▶ response ──▶ client (always)
│
└─ AFTER the response is written:
eligible? (see gates) ──▶ goroutine:
shadow upstream call
usage → cost
event: request.shadow_completed
│
loggerd ──▶ request_logs
(ab_group='shadow',
same request_id)
Pintu setiap permintaan (kegagalan pertama menang, setiap satu mempunyai metrik langkau sendiri):
| Pintu | Sebab langkau | Nota |
|---|---|---|
| ciri didayakan (keadaan masa jalan) | disabled | konfigurasi persekitaran ATAU togol pentadbir |
| model utama ≠ model bayang | same_model | mencerminkan kepada dirinya sendiri ialah pembaziran |
cabutan sampel < sample_rate | sampling | lalai 10% |
| organisasi tidak disemat residensi | residency | data organisasi yang disemat mungkin tidak boleh meninggalkan rantau |
| bajet harian ada ruang kepala | budget_exhausted | dalam memori, hari UTC, bersifat nasihat |
| slot keserentakan dalam tempoh tangguh | semaphore | lalai 4 sedang berjalan, tangguh 250 ms |
Tiada pintu penstriman: sama ada permintaan utama menstrim bukan sebahagian
daripada keputusan cermin. Panggilan bayang sentiasa permintaan biasa bukan
penstriman kepada calon (gerbang memaksa "stream": false dalam badan bayang), jadi
utama penstriman dicerminkan tepat seperti yang bukan penstriman.
Konfigurasi
Semua pemboleh ubah ialah pilihan; apa-apa yang tidak ditetapkan mengekalkan ciri dimatikan atau pada lalai selamatnya.
| Pemboleh ubah | Lalai | Maksud |
|---|---|---|
YABANIN_SHADOW_ENABLED | false | suis induk (aras persekitaran; togol masa jalan mengatasi pada masa jalan) |
YABANIN_SHADOW_MODEL | — | model calon untuk dicerminkan (wajib apabila didayakan) |
YABANIN_SHADOW_UPSTREAM_URL | huluan utama | URL asas penyedia bayang (melalui kolam yang sama → senarai benarkan SSRF terpakai) |
YABANIN_SHADOW_API_KEY | kunci gerbang | kunci yang dikemukakan kepada penyedia bayang |
YABANIN_SHADOW_SAMPLE_RATE | 0.10 | pecahan permintaan layak untuk dicerminkan (0..1, diapit) |
YABANIN_SHADOW_TIMEOUT | 30s | had masa setiap panggilan bayang |
YABANIN_SHADOW_MAX_CONCURRENT | 4 | had panggilan bayang yang sedang berjalan |
YABANIN_SHADOW_DAILY_BUDGET_USD | 0 (tanpa had) | had perbelanjaan sebenar harian, hari UTC, bersifat nasihat |
Setara YAML di bawah gateway.shadow.* dalam config.yaml.
Konfigurasi yang tidak sah (cth. didayakan tanpa model) merosot kepada dinyahdayakan dengan log amaran — bayang ialah kebolehcerapan, bukan kebergantungan laluan permintaan, dan salah taip tidak boleh menjatuhkan gerbang.
Suis pemadaman masa jalan
Pada pendengar pentadbir gerbang (lalai :9090, yang sama yang melayan
/metrics):
# current state (never includes the API key)
curl -H "Authorization: Bearer $YABANIN_METRICS_BEARER_KEY" \
http://gateway:9090/admin/shadow/status
# flip at runtime (no restart)
curl -X POST -H "Authorization: Bearer $YABANIN_METRICS_BEARER_KEY" \
-d '{"enabled": false}' http://gateway:9090/admin/shadow/toggle
- Pengesahan gagal tertutup. Tidak seperti
/metrics(yang jatuh kembali kepada sekatan rangkaian sahaja apabila tiada kunci ditetapkan), togol memerlukanYABANIN_METRICS_BEARER_KEY: tiada kunci dikonfigurasi ⇒403. Kawalan yang menanggung kos tidak boleh lalai terbuka. Perbandingan masa malar. - Semantik: panggilan bayang yang sedang berjalan selesai; tiada yang baharu bermula semasa dinyahdayakan.
- Togol itu setempat proses: mulakan semula menetapkan semula keadaan kepada konfigurasi persekitaran. Pelaksanaan berbilang replika: togol setiap replika (keadaan dikongsi di luar skop v9 secara reka bentuk — ia memerlukan migrasi atau protokol baharu, kedua-duanya dibekukan).
409apabila bayang tidak dikonfigurasi langsung.
Implikasi kos (baca ini sebelum mendayakan)
Panggilan bayang ialah permintaan sebenar pada penyedia bayang dan menelan wang sebenar. Sampel 10% pada organisasi yang sibuk ialah 10% perbelanjaan tambahan, dibilkan oleh penyedia bayang mengikut jamnya sendiri.
Tetapkan YABANIN_SHADOW_DAILY_BUDGET_USD bagi mana-mana organisasi dengan volum yang bermakna.
Lejar itu dalam memori bagi setiap proses (ditetapkan semula semasa mula semula, bergulir pada tengah malam
UTC) dan bersifat nasihat, bukan gred pengebilan.
Pantau yabanin_shadow_cost_usd_total (Prometheus) dan
yabanin_shadow_budget_exhausted_total.
Endpoint perbandingan memberitahu anda jawapan setiap permintaan, iaitu apa yang diperlukan oleh keputusan penghalaan:
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
"https://admin/api/analytics/shadow?days=30"
Respons (bentuk):
{
"period": "last_30_days",
"primary_model": "gpt-4o-mini",
"shadow_model": "gpt-4o",
"overlap": 1240,
"primary_avg_usd": 0.00042,
"shadow_avg_usd": 0.0021,
"delta_pct": 399.9,
"verdict": "pricier",
"by_model": [ ... ]
}
Keputusan: cheaper / pricier / insufficient_data. Di bawah 20 permintaan
bertindih, atau |delta| di bawah 1%, keputusan ialah insufficient_data —
endpoint enggan melebih-lebihkan tuntutan atas hingar. Tetingkap tanpa trafik bayang ialah
laporan yang sah (overlap: 0), bukan ralat.
Semantik perakaunan
- Hasil bayang disimpan sebagai baris
request_logsyang berasingan:request_idyang sama,ab_group='shadow',model_used= model bayang,cost_in_usd= kos dikira sebenar panggilan bayang, token/kos sifar apabila ralat. counterfactual_cost_usdtidak digunakan untuk bayang: lajur itu milik kontrafaktual cache. Kontrafaktual penghalaan dan kontrafaktual cache ialah kuantiti yang berbeza dan tidak boleh berkongsi lajur tanpa pembezaab_group.- Setiap agregat yang kelihatan kepada klien (laporan penjimatan, analitik kos, analitik
cache, amaran perbelanjaan, statistik permintaan, model/organisasi teratas, siri masa, pecahan
ralat, persentil kependaman, ralat terkini) mengecualikan
ab_group='shadow'secara nyata. - Deductor kredit tidak pernah dipanggil bagi baris bayang. Deductor
menyahdupe mengikut
request_id; baris bayang yang berkongsi id utama akan mengenakan caj berganda kepada organisasi. Ini ialah invarian tegar dengan ujian khusus.
Pendirian residensi
Organisasi dengan pin residensi (organizations.residency_region ditetapkan kepada apa-apa
selain global) tidak pernah dicerminkan. Data mereka mungkin tidak boleh meninggalkan
rantau yang disemat, dan penyedia bayang bersifat sewenang-wenang. Langkaun dikira dalam
yabanin_shadow_skipped_total{reason="residency"}. Pilihan masuk per organisasi memerlukan
lajur baharu ⇒ migrasi ⇒ dibekukan, jadi ia di luar skop.
Pendirian penstriman
Utama penstriman memang dicerminkan (v10). Gerbang melepaskan panggilan bayang daripada laluan penstriman sejurus selepas sambungan huluan berjaya (sebelum salir), jadi kependaman calon diukur serentak dengan beban sebenar.
Panggilan bayang itu sendiri sentiasa permintaan biasa bukan penstriman kepada
calon: gerbang menulis semula badan bayang untuk memaksa "stream": false.
Tiada gunanya memancarkan semula strim bayang kepada sesiapa — satu-satunya perkara yang
diperlukan mod bayang ialah token, kos, dan kependaman sebenar calon, yang
dipulangkan oleh pelengkapan biasa. Bait SSE klien tidak pernah disentuh (bayang
berjalan dalam goroutine sendiri dengan konteks sendiri; ujian invarian laluan terus
SSE menegaskan strim tidak berubah bait demi bait walaupun sasaran bayang
mati atau tergantung).
Kaveat kejujuran: penggunaan bayang diukur pada panggilan bukan penstriman sementara utama mungkin telah menstrim. Kiraan token boleh berbeza sedikit kerana penyedia menggunakan cache dan pengelompokan secara berbeza mengikut pengangkutan. Bagi perbandingan kos ini boleh diterima dan itulah maksud "apa yang akan dikenakan oleh calon"; ia bukan main semula tepat bit.
Kebolehcerapan
Prometheus (/metrics gerbang, didaftarkan apabila metrik + bayang dihidupkan):
| Metrik | Maksud |
|---|---|
yabanin_shadow_requests_total{result} | hasil: completed/error/timeout/panic/skipped |
yabanin_shadow_skipped_total{reason} | pecahan pintu |
yabanin_shadow_latency_seconds{model} | tempoh panggilan bayang |
yabanin_shadow_cost_usd_total{model} | USD sebenar yang dibelanjakan |
yabanin_shadow_budget_exhausted_total | langkaun bajet |
yabanin_shadow_enabled | tolok keadaan masa jalan (1/0) |
Papan pemuka Grafana. deploy/grafana/dashboards/shadow.json
diperuntukkan secara automatik (seperti papan pemuka Yabanin yang lain): Yabanin — Shadow
Mode menunjukkan keadaan didayakan, 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. Buka di hos Grafana (demo:
http://localhost:3001, admin / yabanin).
Amaran. deploy/prometheus/alert-rules.yml (kumpulan yabanin-shadow):
ShadowHighErrorRate(amaran) — >50% panggilan bayang gagal sepanjang 15 minit semasa trafik bayang mengalir; ralat berterusan bermakna sasaran salah konfigurasi atau tidak dapat dihubungi.ShadowBudgetBurn(maklumat) — had bajet harian menyekat panggilan bayang yang baharu; laraskanYABANIN_SHADOW_DAILY_BUDGET_USDatau rendahkan kadar sampel.
Runbook
- Pilih calon: tetapkan
YABANIN_SHADOW_MODEL(dan URL/kunci jika ia penyedia yang berbeza). - Mulakan kecil:
YABANIN_SHADOW_SAMPLE_RATE=0.05,YABANIN_SHADOW_DAILY_BUDGET_USDpada nombor yang anda benar-benar akan luluskan.YABANIN_SHADOW_ENABLED=true. - Biarkan ia berjalan 24–72 jam. Pantau
shadow_requests_total{result="error"}— ralat berterusan bermakna sasaran salah konfigurasi (atau tidak menyokong protokol wayar yang diandaikan); dalam kes itu penggunaan/kos ialah sifar dan baris tidak berguna. - Baca
/api/analytics/shadow?days=N. Buat keputusan. - Matikan (togol atau persekitaran) apabila soalan telah dijawab. Trafik bayang yang anda tidak baca ialah wang yang anda tidak perlu belanjakan.
Apa yang ini bukan
- Bukan ujian A/B: klien sentiasa mendapat jawapan model utama.
- Bukan pengimbang beban atau laluan failover: panggilan bayang ialah lepas-dan-lupakan dengan konteks sendiri; pembatalan konteks permintaan tidak sampai kepadanya, dan ia tidak sampai ke respons.
- Bukan pengebilan: perbelanjaan bayang ialah milik operator, bukan sekali-kali milik klien.