Skip to main content

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​

  1. 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).
  2. 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.)
  3. Perakaunan jujur. Kos bayang ialah perbelanjaan sebenar pada penyedia bayang. Ia disimpan sebagai baris request_logs tersendiri (ab_group='shadow', request_id yang 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):

PintuSebab langkauNota
ciri didayakan (keadaan masa jalan)disabledkonfigurasi persekitaran ATAU togol pentadbir
model utama ≠ model bayangsame_modelmencerminkan kepada dirinya sendiri ialah pembaziran
cabutan sampel < sample_ratesamplinglalai 10%
organisasi tidak disemat residensiresidencydata organisasi yang disemat mungkin tidak boleh meninggalkan rantau
bajet harian ada ruang kepalabudget_exhausteddalam memori, hari UTC, bersifat nasihat
slot keserentakan dalam tempoh tangguhsemaphorelalai 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 ubahLalaiMaksud
YABANIN_SHADOW_ENABLEDfalsesuis induk (aras persekitaran; togol masa jalan mengatasi pada masa jalan)
YABANIN_SHADOW_MODEL—model calon untuk dicerminkan (wajib apabila didayakan)
YABANIN_SHADOW_UPSTREAM_URLhuluan utamaURL asas penyedia bayang (melalui kolam yang sama → senarai benarkan SSRF terpakai)
YABANIN_SHADOW_API_KEYkunci gerbangkunci yang dikemukakan kepada penyedia bayang
YABANIN_SHADOW_SAMPLE_RATE0.10pecahan permintaan layak untuk dicerminkan (0..1, diapit)
YABANIN_SHADOW_TIMEOUT30shad masa setiap panggilan bayang
YABANIN_SHADOW_MAX_CONCURRENT4had panggilan bayang yang sedang berjalan
YABANIN_SHADOW_DAILY_BUDGET_USD0 (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 memerlukan YABANIN_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).
  • 409 apabila 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_logs yang berasingan: request_id yang sama, ab_group='shadow', model_used = model bayang, cost_in_usd = kos dikira sebenar panggilan bayang, token/kos sifar apabila ralat.
  • counterfactual_cost_usd tidak digunakan untuk bayang: lajur itu milik kontrafaktual cache. Kontrafaktual penghalaan dan kontrafaktual cache ialah kuantiti yang berbeza dan tidak boleh berkongsi lajur tanpa pembeza ab_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):

MetrikMaksud
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_totallangkaun bajet
yabanin_shadow_enabledtolok 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; laraskan YABANIN_SHADOW_DAILY_BUDGET_USD atau rendahkan kadar sampel.

Runbook​

  1. Pilih calon: tetapkan YABANIN_SHADOW_MODEL (dan URL/kunci jika ia penyedia yang berbeza).
  2. Mulakan kecil: YABANIN_SHADOW_SAMPLE_RATE=0.05, YABANIN_SHADOW_DAILY_BUDGET_USD pada nombor yang anda benar-benar akan luluskan. YABANIN_SHADOW_ENABLED=true.
  3. 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.
  4. Baca /api/analytics/shadow?days=N. Buat keputusan.
  5. 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.