Underclass کے ساتھ مضبوط AI سبسکرپشن پول بنائیں

Underclass کیا کرتا ہے

Underclass ایک مقامی پراکسی ہے جو متعدد ChatGPT/Codex اور GitHub Copilot سبسکرپشنز کو ایک واحد OpenAI-compatible endpoint میں یکجا کرتا ہے۔ کلائنٹس مانوس /v1/* routes کے ذریعے رابطہ کرتے ہیں، جبکہ Underclass ایک اہل سبسکرپشن منتخب کرتا ہے، quota کی صحت کو ٹریک کرتا ہے، اور درخواستیں مناسب upstream service کو بھیجتا ہے۔

یہ اس وقت مفید ہے جب ہر سبسکرپشن کا الگ quota ہو۔ ایک اکاؤنٹ کی حد پوری ہونے پر اکاؤنٹس کو دستی طور پر تبدیل کرنے کے بجائے، آپ اکاؤنٹس کو ایک مشترکہ pool میں رکھ سکتے ہیں۔ quota ختم ہونے والا اکاؤنٹ cooling state میں چلا جاتا ہے اور اس کی quota window reset ہونے کے بعد خودکار طور پر دوبارہ rotation میں شامل ہو جاتا ہے۔

Underclass کا مقصد ایک اچھی طرح provisioned provider کی طرح کام کرنا ہے، جبکہ account health، session affinity، اور prompt-cache effectiveness برقرار رہیں۔

اہم خصوصیات

• OpenAI-compatible API: کلائنٹس /v1/responses، /v1/chat/completions، اور /v1/models استعمال کر سکتے ہیں۔
• متعدد backends: pool میں ChatGPT/Codex اکاؤنٹس، GitHub Copilot اکاؤنٹس، یا دونوں شامل ہو سکتے ہیں۔
• Sticky sessions: prompt_cache_key یا promptCacheKey والی درخواستیں، ممکن ہونے پر، اسی سبسکرپشن کے ساتھ منسلک رہتی ہیں۔
• خودکار cooldowns: quota responses کسی اکاؤنٹ کو rotation سے اس وقت تک باہر کر دیتے ہیں جب تک اس کی retry window ختم نہ ہو جائے۔
• فوری saturation responses: اگر کسی model کے لیے اہل ہر اکاؤنٹ cooling میں ہو، تو Underclass غیر معینہ مدت تک queue کرنے کے بجائے سب سے جلد دستیاب Retry-After value کے ساتھ 429 واپس کرتا ہے۔
• Least-in-flight selection: اہل Codex اور Copilot اکاؤنٹس ایک flat pool میں مقابلہ کرتے ہیں، جسے ہر backend کے model catalog کے مطابق filter کیا جاتا ہے۔
• Persistent state: اکاؤنٹس، model catalogs، credentials، اور sticky bindings restart کے بعد بھی برقرار رہتے ہیں۔
• Administrative web UI: اکاؤنٹس شامل اور منظم کریں، model catalogs میں ترمیم کریں، اور تازہ ترین 200 requests کا جائزہ لیں۔
• Structured observability: ہر response میں ایک x-request-id ہوتا ہے، اور logs اس اکاؤنٹ کا label بتاتے ہیں جس نے ہر request فراہم کی۔

Underclass انسٹال اور شروع کریں

آپشن 1: Rust project سے چلائیں

repository سے API clients اور administrative UI کے لیے الگ secrets بنائیں، پھر server شروع کریں:

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

default listener http://127.0.0.1:8080 ہے، اور web interface root URL پر دستیاب ہے:

http://127.0.0.1:8080/

دونوں generated values کو password manager یا runtime secret file میں محفوظ کریں۔ proxy key /v1/* کو requests کی اجازت دیتی ہے، جبکہ UI token administrative actions کی اجازت دیتا ہے۔ Underclass ان values کو diagnostics میں نہیں لکھتا۔

آپشن 2: Nix کے ساتھ چلائیں

repository ایک Nix flake بھی ہے۔ اسے انسٹال کیے بغیر proxy چلائیں:

nix run github:ghuntley/underclass -- serve

package کو اپنے Nix profile میں انسٹال کرنے کے لیے استعمال کریں:

nix profile install github:ghuntley/underclass

development کے لیے فراہم کردہ shell میں داخل ہوں اور tests چلائیں:

nix develop --no-pure-eval
cargo test

devenv development shell کے لیے --no-pure-eval option ضروری ہے۔ nix run یا nix profile install کے لیے یہ ضروری نہیں ہے۔

Pool میں اکاؤنٹس شامل کریں

1. http://127.0.0.1:8080/ کھولیں۔
2. UNDERCLASS_UI_TOKEN کے طور پر configured value paste کریں۔
3. Add account منتخب کریں۔
4. ChatGPT / Codex یا GitHub Copilot میں سے کسی ایک کا انتخاب کریں۔
5. دکھایا گیا device authorization URL کھولیں اور device code درج کریں۔
6. onboarding مکمل ہونے کا انتظار کریں۔ Underclass اکاؤنٹ کو اس کے email address یا username سے label کرتا ہے۔
7. ہر اس subscription کے لیے یہ عمل دہرائیں جسے pool میں شامل کرنا ہے۔

UI کے ذریعے اکاؤنٹس کو enable، disable، remove، یا دوبارہ login بھی کیا جا سکتا ہے۔ disabled اکاؤنٹ configured رہتا ہے، مگر requests کے لیے منتخب نہیں کیا جاتا۔

OpenCode سے مربوط کریں

Underclass میں ایک connect command شامل ہے جو OpenCode میں Underclass provider شامل کرتی ہے:

cargo run -- connect

default طور پر یہ command global OpenCode configuration کو ~/.config/opencode/ کے تحت update کرتی ہے۔ یہ provider block کو opencode.json یا opencode.jsonc میں merge کرتی ہے، credentials کو auth.json میں لکھتی ہے، اور backups بناتی ہے۔ یہ operation idempotent ہے، اس لیے اسے دوبارہ محفوظ طریقے سے چلایا جا سکتا ہے۔

pool میں exposed model کے ساتھ OpenCode شروع کریں:

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

project-local configuration لکھنے کے لیے --project شامل کریں:

cargo run -- connect --project

کسی file کو لکھے بغیر merged configuration کا preview دیکھیں:

cargo run -- connect --dry-run

جب generated integration کی ضرورت نہ رہے تو اسے remove کریں:

cargo run -- connect --remove

جب آپ کو generated provider configuration کو customize کرنا ہو تو command --base-url، --api-key، --model، اور --no-default-model بھی قبول کرتی ہے۔

OpenAI-Compatible API استعمال کریں

کوئی بھی compatible client، base URL کو Underclass listener پر set کرکے اور proxy key کو bearer token کے طور پر فراہم کرکے proxy استعمال کر سکتا ہے۔

دستیاب models کی فہرست

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

ماڈلز اینڈ پوائنٹ انضمامی کیٹلاگ واپس کرتا ہے جس میں حدود کو یکجا کیا گیا ہے۔ کیٹلاگ میں دستاویزی Codex ماڈل فیملیز اور Copilot کی براہِ راست ماڈل فہرست شامل کی گئی ہے۔ چونکہ کیٹلاگ ڈیٹا کے طور پر محفوظ ہوتا ہے، اس لیے پراکسی کوڈ تبدیل کیے بغیر اسے UI یا انتظامی API کے ذریعے ترمیم کیا جا سکتا ہے۔

چیٹ تکمیل بھیجیں

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

پراکسی POST /v1/responses کو بھی سپورٹ کرتی ہے۔ دونوں ریکویسٹ روٹس منتخب اکاؤنٹ کے ذریعے نتائج کو اسٹریم کرتے ہیں۔ اسٹریم شروع ہونے کے بعد، اپ اسٹریم کی خرابی کو آگے منتقل کیا جاتا ہے، جزوی طور پر مکمل ہونے والی ریکویسٹ کو خاموشی سے دوبارہ نہیں بھیجا جاتا۔

روٹنگ اور فیل اوور کو سمجھیں

اسٹکی سیشن کا رویہ

جب کسی ریکویسٹ میں prompt_cache_key یا promptCacheKey شامل ہو، تو Underclass اس قدر کو ایک سبسکرپشن کے ساتھ منسلک کر دیتا ہے۔ OpenCode، setCacheKey: true کے ساتھ کنفیگر ہونے پر، اپنی سیشن ID بھیج سکتا ہے۔ یہ منسلکات 24 گھنٹے تک برقرار رہتے ہیں اور پراکسی کے دوبارہ شروع ہونے کے بعد بھی قائم رہتے ہیں۔

اگر مقرر کردہ اکاؤنٹ کولنگ شروع کر دے، تو Underclass ترجیحاً اسی بیک اینڈ کے کسی دوسرے اکاؤنٹ کے ساتھ سیشن کو دوبارہ منسلک کرتا ہے۔ یہ ڈیزائن اپ اسٹریم پرامپٹ کیش کے فوائد برقرار رکھنے میں مدد دیتا ہے اور کوٹا ختم ہونے کی صورت میں بحالی کی اجازت بھی دیتا ہے۔

کوٹا اور توثیق کا انتظام

کوٹا رسپانس، جس میں متعلقہ 429 یا استعمال کی حد والے رسپانس شامل ہیں، اکاؤنٹ کو کولنگ حالت میں منتقل کر دیتا ہے۔ Underclass دستیاب ہونے پر اپ اسٹریم کی Retry-After قدر استعمال کرتا ہے، ورنہ کنفیگر کردہ بیک اینڈ کے لیے مخصوص کول ڈاؤن استعمال کرتا ہے۔ کولنگ میں موجود اکاؤنٹس کول ڈاؤن ختم ہونے پر خود بخود دوبارہ اہل ہو جاتے ہیں۔

اپ اسٹریم کی جانب سے 401 ملنے پر Underclass ایک بار ٹوکن ریفریش کرتا ہے اور ایک بار دوبارہ کوشش کرتا ہے۔ اگر توثیق پھر بھی ناکام ہو، تو اکاؤنٹ کے لیے نیا لاگ اِن درکار ہوتا ہے۔

پول کا مکمل استعمال

اگر مطلوبہ ماڈل کے لیے کوئی اہل اکاؤنٹ دستیاب نہ ہو، تو Underclass ریکویسٹ کو قطار میں نہیں روکتا۔ یہ فوراً 429 واپس کرتا ہے اور Retry-After کے ذریعے معلوم شدہ اولین ری سیٹ وقت بتاتا ہے۔

پراکسی کو کنفیگر کریں

اختیاری مستقل کنفیگریشن ~/.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

جب اپ اسٹریم سروس ریٹری وقفہ فراہم نہ کرے تو ہر بیک اینڈ کے لیے ڈیفالٹ کول ڈاؤن 1,800 سیکنڈ ہوتا ہے۔

ماحولیاتی متغیرات متعلقہ کنفیگریشن اقدار کو اوور رائٹ کر دیتے ہیں:

• UNDERCLASS_BIND
• UNDERCLASS_PROXY_KEY
• UNDERCLASS_UI_TOKEN

فرضی سروسز کے خلاف ٹیسٹ کے لیے UNDERCLASS_CODEX_UPSTREAM اور UNDERCLASS_COPILOT_UPSTREAM استعمال کریں۔ ان کی ڈیفالٹ اقدار حقیقی اپ اسٹریم اینڈ پوائنٹس کی طرف اشارہ کرتی ہیں۔

Underclass اسناد، اسٹکی منسلکات، تیار کردہ کیز، اور ماڈل کیٹلاگ کو ~/.local/share/underclass/pool.db میں محفوظ کرتا ہے۔ اس ڈیٹا بیس کو حذف کرنے سے مقامی حالت مکمل طور پر ری سیٹ ہو جاتی ہے۔

اعلیٰ سطحی عملی تجاویز

لاگز کا معائنہ کریں اور ریکویسٹ کو مربوط کریں

ہر ہینڈل کیے گئے رسپانس میں x-request-id شامل ہوتا ہے۔ لاگز ساخت یافتہ ہوتے ہیں اور --log-format json یا --log-format pretty کے ذریعے JSON یا خوب صورت فارمیٹ میں دکھائے جا سکتے ہیں۔ فلٹرنگ کو کنٹرول کرنے کے لیے RUST_LOG استعمال کریں۔

جب preflight کو Underclass کے سامنے رکھا جائے، تو x-request-id کے طور پر فراہم کردہ درست UUIDv4 رسپانس، روٹنگ لاگز، ریٹری لاگز، اور ریکویسٹ ہسٹری میں برقرار رہتا ہے۔ غلط، مکرر، nil، غائب، یا غیر v4 شناخت کار تبدیل کر دیے جاتے ہیں۔ یہ شناخت کار صرف ربط کے لیے ہے؛ یہ اجازت یا معائنے کا ثبوت نہیں دیتا۔

ماڈل کیٹلاگ احتیاط سے منظم کریں

روٹنگ کی اہلیت اور OpenCode ماڈل بلاک محفوظ شدہ کیٹلاگ کی پیروی کرتے ہیں۔ بیک اینڈ ماڈل میپنگز کا معائنہ یا ترمیم کرنے کے لیے ویب UI یا انتظامی کیٹلاگ API استعمال کریں۔ نامعلوم ماڈل شناخت کار Codex کو بھیج دیے جاتے ہیں، جس سے نئے متعارف ہونے والے Codex ماڈلز پراکسی ریلیز کے بغیر کام کر سکتے ہیں۔

سروس کو ڈیفالٹ طور پر نجی رکھیں

Underclass ڈیفالٹ طور پر localhost پر سنتا ہے۔ اس ڈیفالٹ کو برقرار رکھیں، سوائے اس کے کہ ریموٹ رسائی جان بوجھ کر فعال اور محفوظ کی گئی ہو۔ پراکسی ایکسیس ٹوکنز، ریفریش ٹوکنز، authorization headers، یا پرامپٹ باڈیز کو لاگ نہیں کرتی، لیکن اکاؤنٹ لیبلز لاگز اور UI میں نظر آتے ہیں۔

• pool.db یا تیار کردہ *.bak فائلیں commit نہ کریں۔
• UI ٹوکن کو کلائنٹ پراکسی کی سے الگ محفوظ رکھیں۔
• OpenCode کی تیار کردہ auth.json کو نجی رکھیں؛ Underclass اسے 0600 اجازتوں کے ساتھ لکھتا ہے۔
• سروس کو localhost سے باہر ظاہر کرنے سے پہلے محفوظ ٹنل یا اسی نوعیت کا سوچا سمجھا تحفظ استعمال کریں۔

NixOS پر Underclass چلائیں

فلیک ایک NixOS ماڈیول برآمد کرتا ہے۔ سروس کنفیگریشن Underclass کو فعال کر سکتی ہے، اسے مقامی طور پر بائنڈ کر سکتی ہے، رن ٹائم ماحول کی فائل سے اسناد لوڈ کر سکتی ہے، اور بیک اینڈ کول ڈاؤنز مقرر کر سکتی ہے:

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

رن ٹائم ماحول کی فائل رازوں کو Nix اسٹور میں رکھے بغیر محفوظ کر سکتی ہے:

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

ماڈیول ایک متحرک صارف استعمال کرتا ہے، مستقل ڈیٹا /var/lib/underclass میں محفوظ کرتا ہے، پہلے سے localhost پر bind ہوتا ہے، اور فائر وال بند رکھتا ہے۔ services.underclass.openFirewall کو صرف اس وقت فعال کریں جب آپ جان بوجھ کر localhost سے باہر bind کرنا چاہتے ہوں۔

پروجیکٹ تیار کریں اور ٹیسٹ کریں

Cargo کے ذریعے build کریں اور ٹیسٹ سوٹ چلائیں:

cargo build
cargo test

یہ پروجیکٹ unit tests، Hegel property tests، اور end-to-end tests کو یکجا کرتا ہے۔ pool اور health core ہم وقت ساز ہیں اور injected clock استعمال کرتے ہیں، جبکہ غیر ہم وقت ساز رویہ کناروں تک محدود رکھا گیا ہے۔ نئے providers provider::Backend trait نافذ کرتے ہیں اور application کے ساتھ register ہوتے ہیں۔

آرکیٹیکچر کے پس منظر کے لیے پروجیکٹ کے architecture decision records کا جائزہ لیں۔ routing model کی وضاحت ADR 0010 میں کی گئی ہے، جبکہ cross-proxy request correlation کو ADR 0012 میں بیان کیا گیا ہے۔

نتیجہ

Underclass متعدد ChatGPT/Codex اور GitHub Copilot سبسکرپشنز کو ایک مقامی OpenAI-compatible service میں تبدیل کرتا ہے۔ اس کی sticky routing، خودکار cooldown recovery، model-aware account selection، اور fail-fast saturation behavior دستی اکاؤنٹ سوئچنگ کو کم کرتے ہیں اور کلائنٹ کے قابلِ پیش گوئی رویے کو برقرار رکھتے ہیں۔ سرور شروع کریں، web UI کے ذریعے اکاؤنٹس شامل کریں، underclass connect چلائیں، اور OpenCode یا کسی دوسرے compatible client کو حاصل ہونے والے endpoint کی طرف اشارہ کریں۔