.NET developer-দের জন্য AI engineering (পর্ব 10): ফটক, observability, cost, cache, Docker ও CI-তে eval gate

ফোলিওলেন্সকে চালু service বানানো: telemetry, cost-এর সীমা, cache, retry ও fallback, Docker, আর এমন CI, যা eval fail করলে deploy আটকায়।

27 min readUpdated
বিল্ড, টেস্ট, ইভ্যাল ধাপের পরে ফটক নামানো, নিচের লেখচিত্রে স্কোর সীমার নিচে নামায় ডেপ্লয় আটকে গেছে

পর্ব 9-এর শেষে ফোলিওলেন্সের প্রতিটি অভ্যন্তরীণ কম্পোনেন্ট চমৎকারভাবে তৈরি হয়ে গেছে—কিন্তু পুরো সিস্টেমটি এখনো কেবল ইউনিট ও ইন্টিগ্রেশন টেস্টের চার দেয়ালেই সীমাবদ্ধ। এবার বাস্তব জগতের তিনটি বড় প্রশ্ন সামনে এসে দাঁড়ায়: মাস শেষে ক্লাউড ও AI প্রোভাইডারের বিল কত আসবে? প্রোভাইডার যদি হঠাৎ ধীরগতির বা আনরেসপনসিভ হয়ে পড়ে, আমাদের ব্যবহারকারীরা কি অনির্দিষ্টকাল স্ক্রিনের সামনে আটকে থাকবেন? আর টিম মেম্বারদের অজান্তে যদি প্রম্পটের সামান্য কোনো পরিবর্তন সিস্টেমে নীরব বিপর্যয় ডেকে আনে, তবে প্রোডাকশনে ছাড়ার আগেই তা হাতেনাতে ধরবে কে?

এই সমাপনী পর্বে আমরা ফোলিওলেন্সকে কেবল একটি কোডবেস থেকে বাস্তব প্রোডাকশন-রেডি সার্ভিসে রূপান্তর করব—এমন এক রানিং অ্যাপ্লিকেশন, যা চব্বিশ ঘণ্টা নেটওয়ার্কে চালু থেকে রিকোয়েস্টের উত্তর দেবে। এখানে প্রতিটি LLM কলের পুঙ্খানুপুঙ্খ টেলিমেট্রি রেকর্ড করা হবে, বাজেটের কঠোর সীমারেখা থাকবে, প্রাইমারি মডেল ফেইল করলে ব্যাকআপ মডেলে অটোম্যাটিক ফলব্যাক ঘটবে এবং সিআই পাইপলাইনে এমন এক ডিজিটাল প্রহরীর ব্যবস্থা থাকবে, যা কোড পুশের পর স্বয়ংক্রিয় টেস্ট ফেইল করলে ডিপ্লয়মেন্ট সরাসরি আটকে দেবে। এই সুরক্ষাব্যবস্থার নামই ফটক (Evaluation Gate), যা এই পর্বের কেন্দ্রীয় থিম।

কোড: এই পর্বের শেষে কোডের অবস্থা github.com/alaminmain/foliolens-এর part-10 tag-এ। নিজের কাছে এনে চালাতে: git checkout part-10 তারপর dotnet test। আগের পর্বের সঙ্গে তফাত দেখতে: git diff part-09 part-10।

কেন: demo থেকে service

তিনটি বাস্তবসম্মত পরিস্থিতির কথা কল্পনা করা যাক:

  • মাসের শেষে AI প্রোভাইডারের বিল অনুমানের চেয়ে দ্বিগুণ হয়ে এলো, অথচ কোন ফিচারের কারণে এত টোকেন খরচ হলো, তার কোনো সুস্পষ্ট হিসাব কোথাও নেই।
  • কোনো এক পিক আওয়ারে প্রোভাইডারের সার্ভার এক ঘণ্টা ধরে মারাত্মক স্লো ছিল; আমাদের সিস্টেমে থাকা বেপরোয়া রিট্রাই লজিক ব্যবহারকারীদের অপেক্ষার সময় কয়েক গুণ বাড়িয়ে দিয়ে পুরো এপিআইকেই প্রায় স্থবির করে ফেলল।
  • শুক্রবার বিকেলে প্রম্পটের সাইজ ছোট করতে গিয়ে কেউ অসাবধানতাবশত একটি গুরুত্বপূর্ণ নিয়ম মুছে দিল। ইউনিট টেস্টগুলো সব সবুজ পাস থাকায় কোড প্রোডাকশনে চলে গেল, আর সোমবার এসে দেখা গেল—সিস্টেম বাংলা সংখ্যার নোটগুলো ভুল পড়তে শুরু করেছে।

এর কোনোটির জন্যই কিন্তু মডেল নিজে দায়ী নয়। মূল ঘাটতি ছিল—খরচ মনিটর করার দৃশ্যমানতা (observability), ব্যবহারকারীদের অতিরিক্ত অপেক্ষা আটকে দেওয়ার ল্যাটেন্সি বাজেট এবং প্রোডাকশনে কোড ছাড়ার আগে স্বয়ংক্রিয়ভাবে মান যাচাই করার রিগ্রেশন গেটের অনুপস্থিতি। একজন .NET ডেভেলপারের কাছে এই আর্কিটেকচারাল চ্যালেঞ্জগুলো বেশ পরিচিত হলেও AI ইঞ্জিনিয়ারিংয়ে তিনটি নতুন সূক্ষ্ম ফাঁদ তৈরি হয়: টোকেনভিত্তিক খরচের খাতা, ক্লায়েন্ট SDK-র ভেতরে লুকিয়ে থাকা গোপন রিট্রাই পলিসি, এবং ব্যবহারকারীর সংবেদনশীল ইনপুট বা প্রম্পট অসাবধানতাবশত লগের ভেতর ঢুকে পড়া।

ধারণা: layer-এর ক্রমই নকশা

পর্ব 1-এ আমরা মডেলের সাথে যোগাযোগের জন্য IChatClient ইন্টারফেস ব্যবহার করেছিলাম। এর চমৎকার সুবিধা হলো—ইন্টারফেসটির পেছনে যেকোনো মডেল অনায়াসে প্লাগ করা যায়। ক্যাশিং, স্ট্রাকচার্ড লগিং, রিট্রাই মেকানিজম এবং ওপেনটেলিমেট্রি ট্রেসিং—সবকিছুই এই IChatClient-এর ওপর ভিত্তি করে পাইপলাইনের মতো সাজানো যায়। প্রতিটি রেসপনসিবিলিটি একেকটি ডেকোরেটর বা র‍্যাপার হিসেবে কাজ করে, যাকে ASP.NET-এর ভাষায় আমরা মিডলওয়্যার (DelegatingChatClient) বলি।

একটি ইনকামিং রিকোয়েস্ট সবার বাইরের র‍্যাপার দিয়ে প্রবেশ করে ক্রমান্বয়ে ভেতরে যায়, তাই এই লেয়ারগুলোর সাজানোর ক্রমটি (order) অত্যন্ত সংবেদনশীল স্থাপত্য-সিদ্ধান্ত। উদাহরণস্বরূপ: ধরুন আজকের জন্য নির্ধারিত দৈনিক খরচের বাজেট শেষ হয়ে গেছে, কিন্তু ব্যবহারকারী যে প্রশ্নটি করেছেন তার নিখুঁত উত্তর আমাদের ক্যাশে আগেই জমা রয়েছে। ক্যাশ লেয়ারটি যদি বাজেট গার্ডের (budget guard) বাইরে থাকে, তবে মডেলকে কোনো কল না করেই ক্যাশ থেকে সম্পূর্ণ ফ্রিতে উত্তরটি রিটার্ন করা সম্ভব। পক্ষান্তরে, ক্যাশ যদি বাজেট গার্ডের ভেতরে থাকত, তবে গার্ড আগেই "বাজেট শেষ" বলে ব্যবহারকারীর দরকারি রিকোয়েস্টটি ব্যর্থ করে দিত। ফোলিওলেন্সের সুনির্দিষ্ট পাইপলাইন ক্রম:

request প্রশ্ন + id log ও id প্রতি call-এ এক line cache hit হলে cost শূন্য budget guard টাকা শেষ? call নয় hit হলে এখানেই ফেরে fallback chain: প্রতিটি model-এর নিজের stack; fail করলে পরের model-এর stack cost-মিটার টাকা গোনে retry backoff + jitter breaker ভাঙা model বাদ telemetry span, metric sanitizer error text বাদ client OpenRouter বা fake প্রথম model-এর stack-এ ঢোকে
cache (কমলা) budget guard-এর আগে, তাই টাকা ফুরোলেও cache hit মেলে।

এই সুনির্দিষ্ট লেয়ার ক্রমটি আমাদের আর্কিটেকচারাল ডিজাইন চয়েস, কোনো ফ্রেমওয়ার্কের চাপিয়ে দেওয়া নিয়ম নয়। টেলিমেট্রি নেওয়া হয়েছে UseOpenTelemetry থেকে, আর ক্যাশিং ও ফলব্যাক মেকানিজম আমরা নিজস্ব কন্ট্রাক্ট অনুযায়ী লিখেছি—কারণ "কী জিনিস ক্যাশে রাখা যাবে না" এই পলিসি কোডে যাচাই করা দরকার, এবং অফিসিয়াল ডকের অনেক ফেইলওভার ক্লায়েন্ট এখনো পরীক্ষামূলক (experimental) হিসেবে চিহ্নিত।

কোড

জোড়া লাগানো

এই পুরো ক্রমটি কোডে এক সুবিন্যস্ত জায়গায় কনফিগার করা হয়েছে—FolioAiPipeline.Build মেথডে। প্রতিটি মডেলের জন্য আলাদা আলাদা ডেকোরেটর স্ট্যাক তৈরি করে তারপর তাদেরকে একটি রিজিলিয়েন্ট ফলব্যাক চেইনে যুক্ত করা হয়েছে।

