Yakha Iqoqo Eliqinile Lokubhaliselwe Kwe-AI nge-Underclass

Lokho Okwenziwa yi-Underclass

I-Underclass iyi-proxy yasendaweni ehlanganisa okubhaliselwe okuningi kwe-ChatGPT/Codex ne-GitHub Copilot ibe yindawo eyodwa ehambisana ne-OpenAI. Amaklayenti axhumana nemizila ejwayelekile ethi /v1/*, kanti i-Underclass ikhetha okubhaliselwe okufanelekayo, ilandele impilo yesabelo, bese idlulisela izicelo kusevisi efanele yangaphandle.

Lokhu kuyasiza lapho okubhaliselwe ngakunye kunesabelo sako. Esikhundleni sokushintsha ama-akhawunti ngesandla njalo lapho eyodwa ifinyelela emkhawulweni wayo, ungafaka ama-akhawunti echibini elilodwa. I-akhawunti ephelelwe yisabelo ingena esimweni sokupholisa bese ibuyela ngokuzenzakalelayo ekushintshanisweni lapho isikhathi sayo sesabelo sivuselelwa.

I-Underclass ihloselwe ukuziphatha njengomhlinzeki oyedwa onamandla, kuyilapho igcina impilo yama-akhawunti, ukunamathela kweseshini, kanye nokusebenza kahle kwe-prompt cache.

Izici Eziyinhloko

• API ehambisana ne-OpenAI: Amaklayenti angasebenzisa /v1/responses, /v1/chat/completions, kanye ne-/v1/models.
• Ama-backend amaningi: Ichibi lingaba nama-akhawunti e-ChatGPT/Codex, ama-akhawunti e-GitHub Copilot, noma kokubili.
• Amaseshini anamathelayo: Izicelo ezine-prompt_cache_key noma promptCacheKey zihlala zabelwe okubhaliselwe okufanayo uma kungenzeka.
• Ukupholisa okuzenzakalelayo: Izimpendulo eziphathelene nesabelo zisusa i-akhawunti ekushintshanisweni kuze kuphele isikhathi sayo sokuzama futhi.
• Izimpendulo ezisheshayo zokugcwala: Uma wonke ama-akhawunti afanele imodeli ethile epholisa, i-Underclass ibuyisa 429 enenani lokuqala elitholakalayo le-Retry-After esikhundleni sokulinda unomphela emgqeni.
• Ukukhetha okusekelwe emisebenzini esaqhubeka: Ama-akhawunti e-Codex ne-Copilot afanelekayo ancintisana echibini eliyisicaba, ehlungwa yikhathalogi yamamodeli ye-backend ngayinye.
• Isimo esigcinwayo: Ama-akhawunti, amakhathalogi amamodeli, iziqinisekiso, nokubophana okunamathelayo kuhlala kukhona ngemva kokuqalisa kabusha.
• Isixhumi esibonakalayo sewebhu sokuphatha: Engeza futhi uphathe ama-akhawunti, hlela amakhathalogi amamodeli, futhi uhlole izicelo zakamuva ezingu-200.
• Ukuqaphela okuhlelekile: Yonke impendulo ine-x-request-id, futhi amalogi akhomba ilebula ye-akhawunti esebenze isicelo ngasinye.

Faka futhi Qalisa i-Underclass

Inketho 1: Qalisa kuphrojekthi ye-Rust

Kusuka ku-repository, khiqiza izimfihlo ezihlukene zamaklayenti e-API nesixhumi esibonakalayo sokuphatha, bese uqala iseva:

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

Isilaleli esizenzakalelayo sithi http://127.0.0.1:8080, kanti isixhumi esibonakalayo sewebhu sitholakala ku-URL eyisisekelo:

http://127.0.0.1:8080/

Gcina womabili amanani akhiqiziwe kumphathi wamaphasiwedi noma efayeleni lezimfihlo zesikhathi sokusebenza. Ukhiye we-proxy ugunyaza izicelo eziya ku-/v1/*, kanti ithokheni ye-UI igunyaza izenzo zokuphatha. I-Underclass ayiwabhali la manani ekuhlolweni kwezinkinga.

Inketho 2: Qalisa nge-Nix

I-repository nayo iyi-Nix flake. Qalisa i-proxy ngaphandle kokuyifaka:

nix run github:ghuntley/underclass -- serve

Ukufaka iphakheji kuphrofayela yakho ye-Nix, sebenzisa:

nix profile install github:ghuntley/underclass

Ekuthuthukiseni, ngena egobolondweni elinikeziwe bese uqalisa izivivinyo:

nix develop --no-pure-eval
cargo test

Inketho ethi --no-pure-eval iyadingeka egobolondweni lokuthuthukisa le-devenv. Ayidingeki ku-nix run noma ku-nix profile install.

Engeza Ama-akhawunti Echibini

1. Vula http://127.0.0.1:8080/.
2. Namathisela inani elilungiselelwe njenge-UNDERCLASS_UI_TOKEN.
3. Khetha Add account.
4. Khetha ChatGPT / Codex noma GitHub Copilot.
5. Vula i-URL yokugunyazwa kwedivayisi ebonisiwe bese ufaka ikhodi yedivayisi.
6. Lindela ukuthi ukwamukelwa kuqedwe. I-Underclass ilebula i-akhawunti ngekheli layo le-imeyili noma igama lomsebenzisi.
7. Phinda inqubo kukho konke okubhaliselwe okufanele kube yingxenye yechibi.

I-UI ingaphinda inike amandla, ikhubaze, isuse, noma iphinde ingene kuma-akhawunti. I-akhawunti ekhubaziwe ihlala ilungiselelwe kodwa ayikhethwa ezicelweni.

Xhuma i-OpenCode

I-Underclass ihlanganisa umyalo othi connect owengeza umhlinzeki we-Underclass ku-OpenCode:

cargo run -- connect

Ngokuzenzakalelayo, umyalo ubuyekeza ukulungiselelwa komhlaba wonke kwe-OpenCode ngaphansi kwe-~/.config/opencode/. Uhlanganisa ibhulokhi yomhlinzeki ku-opencode.json noma ku-opencode.jsonc, ubhala iziqinisekiso ku-auth.json, futhi udale izipele. Umsebenzi awuphindi imiphumela, ngakho ungaphinda uwuqalise ngokuphepha.

Qalisa i-OpenCode ngemodeli evezwe yichibi:

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

Ukuze ubhale ukulungiselelwa kwendawo yephrojekthi, engeza --project:

cargo run -- connect --project

Buka ukulungiselelwa okuhlanganisiwe ngaphandle kokubhala amafayela:

cargo run -- connect --dry-run

Susa ukuhlanganiswa okukhiqiziwe lapho kungasadingeki:

cargo run -- connect --remove

Umyalo futhi wamukela --base-url, --api-key, --model, kanye no---no-default-model lapho udinga ukwenza ngokwezifiso ukulungiselelwa komhlinzeki okukhiqiziwe.

Sebenzisa i-API Ehambisana ne-OpenAI

Noma yiliphi iklayenti elihambisanayo lingasebenzisa i-proxy ngokusetha i-URL eyisisekelo ibe isilaleli se-Underclass futhi linikeze ukhiye we-proxy njengethokheni ye-bearer.

Faka ohlwini amamodeli atholakalayo

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

I-endpoint yamamodeli ibuyisa ikhathalogi ehlanganisa amamodeli enemikhawulo ehlanganisiwe. Ikhathalogi iqaliswa ngemindeni yamamodeli ye-Codex ebhalwe phansi kanye nohlu lwamamodeli olusebenzayo lwe-Copilot. Njengoba ikhathalogi igcinwa njengedatha, ingahlelwa nge-UI noma nge-API yokuphatha ngaphandle kokushintsha ikhodi ye-proxy.

Thumela ukuqedwa kwengxoxo

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."}
    ]
  }'

I-proxy iphinde isekele POST /v1/responses. Zombili izindlela zezicelo zisakaza imiphumela nge-akhawunti ekhethiwe. Uma ukusakazwa sekuqalile, iphutha elivela phezulu liyadluliselwa kunokuba isicelo esiqedwe kancane sithunyelwe kabusha buthule.

Qonda Ukuqondisa Nokushintsha Lapho Kwehluleka

Ukuziphatha kweseshini enamathelayo

Uma isicelo siqukethe prompt_cache_key noma promptCacheKey, i-Underclass ibopha lelo nani kokubhaliselwe okukodwa. I-OpenCode ingathumela i-ID yeseshini yayo uma ilungiselelwe nge-setCacheKey: true. Lezi zibopho zihlala amahora angu-24 futhi ziyaqhubeka noma i-proxy iqalwe kabusha.

Uma i-akhawunti eyabelwe iqala ukupholiswa, i-Underclass ikhetha ukubopha kabusha iseshini kwenye i-akhawunti ekwi-backend efanayo. Lo mklamo usiza ukugcina izinzuzo ze-upstream prompt-cache ngenkathi uvumela ukubuyiselwa esimweni lapho isabelo sesisetshenzisiwe siphelile.

Ukuphathwa kwesabelo nokuqinisekiswa

Impendulo yesabelo, okuhlanganisa izimpendulo ezifanele ze-429 noma zemikhawulo yokusetshenziswa, ifaka i-akhawunti esimweni sokupholisa. I-Underclass isebenzisa inani le-upstream Retry-After uma litholakala, noma isikhawu sokupholisa esiqondene ne-backend esilungiselelwe uma lingatholakali. Ama-akhawunti apholayo aphinde afaneleke ngokuzenzakalelayo lapho ukupholisa kuphela.

Uma kuvela i-upstream 401, i-Underclass ivuselela ithokheni kanye bese izama futhi kanye. Uma ukuqinisekiswa kusahluleka, i-akhawunti idinga ukungena ngemvume okusha.

Ukugcwala kwe-pool

Uma ingekho i-akhawunti efanele etholakalayo yemodeli eceliwe, i-Underclass ayisigcini isicelo kulayini. Ibuyisa 429 ngokushesha futhi ibike isikhathi sokuqala esaziwayo sokusetha kabusha nge-Retry-After.

Lungiselela I-proxy

Ukulungiselela okuqhubekayo okungakhethwa kungafakwa ku-~/.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

Isikhathi esizenzakalelayo sokupholisa se-backend ngayinye yimizuzwana engu-1,800 lapho isevisi ye-upstream inganikezi isikhawu sokuzama futhi.

Okuguquguqukayo kwemvelo kuthatha indawo yamanani ahambisanayo okucushwa:

• UNDERCLASS_BIND
• UNDERCLASS_PROXY_KEY
• UNDERCLASS_UI_TOKEN

Ukuhlola ngamasevisi mbumbulu, sebenzisa UNDERCLASS_CODEX_UPSTREAM kanye UNDERCLASS_COPILOT_UPSTREAM. Okuzenzakalelayo kwawo kukhomba kuma-endpoint wangempela e-upstream.

I-Underclass igcina imininingwane yokuqinisekisa, izibopho ezinamathelayo, okhiye abakhiqiziwe, kanye nekhathalogi yamamodeli ku-~/.local/share/underclass/pool.db. Ukususa leyo database kusetha kabusha ngokuphelele isimo sendawo.

Amathiphu Okusebenza Athuthukile

Hlola amalogi bese uhlanganisa izicelo

Yonke impendulo ephathwayo ifaka i-x-request-id. Amalogi ahlelekile futhi angasebenzisa okukhiphayo kwe-JSON noma okuhlelekile nge---log-format json noma --log-format pretty. Sebenzisa RUST_LOG ukulawula ukuhlunga.

Uma i-preflight ibekwa phambi kwe-Underclass, i-UUIDv4 evumelekile enikezwe njenge-x-request-id igcinwa empendulweni, kumalogi okuqondisa, kumalogi okuzama futhi, nasemlandweni wezicelo. Izihlonzi ezingavumelekile, eziphindwe kabili, ezingenalutho, ezingekho, noma ezingezona eze-v4 ziyashintshwa. Lesi sihlonzi sisekela ukuhlanganisa kuphela; asifakazeli ukugunyazwa noma ukuhlolwa.

Phatha ikhathalogi yamamodeli ngokucophelela

Ukufaneleka kokuqondisa kanye nebhlokhi yamamodeli ye-OpenCode kulandela ikhathalogi egciniwe. Sebenzisa i-web UI noma i-API yokuphatha ikhathalogi ukuze uhlole noma uhlele ukuhlanganiswa kwamamodeli e-backend. Izihlonzi zamamodeli ezingaziwa zidluliselwa ku-Codex, okwenza amamodeli e-Codex asanda kwethulwa asebenze ngaphandle kokukhishwa kwe-proxy.

Gcina isevisi iyimfihlo ngokuzenzakalelayo

I-Underclass ilalela ku-localhost ngokuzenzakalelayo. Gcina lokho okuzenzakalelayo ngaphandle uma ukufinyelela kude kuhlosiwe futhi kuvikelwe. I-proxy ayiwafaki kumalogi amathokheni okufinyelela, amathokheni okuvuselela, izihloko zokugunyazwa, noma imizimba yezicelo, kodwa amalebula ama-akhawunti ayabonakala kumalogi naku-UI.

• Ungazibophezeli i-pool.db noma amafayela e-*.bak akhiqiziwe.
• Vikela ithokheni ye-UI ngokwehlukana nokhiye we-client proxy.
• Gcina i-auth.json ekhiqizwe yi-OpenCode iyimfihlo; i-Underclass iyibhala ngezimvume ze-0600.
• Sebenzisa i-tunnel evikelekile noma ukuvikelwa okufanayo okuhleliwe ngaphambi kokudalula isevisi ngaphandle kwe-localhost.

Qalisa i-Underclass ku-NixOS

I-flake ithumela imojuli ye-NixOS. Ukucushwa kwesevisi kungavumela i-Underclass, iyibophe endaweni, ilayishe izimfihlo efayeleni lemvelo lesikhathi sokusebenza, futhi isethe izikhathi zokupholisa zama-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;
            };
          };
        }
      ];
    };
  };
}

Ifayela lendawo yokusebenza lingagcina izimfihlo ngaphandle kokuzibeka ku-Nix store:

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

Imojuli isebenzisa umsebenzisi oguqukayo, igcina idatha ephikelelayo ku-/var/lib/underclass, ibophela ku-localhost ngokuzenzakalelayo, futhi ishiya i-firewall ivaliwe. Vumela services.underclass.openFirewall kuphela uma uhlose ngamabomu ukubophela ngaphandle kwe-localhost.

Thuthukisa Futhi Uhlole Iphrojekthi

Yakha futhi usebenzise iqoqo lezivivinyo nge-Cargo:

cargo build
cargo test

Iphrojekthi ihlanganisa izivivinyo zamayunithi, izivivinyo zezakhiwo ze-Hegel, kanye nezivivinyo zokuphela-kuya-ekupheleni. Ingqikithi ye-pool ne-health iyavumelaniswa futhi isebenzisa iwashi elifakiwe, kuyilapho ukuziphatha okuvumelanayo kugcinwa emaphethelweni. Abahlinzeki abasha basebenzisa i-trait provider::Backend futhi babhaliswe nohlelo lokusebenza.

Ukuze uthole isizinda sokwakheka kohlelo, buyekeza amarekhodi ezinqumo zokwakha ephrojekthi. Imodeli yokuqondisa ichazwe ku-ADR 0010, kanti ukuhlobaniswa kwezicelo phakathi kwama-proxy kuhlanganiswe ku-ADR 0012.

Isiphetho

Underclass iguqula okubhaliselwe okuningi kwe-ChatGPT/Codex ne-GitHub Copilot kube isevisi eyodwa yasendaweni ehambisana ne-OpenAI. Ukuqondisa okunamathelayo, ukubuyiselwa okuzenzakalelayo ngemva kwe-cooldown, ukukhethwa kwama-akhawunti okwazi imodeli, kanye nokuziphatha kokugcwala okwehluleka ngokushesha kunciphisa ukushintsha ama-akhawunti ngesandla, kuyilapho kugcinwa ukuziphatha okubikelekayo kweklayenti. Qalisa iseva, faka ama-akhawunti nge-web UI, sebenzisa underclass connect, bese ukhomba i-OpenCode noma elinye iklayenti elihambisanayo endaweni yokugcina etholakele.