Underclass yordamida bardoshli AI obunalar havzasini yarating

Underclass nima qiladi

Underclass bir nechta ChatGPT/Codex va GitHub Copilot obunalarini OpenAI bilan mos keluvchi yagona endpointga birlashtiradigan mahalliy proksi hisoblanadi. Mijozlar tanish /v1/* yo‘llari orqali ulanadi, Underclass esa foydalanish mumkin bo‘lgan obunani tanlaydi, kvota holatini kuzatadi va so‘rovlarni tegishli yuqori darajadagi xizmatga yo‘naltiradi.

Bu har bir obunaning alohida kvotasi bo‘lganida foydalidir. Bitta obuna limitiga yetganda hisoblarni qo‘lda almashtirish o‘rniga, ularni umumiy havzaga joylashingiz mumkin. Kvotasi tugagan hisob sovish holatiga o‘tadi va kvota oynasi yangilangach avtomatik ravishda navbatga qaytadi.

Underclass hisoblar holati, sessiya bog‘liqligi va prompt-kesh samaradorligini saqlagan holda, yaxshi ta’minlangan yagona provayder kabi ishlash uchun mo‘ljallangan.

Asosiy imkoniyatlar

• OpenAI bilan mos API: Mijozlar /v1/responses, /v1/chat/completions va /v1/models yo‘llaridan foydalanishi mumkin.
• Bir nechta backend: Havzada ChatGPT/Codex hisoblari, GitHub Copilot hisoblari yoki ikkalasi ham bo‘lishi mumkin.
• Yopishqoq sessiyalar: prompt_cache_key yoki promptCacheKey bo‘lgan so‘rovlar imkon qadar bir obunaga biriktirilgan holda qoladi.
• Avtomatik sovitish: Kvota haqidagi javoblar hisobni qayta urinish oynasi tugaguncha navbatdan chiqaradi.
• Tezkor to‘yinganlik javoblari: Model uchun foydalanish mumkin bo‘lgan barcha hisoblar sovish holatida bo‘lsa, Underclass cheksiz navbatga qo‘yish o‘rniga eng erta mavjud Retry-After qiymati bilan 429 javobini qaytaradi.
• Jarayondagi so‘rovlar soni eng kam hisobni tanlash: Foydalanish mumkin bo‘lgan Codex va Copilot hisoblari har bir backend model katalogi bo‘yicha filtrlangan yagona havzada raqobatlashadi.
• Saqlanadigan holat: Hisoblar, model kataloglari, ma’lumotlar va yopishqoq bog‘lanishlar qayta ishga tushirishlardan keyin ham saqlanadi.
• Ma’muriy veb-interfeys: Hisoblarni qo‘shish va boshqarish, model kataloglarini tahrirlash hamda so‘nggi 200 ta so‘rovni ko‘rish mumkin.
• Tuzilmaviy kuzatuv: Har bir javobda x-request-id mavjud bo‘ladi, jurnallar esa har bir so‘rovga xizmat ko‘rsatgan hisob yorlig‘ini ko‘rsatadi.

Underclass’ni o‘rnatish va ishga tushirish

1-variant: Rust loyihasidan ishga tushirish

Repositorydan API mijozlari va ma’muriy interfeys uchun alohida maxfiy kalitlar yarating, so‘ng serverni ishga tushiring:

UNDERCLASS_PROXY_KEY="$(openssl rand -hex 32)" \
UNDERCLASS_UI_TOKEN="$(openssl rand -hex 32)" \
cargo run -- serve

Standart tinglovchi manzili http://127.0.0.1:8080, veb-interfeys esa asosiy URL manzilida mavjud:

http://127.0.0.1:8080/

Yaratilgan ikkala qiymatni parol menejerida yoki ish vaqti maxfiy faylida saqlang. Proksi kaliti /v1/* so‘rovlariga ruxsat beradi, UI tokeni esa ma’muriy amallarga ruxsat beradi. Underclass bu qiymatlarni diagnostika ma’lumotlariga yozmaydi.

2-variant: Nix bilan ishga tushirish

Repository shuningdek Nix flake hisoblanadi. Proksini o‘rnatmasdan ishga tushiring:

nix run github:ghuntley/underclass -- serve

Paketni Nix profilingizga o‘rnatish uchun quyidagidan foydalaning:

nix profile install github:ghuntley/underclass

Ishlab chiqish uchun taqdim etilgan shell’ga kiring va testlarni ishga tushiring:

nix develop --no-pure-eval
cargo test

devenv ishlab chiqish shell’i uchun --no-pure-eval opsiyasi talab qilinadi. nix run yoki nix profile install uchun bu opsiya talab qilinmaydi.

Havzaga hisoblar qo‘shish

1. http://127.0.0.1:8080/ manzilini oching.
2. UNDERCLASS_UI_TOKEN sifatida sozlangan qiymatni joylashtiring.
3. Hisob qo‘shishni tanlang.
4. ChatGPT / Codex yoki GitHub Copilot variantlaridan birini tanlang.
5. Ko‘rsatilgan qurilmani avtorizatsiya qilish URL manzilini oching va qurilma kodini kiriting.
6. Ro‘yxatdan o‘tkazish jarayoni tugashini kuting. Underclass hisobga uning elektron pochta manzili yoki foydalanuvchi nomi asosida yorliq beradi.
7. Havzada ishtirok etishi kerak bo‘lgan har bir obuna uchun jarayonni takrorlang.

UI orqali hisoblarni yoqish, o‘chirish, olib tashlash yoki qayta kirish ham mumkin. O‘chirilgan hisob sozlangan holda qoladi, ammo so‘rovlar uchun tanlanmaydi.

OpenCode’ga ulanish

Underclass OpenCode’ga Underclass provayderini qo‘shadigan connect buyrug‘ini o‘z ichiga oladi:

cargo run -- connect

Odatiy holatda buyruq OpenCode’ning global konfiguratsiyasini ~/.config/opencode/ ostida yangilaydi. U provayder blokini opencode.json yoki opencode.jsonc fayliga birlashtiradi, ma’lumotlarni auth.json fayliga yozadi va zaxira nusxalarini yaratadi. Amal idempotent, shuning uchun uni xavfsiz tarzda qayta ishga tushirish mumkin.

Havza taqdim etgan model bilan OpenCode’ni ishga tushiring:

opencode --provider underclass --model underclass/gpt-5.5

Loyiha uchun lokal konfiguratsiyaga yozish uchun --project parametrini qo‘shing:

cargo run -- connect --project

Hech qanday faylga yozmasdan birlashtirilgan konfiguratsiyani oldindan ko‘ring:

cargo run -- connect --dry-run

Endi kerak bo‘lmagan yaratilgan integratsiyani olib tashlang:

cargo run -- connect --remove

Buyruq yaratiladigan provayder konfiguratsiyasini moslashtirish zarur bo‘lganda --base-url, --api-key, --model va --no-default-model parametrlarini ham qabul qiladi.

OpenAI bilan mos API’dan foydalanish

Har qanday mos mijoz proksi serverining asosiy URL manzilini Underclass tinglovchisiga o‘rnatib va proksi kalitini bearer token sifatida taqdim etib, proksidan foydalanishi mumkin.

Mavjud modellarni ko‘rsatish

curl http://127.0.0.1:8080/v1/models \
  -H "Authorization: Bearer $UNDERCLASS_PROXY_KEY"

Models endpointi birlashtirilgan limitlarga ega yagona katalogni qaytaradi. Katalog hujjatlashtirilgan Codex model oilalari va Copilot'ning jonli model ro‘yxati bilan to‘ldiriladi. Katalog ma’lumot sifatida saqlangani sababli uni proksi kodini o‘zgartirmasdan UI yoki ma’muriy API orqali tahrirlash mumkin.

Chat completion yuborish

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Authorization: Bearer $UNDERCLASS_PROXY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "Explain sticky session routing."}
    ]
  }'

Proksi POST /v1/responsesni ham qo‘llab-quvvatlaydi. Har ikkala so‘rov yo‘nalishi ham natijalarni tanlangan akkaunt orqali oqim tarzida uzatadi. Oqim boshlanganidan keyin upstream xatosi qisman bajarilgan so‘rovni sezdirmasdan qayta yuborish o‘rniga to‘g‘ridan-to‘g‘ri uzatiladi.

Marshrutlash va qayta tiklanishni tushunish

Yopishqoq sessiya xatti-harakati

So‘rov prompt_cache_key yoki promptCacheKeyni o‘z ichiga olganida, Underclass bu qiymatni bitta obunaga biriktiradi. OpenCode setCacheKey: true bilan sozlanganda o‘z sessiya ID'sini yuborishi mumkin. Biriktirmalar 24 soat davom etadi va proksi qayta ishga tushirilganda ham saqlanadi.

Agar biriktirilgan akkaunt sovish holatiga o‘tsa, Underclass sessiyani shu backend'dagi boshqa akkauntga ustuvor ravishda qayta biriktiradi. Bu yondashuv upstream prompt-kesh afzalliklarini saqlab qolish bilan birga kvota tugaganidan keyin tiklanish imkonini beradi.

Kvota va autentifikatsiyani boshqarish

Tegishli 429 yoki foydalanish limiti javoblarini o‘z ichiga olgan kvota javobi akkauntni sovish holatiga o‘tkazadi. Underclass mavjud bo‘lganda upstream'dagi Retry-After qiymatidan, aks holda sozlangan backend'ga xos sovish muddatidan foydalanadi. Soviyotgan akkauntlar sovish muddati tugagach avtomatik ravishda yana foydalanish uchun yaroqli bo‘ladi.

Upstream 401 javobi uchun Underclass tokenni bir marta yangilaydi va bir marta qayta urinadi. Autentifikatsiya yana muvaffaqiyatsiz bo‘lsa, akkauntga yangi login talab etiladi.

Hovuzning to‘lib qolishi

Agar so‘ralgan model uchun foydalanish mumkin bo‘lgan akkaunt bo‘lmasa, Underclass so‘rovni navbatda ushlab turmaydi. U darhol 429ni qaytaradi va eng erta ma’lum tiklanish vaqtini Retry-After orqali bildiradi.

Proksini sozlash

Ixtiyoriy doimiy konfiguratsiyani ~/.config/underclass/config.toml fayliga joylashtirish mumkin:

bind = "127.0.0.1:8080"
proxy_key = "replace-with-a-client-secret"
ui_token = "replace-with-an-admin-secret"
codex_cooldown_secs = 1800
copilot_cooldown_secs = 1800

Upstream xizmat qayta urinish oralig‘ini taqdim etmasa, har bir backend uchun standart sovish muddati 1 800 soniyani tashkil etadi.

Muhit o‘zgaruvchilari mos konfiguratsiya qiymatlarining ustidan yozadi:

• UNDERCLASS_BIND
• UNDERCLASS_PROXY_KEY
• UNDERCLASS_UI_TOKEN

Soxta xizmatlar bilan testlar uchun UNDERCLASS_CODEX_UPSTREAM va UNDERCLASS_COPILOT_UPSTREAMdan foydalaning. Ularning standart qiymatlari haqiqiy upstream endpointlariga yo‘naltiriladi.

Underclass hisob ma’lumotlari, yopishqoq biriktirmalar, yaratilgan kalitlar va model katalogini ~/.local/share/underclass/pool.dbda saqlaydi. Ushbu ma’lumotlar bazasini o‘chirish mahalliy holatni to‘liq tiklaydi.

Kengaytirilgan ekspluatatsiya maslahatlari

Loglarni tekshirish va so‘rovlarni bog‘lash

Qayta ishlangan har bir javob x-request-idni o‘z ichiga oladi. Loglar tuzilmaviy bo‘lib, --log-format json yoki --log-format pretty orqali JSON yoki chiroyli formatda chiqarilishi mumkin. Filtrlashni boshqarish uchun RUST_LOGdan foydalaning.

preflight Underclass oldiga joylashtirilganda, x-request-id sifatida berilgan yaroqli UUIDv4 javobda, marshrutlash loglarida, qayta urinish loglarida va so‘rovlar tarixida saqlanadi. Yaroqsiz, takroriy, nil, yetishmayotgan yoki v4 bo‘lmagan identifikatorlar almashtiriladi. Identifikator faqat bog‘lash uchun xizmat qiladi; u avtorizatsiya yoki tekshiruvni tasdiqlamaydi.

Model katalogini ehtiyotkorlik bilan boshqarish

Marshrutlash uchun yaroqlilik va OpenCode model bloki saqlangan katalogga asoslanadi. Backend model mosliklarini tekshirish yoki tahrirlash uchun veb UI yoki ma’muriy katalog API'sidan foydalaning. Noma’lum model identifikatorlari Codex'ga o‘zgartirilmasdan uzatiladi, shu sababli yangi joriy qilingan Codex modellari proksi versiyasini chiqarmasdan ishlashi mumkin.

Xizmatni sukut bo‘yicha maxfiy saqlang

Underclass sukut bo‘yicha localhost'ni tinglaydi. Masofaviy kirish ataylab yoqilmagan va himoyalanmagan bo‘lsa, ushbu standart sozlamani saqlang. Proksi kirish tokenlari, yangilash tokenlari, avtorizatsiya sarlavhalari yoki prompt matnlarini loglamaydi, ammo akkaunt yorliqlari loglarda va UI'da ko‘rinadi.

• pool.db yoki yaratilgan *.bak fayllarini commit qilmang.
• UI tokenini mijoz proksi kalitidan alohida himoyalang.
• OpenCode yaratgan auth.json faylini maxfiy saqlang; Underclass uni 0600 ruxsatlari bilan yozadi.
• Xizmatni localhost'dan tashqarida ochishdan oldin xavfsiz tunnel yoki shunga o‘xshash puxta himoyadan foydalaning.

Underclass'ni NixOS'da ishga tushirish

Flake NixOS modulini eksport qiladi. Xizmat konfiguratsiyasi Underclass'ni yoqishi, uni mahalliy manzilga bog‘lashi, sirlarni ish vaqtida muhit faylidan yuklashi va backend sovish muddatlarini belgilashi mumkin:

{
  inputs.underclass.url = "github:ghuntley/underclass";

  outputs = { nixpkgs, underclass, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        underclass.nixosModules.default
        {
          services.underclass = {
            enable = true;
            bindAddress = "127.0.0.1:8080";
            environmentFile = "/run/secrets/underclass.env";
            settings = {
              codex_cooldown_secs = 1800;
              copilot_cooldown_secs = 1800;
            };
          };
        }
      ];
    };
  };
}

Runtime muhiti fayli maxfiy maʼlumotlarni Nix storeʼiga joylashtirmasdan saqlashi mumkin:

UNDERCLASS_PROXY_KEY=sk-underclass-replace-me
UNDERCLASS_UI_TOKEN=replace-me

Modul dinamik foydalanuvchidan foydalanadi, doimiy maʼlumotlarni /var/lib/underclass ichida saqlaydi, sukut bo‘yicha localhost manziliga ulanadi va firewallʼni yopiq qoldiradi. Faqat localhostʼdan tashqarida ulanishni ataylab yoqmoqchi bo‘lganingizda services.underclass.openFirewall parametrini yoqing.

Loyihani ishlab chiqish va testlash

Cargo yordamida loyihani yig‘ing va testlar to‘plamini ishga tushiring:

cargo build
cargo test

Loyiha unit testlar, Hegel property testlari va end-to-end testlarni birlashtiradi. Pool va health yadrosi sinxron ishlaydi hamda kiritilgan soatdan foydalanadi, asinxron xatti-harakatlar esa chekka qatlamlarda saqlanadi. Yangi providerlar provider::Backend traitʼini amalga oshiradi va ilovada ro‘yxatdan o‘tkaziladi.

Arxitektura asoslari bilan tanishish uchun loyihaning arxitektura qarorlari yozuvlarini ko‘rib chiqing. Routing modeli ADR 0010da tushuntirilgan, proxylararo so‘rovlarni korrelyatsiya qilish esa ADR 0012da yoritilgan.

Xulosa

Underclass bir nechta ChatGPT/Codex va GitHub Copilot obunalarini yagona, lokal OpenAI bilan mos xizmatga birlashtiradi. Uning yopishqoq routing, cooldown holatidan avtomatik tiklanish, modelni hisobga olgan akkaunt tanlovi va to‘yinganlikda darhol xato qaytarish xususiyatlari oldindan taxmin qilinadigan mijoz xatti-harakatini saqlagan holda akkauntlarni qo‘lda almashtirish zaruratini kamaytiradi. Serverni ishga tushiring, akkauntlarni veb-interfeys orqali qo‘shing, underclass connect buyrug‘ini bajaring va OpenCode yoki boshqa mos mijozni hosil bo‘lgan endpointʼga yo‘naltiring.