মূল কনটেন্টে যান
এআই টিউটোরিয়াল

Underclass দিয়ে একটি স্থিতিস্থাপক AI সাবস্ক্রিপশন পুল তৈরি করুন

Underclass কীভাবে চালাতে হয়, OAuth ডিভাইস ফ্লোর মাধ্যমে সাবস্ক্রিপশন অ্যাকাউন্ট যোগ করতে হয়, OpenCode সংযুক্ত করতে হয়, রাউটিং ও কুলডাউন কনফিগার করতে হয়, মডেল পরিদর্শন করতে হয় এবং Cargo, Nix বা NixOS ব্যবহার করে প্রক্সি নিরাপদে পরিচালনা করতে হয় তা শিখুন।

পড়তে প্রায় 26 মিনিট লাগবে
Underclass দিয়ে একটি স্থিতিস্থাপক AI সাবস্ক্রিপশন পুল তৈরি করুন

Underclass যা করে

Underclass একটি স্থানীয় প্রক্সি, যা একাধিক ChatGPT/Codex এবং GitHub Copilot সাবস্ক্রিপশনকে একটি OpenAI-সামঞ্জস্যপূর্ণ এন্ডপয়েন্টে একত্র করে। ক্লায়েন্টরা পরিচিত /v1/* রুট ব্যবহার করে যোগাযোগ করে, আর Underclass একটি ব্যবহারযোগ্য সাবস্ক্রিপশন নির্বাচন করে, কোটার অবস্থা পর্যবেক্ষণ করে এবং অনুরোধ উপযুক্ত আপস্ট্রিম পরিষেবায় ফরওয়ার্ড করে।

প্রতিটি সাবস্ক্রিপশনের আলাদা কোটা থাকলে এটি কার্যকর। কোনো একটি অ্যাকাউন্ট সীমায় পৌঁছালেই ম্যানুয়ালি অ্যাকাউন্ট বদলানোর পরিবর্তে, আপনি অ্যাকাউন্টগুলোকে একটি শেয়ার্ড পুলে রাখতে পারেন। কোনো অ্যাকাউন্টের কোটা শেষ হলে সেটি কুলিং অবস্থায় যায় এবং কোটার সময়সীমা রিসেট হওয়ার পর স্বয়ংক্রিয়ভাবে আবার রোটেশনে ফিরে আসে।

Underclass-এর উদ্দেশ্য হলো অ্যাকাউন্টের স্বাস্থ্য, সেশন অ্যাফিনিটি এবং প্রম্পট-ক্যাশের কার্যকারিতা বজায় রেখে একটি পর্যাপ্তভাবে কনফিগার করা একক প্রোভাইডারের মতো আচরণ করা।

প্রধান বৈশিষ্ট্য

  • OpenAI-সামঞ্জস্যপূর্ণ API: ক্লায়েন্টরা /v1/responses, /v1/chat/completions এবং /v1/models ব্যবহার করতে পারে।
  • একাধিক ব্যাকএন্ড: পুলে ChatGPT/Codex অ্যাকাউন্ট, GitHub Copilot অ্যাকাউন্ট অথবা উভয়ই থাকতে পারে।
  • স্টিকি সেশন: prompt_cache_key বা promptCacheKey থাকা অনুরোধগুলো সম্ভব হলে একই সাবস্ক্রিপশনের সঙ্গে যুক্ত থাকে।
  • স্বয়ংক্রিয় কুলডাউন: কোটাসংক্রান্ত প্রতিক্রিয়া কোনো অ্যাকাউন্টকে রোটেশনের বাইরে সরিয়ে দেয়, যতক্ষণ না তার পুনঃচেষ্টা করার সময়সীমা শেষ হয়।
  • দ্রুত স্যাচুরেশন প্রতিক্রিয়া: কোনো মডেলের জন্য যোগ্য সব অ্যাকাউন্ট কুলিং অবস্থায় থাকলে Underclass অনির্দিষ্টকাল কিউতে না রেখে সবচেয়ে দ্রুত উপলভ্য Retry-After মানসহ 429 ফেরত দেয়।
  • কমপক্ষে ইন-ফ্লাইট অনুরোধ নির্বাচন: যোগ্য Codex ও Copilot অ্যাকাউন্টগুলো একটি সমতল পুলে প্রতিযোগিতা করে, যেখানে প্রতিটি ব্যাকএন্ডের মডেল ক্যাটালগ অনুযায়ী ফিল্টার করা হয়।
  • স্থায়ী অবস্থা: অ্যাকাউন্ট, মডেল ক্যাটালগ, শংসাপত্র এবং স্টিকি বাইন্ডিং রিস্টার্টের পরও সংরক্ষিত থাকে।
  • প্রশাসনিক ওয়েব UI: অ্যাকাউন্ট যোগ ও পরিচালনা করুন, মডেল ক্যাটালগ সম্পাদনা করুন এবং সর্বশেষ 200টি অনুরোধ দেখুন।
  • গঠিত পর্যবেক্ষণব্যবস্থা: প্রতিটি প্রতিক্রিয়ায় একটি x-request-id থাকে এবং প্রতিটি অনুরোধ পরিবেশনকারী অ্যাকাউন্টের লেবেল লগে শনাক্ত করা হয়।

Underclass ইনস্টল ও চালু করুন

বিকল্প 1: Rust প্রকল্প থেকে চালান

রিপোজিটরি থেকে API ক্লায়েন্ট ও প্রশাসনিক UI-এর জন্য আলাদা সিক্রেট তৈরি করে সার্ভার চালু করুন:

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

ডিফল্ট লিসেনার হলো http://127.0.0.1:8080, আর ওয়েব ইন্টারফেসটি রুট URL-এ পাওয়া যাবে:

http://127.0.0.1:8080/

উৎপন্ন দুটি মানই পাসওয়ার্ড ম্যানেজার বা রানটাইম সিক্রেট ফাইলে সংরক্ষণ করুন। প্রক্সি কী /v1/*-এ অনুরোধ অনুমোদন করে, আর UI টোকেন প্রশাসনিক কার্যক্রম অনুমোদন করে। Underclass এই মানগুলো ডায়াগনস্টিকে লিখে না।

বিকল্প 2: Nix দিয়ে চালান

রিপোজিটরিটি একটি Nix flake-ও। ইনস্টল না করেই প্রক্সি চালান:

nix run github:ghuntley/underclass -- serve

আপনার Nix প্রোফাইলে প্যাকেজ ইনস্টল করতে ব্যবহার করুন:

nix profile install github:ghuntley/underclass

ডেভেলপমেন্টের জন্য প্রদত্ত শেলে প্রবেশ করে টেস্ট চালান:

nix develop --no-pure-eval
cargo test

devenv ডেভেলপমেন্ট শেলের জন্য --no-pure-eval অপশনটি আবশ্যক। nix run বা nix profile install-এর ক্ষেত্রে এটি প্রয়োজন নেই।

পুলে অ্যাকাউন্ট যোগ করুন

  1. http://127.0.0.1:8080/ খুলুন।
  2. UNDERCLASS_UI_TOKEN হিসেবে কনফিগার করা মানটি পেস্ট করুন।
  3. Add account নির্বাচন করুন।
  4. ChatGPT / Codex অথবা GitHub Copilot নির্বাচন করুন।
  5. দেখানো ডিভাইস অনুমোদন URL খুলে ডিভাইস কোড লিখুন।
  6. অনবোর্ডিং সম্পূর্ণ হওয়ার জন্য অপেক্ষা করুন। Underclass ইমেল ঠিকানা বা ব্যবহারকারীর নাম দিয়ে অ্যাকাউন্টটির লেবেল নির্ধারণ করে।
  7. পুলে অংশ নেওয়া উচিত এমন প্রতিটি সাবস্ক্রিপশনের জন্য প্রক্রিয়াটি পুনরাবৃত্তি করুন।

UI থেকে অ্যাকাউন্ট সক্রিয়, নিষ্ক্রিয়, অপসারণ বা পুনরায় লগইনও করা যায়। নিষ্ক্রিয় অ্যাকাউন্ট কনফিগার করা থাকে, তবে অনুরোধের জন্য নির্বাচিত হয় না।

OpenCode সংযুক্ত করুন

Underclass-এ একটি connect কমান্ড রয়েছে, যা OpenCode-এ একটি Underclass প্রোভাইডার যোগ করে:

cargo run -- connect

ডিফল্টভাবে, কমান্ডটি ~/.config/opencode/-এর অধীনে থাকা গ্লোবাল OpenCode কনফিগারেশন আপডেট করে। এটি প্রোভাইডার ব্লকটি opencode.json বা opencode.jsonc-এ একীভূত করে, শংসাপত্র auth.json-এ লেখে এবং ব্যাকআপ তৈরি করে। অপারেশনটি idempotent, তাই নিরাপদে আবার চালানো যায়।

পুলে প্রকাশিত কোনো মডেল দিয়ে OpenCode চালু করুন:

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

এর পরিবর্তে প্রকল্প-স্থানীয় কনফিগারেশন লিখতে --project যোগ করুন:

cargo run -- connect --project

কোনো ফাইল না লিখে একীভূত কনফিগারেশন প্রিভিউ করুন:

cargo run -- connect --dry-run

আর প্রয়োজন না থাকলে তৈরি করা ইন্টিগ্রেশন সরিয়ে ফেলুন:

cargo run -- connect --remove

তৈরি করা প্রোভাইডার কনফিগারেশন কাস্টমাইজ করার প্রয়োজন হলে কমান্ডটি --base-url, --api-key, --model এবং --no-default-model-ও গ্রহণ করে।

OpenAI-সামঞ্জস্যপূর্ণ API ব্যবহার করুন

যেকোনো সামঞ্জস্যপূর্ণ ক্লায়েন্ট Underclass লিসেনারকে তার বেস URL হিসেবে সেট করে এবং প্রক্সি কীকে bearer token হিসেবে পাঠিয়ে প্রক্সি ব্যবহার করতে পারে।

উপলভ্য মডেলের তালিকা দেখুন

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 ওই মানটিকে একটি সাবস্ক্রিপশনের সঙ্গে যুক্ত করে। setCacheKey: true দিয়ে কনফিগার করা হলে OpenCode তার সেশন ID পাঠাতে পারে। এই সংযোগ ২৪ ঘণ্টা স্থায়ী হয় এবং প্রক্সি পুনরায় চালু হলেও বজায় থাকে।

নির্ধারিত অ্যাকাউন্টটি কুলিং অবস্থায় গেলে 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

আপস্ট্রিম পরিষেবা কোনো পুনঃচেষ্টা-ব্যবধান না দিলে প্রতিটি ব্যাকএন্ডের ডিফল্ট কুলডাউন ১,৮০০ সেকেন্ড।

এনভায়রনমেন্ট ভেরিয়েবলগুলো সংশ্লিষ্ট কনফিগারেশন মানকে ওভাররাইড করে:

  • 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 ব্যবহার করুন।

Underclass-এর সামনে preflight বসানো হলে x-request-id হিসেবে দেওয়া বৈধ UUIDv4 প্রতিক্রিয়া, রাউটিং লগ, পুনঃচেষ্টা লগ এবং অনুরোধের ইতিহাসে অপরিবর্তিত থাকে। অবৈধ, পুনরাবৃত্ত, nil, অনুপস্থিত বা v4 নয় এমন শনাক্তকারীগুলো প্রতিস্থাপিত হয়। শনাক্তকারীর কাজ কেবল সম্পর্ক নির্ণয়ে সহায়তা করা; এটি অনুমোদন বা পরিদর্শণের প্রমাণ নয়।

মডেল ক্যাটালগ সতর্কতার সঙ্গে পরিচালনা করুন

রাউটিংয়ের যোগ্যতা এবং OpenCode-এর মডেল ব্লক সংরক্ষিত ক্যাটালগ অনুসরণ করে। ব্যাকএন্ড মডেল ম্যাপিং পরিদর্শন বা সম্পাদনা করতে ওয়েব UI অথবা প্রশাসনিক ক্যাটালগ API ব্যবহার করুন। অজানা মডেল শনাক্তকারীগুলো Codex-এ পাঠানো হয়, ফলে প্রক্সি রিলিজ ছাড়াই নতুনভাবে চালু হওয়া Codex মডেলগুলো কাজ করতে পারে।

ডিফল্টভাবে পরিষেবাটি ব্যক্তিগত রাখুন

ডিফল্টভাবে Underclass লোকালহোস্টে শোনে। দূরবর্তী অ্যাক্সেস ইচ্ছাকৃতভাবে চালু ও সুরক্ষিত না হলে এই ডিফল্ট বজায় রাখুন। প্রক্সি অ্যাক্সেস টোকেন, রিফ্রেশ টোকেন, অথরাইজেশন হেডার বা প্রম্পটের বিষয়বস্তু লগ করে না, তবে অ্যাকাউন্টের লেবেল লগ ও UI-তে দেখা যায়।

  • pool.db বা তৈরি হওয়া *.bak ফাইল কমিট করবেন না।
  • UI টোকেনকে ক্লায়েন্ট প্রক্সি কী থেকে আলাদাভাবে সুরক্ষিত রাখুন।
  • OpenCode-এর তৈরি auth.json ব্যক্তিগত রাখুন; Underclass এটি 0600 পারমিশন দিয়ে লেখে।
  • লোকালহোস্টের বাইরে পরিষেবাটি প্রকাশ করার আগে একটি নিরাপদ টানেল বা সমপর্যায়ের পরিকল্পিত সুরক্ষা ব্যবহার করুন।

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-এ সংযুক্ত হয় এবং ফায়ারওয়াল বন্ধ রাখে। localhost-এর বাইরে ইচ্ছাকৃতভাবে সংযুক্ত করার সময়ই কেবল services.underclass.openFirewall সক্রিয় করুন।

প্রকল্প ডেভেলপ ও পরীক্ষা করুন

Cargo দিয়ে বিল্ড করুন এবং টেস্ট স্যুট চালান:

cargo build
cargo test

প্রকল্পটিতে ইউনিট টেস্ট, Hegel প্রপার্টি টেস্ট এবং এন্ড-টু-এন্ড টেস্ট রয়েছে। পুল ও হেলথ কোর সিঙ্ক্রোনাস এবং ইনজেক্ট করা ঘড়ি ব্যবহার করে, আর অ্যাসিঙ্ক্রোনাস আচরণ প্রান্তসীমায় সীমাবদ্ধ রাখা হয়েছে। নতুন প্রোভাইডারগুলো provider::Backend ট্রেইট বাস্তবায়ন করে এবং অ্যাপ্লিকেশনের সঙ্গে রেজিস্টার হয়।

আর্কিটেকচার সম্পর্কে পটভূমি জানতে প্রকল্পের আর্কিটেকচার ডিসিশন রেকর্ডগুলো দেখুন। রাউটিং মডেলটি ADR 0010-এ ব্যাখ্যা করা হয়েছে, আর ক্রস-প্রক্সি রিকোয়েস্ট কোরিলেশন ADR 0012-এ আলোচনা করা হয়েছে।

উপসংহার

Underclass একাধিক ChatGPT/Codex এবং GitHub Copilot সাবস্ক্রিপশনকে একটি স্থানীয় OpenAI-সামঞ্জস্যপূর্ণ সার্ভিসে রূপান্তর করে। এর স্টিকি রাউটিং, স্বয়ংক্রিয় কুলডাউন পুনরুদ্ধার, মডেল-সচেতন অ্যাকাউন্ট নির্বাচন এবং স্যাচুরেশনে দ্রুত ব্যর্থ হওয়ার আচরণ ম্যানুয়ালি অ্যাকাউন্ট বদলানোর প্রয়োজন কমায়, একই সঙ্গে ক্লায়েন্টের পূর্বানুমানযোগ্য আচরণ বজায় রাখে। সার্ভার চালু করুন, ওয়েব UI-এর মাধ্যমে অ্যাকাউন্ট যুক্ত করুন, underclass connect চালান এবং OpenCode বা অন্য কোনো সামঞ্জস্যপূর্ণ ক্লায়েন্টকে তৈরি হওয়া এন্ডপয়েন্টে নির্দেশ করুন।