Jenga Kundi Imara la Usajili wa AI kwa Underclass

Underclass Inachofanya

Underclass ni proksi ya ndani inayochanganya usajili nyingi za ChatGPT/Codex na GitHub Copilot kuwa sehemu moja ya kufikia inayooana na OpenAI. Wateja huwasiliana kupitia njia zinazojulikana za /v1/*, huku Underclass ikichagua usajili unaostahili, kufuatilia hali ya mgao, na kupeleka maombi kwenye huduma inayofaa ya upstream.

Hii ni muhimu wakati kila usajili una mgao wake binafsi. Badala ya kubadilisha akaunti mwenyewe kila moja inapofikia kikomo chake, unaweza kuweka akaunti hizo kwenye kundi moja. Akaunti iliyomaliza mgao huingia katika hali ya kusubiri na hurudi kiotomatiki kwenye mzunguko baada ya muda wake wa mgao kuwekwa upya.

Underclass imeundwa kufanya kazi kama mtoa huduma mmoja mwenye rasilimali za kutosha, huku ikihifadhi hali ya akaunti, uhusiano wa kipindi, na ufanisi wa akiba ya vidokezo.

Vipengele Muhimu

• API inayooana na OpenAI: Wateja wanaweza kutumia /v1/responses, /v1/chat/completions, na /v1/models.
• Sehemu nyingi za nyuma: Kundi linaweza kuwa na akaunti za ChatGPT/Codex, akaunti za GitHub Copilot, au zote mbili.
• Vipindi vinavyodumu: Maombi yenye prompt_cache_key au promptCacheKey hubaki yamehusishwa na usajili uleule inapowezekana.
• Muda wa kusubiri wa kiotomatiki: Majibu kuhusu mgao huiondoa akaunti kwenye mzunguko hadi muda wake wa kujaribu tena uishe.
• Majibu ya haraka wakati wa msongamano: Ikiwa kila akaunti inayostahili modeli iko katika hali ya kusubiri, Underclass hurudisha 429 yenye thamani ya mapema zaidi ya Retry-After badala ya kuweka maombi kwenye foleni bila kikomo.
• Uteuzi wa mzigo mdogo unaoendelea: Akaunti zinazostahili za Codex na Copilot hushindana katika kundi moja, zikichujwa kulingana na katalogi ya modeli ya kila sehemu ya nyuma.
• Hali endelevu: Akaunti, katalogi za modeli, vitambulisho vya kuingia, na miunganisho thabiti huhifadhiwa hata baada ya kuwasha upya.
• Kiolesura cha wavuti cha usimamizi: Ongeza na simamia akaunti, hariri katalogi za modeli, na kagua maombi 200 ya hivi karibuni.
• Ufuatiliaji uliopangwa: Kila jibu lina x-request-id, na kumbukumbu hutaja lebo ya akaunti iliyohudumia kila ombi.

Sakinisha na Anzisha Underclass

Chaguo la 1: Endesha kutoka kwenye mradi wa Rust

Kutoka kwenye hifadhi, tengeneza siri tofauti za wateja wa API na kiolesura cha usimamizi, kisha anzisha seva:

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

Kisikiaji chaguomsingi ni http://127.0.0.1:8080, na kiolesura cha wavuti kinapatikana kwenye URL ya mzizi:

http://127.0.0.1:8080/

Hifadhi thamani zote mbili zilizozalishwa katika kidhibiti cha nywila au faili ya siri ya wakati wa kuendesha. Ufunguo wa proksi huidhinisha maombi kwenye /v1/*, huku tokeni ya kiolesura ikiidhinisha vitendo vya usimamizi. Underclass haiandiki thamani hizi kwenye taarifa za uchunguzi.

Chaguo la 2: Endesha kwa Nix

Hifadhi hii pia ni flake ya Nix. Endesha proksi bila kuisakinisha:

nix run github:ghuntley/underclass -- serve

Ili kusakinisha kifurushi kwenye wasifu wako wa Nix, tumia:

nix profile install github:ghuntley/underclass

Kwa ajili ya maendeleo, ingia kwenye shell iliyotolewa na uendeshe majaribio:

nix develop --no-pure-eval
cargo test

Chaguo la --no-pure-eval linahitajika kwa shell ya maendeleo ya devenv. Halihitajiki na nix run au nix profile install.

Ongeza Akaunti kwenye Kundi

1. Fungua http://127.0.0.1:8080/.
2. Bandika thamani iliyosanidiwa kama UNDERCLASS_UI_TOKEN.
3. Chagua Add account.
4. Chagua ChatGPT / Codex au GitHub Copilot.
5. Fungua URL ya uidhinishaji wa kifaa iliyoonyeshwa na uweke msimbo wa kifaa.
6. Subiri uanzishaji ukamilike. Underclass huipa akaunti lebo yenye anwani yake ya barua pepe au jina la mtumiaji.
7. Rudia mchakato kwa kila usajili unaopaswa kushiriki kwenye kundi.

Kiolesura pia kinaweza kuwezesha, kuzima, kuondoa, au kuingia tena kwenye akaunti. Akaunti iliyozimwa hubaki ikiwa imesanidiwa lakini haichaguliwi kwa maombi.

Unganisha OpenCode

Underclass inajumuisha amri ya connect inayoongeza mtoa huduma wa Underclass kwenye OpenCode:

cargo run -- connect

Kwa chaguomsingi, amri husasisha usanidi wa OpenCode wa jumla chini ya ~/.config/opencode/. Huunganisha kizuizi cha mtoa huduma kwenye opencode.json au opencode.jsonc, huandika vitambulisho kwenye auth.json, na huunda nakala rudufu. Operesheni hii inaweza kurudiwa bila madhara, hivyo inaweza kuendeshwa tena kwa usalama.

Anzisha OpenCode kwa modeli iliyowekwa wazi na kundi:

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

Ili kuandika usanidi wa ndani ya mradi badala yake, ongeza --project:

cargo run -- connect --project

Hakiki usanidi uliounganishwa bila kuandika faili lolote:

cargo run -- connect --dry-run

Ondoa muunganisho uliotengenezwa usipohitajika tena:

cargo run -- connect --remove

Amri hii pia inakubali --base-url, --api-key, --model, na --no-default-model unapohitaji kubinafsisha usanidi wa mtoa huduma uliotengenezwa.

Tumia API Inayooana na OpenAI

Mteja yeyote anayooana anaweza kutumia proksi kwa kuweka URL yake ya msingi kuwa kisikiaji cha Underclass na kutoa ufunguo wa proksi kama tokeni ya bearer.

Orodhesha modeli zinazopatikana

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

Endpoint ya models hurejesha katalogi ya muungano yenye vikomo vilivyounganishwa. Katalogi huanzishwa na familia za modeli za Codex zilizoandikwa kwenye nyaraka pamoja na orodha hai ya modeli za Copilot. Kwa kuwa katalogi huhifadhiwa kama data, inaweza kuhaririwa kupitia UI au API ya kiutawala bila kubadilisha msimbo wa proksi.

Tuma ukamilishaji wa mazungumzo

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 pia inasaidia POST /v1/responses. Njia zote mbili za ombi hutiririsha matokeo kupitia akaunti iliyochaguliwa. Baada ya utiririshaji kuanza, hitilafu ya upstream hupitishwa badala ya kutuma tena kwa siri ombi lililokamilishwa kwa sehemu.

Elewa Uelekezaji na Kushindwa kwa Huduma

Tabia ya vipindi vinavyoshikiliwa

Ombi linapojumuisha prompt_cache_key au promptCacheKey, Underclass hufunga thamani hiyo kwenye usajili mmoja. OpenCode inaweza kutuma kitambulisho cha kipindi chake inapowekwa kwa setCacheKey: true. Vifungo hudumu kwa saa 24 na huendelea kuwepo hata proksi inapowashwa upya.

Akaunti iliyopangiwa inapoanza kupoa, Underclass hupendelea kuunganisha tena kipindi hicho na akaunti nyingine kwenye backend ileile. Muundo huu husaidia kuhifadhi manufaa ya akiba ya prompt ya upstream huku ukiwezesha kupona kutokana na kwisha kwa kiwango.

Udhibiti wa kiwango na uthibitishaji

Jibu la kiwango, likiwemo majibu husika ya 429 au yanayoonyesha kikomo cha matumizi, huiweka akaunti katika hali ya kupoa. Underclass hutumia thamani ya upstream ya Retry-After inapopatikana, au muda wa kupoa uliowekwa kwa backend husika vinginevyo. Akaunti zinazopoa huwa zinastahiki tena kiotomatiki muda wa kupoa unapoisha.

Kwa 401 ya upstream, Underclass hufanya uonyeshaji upya wa tokeni mara moja na kujaribu tena mara moja. Uthibitishaji ukiendelea kushindwa, akaunti inahitaji kuingia upya.

Kujaza kwa hifadhi ya akaunti

Hakuna akaunti inayostahiki kwa modeli iliyoombwa, Underclass haiweki ombi kwenye foleni. Hurejesha 429 mara moja na kuripoti muda wa mwanzo wa uwekaji upya unaojulikana kupitia Retry-After.

Sanidi Proksi

Usanidi wa hiari unaodumu unaweza kuwekwa katika ~/.config/underclass/config.toml:

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

Muda chaguomsingi wa kupoa kwa kila backend ni sekunde 1,800 wakati huduma ya upstream haitoi muda wa kujaribu tena.

Vigezo vya mazingira hubatilisha thamani za usanidi zinazolingana:

• UNDERCLASS_BIND
• UNDERCLASS_PROXY_KEY
• UNDERCLASS_UI_TOKEN

Kwa majaribio dhidi ya huduma za kejeli, tumia UNDERCLASS_CODEX_UPSTREAM na UNDERCLASS_COPILOT_UPSTREAM. Chaguo-msingi zake zinaelekeza kwenye endpoint halisi za upstream.

Underclass huhifadhi vitambulisho vya kuingia, vifungo vinavyoshikiliwa, funguo zilizotengenezwa, na katalogi ya modeli katika ~/.local/share/underclass/pool.db. Kufuta hifadhidata hiyo huweka upya kabisa hali ya ndani.

Vidokezo vya Juu vya Uendeshaji

Kagua kumbukumbu na unganisha maombi

Kila jibu linaloshughulikiwa linajumuisha x-request-id. Kumbukumbu zimepangwa na zinaweza kutumia towe la JSON au linalosomeka kupitia --log-format json au --log-format pretty. Tumia RUST_LOG kudhibiti uchujaji.

preflight ikiwekwa mbele ya Underclass, UUIDv4 halali iliyotolewa kama x-request-id huhifadhiwa katika jibu, kumbukumbu za uelekezaji, kumbukumbu za majaribio tena, na historia ya maombi. Vitambulisho visivyo halali, vinavyojirudia, tupu, vilivyokosekana, au visivyo vya v4 hubadilishwa. Kitambulisho hiki ni cha kuunganisha tu; hakithibitishi uidhinishaji au ukaguzi.

Dhibiti katalogi ya modeli kwa uangalifu

Ustahiki wa uelekezaji na sehemu ya modeli ya OpenCode hufuata katalogi iliyohifadhiwa. Tumia UI ya wavuti au API ya kiutawala ya katalogi kukagua au kuhariri upangaji wa modeli za backend. Vitambulisho vya modeli visivyojulikana hupitishwa kwa Codex, hivyo kuwezesha modeli mpya za Codex kufanya kazi bila kutolewa kwa toleo jipya la proksi.

Weka huduma kuwa ya faragha kwa chaguo-msingi

Underclass husikiliza localhost kwa chaguo-msingi. Dumisha chaguo-msingi hiyo isipokuwa ufikiaji wa mbali unakusudiwa na umelindwa. Proksi haihifadhi tokeni za ufikiaji, tokeni za kuonyesha upya, vichwa vya uidhinishaji, au miili ya prompt kwenye kumbukumbu, lakini lebo za akaunti huonekana kwenye kumbukumbu na UI.

• Usiweke pool.db au faili za *.bak zilizotengenezwa kwenye mfumo wa kudhibiti matoleo.
• Linda tokeni ya UI kando na ufunguo wa proksi wa mteja.
• Weka auth.json iliyotengenezwa na OpenCode kuwa ya faragha; Underclass huiandika kwa ruhusa za 0600.
• Tumia handaki salama au ulinzi mwingine uliopangwa kwa makusudi kabla ya kuufichua huduma nje ya localhost.

Endesha Underclass kwenye NixOS

Flake hutoa moduli ya NixOS. Usanidi wa huduma unaweza kuwezesha Underclass, kuifunga ndani ya eneo lako, kupakia siri kutoka faili ya mazingira ya wakati wa utekelezaji, na kuweka muda wa kupoa wa backend:

{
  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;
            };
          };
        }
      ];
    };
  };
}

Faili ya mazingira ya wakati wa utekelezaji inaweza kuhifadhi siri bila kuziweka kwenye hifadhi ya Nix:

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

Moduli hutumia mtumiaji wa nguvu, huhifadhi data endelevu katika /var/lib/underclass, hufungamana na localhost kwa chaguo-msingi, na huacha ngome ikiwa imefungwa. Washa services.underclass.openFirewall tu unapokusudia kwa makusudi kufungamana nje ya localhost.

Kuendeleza na Kujaribu Mradi

Jenga na endesha mkusanyiko wa majaribio kwa Cargo:

cargo build
cargo test

Mradi unajumuisha majaribio ya vitengo, majaribio ya sifa ya Hegel, na majaribio ya mwisho hadi mwisho. Msingi wa pool na afya ni wa kusawazisha na hutumia saa iliyoingizwa, huku tabia ya asincroni ikihifadhiwa kwenye kingo. Watoa huduma wapya hutekeleza sifa ya provider::Backend na kujisajili kwenye programu.

Kwa maelezo ya usanifu, kagua rekodi za maamuzi ya usanifu za mradi. Muundo wa uelekezaji umefafanuliwa katika ADR 0010, huku uhusishaji wa maombi kati ya proksi ukishughulikiwa na ADR 0012.

Hitimisho

Underclass hubadilisha usajili kadhaa wa ChatGPT/Codex na GitHub Copilot kuwa huduma moja ya ndani inayooana na OpenAI. Uelekezaji wake unaodumu, urejeshaji wa kiotomatiki baada ya kipindi cha kusubiri, uteuzi wa akaunti unaotambua modeli, na tabia ya kushindwa haraka inapofikia ukomo hupunguza kubadilisha akaunti kwa mikono huku ikihifadhi tabia inayotabirika ya mteja. Anzisha seva, sajili akaunti kupitia kiolesura cha wavuti, endesha underclass connect, kisha elekeza OpenCode au mteja mwingine anayeoana kwenye endpoint inayotokana.