foreach (var model in options.Models)
{
    TokenPricing? pricing = model.InputPerMillion is { } i && model.OutputPerMillion is { } o ? new TokenPricing(i, o) : null;
    CircuitBreakerChatClient? breaker = null;
 
    var chain = new ChatClientBuilder(createRaw(model))
        // The builder lists outermost first.
        .Use(inner => new CostMeterChatClient(inner, model.Id, pricing, ledger, telemetry))
        .Use(inner => new RetryChatClient(inner, retry, model.Id, telemetry, clock, sleep, random, logger))
        .Use(inner => breaker = new CircuitBreakerChatClient(inner, model.Id, breakerOptions, telemetry, clock, logger))
        .ConfigureOptions(chatOptions => chatOptions.ModelId ??= model.Id) // so the span says which model, whatever the caller passed
        // No logger factory on purpose: given one, the OpenTelemetry client logs every failure together with the
        // exception text, and a provider may echo the request in that text (see the pii_never_reaches_the_logs test).
        .UseOpenTelemetry(loggerFactory: null, sourceName: telemetry.Name)
        // The span records exception text as its status; this layer makes sure there is none worth recording.
        .Use(inner => new SanitizingChatClient(inner))
        .Build();
  • new ChatClientBuilder(createRaw(model)): একদম রুট ক্লায়েন্ট থেকে বিল্ড শুরু হয়। প্রতিটি .Use(...) একটি করে ডেকোরেটর র‍্যাপার যুক্ত করে, এবং বিল্ডারে আগে যুক্ত করা লেয়ারটি পাইপলাইনে সবচেয়ে বাইরে অবস্থান নেয়।
  • CostMeterChatClient সবার বাইরে থাকায় ভেতরে যতবারই অভ্যন্তরীণ রিট্রাই চলুক না কেন, মূল রিকোয়েস্টটির জন্য খরচের খাতায় কেবল একটিই চূড়ান্ত রেকর্ড বসবে।
  • CircuitBreakerChatClient রাখা হয়েছে রিট্রাইয়ের ভেতরে, যাতে প্রোভাইডারে পাঠানো প্রতিটি পৃথক চেষ্টার ব্যর্থতা সার্কিট ব্রেকারের হিসাবে সঠিকভাবে নথিভুক্ত হয়।
  • UseOpenTelemetry আরও ভেতরে বসানো, যাতে প্রতিটি একক এটেম্পট একটি স্বয়ংক্রিয় স্প্যান হিসেবে ট্রেস হয়। এখানে ইচ্ছাকৃতভাবেই logger factory প্যারামিটারে null পাস করা হয়েছে—এর কারণ পরের সেকশনে স্পষ্ট হবে।
  • SanitizingChatClient বসেছে সরাসরি আসল ক্লায়েন্টের ঠিক ওপরে, যার কাজ হলো এরর মেসেজের স্পর্শকাতর টেক্সট ফিল্টার করা।

মডেলের নাম, এন্ডপয়েন্ট ও প্রাইসিং মেট্রিক্স সবকিছু লোড হয় সেন্ট্রাল কনফিগ ফাইল (FolioAi:Models) থেকে।

observability: যা সত্যিই বেরোল

অবজারেবিলিটি (Observability) মানে হলো একটি রানিং সিস্টেম বাইরে থেকে দেখে বোঝা যে ভেতরে ঠিক কী ঘটছে। এর জন্য মূলত তিনটি মৌলিক ডেটাস্ট্রিম প্রয়োজন হয়। ধরুন, একটি রিকোয়েস্টে প্রোভাইডার প্রথম দুইবার রেট লিমিটের কারণে 429 ("Too Many Requests") স্ট্যাটাস কোড দিল এবং তৃতীয়বারে সফলভাবে উত্তর দিল:

  • Log হলো যেকোনো নির্দিষ্ট ঘটনার একটি টেক্সচুয়াল রেকর্ড; যেমন: "attempt 1, status 429, wait 500 ms"।
  • Trace হলো ব্যবহারকারীর একটি সম্পূর্ণ রিকোয়েস্টের পুরো ট্রাভেল জার্নি। এই জার্নির প্রতিটি স্বতন্ত্র অংশকে স্প্যান (Span) বলা হয়। এই সিনারিওতে তিনটি স্প্যান তৈরি হবে: প্রথম দুটি ফেইল্ড এটেম্পটের জন্য এবং শেষটি সফল কলের জন্য।
  • Metric হলো অসংখ্য রিকোয়েস্টের ওপর ভিত্তি করে তৈরি অ্যাগ্রিগেটেড সংখ্যাসূচক ডেটা; যেমন: "আজ মোট কতটি কল করা হয়েছে এবং মোট খরচ কত ডলার"। কোনো একক রিকোয়েস্টের ভেতরে কী ঘটেছিল, মেট্রিক তা আলাদা করে বলে না।

মাইক্রোসফটের অফিশিয়াল গাইডলাইন অনুযায়ী UseOpenTelemetry ওপেনটেলিমেট্রির জেনারেটিভ এআই কনভেনশন (Generative AI semantic conventions) মেনে স্প্যান ও মেট্রিক তৈরি করে। OpenTelemetry মূলত মেট্রিক ও ট্রেসের নামগুলোর একটি ওপেন স্ট্যান্ডার্ড, যাতে যেকোনো প্রমিথিউস বা গ্রাফানা মনিটরিং টুল সহজেই তা রিড করতে পারে। টেস্টের সুবিধার্থে সবকিছু মেমোরিতে ধরে রাখা হয়েছে, কোনো রিমোট কালেক্টরে পুশ করা হয়নি। তিনটি এটেম্পটের সেই রিকোয়েস্টে (স্ক্রিপ্টেড প্রোভাইডারে) তিনটি chat স্প্যান তৈরি হয়। নিচে প্রথম ফেইল্ড স্প্যান, শেষ সফল স্প্যান এবং রিট্রাই ইভেন্টের নমুনা:

chat vendor/model-name   kind=Client   status=Error
  gen_ai.operation.name = chat
  gen_ai.request.model = vendor/model-name
  gen_ai.provider.name = 
  gen_ai.request.max_tokens = 200
  gen_ai.request.temperature = 0
  error.type = FolioLens.Observability.ProviderCallException
 
chat vendor/model-name   kind=Client   status=Unset
  gen_ai.operation.name = chat
  gen_ai.request.model = vendor/model-name
  gen_ai.provider.name = 
  gen_ai.request.max_tokens = 200
  gen_ai.request.temperature = 0
  gen_ai.response.finish_reasons = ["stop"]
  gen_ai.usage.input_tokens = 120
  gen_ai.usage.output_tokens = 30
 
folio.ask event folio.retry: folio.attempt=1, folio.wait_ms=500, folio.status=429
folio.ask event folio.retry: folio.attempt=2, folio.wait_ms=1000, folio.status=429
  • প্রথম স্প্যানে status=Error, এবং error.type ফিল্ডে স্পষ্ট উল্লেখ আছে কোন এক্সেপশনটি এসেছিল।
  • দ্বিতীয় স্প্যানটি সফল, যাতে টোকেন খরচের মেট্রিক উপস্থিত: input 120, output 30।
  • শেষের দুই লাইনে রিট্রাই ইভেন্টের পরিষ্কার হিসাব: 500 ms এবং 1000 ms অপেক্ষা, যেখানে দুইবারই স্ট্যাটাস কোড ছিল 429।

মেট্রিক্সের হিসাবে একটি ক্যাশ মিস এবং একটি ক্যাশ হিট:

folio.ai.cache.requests [{request}] result=miss = 1
folio.ai.cache.requests [{request}] result=hit = 1
folio.ai.calls [{call}] feature=ask-docs, model=vendor/model-name = 1
folio.ai.cost [{cost_unit}] feature=ask-docs, model=vendor/model-name = 0.002
gen_ai.client.operation.duration [s] gen_ai.operation.name=chat, gen_ai.provider.name=, gen_ai.request.model=vendor/model-name = 0.0001558
gen_ai.client.token.usage [{token}] gen_ai.operation.name=chat, gen_ai.provider.name=, gen_ai.request.model=vendor/model-name, gen_ai.token.type=input = 1000
gen_ai.client.token.usage [{token}] gen_ai.operation.name=chat, gen_ai.provider.name=, gen_ai.request.model=vendor/model-name, gen_ai.token.type=output = 500

folio.ai.cache.requests নির্ভুলভাবে গুনেছে miss 1, hit 1। ask-docs ফিচারে folio.ai.calls হয়েছে 1টি এবং folio.ai.cost উঠেছে 0.002 ডলার। দ্বিতীয় কলের ক্ষেত্রে ক্যাশ হিট হওয়ায় কোনো নতুন টোকেন পুড়েনি, তাই gen_ai.client.token.usage কেবল প্রথম কলের টোকেনই কাউন্ট করেছে: input 1000, output 500। gen_ai.provider.name ফাঁকা দেখাচ্ছে কারণ আমাদের ফেইক টেস্ট ক্লায়েন্ট কোনো প্রোভাইডার নাম পাঠায়নি।

সতর্কতা: GenAI semantic convention এখনো বিকাশমান ("Development") পর্যায়ে রয়েছে, অর্থাৎ এটি এখনো চূড়ান্ত স্ট্যান্ডার্ডে পৌঁছায়নি। ওপরের ফিল্ডগুলোর নাম এই নির্দিষ্ট প্যাকেজ ভার্সনের (10.11.0) আউটপুট অনুযায়ী প্রদর্শিত। তাই প্রোডাকশন ড্যাশবোর্ড তৈরির আগে ব্যবহৃত প্যাকেজ ভার্সনের ডকের সাথে ফিল্ড নেমগুলো যাচাই করে নেওয়া উচিত।

যা log-এ ও span-এ যাবে না

লগের প্রতিটি লাইনে থাকবে কেবল মডেলের নাম, টোকেন সংখ্যা, আনুমানিক খরচ, লেটেন্সি (ms), এইচটিটিপি স্ট্যাটাস এবং এক্সেপশনের type। কোনো অবস্থাতেই লগে আসল প্রম্পট, ব্যবহারকারীর ইনপুট, মডেলের উত্তর বা এক্সেপশনের অভ্যন্তরীণ text ঢুকতে দেওয়া যাবে না। এর কারণ—প্রম্পটের ভেতরে ব্যবহারকারীর সংবেদনশীল নাম, ব্যাংক অ্যাকাউন্ট নম্বর কিংবা PII (Personally Identifiable Information) ডেটা থাকতে পারে। অসাবধানতাবশত এগুলো লগে চলে গেলে আপনার লগিং সিস্টেম নিজেই একটি আনপ্রোটেক্টেড সেকেন্ডারি database-এ রূপ নেবে।

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

  1. UseOpenTelemetry-তে যদি সাধারণ কোনো লগার ফ্যাক্টরি পাস করা হয়, তবে প্রতিটি ফেইলিউরে সে এক্সেপশনের সম্পূর্ণ টেক্সটসহ ডাম্প করে দেয়।
  2. ফ্যাক্টরি পাস না করলেও ওপেনটেলিমেট্রির স্প্যান স্ট্যাটাস ডেসক্রিপশনের ভেতরে সেই এক্সেপশন টেক্সটটি অবিকল ঢুকে পড়ে, এবং স্প্যানটি সরাসরি ওটিএলপি কালেক্টরে ট্রান্সমিট হয়ে যায়।

এই ডেটা লিকের চমৎকার সমাধান: লগার ফ্যাক্টরিকে null রাখা এবং রুট ক্লায়েন্টের ঠিক ওপরে একটি কাস্টম SanitizingChatClient মিডলওয়্যার বসানো। এই স্যানিটাইজার প্রোভাইডারের পাঠানো যেকোনো কাঁচা এক্সেপশনকে আটকে দিয়ে স্পর্শকাতর টেক্সট সম্পূর্ণ ছেঁটে ফেলে এবং একটি নিরাপদ ProviderCallException-এ র‍্যাপ করে ছুঁড়ে দেয়:

public sealed class SanitizingChatClient(IChatClient inner) : FolioChatClient(inner)
{
    public override async Task<ChatResponse> GetResponseAsync(
        IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default)
    {
        try
        {
            return await base.GetResponseAsync(messages, options, cancellationToken).ConfigureAwait(false);
        }
        catch (OperationCanceledException ex) when (!cancellationToken.IsCancellationRequested)
        {
            // Nobody above cancelled, so this is the HTTP client's own timeout.
            throw new ProviderCallException(FailureKind.Transient, null, ex.GetType().Name, null);
        }
        catch (Exception ex) when (ex is not OperationCanceledException and not ProviderCallException)
        {
            // Classified without the token: a timeout we started is transient, and the layers above decide about the caller's own token.
            throw new ProviderCallException(
                Failures.Classify(ex, CancellationToken.None), Failures.StatusOf(ex), ex.GetType().Name, Failures.RetryAfter(ex));
        }
    }
}

প্রথম catch ব্লকটি এইচটিটিপি ক্লায়েন্টের নিজস্ব ইন্টারনাল টাইমআউট শনাক্ত করে: কলার নিজে রিকোয়েস্ট ক্যানসেল করেননি, অথচ OperationCanceledException থ্রো হয়েছে। অর্থাৎ এটি একটি সাময়িক (Transient) নেটওয়ার্ক ফেইলিউর। দ্বিতীয় catch ব্লকটি বাকি সব এক্সেপশন ধরে এবং আসল এরর মেসেজ ও ব্যবহারকারীর ডেটা মুছে ফেলে কেবল ফেইলিউরের ধরন, এইচটিটিপি স্ট্যাটাস, এক্সেপশনের টাইপ ও Retry-After হেডার রেখে নতুন নিরাপদ এক্সেপশন তৈরি করে। এর ফলে মূল এরর টেক্সট ও ইন্টারনাল স্ট্যাকট্রেস পুরোপুরি ফিল্টার হয়ে যায়। টেস্ট রানের পর প্রাপ্ত আউটপুট:

Warning: ai.retry model=vendor/primary attempt=1 status=502 wait_ms=500
Information: ai.call ok cid=req-0001-abcd feature=ask-docs served_by=vendor/primary cache=bypass tokens_in=100 tokens_out=50 cost=0.0002 ms=5
Warning: ai.call failed cid=req-0001-abcd feature=ask-docs error=HttpRequestException status=400 ms=0
 
SPAN status=Error description='Provider call failed: HttpRequestException, HTTP status 502.' error.type=FolioLens.Observability.ProviderCallException

প্রথম এটেম্পটের ফেইল্ড রিকোয়েস্টে কাল্পনিক ব্যবহারকারীর নাম ও অ্যাকাউন্ট নম্বর ছিল। ওপরের কোনো লগে বা স্প্যান ট্রেসে কিংবা এক্সেপশন অবজেক্টের ToString()-এ তার বিন্দুমাত্র অস্তিত্ব নেই।

cost ও budget

পর্ব 1-এর মিটার এখানে ফিরল, মানে প্রতিটি call-এর token গুনে দাম ধরা। সেখানে একটা কথা খোলা ছিল: অজানা cost আর শূন্য cost এক নয়। দাম থাকে config-এ। দাম না থাকলে, বা provider token-সংখ্যা না পাঠালে cost হয় null, মানে অজানা। খাতা (CostLedger) একে "অজানা-cost-এর call" হিসেবে আলাদা গোনে, "ফ্রি" ধরে মোট cost-এ মেশায় না।

var feature = RequestContext.Feature(options);
var cost = pricing is null ? null : CostCalculator.Calculate(response.Usage, pricing);
var inputTokens = response.Usage?.InputTokenCount ?? 0;
var outputTokens = response.Usage?.OutputTokenCount ?? 0;
 
ledger.Record(feature, cost, inputTokens, outputTokens);

ledger.Record(...) মেথডটি ফিচারের নামসহ প্রতিটি হিসাব লেজারে লিখে রাখে। খাতাটি ক্যালেন্ডার দিন এবং ফিচার অনুযায়ী ডেটা অ্যাগ্রিগেট করে, যা সরাসরি /usage এন্ডপয়েন্টে দেখা যায়। ফিচারের নাম ও ক্যাশ করার পলিসি মূলত রাখা হয়েছে অ্যাম্বিয়েন্ট RequestContext-এ, যাতে পর্ব 4 আর পর্ব 6-এর কোডে হাত না দিতে হয়।

বাজেট গার্ড cost হওয়ার আগে ঠেকায়। পরে ঠেকালে টাকা খরচ হয়ে যায়।

var committed = ledger.CommittedToday();
if (committed + inFlightBefore * budget.PerCallReserve >= budget.DailyLimit)
{
    telemetry.BudgetRefusals.Add(1, new TagList { { "feature", RequestContext.Feature(options) } });
    throw new BudgetExceededException(committed, budget.DailyLimit, ledger.NextReset());
}

committed হলো আজ এ পর্যন্ত খরচ। যে call-গুলো এখন চলছে, তাদের cost এখনো আসেনি, তাই প্রতিটির জন্য একটা ধরে-নেওয়া অঙ্ক (PerCallReserve) যোগ হয়। নইলে সীমার ঠিক আগে দশটা parallel call সবাই "টাকা আছে" দেখে ঢুকে পড়ত। যোগফল DailyLimit ছুঁলে call-ই করা হয় না।

cache: কী নয়, সেটাই আসল প্রশ্ন

Cache মানে একই প্রশ্ন আবার এলে আগের উত্তর ফিরিয়ে দেওয়া, model-কে না ডেকে। তাতে cost শূন্য। কিন্তু কঠিন প্রশ্নটা "কী রাখব না"। ভুল উত্তর একবার ঢুকলে বারবার সবাই সেটাই পায়। তাই নীতি default-এ "না", আর feature-কে অনুমতি দিতে হয়।

private string? KeyFor(IReadOnlyList<ChatMessage> messages, ChatOptions? options)
{
    if (!RequestContext.Cacheable(options)) return null;
    if (_options.OnlyDeterministic && options?.Temperature != 0f) return null;
    if (options?.ConversationId is not null) return null;
    return CacheKey.TryBuild(messages, options, _modelKey, RequestContext.CacheScope(options));
}

প্রতিটি return null মানে "cache করো না": feature অনুমতি দেয়নি, বা Temperature শূন্য নয় (তখন model একই প্রশ্নে আলাদা উত্তর দিতে পারে), বা এটা stateful কথোপকথন (ConversationId)। কখনো cache হয় না ব্যক্তিগত উত্তর (যেমন portfolio-র প্রশ্ন), কাটা বা ফাঁকা বা শুধু-tool-call-এর উত্তর, আর fallback model-এর উত্তর। কাটা উত্তর মানে মাঝপথে থেমে যাওয়া (FinishReason.Length), cache করলে প্রতিবার কাটা বাক্যই মিলত। fallback-এর উত্তর বাদ, নইলে outage কেটে গেলেও backup-এর উত্তর primary-র key-তে বসে থাকত।

cache key হলো model, সব option, tool আর প্রতিটি message-এর SHA-256। তাই prompt বদলালে key বদলায়, আর পুরোনো উত্তর নতুন deploy-এ আসে না। একই key-তে একসঙ্গে আসা request একটা call-এই মেটে (single flight): test-এ পাঁচটা request-এ একটা call।

retry, breaker, fallback

Retry মানে ব্যর্থ call আবার চেষ্টা করা, শুধু সাময়িক failure-এ (408, 429, 5xx, সাড়া না পাওয়া, attempt-এর timeout)। অপেক্ষা দ্বিগুণ হয়: 500 millisecond, 1 সেকেন্ড, 2 সেকেন্ড, সর্বোচ্চ 8 সেকেন্ড। সঙ্গে jitter, মানে শূন্য থেকে ওই সীমা পর্যন্ত এলোমেলো অপেক্ষা, যাতে সব client একই মুহূর্তে ফিরে না আসে। provider Retry-After পাঠালে (সেকেন্ডে) সেটা মানা হয়, তবে তা deadline ছাড়ালে এখনই fail। 400 বা 401 কখনো retry হয় না, caller cancel করলেও না।

Breaker (পুরো নাম circuit breaker)। provider ধীর থাকলে retry পরিস্থিতি আরও খারাপ করে: প্রতিটি request আবার ঘা দেয়, প্রতিটি ব্যবহারকারী বসে থাকে। কয়েকটা টানা failure-এর পর breaker call পাঠায়ই না, সঙ্গে সঙ্গে ফেরত দেয়। মাঝে মাঝে একটা probe call পাঠিয়ে দেখে provider ফিরল কি না।

closed call যায়, failure গোনা হয় open call যায় না, সঙ্গে সঙ্গে ফেরত half-open একটাই probe call টানা 5টা failure (default) 30 সেকেন্ড পর probe সফল probe fail 400 বা 401 failure হিসেবে গোনা হয় না: provider উত্তর দিয়েছে, অর্থাৎ বেঁচে আছে
open অবস্থায় (কমলা) call সঙ্গে সঙ্গে পরের model-এ যায়, ব্যবহারকারী বসে থাকে না।

Fallback: config-এর তালিকা ধরে একটার পর একটা model চেষ্টা, কিন্তু শুধু সেই failure-এ, যা অন্য model সারাতে পারে (সাময়িক failure, খোলা circuit, deadline)। 400 বা 401 লুকানো হয় না। ওটা আমাদের ভুল, ঢাকা পড়লে কেউ জানবে না।

অপেক্ষা গুণ হয়

সুতো বাঁধা: পর্ব 1-এ খুলে রেখেছিলাম, SDK নিজেই retry করে, তাই একটা call চারটা request হতে পারে। এখানে সেই গুণফল একটা গোনা সংখ্যা হলো, WorstCase: সবচেয়ে খারাপ অবস্থায় কতক্ষণ বসে থাকতে হবে। সংখ্যাটা /ready-তে দেখা যায়।

এখন আমাদের layer-ও retry করে, SDK-ও। দুটো গুণ হয়: আমাদের 3 চেষ্টা × SDK-র 4 চেষ্টা = এক call-এ 12টা request। সময়ও বাড়ে। SDK-র নিজের অপেক্ষা প্রথমে 0.8 সেকেন্ড, তারপর প্রতিবার দ্বিগুণ, jitter বা সীমা ছাড়া (ClientRetryPolicy.cs)। তাই 0.8 + 1.6 + 3.2 = 5.6 সেকেন্ড, যেমন পর্ব 1-এ মাপা হয়েছিল। এবার local stub-এ আসল client দিয়ে মাপা হলো। stub একটা নকল server, যা প্রতিবার সঙ্গে সঙ্গে 503 ফেরায়। আমাদের নিজের অপেক্ষা শূন্য:

0 5 10 15 20 সেকেন্ড 0.004 সেকেন্ড 3টা request SDK retry 0 আমাদের চেষ্টা 3 5.6 সেকেন্ড 4টা request SDK retry 3 আমাদের চেষ্টা 1 16.9 সেকেন্ড 12টা request SDK retry 3 আমাদের চেষ্টা 3 প্রতিটি request-এ সঙ্গে সঙ্গে 503 ফেরে; আমাদের নিজের অপেক্ষা শূন্য। বাকি সময়টা SDK-র নিজস্ব backoff।
আসল client, local stub: দুই layer-এর retry গুণ হয়। কমলা bar-এ একটা call মানে বারোটা request।

তৃতীয় bar-এ একটা call, বারোটা request, 16.9 সেকেন্ড। অথচ provider প্রতিবার সঙ্গে সঙ্গে "না" বলেছে। সবচেয়ে খারাপ অপেক্ষা বের করে LatencyBudget:

public static TimeSpan WorstCase(RetryOptions retry, int sdkMaxRetries, TimeSpan sdkTimeout)
{
    var sdkSequence = TimeSpan.FromTicks(sdkTimeout.Ticks * (1 + sdkMaxRetries)) + SdkBackoff(sdkMaxRetries);
    var perAttempt = sdkSequence < retry.PerAttemptTimeout ? sdkSequence : retry.PerAttemptTimeout;
 
    var total = TimeSpan.FromTicks(perAttempt.Ticks * retry.MaxAttempts);
    for (var failed = 1; failed < retry.MaxAttempts; failed++) total += retry.BackoffCeiling(failed);
 
    return total < retry.OverallDeadline ? total : retry.OverallDeadline;
}

sdkSequence হলো SDK একা সবচেয়ে বেশি কত সময় নিতে পারে। perAttempt হলো তার আর আমাদের attempt-প্রতি timeout-এর ছোটটা। total হলো perAttempt × চেষ্টার সংখ্যা, সঙ্গে আমাদের backoff, আর OverallDeadline ছাড়ালে deadline-ই ধরা হয়। stub request ঝুলিয়ে রাখলে (SDK-র timeout 0.1 সেকেন্ড, আমাদের backoff শূন্য) হিসাব আর মাপ মেলে: SDK retry 3 আর আমাদের 1 চেষ্টায় হিসাব 6000 ms, মাপা 6050 ms। attempt-প্রতি timeout 0.2 সেকেন্ড দিলে SDK-র retry কেটে যায়: request 8 নয়, 2। তাই তিনটা নিয়ম:

  1. SDK-র নিজের retry বন্ধ রাখুন (OpenRouterOptions.MaxRetries = 0, config-এ FolioAi:Retry:SdkMaxRetries), যাতে প্রতিটি চেষ্টা গোনা যায়।
  2. attempt-প্রতি timeout দিন।
  3. পুরো call-এর deadline দিন। caller-এর ধৈর্যের সঙ্গে সরাসরি মেলে এই একটাই সংখ্যা।

নিয়ম না মানলে? SDK-র 3 retry, আমাদের 3 চেষ্টা, 60 সেকেন্ড timeout আর কার্যত deadline ছাড়া WorstCase দেয় 738.3 সেকেন্ড, বারো মিনিটের বেশি (হিসাব, মাপা নয়)। আমাদের default-এ deadline 45 সেকেন্ডে কেটে দেয়, আর দুই model-এর chain-এ সবচেয়ে খারাপ 90 সেকেন্ড, যা /ready-তে দেখা যায়। default আমাদের পছন্দ, caller-এর ধৈর্য মেপে বদলান।

service: API

FolioLens.Api একটা minimal API host। পর্ব 4-এর PortfolioAssistant (portfolio-র প্রশ্নের উত্তর) আর পর্ব 5-6-এর RagAnswerer (নথি খুঁজে উত্তর) একই pipeline-এর পেছনে বসেছে, বদল ছাড়া।

পথকাজ
GET /healthliveness: process বেঁচে আছে। model-কে ডাকে না
GET /readyreadiness: breaker ও budget পড়ে। ok, degraded (200), unavailable (503)
GET /usagefeature-ভিত্তিক cost, অজানা-cost-এর call, cache-এর hit-miss
POST /askkind হয় portfolio (পর্ব 4) নয়তো docs (পর্ব 5-6)

liveness fail করলে orchestrator (যে tool container চালায়) সাধারণত process মেরে ফেলে। provider ধীর হলে তাতে লাভ নেই, উল্টো restart-এর ঝড় ওঠে। তাই /health সবসময় 200, আর কোনো model-ই চেষ্টা করার মতো না থাকলে /ready 503। দুটোই শুধু state পড়ে, কারণ health check টাকা খরচ করলে সেটা নিজেই bug। test-এ একশোটা probe-এর পরেও breaker-এর গোনা নড়েনি।

/ask-এর তিনটা line নীতি ঠিক করে দেয়:

// Default-deny cache: only the document feature (a public, fictional knowledge base) may be cached.
// A portfolio answer is about one person's holdings; it is never cached here.
var trace = new CallTrace();
var info = new RequestInfo(cid, kind == "docs" ? "ask-docs" : "ask-portfolio", Cacheable: kind == "docs", Trace: trace);
using var scope = RequestContext.Begin(info);

Cacheable: kind == "docs" মানে শুধু নথির প্রশ্ন (ask-docs, কাল্পনিক ও সবার জন্য খোলা knowledge base) cache-এর অনুমতি পায়। portfolio-র উত্তর একজনের holding নিয়ে, তাই কখনো cache হয় না।

প্রতি request-এ একটা X-Correlation-Id থাকে, যা একটা request-এর সব log line জোড়া দেয়। caller-এর পাঠানো id ^[A-Za-z0-9_-]{8,64}$-এর সঙ্গে মিললে চলে, নইলে নতুন id বানানো হয়, কারণ নইলে header দিয়ে কেউ নকল log line ঢোকাতে পারত। id যায় log-এ, span-এ (folio.correlation_id) আর error response-এ।

Docker

Docker image হলো একটা প্যাকেজ, যার ভেতরে program আর তা চালাতে যা লাগে সব থাকে। Dockerfile তার রেসিপি। এটা multi-stage: প্রথম ধাপে SDK image দিয়ে build, দ্বিতীয় ধাপে শুধু runtime। তাই SDK আর compiler production image-এ যায় না।

# syntax=docker/dockerfile:1
 
# ---- build stage: the SDK image, thrown away after publish ---------------------------------------------------------
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
 
# Restore first, using only the files that decide what to restore. Docker caches this layer until a .csproj changes,
# so editing C# does not download packages again.
COPY Directory.Build.props ./
COPY src/FolioLens.Core/FolioLens.Core.csproj src/FolioLens.Core/
COPY src/FolioLens.Ai/FolioLens.Ai.csproj src/FolioLens.Ai/
COPY src/FolioLens.Tools/FolioLens.Tools.csproj src/FolioLens.Tools/
COPY src/FolioLens.Rag/FolioLens.Rag.csproj src/FolioLens.Rag/
COPY src/FolioLens.Observability/FolioLens.Observability.csproj src/FolioLens.Observability/
COPY src/FolioLens.Api/FolioLens.Api.csproj src/FolioLens.Api/
RUN dotnet restore src/FolioLens.Api/FolioLens.Api.csproj
 
COPY src/ src/
RUN dotnet publish src/FolioLens.Api/FolioLens.Api.csproj -c Release --no-restore -o /app
 
# ---- runtime stage: ASP.NET runtime only, no SDK, no compiler -----------------------------------------------------
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
WORKDIR /app
COPY --from=build /app .
 
# The official images define a non-root user "app" and expose its id as APP_UID. Never run the service as root.
USER $APP_UID
 
ENV ASPNETCORE_HTTP_PORTS=8080
EXPOSE 8080
 
# The app checks itself, so the image needs no extra tools: --healthcheck calls its own /health and exits 0 or 1.
HEALTHCHECK --interval=10s --timeout=5s --start-period=15s --retries=3 \
  CMD ["dotnet", "FolioLens.Api.dll", "--healthcheck"]
 
ENTRYPOINT ["dotnet", "FolioLens.Api.dll"]

আগে শুধু .csproj কপি করে dotnet restore চলে। Docker এই ধাপ cache করে, তাই C# কোড বদলালে package আবার নামে না। USER $APP_UID দিয়ে app root নয়, সাধারণ user হিসেবে চলে। HEALTHCHECK app-এর নিজের --healthcheck argument ডাকে, image-এ আলাদা tool না বসিয়ে। Microsoft-এর doc অনুযায়ী .NET 8 থেকে image-এ non-root user app আছে (UID 1654), আর default port 80 থেকে 8080 হয়েছে (Microsoft Learn)। APP_UID নামটা ওই doc-এর অংশে নেই। নিচের চালানোয় uid=1654 মিলেছে।

docker-compose.yml-এ দুটো service: db (pgvector) আর api। api-র অংশ:

api:
  build: .
  image: folio-api:local
  depends_on:
    db:
      condition: service_healthy
  ports:
    - "8080:8080"
  environment:
    FolioAi__Mode: ${FOLIO_MODE:-fake}
    FolioAi__VectorStore: postgres
    FolioAi__Models__0__Id: ${FOLIO_MODEL_PRIMARY:-vendor/primary-model}
    FolioAi__Models__1__Id: ${FOLIO_MODEL_BACKUP:-vendor/backup-model}
    ConnectionStrings__Postgres: Host=db;Database=folio;Username=postgres;Password=${FOLIO_DB_PASSWORD:-folio-dev-only}
    OPENROUTER_API_KEY: ${OPENROUTER_API_KEY:-}               # read from your shell, never written here
  read_only: true
  tmpfs:
    - /tmp
  cap_drop:
    - ALL
  security_opt:
    - no-new-privileges:true
  restart: unless-stopped

FOLIO_MODE না দিলে mode fake, তাই key ছাড়াই চলে। OPENROUTER_API_KEY আসে আপনার shell থেকে, ফাইলে লেখা নেই। db-তে ports: নেই, তাই database host-এ খোলা নয়।

এবার আসল চালানো, fake mode-এ, কোনো key ছাড়া। (command-এ 8080 লেখা। docker compose ছাড়া সব ধাপে আসল host port ছিল 18080 থেকে 18082।) প্রথম build 3 মিনিট 23 সেকেন্ড (base image নামানোসহ), image 355 MB। সংখ্যাগুলো লেখকের প্রথম দৌড়ের। post লেখার সময় compose আবার চালিয়ে একই কাঠামো মিলেছে (নথির প্রশ্নে miss, তারপর hit; গড় 124.29; worstCaseWaitSeconds 90)।

$ curl -si localhost:8080/health
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Correlation-Id: 8aa76edab76d4c09
 
{"status":"ok"}
 
$ curl -s -X POST localhost:8080/ask -d {docs question}      # first time
{"kind":"docs","sources":["alfa-agm#0","alfa-agm#1","alfa-dividend#0","alfa-dividend#1"],"cited":["alfa-agm#0"],"calls":[{"outcome":"ok","servedBy":"vendor/primary-model","cache":"miss","cost":0.000447,"tokensIn":395,"tokensOut":26,"ms":33}]}
$ (same question again)
{"calls":[{"outcome":"ok","servedBy":null,"cache":"hit","cost":0,"tokensIn":0,"tokensOut":0,"ms":1}]}
$ curl -s -X POST localhost:8080/ask -d {portfolio question: ALFA}
{"answer":"ALFA-এর গড় ক্রয়মূল্য শেয়ারপ্রতি 124.29 টাকা (ডেমো মডেল, আসল মডেল নয়)।","status":"Verified","toolsCalled":["get_average_cost"],"calls":[{"outcome":"ok","servedBy":"vendor/primary-model","cache":"bypass","cost":0.000066,"tokensIn":66,"tokensOut":0,"ms":15},{"outcome":"ok","servedBy":"vendor/primary-model","cache":"bypass","cost":0.000104,"tokensIn":66,"tokensOut":19,"ms":1}]}
$ curl -s localhost:8080/usage
{"budgetDay":"2026-11-09","dailyLimit":5.0,"committed":0.000617,"features":{"ask-docs":{"cost":0.000447,"calls":1,"unknownCostCalls":0,"inputTokens":395,"outputTokens":26},"ask-portfolio":{"cost":0.000170,"calls":2,"unknownCostCalls":0,"inputTokens":132,"outputTokens":19}},"cache":{"hits":1,"misses":1,"bypasses":2,"skippedStores":0}}

নথির প্রশ্ন প্রথমবার miss, দ্বিতীয়বার hit (token 0, cost 0)। portfolio-র প্রশ্নে দুটো call (একটা tool চায়, একটা উত্তর দেয়), দুটোই bypass, মানে cache ছোঁয়া হয়নি। উত্তরটা demo model-এর, আসল model নয়, তাই উত্তরের মান নিয়ে কিছু বলার নেই। container-এর log (প্রতি line-এর scope-prefix ছেঁটে ছোট করা):

health: healthy
uid=1654(app) gid=1654(app) groups=1654(app)
04:03:47 info: FolioLens.Api[0] startup mode=fake models=vendor/primary-model,vendor/backup-model vector_store=memory documents=18 chunks=36
04:03:47 info: Microsoft.Hosting.Lifetime[14] Now listening on: http://[::]:8080
04:03:47 info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down.
04:03:47 info: Microsoft.Hosting.Lifetime[0] Hosting environment: Production
04:03:47 info: Microsoft.Hosting.Lifetime[0] Content root path: /app
04:03:48 info ai.call ok cid=92bcac9d290248ab feature=ask-docs served_by=vendor/primary-model cache=miss tokens_in=395 tokens_out=26 cost=0.000447 ms=33
04:03:49 info ai.call ok cid=0730a6e148fd4bf6 feature=ask-docs served_by=- cache=hit tokens_in=0 tokens_out=0 cost=0 ms=1
04:03:49 info ai.call ok cid=db1a2c727f6b4d6d feature=ask-portfolio served_by=vendor/primary-model cache=bypass tokens_in=66 tokens_out=0 cost=0.000066 ms=15
04:03:49 info ai.call ok cid=db1a2c727f6b4d6d feature=ask-portfolio served_by=vendor/primary-model cache=bypass tokens_in=66 tokens_out=19 cost=0.000104 ms=1

এবার primary model scripted outage-এ (FolioAi__Models__0__FakeBehavior=outage), পরপর তিনটা প্রশ্ন:

$ ask #1 (primary model: scripted outage)
{"calls":[{"outcome":"ok","servedBy":"vendor/backup-model","cache":"miss","cost":0.000241,"tokensIn":442,"tokensOut":20,"ms":932}]}
$ ask #2 (primary model: scripted outage)
{"calls":[{"outcome":"ok","servedBy":"vendor/backup-model","cache":"miss","cost":0.00024,"tokensIn":446,"tokensOut":17,"ms":250}]}
$ ask #3 (primary model: scripted outage)
{"calls":[{"outcome":"ok","servedBy":"vendor/backup-model","cache":"miss","cost":0.0002155,"tokensIn":383,"tokensOut":24,"ms":1}]}
$ curl -s -w "\nHTTP %{http_code}\n" localhost:8080/ready
{"status":"degraded","budgetExhausted":false,"breakers":[{"model":"vendor/primary-model","state":"open","consecutiveFailures":5,"probeAllowedInSeconds":29.8},{"model":"vendor/backup-model","state":"closed","consecutiveFailures":0,"probeAllowedInSeconds":null}],"worstCaseWaitSeconds":90}
HTTP 200

তিনবারই backup model উত্তর দিয়েছে, সময় 932 ms, 250 ms, 1 ms। প্রথমবার primary-তে দুবার fail করে দুবার অপেক্ষা। দ্বিতীয়বার পঞ্চম failure-এ circuit খুলল, তাই বাড়তি অপেক্ষা ছাড়াই backup। তৃতীয়বার সোজা backup। /ready তখন degraded, কিন্তু 200, কারণ backup উত্তর দিতে পারে। log-এও তাই:

04:04:00 warn ai.retry model=vendor/primary-model attempt=1 status=503 wait_ms=450
04:04:00 warn ai.retry model=vendor/primary-model attempt=2 status=503 wait_ms=441
04:04:01 info ai.call ok cid=61d1fbe12bd94d46 feature=ask-docs served_by=vendor/backup-model cache=miss tokens_in=442 tokens_out=20 cost=0.000241 ms=932
04:04:01 warn ai.retry model=vendor/primary-model attempt=1 status=503 wait_ms=245
04:04:01 warn ai.breaker model=vendor/primary-model Closed->Open consecutive_failures=5
04:04:01 info ai.call ok cid=8464de4e2d9c4d13 feature=ask-docs served_by=vendor/backup-model cache=miss tokens_in=446 tokens_out=17 cost=0.00024 ms=250
04:04:01 info ai.call ok cid=d5ddee405fde4208 feature=ask-docs served_by=vendor/backup-model cache=miss tokens_in=383 tokens_out=24 cost=0.0002155 ms=1

দুটো model-ই down হলে:

$ ask (every model down)
HTTP/1.1 503 Service Unavailable
X-Correlation-Id: 26f8c72549c24578
 
{"error":"model_unavailable","correlationId":"26f8c72549c24578"}
 
$ curl -s -w "\nHTTP %{http_code}\n" localhost:8080/ready
{"status":"unavailable","budgetExhausted":false,"breakers":[{"model":"vendor/primary-model","state":"open","consecutiveFailures":2,"probeAllowedInSeconds":29.9},{"model":"vendor/backup-model","state":"open","consecutiveFailures":2,"probeAllowedInSeconds":29.9}],"worstCaseWaitSeconds":90}
HTTP 503
$ curl -s -w "\nHTTP %{http_code}\n" localhost:8080/health
{"status":"ok"}
HTTP 200

liveness সবুজ, readiness 503। ব্যবহারকারী পায় নির্দিষ্ট error ও একটা id। এরপর docker compose up, pgvector-সহ:

$ docker compose ps
NAME          IMAGE                           STATUS
folio-api-1   folio-api:local                 Up 11 seconds (healthy)
folio-db-1    pgvector/pgvector:pg18-trixie   Up 15 seconds (healthy)
 
$ docker compose logs api
Cannot load library libgssapi_krb5.so.2 
Error: libgssapi_krb5.so.2: cannot open shared object file: No such file or directory
04:04:13 info: FolioLens.Api[0] startup mode=fake models=vendor/primary-model,vendor/backup-model vector_store=postgres documents=18 chunks=36
04:04:13 info: Microsoft.Hosting.Lifetime[14] Now listening on: http://[::]:8080
 
$ curl -s -X POST localhost:8080/ask -d {docs question: margin loan}
{"kind":"docs","sources":["rulebook#0","rulebook#1","rulebook#2","rulebook#3"],"cited":["rulebook#0"]}
 
$ psql: what is in PostgreSQL
 chunks | documents 
--------+-----------
     36 |        18
(1 row)
 
 extname | extversion 
---------+------------
 vector  | 0.8.7
(1 row)
 
$ the api container
uid=1654(app) gid=1654(app) groups=1654(app)
read-only root filesystem: true, capabilities dropped: [ALL]

দুটো container-ই healthy, database-এ 18টা নথির 36টা chunk। log-এর শুরুতে libgssapi_krb5-এর একটা error বার্তা আছে। কারণ যাচাই করা হয়নি (সম্ভবত Npgsql-এর GSS lookup), তবু connection ঠিকই হয়েছে। শেষে সব মুছে ফেলা হয়েছে (docker compose down -v, docker rmi)।

CI: ফটক

CI মানে কোড জমা দিলেই স্বয়ংক্রিয়ভাবে build, test আর বাকি check চলা। workflow .github/workflows/ci.yml তিন job-এ ভাগ: build-test-gate (main-এ push-এ ও প্রতি PR-এ), container (image build ও smoke test, মানে চালু করে দেখা যে ওঠে কি না), আর live-eval (রাতে বা হাতে)।

push বা PR key ছাড়া build ও test প্রতি project eval run scripted gate বনাম baseline image build ও smoke test ফটক খোলা merge করা যায় pass pass pass pass ফটক বন্ধ exit 1: merge আটকায় fail test fail nightly live eval key লাগে; এখানে চালানো হয়নি schedule বা হাতে চালানো, কখনো PR-এ নয়
gate (কমলা) fail করলে পুরো job fail। live মাপ আলাদা job, নিজের key-তে।

ফটকের মূল দায়িত্ব দুটি পদক্ষেপে সম্পন্ন হয়: প্রথম পদক্ষেপে সিস্টেম ইভ্যালুয়েশন চালায়—অর্থাৎ সোনার খাতার কন্ট্রাক্ট নোটগুলোর ওপর মডেল এক্সিকিউট করে প্রত্যাশিত সঠিক ফলাফলের সাথে তুলনা করে। দ্বিতীয় পদক্ষেপে গেট রানার নতুন প্রাপ্ত মেট্রিক্সকে পূর্ববর্তী অনুমোদিত বেঞ্চমার্ক বা বেসলাইনের সাথে মিলিয়ে দেখে; যদি নির্ভুলতার হার সীমার নিচে নেমে যায়, তবে প্রসেসটি সাথে সাথে exit code 1 দিয়ে থেমে যায় এবং পিআর মার্জ হওয়া আটকে দেয়।

# The gate. Scripted model: no key, no network, no cost. The profile "prompt-sensitive" behaves like a perfect model
# unless the extraction prompt has lost a rule, so a prompt edit that breaks the rule closes the gate.
- name: Evaluation run (scripted model)
  run: dotnet run -c Release --project src/FolioLens.Eval.Cli -- run --mode fake --profile prompt-sensitive --out report.json
 
- name: Evaluation gate
  run: dotnet run -c Release --project src/FolioLens.Eval.Cli -- gate --report report.json --baseline eval/eval-baseline.json

প্রথম পদক্ষেপটি স্ক্রিপ্টেড ডেমো মডেলে চলে—ফলে এতে কোনো API key, ক্লাউড নেটওয়ার্ক বা অতিরিক্ত আর্থিক খরচের প্রয়োজন হয় না। এখানে প্রশ্ন উঠতে পারে: কেন --profile prompt-sensitive ব্যবহার করা হলো? পর্ব 3-এ তৈরি করা এই ফেইক মডেলটি শতভাগ নির্ভুল ফলাফল দেয়, ঠিক যতক্ষণ পর্যন্ত এক্সট্রাকশন প্রম্পটে ASCII ডিজিট ব্যবহারের নিয়মটি বলবৎ থাকে। যদি অসতর্কতাবশত প্রম্পট এডিটের সময় সেই নিয়মটি মুছে যায়, তবে মডেলটি বাংলা সংখ্যার নোট পড়তে ভুল করে। তাই সিআই পাইপলাইনে এই দ্রুত টেস্টটি আসল মডেলের ক্ষমতা মাপার জন্য নয়, বরং প্রম্পট থেকে কোনো অত্যাবশ্যকীয় রুল মুছে গেছে কি না তা কয়েক মিলিসেকেন্ডের মধ্যে ডিটারমিনিস্টিক উপায়ে যাচাই করার জন্য বসানো হয়েছে। আসল ক্লাউড মডেলের ওপর পূর্ণাঙ্গ মূল্যায়ন চলে রাতের শিডিউলড জবে।

লোকাল মেশিনে গেট সফলভাবে পাস করার বাস্তব আউটপুট:

$ dotnet run -c Release --project src/FolioLens.Eval.Cli -- run --mode fake --profile prompt-sensitive --out report.json
wrote report.json: 25 cases, exact match 1.000, false accepts 0, 332.7 tokens/case
exit code: 0
 
$ dotnet run -c Release --project src/FolioLens.Eval.Cli -- gate --report report.json --baseline eval/eval-baseline.json
PASS  case_count               baseline 25         actual 25         limit >= 25 (the golden set must not shrink)
PASS  exact_match              baseline 1.000      actual 1.000      limit >= 0.950
PASS  field:tradeDate          baseline 1.000      actual 1.000      limit >= 0.950
PASS  outcome_agreement        baseline 1.000      actual 1.000      limit >= 0.950
PASS  false_accepts            baseline 0          actual 0          limit <= 0 (wrong drafts that passed every lock)
PASS  tokens_per_case          baseline 332.68     actual 332.68     limit <= 415.85
GATE: PASS
exit code: 0

প্রতিটি টেস্ট মেট্রিক্সে বেসলাইন মান, বর্তমান প্রাপ্ত মান এবং গ্রহণযোগ্য থ্রেশহোল্ড সীমা পাশাপাশি যাচাই করা হয়। সবকটি চেক PASS হলে সামগ্রিক ফলাফল দাঁড়ায় GATE: PASS (exit code 0)।

সুতো বাঁধা: পর্ব 1-এ আমরা দেখেছিলাম প্রম্পটে একটি শূন্য খসে পড়ে শেয়ারের দর 120.00 থেকে 12.00 হয়ে গিয়েছিল। পর্ব 2-এর business validation সেই ভুলটি আটকে দিয়েছিল। পর্ব 3-এ এর নীরব রূপকে আমরা বলেছিলাম মিথ্যা-গ্রহণ বা ফলস অ্যাকসেপ্ট (False Accept)—যেখানে সব পাহারা ফাঁকি দিয়ে ভুল খসড়া অনুমোদিত হয়ে যায়। ওপরের টেবিলে false_accepts সারির সর্বোচ্চ গ্রহণযোগ্য সীমা হলো 0। ফটকের সবচেয়ে কঠোর নিরাপত্তা অঙ্গীকার এটাই।

এবার সেই বহুল আলোচিত "শুক্রবার বিকেলের অসতর্কতা": প্রোজেক্টের একটি পরীক্ষামূলক ব্রাঞ্চে প্রম্পট থেকে একটিমাত্র লাইন (Write numbers with ASCII digits ...) মুছে সিআই গেট কমান্ড চালানো হলো:

$ dotnet run -c Release --project src/FolioLens.Eval.Cli -- run --mode fake --profile prompt-sensitive --out report.json
wrote report.json: 25 cases, exact match 0.680, false accepts 0, 625.7 tokens/case
exit code: 0
 
$ dotnet run -c Release --project src/FolioLens.Eval.Cli -- gate --report report.json --baseline eval/eval-baseline.json
PASS  mode                     baseline fake       actual fake       limit a fake run is never compared with a live baseline
PASS  case_count               baseline 25         actual 25         limit >= 25 (the golden set must not shrink)
PASS  errors                   baseline 0          actual 0          limit <= 0 (no case may crash)
FAIL  exact_match              baseline 1.000      actual 0.680      limit >= 0.950
FAIL  field:symbol             baseline 1.000      actual 0.680      limit >= 0.950
FAIL  field:side               baseline 1.000      actual 0.680      limit >= 0.950
FAIL  field:quantity           baseline 1.000      actual 0.680      limit >= 0.950
FAIL  field:price              baseline 1.000      actual 0.680      limit >= 0.950
FAIL  field:fees               baseline 1.000      actual 0.680      limit >= 0.950
FAIL  field:tradeDate          baseline 1.000      actual 0.680      limit >= 0.950
FAIL  field:netAmountPrinted   baseline 1.000      actual 0.680      limit >= 0.950
FAIL  outcome_agreement        baseline 1.000      actual 0.680      limit >= 0.950
PASS  false_accepts            baseline 0          actual 0          limit <= 0 (wrong drafts that passed every lock)
FAIL  tokens_per_case          baseline 332.68     actual 625.72     limit <= 415.85
GATE: FAIL
exit code: 1

লাইনটি মুছতেই মডেলের এক্স্যাক্ট ম্যাচ ড্রপ করে 1.000 থেকে 0.680-এ নেমে আসে এবং অতিরিক্ত রিপেয়ারের কারণে টোকেন খরচ প্রায় দ্বিগুণ (625.7) হয়ে যায়। গেট সাথে সাথে লাল বাতি জ্বালিয়ে দেয়: GATE: FAILED (exit code 1)। কোনো খারাপ কোড বা ত্রুটিপূর্ণ প্রম্পট কখনোই ডেভেলপারের লোকাল মেশিন পেরিয়ে প্রোডাকশনের দিকে এক পা-ও এগোতে পারবে না।

GitHub Actions-এ এই ওয়ার্কফ্লোটি কার্যকর করা হয়েছে .github/workflows/ci.yml ফাইলে। প্রতি পুশ ও পুল রিকোয়েস্টে স্ক্রিপ্টেড গেট রান হয়; আর আসল ওপেনরাউটার ক্লাউড মডেলের ওপর লাইভ মূল্যায়ন চালানো হয় প্রতি মধ্যরাতে শিডিউলড ক্রন জবের মাধ্যমে।

GitHub-এর doc অনুযায়ী schedule default branch-এ চলে, default-এ UTC-তে (events doc, secrets doc)।

দৃশ্যপট: কয়েকটা ঘটনা

আমাদের প্রোডাকশন টেস্ট স্যুটে মোট 14টি বাস্তবমুখী ঘটনা ইউনিট ও ইন্টিগ্রেশন টেস্টের মাধ্যমে সার্বক্ষণিক যাচাই করা হয়। নিচে তার মধ্যে ছয়টি প্রধান দৃশ্যপট তুলে ধরা হলো:

#টেস্ট কেসপরিস্থিতি ও সিস্টেমের আচরণ
1rate_limit_stormপরপর দুবার 429 রেট লিমিট এরর, তৃতীয়বারে সফল উত্তর: মোট 3টি কল, এক্সপোনেনশিয়াল ব্যাকঅফ ও জিটার সহ অপেক্ষা
2circuit_opens_and_falls_backপ্রাইমারি প্রোভাইডারে টানা 503 এরর: সার্কিট ওপেন হয়ে সরাসরি ব্যাকআপ মডেলে ট্রাফিক স্থানান্তর
7budget_exhausted_at_3pmদৈনিক বাজেট সীমা অতিক্রম: নতুন মডেল কল প্রত্যাখ্যান, কিন্তু ক্যাশড উত্তর পরিবেশন অব্যাহত
9retry_multiplicationক্লাউড এসডিকে-র নিজস্ব রিট্রাই বন্ধ না করলে 12টি অনাকাঙ্ক্ষিত কল ও 16.9 সেকেন্ডের বিপজ্জনক লেটেন্সি স্পাইক
12Health_checks_during_a_full_outage…উভয় মডেল প্রোভাইডার ডাউন হলে: /health 200 (প্রসেস জীবিত), কিন্তু /ready 503 (ট্রাফিক নিতে অক্ষম)
14regressed_prompt_blocked_by_gateপ্রম্পট থেকে রুল ড্রপ করলে এক্সেপশন ছাড়াই ইভ্যালুয়েশন গেট ফেইল (exit code 1)

দৃশ্যপট 2: সার্কিট ব্রেকার খোলে এবং ফলব্যাক সক্রিয় হয়। সার্কিট ব্রেকারের ফেইলিউর সীমা 5 এবং প্রতিটি কলে সর্বোচ্চ 3 বার চেষ্টা। টেস্টের বাস্তব রানার লগ:

call 1: served_by=vendor/backup, primary_calls=3, circuit=Closed
call 2: served_by=vendor/backup, primary_calls=5, circuit=Open
call 3 (circuit open): served_by=vendor/backup, primary_calls=5, circuit=Open
call 4 (probe after 31 s): served_by=vendor/primary, primary_calls=6, circuit=Closed

প্রথম কলে প্রাইমারিতে 3টি ব্যর্থতা নথিভুক্ত হয়। দ্বিতীয় কলে 5 নম্বর ব্যর্থতা পৌঁছানো মাত্রই সার্কিট ব্রেকার Open স্টেটে চলে যায় এবং তাৎক্ষণিকভাবে ব্যাকআপ মডেলে রুট করে। তৃতীয় কলে প্রাইমারি প্রোভাইডারকে আর কোনো রিকোয়েস্টই পাঠানো হয় না। 31 সেকেন্ড পর সার্কিট টেস্ট প্রোব পাঠায় এবং প্রাইমারি সুস্থ হলে পুনরায় সার্কিট বন্ধ হয়ে স্বাভাবিক অবস্থায় ফিরে আসে।

দৃশ্যপট 7: বাজেট নিঃশেষ। বাজেট সীমা 0.005 ডলার এবং প্রতি কলের খরচ 0.002 ডলার। তৃতীয় কল সফলভাবে সম্পন্ন হওয়ার পর মোট খরচ দাঁড়ায় 0.006 ডলার। ফলে চতুর্থ রিকোয়েস্টে ক্লাউড প্রোভাইডারের কাছে কল পাঠানো পুরোপুরি আটকে দেওয়া হয়; তবে পূর্বে সংরক্ষিত ক্যাশ থেকে গ্রাহক দ্রুত উত্তর পেতে থাকেন।

production-এ কী ভাঙে

বাস্তব প্রোডাকশনে এআই সিস্টেম পরিচালনার সময় এই গভীর ইঞ্জিনিয়ারিং ফাঁদগুলো সতর্কতার সাথে মাথায় রাখতে হবে:

  1. প্রসেস মেমোরিতে স্টেট সংরক্ষণ: আমাদের লেজার, ক্যাশ এবং সার্কিট ব্রেকারের স্টেট বর্তমানে ইন-মেমোরিতে সংরক্ষিত। কুবারনেটিসে একাধিক রেপ্লিকা চালালে প্রতিটি রেপ্লিকা আলাদা বাজেট গণনা করবে এবং পড রিস্টার্ট হলে দৈনিক খরচের কাউন্টার শূন্য হয়ে যাবে। প্রোডাকশনে হাই-স্কেলিংয়ের জন্য এই স্টেটগুলো সেন্ট্রাল ডিস্ট্রিবিউটেড স্টোরে (যেমন: Redis বা Postgres) স্থানান্তর করা আবশ্যক।
  2. ফলব্যাকে মডেলের গুণগত মানের অবনতি: প্রাইমারি মডেল ডাউন হলে যদি অপেক্ষাকৃত সস্তা ব্যাকআপ মডেলে ট্রাফিক পাঠানো হয়, তবে উত্তরের নির্ভুলতা সাময়িকভাবে কমতে পারে। ব্যাকআপ মডেলটি বিজনেসের ন্যূনতম মান রক্ষা করতে পারছে কি না, তা আগে থেকেই ইভ্যালুয়েশন স্যুট দিয়ে যাচাই করে রাখা বাধ্যতামূলক।
  3. বাসি ক্যাশের বিভ্রান্তি: ডিফল্ট ক্যাশের মেয়াদ 1 ঘণ্টা। ক্লাউড প্রোভাইডার যদি একই মডেল নামের আড়ালে ব্যাকএন্ডের ওয়েট বা আচরণ পরিবর্তন করে ফেলে, তবে লোকাল ক্যাশ সেই পরিবর্তন তাৎক্ষণিকভাবে ধরতে পারে না।
  4. সার্কিট ব্রেকারের প্যারামিটার টিউনিং: 5টি ব্যর্থতা এবং 30 সেকেন্ডের কুলডাউন কেবল একটি যুক্তিসঙ্গত ডিফল্ট। কম ট্রাফিকের সিস্টেমে 5টি ফেইলিউর জমতেই কয়েক ঘণ্টা লেগে যেতে পারে। তাই প্রোডাকশনের বাস্তব ট্রাফিক ভলিউম বিশ্লেষণ করে প্যারামিটার ফাইন-টিউন করতে হবে।

production readiness checklist

প্রোডাকশনে ডেপ্লয় করার আগে প্রতিটি ইঞ্জিনিয়ারিং টিমের জন্য আবশ্যক চেকলিস্ট:

অবস্থাচেকলিস্ট আইটেমকীভাবে যাচাই করবেন
☐API key সোর্স কোড ও গিটহাবে নেই; মডেলের নাম ও টোকেন রেট কনফিগারেশনেSecret Manager, FolioAi:Models
☐ক্লাউড এসডিকে-র অবাধ্য রিট্রাই বন্ধ; প্রতিটি চেষ্টার টাইমআউট ও মোট ডেডলাইন কার্যকরLatencyBudget, /ready প্রোব
☐দৈনিক আর্থিক বাজেট ও ফিচারভিত্তিক খরচ ট্র্যাকিং সক্রিয়/usage ড্যাশবোর্ড এন্ডপয়েন্ট
☐রেসপন্স ক্যাশিং ডিফল্টভাবে সুরক্ষিত এবং সুনির্দিষ্ট টিটিএল কনফিগার করাCacheable পলিসি ও মেমোরি সীমা
☐সার্কিট ব্রেকার ও ফলব্যাক সক্রিয়; ব্যাকআপ মডেলের ইভ্যালুয়েশন ভেরিফাইডটেস্ট স্যুট ও ফলব্যাক মেটাবলিজম
☐লগ ফাইলে আসল প্রম্পট, রেসপন্স ও এক্সেপশন স্ট্যাক নেই; সেনসিটিভ ট্রেসিং নিষ্ক্রিয়অডিট লগ ও স্প্যান ট্যাগিং
☐ইন্টারনাল এন্ডপয়েন্ট (/ready, /usage) বাইরের ইন্টারনেটে উন্মুক্ত নয়; ডকার নন-রুটNetwork Security Rules, docker inspect
☐সিআই পাইপলাইনে বিল্ড, টেস্ট ও স্ক্রিপ্টেড ইভ্যালুয়েশন গেট স্বয়ংক্রিয়ভাবে গ্রিনci.yml অ্যাকশন পাইপলাইন
☐মাল্টি-রেপ্লিকা ক্লাস্টারে বাজেট ও সার্কিট ব্রেকারের ডিস্ট্রিবিউটেড স্টেট ডিজাইন নিশ্চিতআর্কিটেকচারাল সাইন-অফ

এখনও যা আপনার করার

দুটি গুরুত্বপূর্ণ দায়িত্ব সফটওয়্যার ডেভেলপার হিসেবে আপনার নিজের হাতে সম্পন্ন করতে হবে:

নিজের API key দিয়ে লাইভ ইভ্যালুয়েশন: পুরো টিউটোরিয়াল সিরিজটি স্ক্রিপ্টেড ও ফেইক মডেলের নিয়ন্ত্রিত পরিবেশে পরিচালিত হয়েছে—যাতে কোনো পাঠককে ক্রেডিট কার্ড বা ক্লাউড বিলের ঝুঁকিতে না পড়তে হয়। সবুজ সিআই গেট প্রমাণ করে আমাদের ফ্রেমওয়ার্ক ও কোড কন্ট্রোল নিখুঁত, কিন্তু আপনার নির্বাচিত আসল ক্লাউড মডেলটি প্রোডাকশনে কতটা বুদ্ধিমান আচরণ করবে তা জানতে আপনাকে নিজস্ব API key দিয়ে --mode live চালাতে হবে এবং নিজস্ব সোনার খাতা প্রসারিত করতে হবে।

ডেটা প্রটেকশন ও রেগুলেটরি কমপ্লায়েন্স: কোন তথ্য ক্লাউড প্রোভাইডারের কাছে পাঠানো যাবে এবং কোনটি প্রাঙ্গণে (on-premise) রাখতে হবে, তা আপনার প্রতিষ্ঠানের অভ্যন্তরীণ ডেটা পলিসি ও দেশের ব্যাংকিং/আর্থিক আইন মেনে নির্ধারণ করতে হবে। এই সিরিজের সমস্ত ডেটা সম্পূর্ণ কাল্পনিক ছিল। এটি কোনো আইনি বা আর্থিক বিনিয়োগ পরামর্শ নয়।

অনুশীলন

  1. সার্কিট ব্রেকার টেস্ট: ডকার কম্পোজে প্রাইমারি মডেলের ফেইক বিহেভিয়ার আউটেজ সেট করুন (FolioAi__Models__0__FakeBehavior=outage)। docker compose logs api পর্যবেক্ষণ করে দেখুন ঠিক কততম রিকোয়েস্টে সার্কিট ওপেন হয় এবং ব্যাকআপ মডেলে ট্রাফিক সুইচ করে।
  2. লেটেন্সি হিসাব: এসডিকে রিট্রাই 3 এবং প্রতি চেষ্টার ব্যাকঅফ দ্বিগুণ করলে সবচেয়ে খারাপ পরিস্থিতিতে ক্লায়েন্টকে কত সেকেন্ড অপেক্ষা করতে হবে, তা লগ দেখে মিলিয়ে নিন।
  3. গেট টেস্ট: এক্সট্রাকশন প্রম্পটে ইচ্ছে করে 20টি অতিরিক্ত উদাহরণ যুক্ত করুন কিন্তু আসল লজিক অপরিবর্তিত রাখুন। ইভ্যালুয়েশন গেট রান করে পর্যবেক্ষণ করুন কীভাবে টোকেন বাজেটের সীমা ভেঙে টেস্ট ফেইল করে।

সেই নোটের পুরো দিন

আমাদের এই দীর্ঘ ইঞ্জিনিয়ারিং যাত্রাটি শুরু হয়েছিল একটি একক ব্রোকার কন্ট্রাক্ট নোট দিয়ে: আলফা টেক লিমিটেড, 200টি শেয়ার, একক দর 120.00 টাকা, এবং নেট মূল্য 24,120.00 টাকা। দশটি গভীর পর্ব জুড়ে সেই নোটটি কীভাবে একটি পরিপক্ব এন্টারপ্রাইজ সিস্টেমের মধ্য দিয়ে যাত্রা করেছে, চলুন সংক্ষেপে তার একটি পূর্ণাঙ্গ চিত্র দেখা যাক:

  1. পর্ব 1, মিটার: মডেলের কাছে আমাদের প্রথম কল, এবং প্রতিটি টোকেনের সূক্ষ্ম হিসাব মিটারে তোলা।
  2. পর্ব 2, ছাঁচ (Schema): মডেলের আউটপুটকে কঠোর টাইপ-সেফ C# অবজেক্টে রূপান্তর এবং কোড দিয়ে হিসাব মেলানো। মডেল শেয়ার দর 12.00 পড়লে কোড সাথে সাথে ভুল ধরে খসড়া বাতিল করে দেয়।
  3. পর্ব 3, সোনার খাতা: হাতে-কলমে যাচাই করা সঠিক উত্তরের টেস্ট সেট (Golden Set) দিয়ে মডেলের নির্ভুলতা বৈজ্ঞানিক সংখ্যায় পরিমাপ করা।
  4. পর্ব 4, কোড গোনে: গাণিতিক হিসাব ও database query-র কাজ মডেলের ওপর না ছেড়ে নির্ভরযোগ্য C# কোড ও টুলের হাতে অর্পণ করা।
  5. পর্ব 5, মানচিত্র: আর্থিক নথিগুলোকে অর্থপূর্ণ chunk-এ ভাগ করে পোস্টগ্রেসের pgvector database-এ বহু-মাত্রিক ভেক্টরে সাজিয়ে রাখা।
  6. পর্ব 6, পাদটীকা: হাইব্রিড সার্চের মাধ্যমে তথ্য উদ্ধার করে প্রতিটি দাবির নিচে অকাট্য সাইটেশনসহ গ্রাউন্ডেড রিপোর্ট প্রস্তুত করা।
  7. পর্ব 7, সই: স্টেট মেশিন ও ট্রানজ্যাকশন দ্বারা সুরক্ষিত ওয়ার্কফ্লো—যেখানে AI শুধুমাত্র প্রস্তাব করে এবং স্বাধীন মানুষ সই করেন।
  8. পর্ব 8, তিন প্রহরী: ইনপুট, টুল এবং আউটপুটে সিকিউরিটি গার্ডরেল স্থাপন, ব্যক্তিগত তথ্য মাস্কিং এবং হ্যাশ-চেইনের অপরিবর্তনীয় অডিট ট্রেইল।
  9. পর্ব 9, ইউএসবি-সি: স্ট্যান্ডার্ড Model Context Protocol সার্ভারের মাধ্যমে টুলগুলোকে যেকোনো এআই অ্যাপ্লিকেশনে প্লাগ-অ্যান্ড-প্লে করার উপযোগী করা।
  10. ফটক (এই পর্ব): ডকার কন্টেইনার, ওপেনটেলিমেট্রি মনিটরিং, সার্কিট ব্রেকার এবং সিআই পাইপলাইনে অটোমেটেড রিগ্রেশন গেট দিয়ে পুরো ইকোসিস্টেমকে সুরক্ষিত করা। প্রম্পটের একটা লাইন মুছে গেলে টেস্ট সবুজ থাকলেও সিআই ফটক লাল বাতি জ্বালিয়ে কোড আটকে দেয়।
ফটক (10): observability · cost · cache · fallback · Docker · CI-তে eval gate তালা 1: AI খসড়া করে তালা 2: কোড যাচাই করে তালা 3: মানুষ সই করে মিটার (1): call, token, cost মানচিত্র (5): আগে খুঁজে আনো ছাঁচ (2): নির্দিষ্ট আকার, যাচাই সোনার খাতা (3): তালা মাপা কোড গোনে (4): অঙ্ক কোডের পাদটীকা (6): উৎসসহ দাবি সই (7): প্রস্তাব, অনুমোদন তিন প্রহরী (8): নথি তথ্য দেয়, হুকুম দেয় না; input, tool, output-এ পাহারা, সঙ্গে audit log ইউএসবি-সি (9): tool একবার বানিয়ে MCP-তে, সবখানে; পাঁচটাই শুধু-পড়ার, বর্ণনা pin করা
ফোলিওলেন্সের পুরো স্থাপত্য: দশটি পর্বের সমস্ত প্রকৌশল উপাদান একটি একক সুসংহত চিত্রে। প্রতিটি স্তর তার পূর্ববর্তী স্তরের ভিত্তির ওপর দাঁড়িয়ে প্রোডাকশন-গ্রেড নির্ভরযোগ্যতা নিশ্চিত করে।

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

মনে রাখুন: টেস্ট না পেরোলে ফটক খোলে না। আর ফটক ততটুকুই পাহারা দেয়, যতটুকু আপনার টেস্ট মাপে। তাই মাপার ঘর বাড়াতে থাকুন।

যাচাইয়ের অবস্থা

  • FolioLens.Observability.Tests-এর 75টি এবং FolioLens.Api.Tests-এর 17টি টেস্ট .NET 10 প্ল্যাটফর্মে শতভাগ সফলভাবে পাস করেছে।
  • ডকার মাল্টি-স্টেজ ইমেজ বিল্ড করে কন্টেইনার ও ডকার কম্পোজ (pgvector সহ) সফলভাবে এক্সিকিউট করা হয়েছে।
  • GitHub Actions পাইপলাইনে build-test-gate জব এবং কন্টেইনারাইজেশন ধাপ সম্পূর্ণ সবুজ হয়ে পাস করেছে।
  • ওপেনটেলিমেট্রি ট্রেসিং এবং ডিস্ট্রিবিউটেড স্প্যান কনভেনশন সম্পূর্ণ স্পেসিফিকেশন মেনে বাস্তবায়িত।

সূত্র

পরের পর্ব

এটি আমাদের সিরিজের দশম ও চূড়ান্ত পর্ব। কিন্তু সফটওয়্যার ইঞ্জিনিয়ারিংয়ে কোনো যাত্রাই আসলে শেষ হয় না; আপনার পরবর্তী ধাপ হলো আপনার নিজস্ব প্রজেক্টে এই প্যাটার্নগুলো প্রয়োগ করা: নিজের মডেল নির্বাচন করা, নিজস্ব ডোমেনের সোনার খাতা তৈরি করা এবং নিজের সিআই পাইপলাইনে নির্ভরযোগ্য রিগ্রেশন গেট স্থাপন করা। প্রোডাকশনের প্রতিটি অপ্রত্যাশিত ভুল যেন একটি নতুন টেস্ট কেস হয়ে আপনার সোনার খাতায় স্থান পায়। আপনার সোনার খাতা সমৃদ্ধ হোক, আপনার ফটক হোক আরও সুদৃঢ়।


সিরিজের পথ: ← পর্ব 9: ইউএসবি-সি · সিরিজের মানচিত্র

দশ পর্ব: 1 মিটার · 2 ছাঁচ · 3 সোনার খাতা · 4 কোড গোনে · 5 মানচিত্র · 6 পাদটীকা · 7 সই · 8 তিন প্রহরী · 9 ইউএসবি-সি · 10 ফটক

Related reading