آموزش کامل یادگیری ماشین با ML.NET از صفر تا صد

⚡ خلاصه سریع — اصل کاری‌ها

این‌ها مهم‌ترین چیزهایی هستن که اگه هیچی ندونی، فقط اینا رو بدونی کافیه:

MLContext: نقطه شروع همه‌چیز است؛ همه عملیات داده، آموزش و ارزیابی با آن انجام می‌شود.
IDataView: قالب داده ستونی بهینه‌شده برای آموزش مدل است؛ از List و DataTable استفاده نکن.
Pipeline: زنجیره‌ای از Transform و Trainer است که داده را آماده و مدل را آموزش می‌دهد.
Fit: مدل را روی داده‌های آموزشی آموزش می‌دهد و Transformer نهایی تولید می‌کند.
Transform: داده‌های جدید را با همان مراحل آماده‌سازی مدل، تبدیل می‌کند.
PredictionEngine: برای پیش‌بینی تک‌داده بعد از آموزش استفاده می‌شود؛ آن را Singleton نگه دار.
TrainTestSplit: داده را به دو بخش آموزش و آزمون تقسیم کن تا مدل را واقعاً بسنجی.
Evaluate: با متریک مناسب (Accuracy/RSquared/AUC) کیفیت مدل را بررسی کن.
Model.Save/Load: مدل را ذخیره و دوباره بارگذاری کن تا هر بار از اول آموزش ندهی.

۳ اشتباه رایج که باید ازشون پرهیز کنی:

استفاده از داده‌های آزمون برای آموزش یا انتخاب مدل (نشت داده).
فراموش کردن اعمال همان Transform های آموزش روی داده جدید.
ساخت مکرر PredictionEngine به ازای هر درخواست (هزینه بالا و thread-safety ضعیف).

اگر فقط ۵ دقیقه وقت داری، این‌ها رو یاد بگیر:

ساخت MLContext و بارگذاری داده با LoadFromEnumerable.
ساخت Pipeline شامل Concatenate + Trainer و اجرای Fit.
ذخیره مدل و استفاده از PredictionEngine برای پیش‌بینی.

۱. مقدمه

ML.NET چیست؟

ML.NET یک چارچوب متن‌باز و چندسکویی مایکروسافت برای یادگیری ماشین و هوش مصنوعی در اکوسیستم .NET است. با ML.NET می‌توانی مدل‌های یادگیری ماشین را با استفاده از زبان C# یا F# بدون نیاز به مهاجرت به پایتون یا ابزارهای دیگر، آموزش دهی، ارزیابی کنی و در برنامه‌های واقعی استفاده کنی.

چرا باید ML.NET را یاد بگیری؟

اگر برنامه‌نویس .NET هستی، می‌توانی بدون تغییر زبان، قابلیت‌های هوش مصنوعی به برنامه‌های خود اضافه کنی.
ML.NET از رگرسیون، طبقه‌بندی، خوشه‌بندی، تشخیص ناهنجاری و حتی مدل‌های TensorFlow پشتیبانی می‌کند.
با .NET یکپارچه شده و از Performance و امنیت بالای .NET بهره می‌برد.
مدل‌ها را می‌توانی به‌سادگی در وب، موبایل، دسکتاپ و سرویس‌های ابری منتشر کنی.

کجا استفاده می‌شود؟

تشخیص احساسات در نظرات کاربران (Sentiment Analysis)
پیش‌بینی قیمت مسکن، فروش یا مصرف انرژی
تشخیص کلاه‌برداری در تراکنش‌های بانکی
سیستم‌های پیشنهاددهنده (Recommendation)
طبقه‌بندی تصاویر و متن
پیش‌بینی ریزش مشتری (Churn Prediction)

۲. پیش‌نیازها

چه چیزهایی باید از قبل بدانی؟

آشنایی مقدماتی با زبان C# (کلاس، متد، LINQ، Generics)
کار با پروژه‌های .NET و NuGet
آشنایی اولیه با مفاهیم یادگیری ماشین (ویژگی، برچسب، مدل) مفید است ولی اجباری نیست.

ابزارهای لازم

.NET SDK نسخه 6 یا بالاتر
Visual Studio 2022 یا Visual Studio Code
دسترسی به NuGet (برای نصب بسته Microsoft.ML)

۳. نصب و راه‌اندازی

گام ۱: نصب .NET SDK

از آدرس رسمی dotnet.microsoft.com نسخه مناسب سیستم‌عامل خود را دانلود و نصب کن.

گام ۲: ساخت پروژه جدید

dotnet new console -n MLNetDemo
cd MLNetDemo

گام ۳: نصب بسته Microsoft.ML

dotnet add package Microsoft.ML

گام ۴: اولین برنامه ساده

در فایل Program.cs کد زیر را بنویس:

using Microsoft.ML;
using Microsoft.ML.Data;

// تعریف یک کلاس داده ساده
public class HouseData
{
    public float Size { get; set; }
    public float Price { get; set; }
}

var mlContext = new MLContext();

var data = new List<HouseData>
{
    new HouseData { Size = 600, Price = 100_000 },
    new HouseData { Size = 800, Price = 120_000 },
    new HouseData { Size = 1000, Price = 150_000 },
    new HouseData { Size = 1200, Price = 180_000 }
};

// تبدیل List به IDataView
IDataView dataView = mlContext.Data.LoadFromEnumerable(data);

// نمایش ساختار داده
var preview = dataView.Preview();
Console.WriteLine($"تعداد ردیف‌ها: {preview.RowView.Length}");
foreach (var row in preview.RowView)
{
    Console.WriteLine(string.Join(", ", row.Values.Select(v => $"{v.Key}: {v.Value}")));
}

اجرا کن:

dotnet run

خروجی باید نشان دهد که داده‌ها به درستی بارگذاری شده‌اند.

۴. مفاهیم پایه

۴.۱ MLContext

MLContext نقطه شروع همه کارها در ML.NET است. این کلاس محیط اجرا، داده، آموزش، ارزیابی و پیش‌بینی را مدیریت می‌کند. معمولاً در برنامه یک بار نمونه‌سازی می‌شود.

var mlContext = new MLContext();

۴.۲ IDataView

IDataView قالب داده ستونی و بهینه برای ML.NET است. شبیه جدول در پایگاه داده است. همه داده‌ها قبل از آموزش باید به IDataView تبدیل شوند.

IDataView dataView = mlContext.Data.LoadFromEnumerable(data);

۴.۳ Transformer و Trainer

Transformer: داده را تبدیل می‌کند. مثال: تبدیل متن به بردار عددی، نرمال‌سازی اعداد.
Trainer: الگوریتم یادگیری ماشین است که مدل را می‌سازد. مثال: رگرسیون خطی، جنگل تصادفی.

Pipeline شامل ترکیبی از Transformer ها و یک Trainer نهایی است.

۴.۴ Pipeline

Pipeline یک زنجیره از Estmatorهاست که با Append ترکیب می‌شوند. ابتدا Transform ها و سپس Trainer می‌آید.

var pipeline = mlContext.Transforms.Concatenate("Features", nameof(HouseData.Size))
    .Append(mlContext.Regression.Trainers.Sdca(labelColumnName: nameof(HouseData.Price), featureColumnName: "Features"));

۴.۵ Fit و Transform

Fit(data) مدل را روی داده آموزش می‌دهد و Transformer نهایی برمی‌گرداند.
Transform(data) داده جدید را با مراحل آموزشی تبدیل می‌کند (مثل همان آماده‌سازی).

ITransformer model = pipeline.Fit(dataView);
IDataView transformed = model.Transform(dataView);

۴.۶ PredictionEngine

برای پیش‌بینی روی یک نمونه جدید، از PredictionEngine استفاده می‌کنیم. بهتر است بعد از ساخت، آن را Singleton نگه داریم.

var engine = mlContext.Model.CreatePredictionEngine<HouseData, HousePrediction>(model);
var prediction = engine.Predict(new HouseData { Size = 900 });

۵. مثال‌های کد ساده

۵.۱ رگرسیون خطی: پیش‌بینی قیمت خانه

کد کامل:

using Microsoft.ML;
using Microsoft.ML.Data;

public class HouseData
{
    public float Size { get; set; }
    public float Price { get; set; }
}

public class HousePrediction
{
    [ColumnName("Score")]
    public float PredictedPrice { get; set; }
}

var mlContext = new MLContext();

var data = new List<HouseData>
{
    new HouseData { Size = 600, Price = 100_000 },
    new HouseData { Size = 800, Price = 120_000 },
    new HouseData { Size = 1000, Price = 150_000 },
    new HouseData { Size = 1200, Price = 180_000 }
};

IDataView dataView = mlContext.Data.LoadFromEnumerable(data);

var pipeline = mlContext.Transforms.Concatenate("Features", nameof(HouseData.Size))
    .Append(mlContext.Regression.Trainers.Sdca(
        labelColumnName: nameof(HouseData.Price),
        featureColumnName: "Features"));

var model = pipeline.Fit(dataView);

var engine = mlContext.Model.CreatePredictionEngine<HouseData, HousePrediction>(model);

var prediction = engine.Predict(new HouseData { Size = 950 });
Console.WriteLine($"قیمت پیش‌بینی شده: {prediction.PredictedPrice:N0}");

توضیح: ابتدا ویژگی Size به بردار Features تبدیل شده، سپس مدل رگرسیون یاد می‌گیرد که Price را پیش‌بینی کند.

۵.۲ طبقه‌بندی دودویی: تشخیص احساسات

کلاس داده و پیش‌بینی:

using Microsoft.ML;
using Microsoft.ML.Data;

public class SentimentData
{
    public string Text { get; set; }
    public bool Label { get; set; }
}

public class SentimentPrediction
{
    [ColumnName("PredictedLabel")]
    public bool PredictedLabel { get; set; }

    [ColumnName("Score")]
    public float Score { get; set; }

    [ColumnName("Probability")]
    public float Probability { get; set; }
}

ساخت داده، pipeline و آموزش:

var mlContext = new MLContext();

var data = new List<SentimentData>
{
    new() { Text = "عالی بود، خیلی راضی هستم", Label = true },
    new() { Text = "بدترین تجربه ممکن بود", Label = false },
    new() { Text = "خوب بود اما می‌تونست بهتر باشه", Label = true },
    new() { Text = "اصلاً پیشنهاد نمی‌کنم", Label = false },
    new() { Text = "فوق‌العاده عالی", Label = true },
    new() { Text = "خیلی ضعیف و ناامیدکننده", Label = false }
};

IDataView dataView = mlContext.Data.LoadFromEnumerable(data);

var pipeline = mlContext.Transforms.Text.FeaturizeText(
        outputColumnName: "Features",
        inputColumnName: nameof(SentimentData.Text))
    .Append(mlContext.BinaryClassification.Trainers.SdcaLogisticRegression(
        labelColumnName: nameof(SentimentData.Label),
        featureColumnName: "Features"));

var model = pipeline.Fit(dataView);

var engine = mlContext.Model.CreatePredictionEngine<SentimentData, SentimentPrediction>(model);
var result = engine.Predict(new SentimentData { Text = "به شدت عالی" });

Console.WriteLine($"پیش‌بینی: {(result.PredictedLabel ? "مثبت" : "منفی")}");
Console.WriteLine($"احتمال: {result.Probability:P0}");

توضیح: FeaturizeText متن را به بردار عددی تبدیل می‌کند و SdcaLogisticRegression مدل طبقه‌بندی را آموزش می‌دهد.

۶. مثال واقعی و کاربردی

پروژه کوچک: تشخیص احساسات نظرات کاربران با ارزیابی و ذخیره مدل

در این پروژه گام به گام یک مدل کامل می‌سازیم، ارزیابی می‌کنیم، ذخیره می‌کنیم و دوباره بارگذاری می‌کنیم.

گام ۱: ساخت پروژه و نصب بسته

dotnet new console -n SentimentApp
cd SentimentApp
dotnet add package Microsoft.ML

گام ۲: تعریف کلاس‌ها

public class SentimentData
{
    public string Text { get; set; }
    public bool Label { get; set; }
}

public class SentimentPrediction
{
    [ColumnName("PredictedLabel")]
    public bool PredictedLabel { get; set; }

    [ColumnName("Score")]
    public float Score { get; set; }

    [ColumnName("Probability")]
    public float Probability { get; set; }
}

گام ۳: ساخت نمونه داده‌ها

var data = new List<SentimentData>
{
    new() { Text = "این محصول فوق العاده است", Label = true },
    new() { Text = "کیفیت خوبی داره و قیمت مناسبه", Label = true },
    new() { Text = "بسته بندی عالی و ارسال سریع", Label = true },
    new() { Text = "اصلاً راضی نیستم", Label = false },
    new() { Text = "خیلی بد بود، پشیمون شدم", Label = false },
    new() { Text = "کیفیت پایین و بد", Label = false },
    new() { Text = "خوب بود ولی انتظار بیشتری داشتم", Label = true },
    new() { Text = "بی‌نهایت ناامیدکننده", Label = false },
    new() { Text = "پیشنهاد می‌کنم حتماً بخرید", Label = true },
    new() { Text = "افتضاح بود", Label = false }
};

گام ۴: بارگذاری داده و تقسیم آموزش/آزمون

var mlContext = new MLContext();
IDataView dataView = mlContext.Data.LoadFromEnumerable(data);

var split = mlContext.Data.TrainTestSplit(dataView, testFraction: 0.3, seed: 42);
IDataView trainData = split.TrainSet;
IDataView testData = split.TestSet;

گام ۵: ساخت Pipeline

var pipeline = mlContext.Transforms.Text.FeaturizeText(
        outputColumnName: "Features",
        inputColumnName: nameof(SentimentData.Text))
    .Append(mlContext.BinaryClassification.Trainers.SdcaLogisticRegression(
        labelColumnName: nameof(SentimentData.Label),
        featureColumnName: "Features"));

گام ۶: آموزش و ارزیابی

ITransformer model = pipeline.Fit(trainData);

var predictions = model.Transform(testData);
var metrics = mlContext.BinaryClassification.Evaluate(predictions, labelColumnName: nameof(SentimentData.Label));

Console.WriteLine($"Accuracy: {metrics.Accuracy:P2}");
Console.WriteLine($"AUC: {metrics.AreaUnderRocCurve:P2}");
Console.WriteLine($"F1 Score: {metrics.F1Score:P2}");

گام ۷: ذخیره مدل

string modelPath = Path.Combine(Directory.GetCurrentDirectory(), "sentiment_model.zip");
mlContext.Model.Save(model, trainData.Schema, modelPath);
Console.WriteLine($"مدل ذخیره شد: {modelPath}");

گام ۸: بارگذاری و استفاده در برنامه واقعی

ITransformer loadedModel = mlContext.Model.Load(modelPath, out var schema);
var engine = mlContext.Model.CreatePredictionEngine<SentimentData, SentimentPrediction>(loadedModel);

var userText = "این محصول واقعاً خوبه";
var result = engine.Predict(new SentimentData { Text = userText });

Console.WriteLine($"متن: {userText}");
Console.WriteLine($"نظر: {(result.PredictedLabel ? "مثبت" : "منفی")}");
Console.WriteLine($"احتمال: {result.Probability:P0}");

توضیح: این یک جریان کامل واقعی است: ساخت داده، تقسیم، آموزش، ارزیابی، ذخیره و پیش‌بینی.

۷. مباحث پیشرفته

۷.۱ Cross-Validation

به جای یک بار تقسیم داده، می‌توانی اعتبارسنجی متقاطع انجام دهی تا مطمئن شوی مدل پایدار است.

var cvResults = mlContext.BinaryClassification.CrossValidateNonCalibrated(
    dataView,
    pipeline,
    numberOfFolds: 5,
    labelColumnName: nameof(SentimentData.Label),
    seed: 42);

foreach (var result in cvResults)
{
    Console.WriteLine($"Fold Accuracy: {result.Metrics.Accuracy:P2}");
}
Console.WriteLine($"میانگین Accuracy: {cvResults.Average(r => r.Metrics.Accuracy):P2}");

۷.۲ Feature Engineering

Normalization: مقیاس‌سازی ویژگی‌های عددی.

mlContext.Transforms.NormalizeMinMax(outputColumnName: "NormalizedSize", inputColumnName: nameof(HouseData.Size));

One-Hot Encoding: تبدیل مقادیر دسته‌ای به ستون‌های دودویی.

mlContext.Transforms.Categorical.OneHotEncoding(outputColumnName: "CategoryEncoded", inputColumnName: nameof(Product.Category));

Text Featurization: استخراج n-gram یا TF-IDF.

mlContext.Transforms.Text.FeaturizeText(outputColumnName: "Features",
    new Microsoft.ML.Transforms.Text.TextFeaturizingEstimator.Options
    {
        WordFeatureExtractor = new Microsoft.ML.Transforms.Text.WordBagEstimator.Options { NgramLength = 2 }
    },
    inputColumnNames: nameof(SentimentData.Text));

۷.۳ AutoML

با AutoML می‌توانی بدون دانش عمیق، بهترین مدل را خودکار انتخاب کنی.

using Microsoft.ML.AutoML;

var experiment = mlContext.Auto().CreateBinaryClassificationExperiment(maxModels: 20);
var result = experiment.Execute(
    trainData: trainData,
    labelColumnName: nameof(SentimentData.Label),
    progressHandler: new Progress<RunDetail<BinaryClassificationMetrics>>(update =>
    {
        if (update.TrainerName != null)
            Console.WriteLine($"{update.TrainerName}: {update.Metrics.Accuracy:P2}");
    }));

۷.۴ مدل‌های TensorFlow

ML.NET می‌تواند مدل‌های TensorFlow یا ONNX را مصرف کند.

var pipeline = mlContext.Model.LoadTensorFlowModel("model.pb")
    .ScoreTensorFlowModel(outputColumnNames: new[] { "dense_1/Softmax" }, inputColumnNames: new[] { "input" });

۷.۵ بهینه‌سازی

از Cache قبل از trainer برای داده‌های کوچک استفاده کن.
تعداد تکرار (epoch) و regularize را برای جلوگیری از overfit تنظیم کن.
برای داده‌های حجیم از trainers با streaming پشتیبانی کن.
تا حد امکان از PredictionEnginePool در ASP.NET Core برای مدیریت thread-safe استفاده کن.

۸. اشتباهات رایج

نشت داده (Data Leakage): استفاده از داده‌های آزمون در آموزش یا پیش‌پردازش.
فراموشی اعمال Transform ها: بعد از آموزش مدل، روی داده جدید فقط Predict می‌زنید اما فراموش می‌کنید همان پاک‌سازی/تبدیل متن یا نرمال‌سازی را انجام دهید.
مقیاس‌سازی نکردن ویژگی‌های عددی: برخی الگوریتم‌ها مثل SVM یا k-means به مقیاس حساس‌اند.
استفاده از متن خام بدون FeaturizeText: متن باید به بردار عددی تبدیل شود وگرنه trainer خطا می‌دهد.
ارزیابی نکردن مدل: فقط آموزش و سپس پیش‌بینی کافی نیست؛ همیشه Accuracy/RMSE/AUC را بسنج.
ساخت PredictionEngine به ازای هر درخواست: این کار very slow است و thread-safe ضعیف دارد.
استفاده از یک مدل برای همه انواع پیش‌بینی: هر مسئله (رگرسیون، طبقه‌بندی) متریک و trainer متفاوت دارد.
نادیده گرفتن تعادل کلاس‌ها: در طبقه‌بندی اگر کلاس‌ها نامتوازن باشند، Accuracy گمراه‌کننده است.

۹. بهترین روش‌ها (Best Practices)

همیشه داده را به آموزش/آزمون تقسیم کن و از داده‌های آزمون فقط برای ارزیابی نهایی استفاده کن.
Pipeline خود را مجدداً استفاده کن: Pipeline آموزش‌دیده را ذخیره کن تا مراحل Transform حفظ شود.
از PredictionEnginePool در ASP.NET Core استفاده کن تا به صورت thread-safe مدیریت شود.
مدل را ذخیره و بارگذاری کن تا در محیط Production سریع راه‌اندازی شود.
برای داده‌های بزرگ از streaming و caching مناسب استفاده کن.
کنترل خطا: تمام Exception های ممکن در خواندن داده و ذخیره مدل را مدیریت کن.
متریک مناسب انتخاب کن: در رگرسیون RMSE/RSquared، در طبقه‌بندی Accuracy/AUC/F1.
از Cross-Validation برای تنظیم Hyperparameter استفاده کن.
Versioning مدل: تاریخ و نسخه مدل را در نام فایل ذخیره کن.

۱۰. منابع و ادامه مسیر

۱۱. مرجع کامل توابع و متدها (API Deep Dive)

در این بخش ۱۱ متد و کلاس کلیدی ML.NET را عمیق بررسی می‌کنیم.

📌 متد: `MLContext.Data.LoadFromEnumerable<T>()`

امضای متد (Signature):

IDataView LoadFromEnumerable<T>(IEnumerable<T> data, DataViewSchema.Annotations annotations = null)

ورودی‌ها (Parameters):

نام پارامتر	نوع	اجباری؟	توضیح دقیق	مثال مقدار
`data`	`IEnumerable<T>`	بله	مجموعه‌ای از اشیاء نوع `T` که قرار است به `IDataView` تبدیل شود.	`List<HouseData>`
`annotations`	`DataViewSchema.Annotations`	خیر	اطلاعات متادیتای سفارشی برای ستون‌ها. پیش‌فرض `null` است.	`null`

مقدار برگشتی (Return Value):

نوع: IDataView
توضیح: یک نمای داده‌ی ستونی که می‌تواند برای آموزش یا تبدیل استفاده شود.
در صورتی که data خالی باشد، IDataView بدون ردیف برمی‌گرداند.

کاری که انجام می‌ده (گام به گام):

با استفاده از Reflection ساختار کلاس T را بررسی و ستون‌ها را استخراج می‌کند.
از هر شیء یک ردیف در IDataView ایجاد می‌کند.
مقادیر خصوصیت‌ها را به ستون‌های متناظر اختصاص می‌دهد و IDataView برمی‌گرداند.

مثال ساده و قابل اجرا:

var mlContext = new MLContext();
var data = new List<HouseData>
{
    new() { Size = 600, Price = 100_000 }
};
IDataView dataView = mlContext.Data.LoadFromEnumerable(data);
var preview = dataView.Preview();
Console.WriteLine($"تعداد ردیف‌ها: {preview.RowView.Length}");

خروجی:

تعداد ردیف‌ها: 1

مثال واقعی و کاربردی:

var users = iqDbContext.Users.ToList();
IDataView dataView = mlContext.Data.LoadFromEnumerable(users);
var model = pipeline.Fit(dataView);

خطاها و Exceptions احتمالی:

Exception	زمان رخ دادن	راه‌حل
`ArgumentNullException`	اگر `data` برابر `null` باشد.	قبل از فراخوانی، بررسی کن `data != null`.
`InvalidOperationException`	اگر دو ستون با نام یکسان در کلاس تعریف شده باشند.	نام خصوصیت‌ها را منحصر به فرد کن.

Overloadها:

IDataView LoadFromEnumerable<T>(IEnumerable<T> data, DataViewSchema.Annotations annotations = null)
IDataView LoadFromEnumerable<T>(IEnumerable<T> data, SchemaDefinition schemaDefinition = null, DataViewSchema.Annotations annotations = null)

اشتباهات رایج:

❌ استفاده از List<object> یا anonymous type به جای کلاس مشخص.
✅ استفاده از کلاس با خصوصیت‌های عمومی و getter/setter.

متدهای مرتبط:

LoadFromTextFile<T>: بارگذاری از فایل متنی.
LoadFromBinary: بارگذاری از فایل باینری.
CreateEnumerable<T>: تبدیل IDataView به IEnumerable<T>.

📌 متد: `MLContext.Data.TrainTestSplit()`

امضای متد (Signature):

TrainTestData TrainTestSplit(IDataView data, double testFraction = 0.1, string samplingKey = null, int? seed = null)

ورودی‌ها (Parameters):

نام پارامتر	نوع	اجباری؟	توضیح دقیق	مثال مقدار
`data`	`IDataView`	بله	داده ورودی که باید تقسیم شود.	`dataView`
`testFraction`	`double`	خیر	نسبت داده‌های آزمون؛ بین 0 تا 1. پیش‌فرض 0.1.	`0.3`
`samplingKey`	`string`	خیر	نام ستون برای نمونه‌گیری طبقه‌بندی‌شده؛ اگر null باشد تصادفی ساده.	`null`
`seed`	`int?`	خیر	بذر عدد تصادفی برای بازتولیدپذیری.	`42`

مقدار برگشتی (Return Value):

نوع: TrainTestData
توضیح: شی‌ای شامل دو IDataView به نام‌های TrainSet و TestSet.
اگر testFraction=0، بخش آزمون خالی است.

کاری که انجام می‌ده (گام به گام):

ردیف‌های داده را به صورت تصادفی یا بر اساس samplingKey مرتب می‌کند.
داده را به دو بخش آموزش و آزمون با نسبت مشخص تقسیم می‌کند.
یک TrainTestData برمی‌گرداند.

مثال ساده و قابل اجرا:

var split = mlContext.Data.TrainTestSplit(dataView, testFraction: 0.2, seed: 123);
Console.WriteLine($"Train rows: {split.TrainSet.Preview().RowView.Length}");
Console.WriteLine($"Test rows: {split.TestSet.Preview().RowView.Length}");

خروجی:

Train rows: 8
Test rows: 2

مثال واقعی و کاربردی:

var split = mlContext.Data.TrainTestSplit(dataView, testFraction: 0.25, seed: 42);
ITransformer model = pipeline.Fit(split.TrainSet);
var metrics = mlContext.BinaryClassification.Evaluate(model.Transform(split.TestSet), labelColumnName: "Label");

خطاها و Exceptions احتمالی:

Exception	زمان رخ دادن	راه‌حل
`ArgumentOutOfRangeException`	اگر `testFraction` خارج از بازه [0,1] باشد.	مقدار معتبر بده.
`ArgumentNullException`	اگر `data` null باشد.	داده را بارگذاری کن.

Overloadها:

TrainTestData TrainTestSplit(IDataView data, double testFraction = 0.1, string samplingKey = null, int? seed = null, bool stratify = false)

اشتباهات رایج:

❌ استفاده از testFraction=0.5 برای داده‌های کوچک؛ باعث آموزش ضعیف می‌شود.
✅ برای داده‌های کوچک از testFraction=0.2 یا 0.3 استفاده کن.

متدهای مرتبط:

CrossValidate: اعتبارسنجی متقاطع.
BootstrapSample: نمونه‌گیری با جایگذاری.
ShuffleRows: جابجایی تصادفی ردیف‌ها.

📌 متد: `MLContext.Transforms.Concatenate()`

امضای متد (Signature):

ColumnConcatenatingEstimator Concatenate(string outputColumnName, params string[] inputColumnNames)

ورودی‌ها (Parameters):

نام پارامتر	نوع	اجباری؟	توضیح دقیق	مثال مقدار
`outputColumnName`	`string`	بله	نام ستون خروجی که بردار ویژگی‌ها را شامل می‌شود.	`"Features"`
`inputColumnNames`	`string[]`	بله	نام ستون‌های ورودی که باید ادغام شوند.	`"Size"`، `"Bedrooms"`

مقدار برگشتی (Return Value):

نوع: ColumnConcatenatingEstimator
توضیح: یک Estimator که با اعمال Fit، ستون‌ها را به یک بردار عددی تبدیل می‌کند.

کاری که انجام می‌ده (گام به گام):

ستون‌های ورودی را از نظر نوع بررسی می‌کند (معمولاً عددی).
در زمان Transform، مقادیر را به هم متصل کرده و یک بردار Vector<Single> می‌سازد.
خروجی را در ستون مشخص‌شده ذخیره می‌کند.

مثال ساده و قابل اجرا:

var pipeline = mlContext.Transforms.Concatenate("Features", nameof(HouseData.Size), nameof(HouseData.MonthlyTax));

خروجی:

Features = [600, 1500]

مثال واقعی و کاربردی:

var pipeline = mlContext.Transforms.Concatenate("Features",
        nameof(Customer.Age),
        nameof(Customer.Income),
        nameof(Customer.Recency))
    .Append(mlContext.Clustering.Trainers.KMeans(featureColumnName: "Features"));

خطاها و Exceptions احتمالی:

Exception	زمان رخ دادن	راه‌حل
`ArgumentNullException`	اگر `outputColumnName` null باشد.	نام ستون را مشخص کن.
`InvalidOperationException`	اگر ستون‌های ورودی وجود نداشته باشند یا نوع غیرعددی باشند.	از `Categorical.OneHotEncoding` برای متنی/دسته‌ای استفاده کن.

Overloadها:

ColumnConcatenatingEstimator Concatenate(string outputColumnName, IEnumerable<string> inputColumnNames)

اشتباهات رایج:

❌ استفاده از نام خروجی یکسان با یک ستون ورودی؛ باعث overwrite می‌شود.
✅ همیشه یک نام خروجی جدید مثل "Features" انتخاب کن.

متدهای مرتبط:

NormalizeMinMax: مقیاس‌سازی قبل از Concatenate.
Categorical.OneHotEncoding: تبدیل دسته‌ای به عددی.

📌 متد: `MLContext.Transforms.Text.FeaturizeText()`

امضای متد (Signature):

TextFeaturizingEstimator FeaturizeText(string outputColumnName, params string[] inputColumnNames)

ورودی‌ها (Parameters):

نام پارامتر	نوع	اجباری؟	توضیح دقیق	مثال مقدار
`outputColumnName`	`string`	بله	نام ستون خروجی بردار متن.	`"Features"`
`inputColumnNames`	`string[]`	بله	نام ستون(های) ورودی متنی.	`"Text"`

مقدار برگشتی (Return Value):

نوع: TextFeaturizingEstimator
توضیح: یک Estimator که متن را به بردار عددی (Vector<Single>) تبدیل می‌کند.

کاری که انجام می‌ده (گام به گام):

متن را tokenize و نرمال‌سازی می‌کند.
از n-gram و TF-IDF یا Bag-of-Words استفاده می‌کند.
بردار ویژگی عددی ایجاد می‌کند.

مثال ساده و قابل اجرا:

var pipeline = mlContext.Transforms.Text.FeaturizeText("Features", nameof(SentimentData.Text));

خروجی: (مفهومی)

Text = "good product" => Features = [0.5, 0.2, ...]

مثال واقعی و کاربردی:

var pipeline = mlContext.Transforms.Text.FeaturizeText(
        outputColumnName: "Features",
        new TextFeaturizingEstimator.Options
        {
            WordFeatureExtractor = new WordBagEstimator.Options { NgramLength = 2 }
        },
        inputColumnNames: nameof(TextData.Title))
    .Append(mlContext.Clustering.Trainers.KMeans(featureColumnName: "Features"));

خطاها و Exceptions احتمالی:

Exception	زمان رخ دادن	راه‌حل
`ArgumentNullException`	اگر `outputColumnName` null باشد.	نام ستون را بده.
`InvalidOperationException`	اگر ستون ورودی نوع `Text` نباشد.	مطمئن شو ستون متنی است.

Overloadها:

TextFeaturizingEstimator FeaturizeText(string outputColumnName, TextFeaturizingEstimator.Options options, params string[] inputColumnNames)

اشتباهات رایج:

❌ استفاده از FeaturizeText روی ستون عددی؛ خطا می‌دهد.
✅ فقط برای متن استفاده کن.

متدهای مرتبط:

NormalizeText: پاک‌سازی و نرمال‌سازی متن.
ApplyWordEmbedding: استفاده از word2vec.
TokenizeIntoWords: تبدیل به توکن.

📌 متد: `MLContext.Regression.Trainers.Sdca()`

امضای متد (Signature):

SdcaRegressionTrainer Sdca(string labelColumnName = "Label", 
                           string featureColumnName = "Features", 
                           string exampleWeightColumnName = null,
                           Microsoft.ML.Trainers.ISupportSdcaRegressionLoss loss = null,
                           float? l2Regularization = null,
                           float? l1Regularization = null,
                           int? maxIterations = null)

ورودی‌ها (Parameters):

نام پارامتر	نوع	اجباری؟	توضیح دقیق	مثال مقدار
`labelColumnName`	`string`	خیر	نام ستون برچسب (هدف). پیش‌فرض `"Label"`.	`"Price"`
`featureColumnName`	`string`	خیر	نام ستون ویژگی‌ها. پیش‌فرض `"Features"`.	`"Features"`
`exampleWeightColumnName`	`string`	خیر	ستون وزن نمونه‌ها برای یادگیری وزن‌دار.	`null`
`loss`	`ISupportSdcaRegressionLoss`	خیر	تابع خطا برای رگرسیون. پیش‌فرض `SquaredLoss`.	`new SquaredLoss()`
`l2Regularization`	`float?`	خیر	ضریب منظمسازی L2 برای جلوگیری از overfit.	`0.01f`
`l1Regularization`	`float?`	خیر	ضریب منظمسازی L1.	`0.01f`
`maxIterations`	`int?`	خیر	حداکثر تعداد تکرارها.	`100`

مقدار برگشتی (Return Value):

نوع: SdcaRegressionTrainer
توضیح: یک Trainer که مدل رگرسیون خطی (و انواع loss) را آموزش می‌دهد.

کاری که انجام می‌ده (گام به گام):

از الگوریتم Stochastic Dual Coordinate Ascent برای بهینه‌سازی خطی استفاده می‌کند.
روی داده‌های آموزش Fit شده و وزن‌ها را محاسبه می‌کند.
مدل نهایی که بتواند خروجی عددی پیش‌بینی کند تولید می‌کند.

مثال ساده و قابل اجرا:

var trainer = mlContext.Regression.Trainers.Sdca(
    labelColumnName: nameof(HouseData.Price),
    featureColumnName: "Features");

مثال واقعی و کاربردی:

var pipeline = mlContext.Transforms.Concatenate("Features", nameof(SalesData.Marketing), nameof(SalesData.Budget))
    .Append(mlContext.Regression.Trainers.Sdca(
        labelColumnName: nameof(SalesData.Sales),
        featureColumnName: "Features",
        maxIterations: 200));

خطاها و Exceptions احتمالی:

Exception	زمان رخ دادن	راه‌حل
`InvalidOperationException`	اگر ستون label یا features یافت نشود یا نوعش اشتباه باشد.	نام ستون‌ها را بررسی کن.

Overloadها:

SdcaRegressionTrainer Sdca(string labelColumnName = "Label", string featureColumnName = "Features")

اشتباهات رایج:

❌ استفاده از Sdca برای طبقه‌بندی چندکلاسه؛ خطا می‌دهد.
✅ برای رگرسیون از Sdca و برای طبقه‌بندی از SdcaLogisticRegression استفاده کن.

متدهای مرتبط:

FastTree: رگرسیون درختی.
OnlineGradientDescent: رگرسیون آنلاین.
LightGbm: رگرسیون پیشرفته.

📌 متد: `MLContext.BinaryClassification.Trainers.SdcaLogisticRegression()`

امضای متد (Signature):

SdcaLogisticRegressionTrainer SdcaLogisticRegression(string labelColumnName = "Label",
                                                      string featureColumnName = "Features",
                                                      string exampleWeightColumnName = null,
                                                      float? l2Regularization = null,
                                                      float? l1Regularization = null,
                                                      int? maxIterations = null)

ورودی‌ها (Parameters):

نام پارامتر	نوع	اجباری؟	توضیح دقیق	مثال مقدار
`labelColumnName`	`string`	خیر	ستون برچسب دودویی (true/false).	`"Label"`
`featureColumnName`	`string`	خیر	ستون ویژگی‌ها.	`"Features"`
`exampleWeightColumnName`	`string`	خیر	وزن نمونه‌ها.	`null`
`l2Regularization`	`float?`	خیر	تنظیم L2.	`0.01f`
`l1Regularization`	`float?`	خیر	تنظیم L1.	`0.01f`
`maxIterations`	`int?`	خیر	حداکثر تعداد تکرارها.	`100`

مقدار برگشتی (Return Value):

نوع: SdcaLogisticRegressionTrainer
توضیح: یک Trainer برای طبقه‌بندی دودویی که احتمال و Label را تولید می‌کند.

کاری که انجام می‌ده (گام به گام):

مدل رگرسیون لجستیک را با الگوریتم SDCA آموزش می‌دهد.
تابع سیگموئید را برای تولید احتمال اعمال می‌کند.
خروجی شامل Score، Probability و PredictedLabel است.

مثال ساده و قابل اجرا:

var trainer = mlContext.BinaryClassification.Trainers.SdcaLogisticRegression(
    labelColumnName: "Label",
    featureColumnName: "Features");

مثال واقعی و کاربردی:

var pipeline = mlContext.Transforms.Text.FeaturizeText("Features", nameof(SentimentData.Text))
    .Append(mlContext.BinaryClassification.Trainers.SdcaLogisticRegression(
        labelColumnName: nameof(SentimentData.Label),
        featureColumnName: "Features",
        maxIterations: 200));

خطاها و Exceptions احتمالی:

Exception	زمان رخ دادن	راه‌حل
`InvalidOperationException`	اگر label column از نوع bool نباشد.	نوع برچسب را `bool` تعریف کن.
`InvalidOperationException`	اگر feature column بردار عددی نباشد.	`Concatenate` یا `FeaturizeText` را اضافه کن.

Overloadها:

SdcaLogisticRegressionTrainer SdcaLogisticRegression(string labelColumnName = "Label", string featureColumnName = "Features")

اشتباهات رایج:

❌ استفاده از این متد برای رگرسیون (خروجی پیوسته) به اشتباه.
✅ برای رگرسیون از Regression.Trainers.Sdca استفاده کن.

متدهای مرتبط:

AveragedPerceptron: طبقه‌بندی خطی ساده.
FastTree: طبقه‌بندی درختی.
LightGbm: طبقه‌بندی با گرادیان تقویتی.

📌 متد: `IEstimator<TTransformer>.Fit()`

امضای متد (Signature):

TTransformer Fit(IDataView input)

ورودی‌ها (Parameters):

نام پارامتر	نوع	اجباری؟	توضیح دقیق	مثال مقدار
`input`	`IDataView`	بله	داده آموزشی که مدل روی آن آموزش می‌بیند.	`trainData`

مقدار برگشتی (Return Value):

نوع: TTransformer
توضیح: مدل آموزش‌دیده که شامل تمام مراحل Pipeline است و می‌تواند داده جدید را Transform کند.

کاری که انجام می‌ده (گام به گام):

تمام Estimator های Pipeline را به ترتیب روی داده اعمال می‌کند.
پارامترهای هر Transformer و Trainer را محاسبه و تنظیم می‌کند.
یک TransformerChain یا Transformer نهایی برمی‌گرداند.

مثال ساده و قابل اجرا:

ITransformer model = pipeline.Fit(trainData);

مثال واقعی و کاربردی:

ITransformer trainedModel = mlContext.Transforms.Concatenate("Features", nameof(Product.Price), nameof(Product.Weight))
    .Append(mlContext.Clustering.Trainers.KMeans(featureColumnName: "Features"))
    .Fit(dataView);

خطاها و Exceptions احتمالی:

Exception	زمان رخ دادن	راه‌حل
`InvalidOperationException`	اگر ستون‌های مورد نیاز Transform یا Trainer وجود نداشته باشند یا نوع آن‌ها اشتباه باشد.	schema داده را با `Preview` یا `Schema` بررسی کن.
`ArgumentNullException`	اگر `input` null باشد.	داده را بارگذاری کن.

Overloadها:

// معمولاً نسخه اصلی:
TTransformer Fit(IDataView input)

اشتباهات رایج:

❌ فراخوانی Fit روی داده آزمون؛ باعث نشت داده می‌شود.
✅ همیشه Fit را فقط با TrainSet انجام بده.

متدهای مرتبط:

Transform: اعمال مدل بر داده جدید.
GetOutputSchema: دریافت schema خروجی بدون آموزش.

📌 متد: `MLContext.Model.CreatePredictionEngine<TSrc,TDst>()`

امضای متد (Signature):

PredictionEngine<TSrc,TDst> CreatePredictionEngine<TSrc,TDst>(ITransformer model, DataViewSchema inputSchema = null)

ورودی‌ها (Parameters):

نام پارامتر	نوع	اجباری؟	توضیح دقیق	مثال مقدار
`model`	`ITransformer`	بله	مدل آموزش‌دیده.	`trainedModel`
`inputSchema`	`DataViewSchema`	خیر	schema ورودی صریح. اگر null باشد از نوع `TSrc` ساخته می‌شود.	`trainData.Schema`

مقدار برگشتی (Return Value):

نوع: PredictionEngine<TSrc,TDst>
توضیح: موتور پیش‌بینی تک‌داده که TSrc را به TDst تبدیل می‌کند.

کاری که انجام می‌ده (گام به گام):

یک pipeline سبک از مدل و schema می‌سازد.
برای هر درخواست Predict، داده را Transform کرده و خروجی را به TDst نگاشت می‌کند.
برای عملکرد بهتر باید singleton باشد.

مثال ساده و قابل اجرا:

var engine = mlContext.Model.CreatePredictionEngine<HouseData, HousePrediction>(trainedModel);

مثال واقعی و کاربردی:

services.AddSingleton(sp =>
{
    var model = sp.GetRequiredService<ITransformer>();
    return model;
});
// استفاده در controller
var engine = provider.GetRequiredService<PredictionEngine<SentimentData, SentimentPrediction>>();

خطاها و Exceptions احتمالی:

Exception	زمان رخ دادن	راه‌حل
`ArgumentNullException`	اگر `model` null باشد.	مدل را ابتدا آموزش/بارگذاری کن.
`InvalidOperationException`	اگر type `TSrc` با schema مدل هماهنگ نباشد.	از کلاس داده صحیح استفاده کن.

Overloadها:

PredictionEngine<TSrc,TDst> CreatePredictionEngine<TSrc,TDst>(ITransformer model, DataViewSchema inputSchema = null)
PredictionEngine<TSrc,TDst> CreatePredictionEngine<TSrc,TDst>(ITransformer model, SchemaDefinition inputSchemaDefinition = null)

اشتباهات رایج:

❌ ساخت PredictionEngine به ازای هر درخواست؛ overhead بزرگی دارد.
✅ آن را به عنوان Singleton یا از PredictionEnginePool استفاده کن.

متدهای مرتبط:

Predict: انجام پیش‌بینی.
PredictionEnginePool: مدیریت Pool در ASP.NET Core.
Load: بارگذاری مدل.

📌 متد: `PredictionEngine<TSrc,TDst>.Predict()`

امضای متد (Signature):

TDst Predict(TSrc example)

ورودی‌ها (Parameters):

نام پارامتر	نوع	اجباری؟	توضیح دقیق	مثال مقدار
`example`	`TSrc`	بله	نمونه ورودی برای پیش‌بینی.	`new HouseData { Size = 850 }`

مقدار برگشتی (Return Value):

نوع: TDst
توضیح: شیء خروجی شامل پیش‌بینی (مانند Score، PredictedLabel، Probability).
هیچ‌وقت null برنمی‌گرداند مگر آن‌که mapping خطا داشته باشد.

کاری که انجام می‌ده (گام به گام):

نمونه را به IDataView تک‌ردیفی تبدیل می‌کند.
مدل Transform را روی آن اعمال می‌کند.
نتایج را به خصوصیت‌های TDst نگاشت می‌کند و برمی‌گرداند.

مثال ساده و قابل اجرا:

var result = engine.Predict(new SentimentData { Text = "I love this product!" });
Console.WriteLine($"PredictedLabel: {result.PredictedLabel}");
Console.WriteLine($"Probability: {result.Probability}");

خروجی:

PredictedLabel: True
Probability: 0.98

مثال واقعی و کاربردی:

[HttpPost]
public IActionResult PredictSentence(string text)
{
    var result = _predictionEngine.Predict(new SentimentData { Text = text });
    return Ok(new { sentiment = result.PredictedLabel ? "positive" : "negative" });
}

خطاها و Exceptions احتمالی:

Exception	زمان رخ دادن	راه‌حل
`ArgumentNullException`	اگر `example` null باشد.	همیشه نمونه واقعی بده.
`InvalidOperationException`	اگر type `TSrc` با schema هماهنگ نباشد.	از کلاس صحیح استفاده کن.

Overloadها:

// نسخه کلی:
TDst Predict(TSrc example)

اشتباهات رایج:

❌ تغییر type TSrc بعد از آموزش؛ باعث mismatch می‌شود.
✅ کلاس‌های داده را ثابت نگه دار.

متدهای مرتبط:

Predict (این متد)
Transform: برای داده‌های انبوه.

📌 متد: `MLContext.Model.Save()`

امضای متد (Signature):

void Save(ITransformer model, DataViewSchema inputSchema, string filePath)

ورودی‌ها (Parameters):

نام پارامتر	نوع	اجباری؟	توضیح دقیق	مثال مقدار
`model`	`ITransformer`	بله	مدل آموزش‌دیده برای ذخیره‌سازی.	`trainedModel`
`inputSchema`	`DataViewSchema`	بله	schema ورودی مدل که برای بازسازی لازم است.	`trainData.Schema`
`filePath`	`string`	بله	مسیر فایل zip ذخیره مدل.	`"model.zip"`

مقدار برگشتی (Return Value):

نوع: void
توضیح: چیزی برنمی‌گرداند، مدل را در فایل zip ذخیره می‌کند.

کاری که انجام می‌ده (گام به گام):

مدل و schema را serialize می‌کند.
خروجی فشرده zip می‌سازد.
در مسیر مشخص ذخیره می‌کند.

مثال ساده و قابل اجرا:

mlContext.Model.Save(trainedModel, trainData.Schema, "model.zip");

مثال واقعی و کاربردی:

string modelPath = Path.Combine(Directory.GetCurrentDirectory(), $"housing_model_{DateTime.Now:yyyyMMdd}.zip");
mlContext.Model.Save(trainedModel, dataView.Schema, modelPath);

خطاها و Exceptions احتمالی:

Exception	زمان رخ دادن	راه‌حل
`DirectoryNotFoundException`	اگر پوشه مقصد وجود نداشته باشد.	قبل از Save پوشه را بسازید.
`ArgumentNullException`	اگر model یا filePath null باشد.	مقادیر را بررسی کن.

Overloadها:

void Save(ITransformer model, DataViewSchema inputSchema, string filePath)
void Save(ITransformer model, DataViewSchema inputSchema, Stream stream)

اشتباهات رایج:

❌ ذخیره نکردن schema ورودی؛ بارگذاری را مشکل می‌کند.
✅ همیشه از همان dataView.Schema که Model با آن ساخته شده استفاده کن.

متدهای مرتبط:

Load: بارگذاری مدل.
Save overload با Stream.

📌 متد: `MLContext.Model.Load()`

امضای متد (Signature):

ITransformer Load(string filePath, out DataViewSchema inputSchema)

ورودی‌ها (Parameters):

نام پارامتر	نوع	اجباری؟	توضیح دقیق	مثال مقدار
`filePath`	`string`	بله	مسیر فایل zip مدل.	`"model.zip"`
`inputSchema`	`out DataViewSchema`	بله	خروجی schema که در فایل ذخیره شده است.	`var schema`

مقدار برگشتی (Return Value):

نوع: ITransformer
توضیح: مدل بارگذاری‌شده که می‌تواند برای پیش‌بینی استفاده شود.
در صورت عدم وجود فایل، Exception پرتاب می‌کند.

کاری که انجام می‌ده (گام به گام):

فایل zip را از مسیر می‌خواند.
مدل و schema را deserialize می‌کند.
ITransformer و schema را برمی‌گرداند.

مثال ساده و قابل اجرا:

ITransformer loadedModel = mlContext.Model.Load("model.zip", out var schema);
Console.WriteLine($"Schema has {schema.Count} columns");

خروجی:

Schema has 2 columns

مثال واقعی و کاربردی:

string modelPath = "prod_model.zip";
if (!File.Exists(modelPath)) throw new FileNotFoundException("مدل پیدا نشد");
ITransformer model = mlContext.Model.Load(modelPath, out var schema);
var engine = mlContext.Model.CreatePredictionEngine<SentimentData, SentimentPrediction>(model, schema);

خطاها و Exceptions احتمالی:

Exception	زمان رخ دادن	راه‌حل
`FileNotFoundException`	اگر فایل وجود نداشته باشد.	قبل از Load بررسی `File.Exists`.
`InvalidOperationException`	اگر فایل خراب یا نامعتبر باشد.	مدل را دوباره ذخیره/بارگذاری کن.

Overloadها:

ITransformer Load(string filePath, out DataViewSchema inputSchema)
ITransformer Load(Stream stream)

اشتباهات رایج:

❌ استفاده از schema متفاوت از schema ذخیره‌شده در CreatePredictionEngine.
✅ از همان out schema استفاده کن یا null بگذار تا از Type استنتاج کند.

متدهای مرتبط:

Save: ذخیره مدل.
CreatePredictionEngine: ساخت PredictionEngine با مدل بارگذاری‌شده.

۱۲. مقایسه کلاس‌ها/توابع مشابه

IDataView در برابر IEnumerable/DataTable

ویژگی	IDataView	IEnumerable / DataTable
قالب	ستونی و بهینه	ردیفی و حافظه‌محور
پشتیبانی Trainer	بله (مورد نیاز)	خیر
Performance	بالا	پایین
قابلیت Streaming	دارد	محدود

Fit در برابر Transform

روش	هدف	ورودی	خروجی
`Fit`	آموزش مدل	IDataView آموزشی	Transformer (مدل)
`Transform`	اعمال مدل بر داده جدید	IDataView	IDataView تبدیل‌شده

PredictionEngine در برابر Model.Transform

ویژگی	PredictionEngine	Model.Transform
داده	تک نمونه	انبوه
Performance	کم‌قدرت در انبوه	بهینه برای Batch
Thread Safety	ضعیف (singleton)	دارد
Use Case	API بلادرنگ	پردازش دسته‌ای

۱۳. سناریوهای واقعی (Real-World Scenarios)

سناریو ۱: پیش‌بینی ریزش مشتری در یک سرویس اشتراکی

داده: سن، مدت اشتراک، تعداد شکایت، وضعیت فعال/غیرفعال
رویکرد: Pipeline شامل Normalization + OneHot + SDCA Logistic Regression
ارزیابی: AUC حداقل 0.8
خروجی: احتمال ریزش و Label دودویی

سناریو ۲: سیستم پیشنهاددهنده فیلم

داده: کاربر وفیلم و امتیاز
رویکرد: Matrix Factorization با MatrixFactorizationTrainer
ارزیابی: RMSE در پیش‌بینی امتیاز
خروجی: لیست پیشنهادها برای کاربر

سناریو ۳: تشخیص کلاه‌برداری در تراکنش‌های بانکی

داده: مبلغ، زمان، مکان، نوع تراکنش
رویکرد: طبقه‌بندی دودویی با FastTree یا LightGbm + SMOTE برای تعادل کلاس
ارزیابی: Precision/Recall بالا با توجه به هزینه کلاه‌برداری
خروجی: هشدار بلادرنگ

سناریو ۴: خوشه‌بندی مشتریان برای کمپین بازاریابی

داده: خرید، بازدید، تناوب، مبلغ
رویکرد: KMeans با نرمال‌سازی MinMax
ارزیابی: میانگین فاصله درون‌خوشه‌ای
خروجی: برچسب خوشه برای هر مشتری

۱۴. کارایی و Performance

نکات بهینه‌سازی

Caching: برای داده‌های کوچک که چندین بار خوانده می‌شوند، از mlContext.Data.Cache(dataView) استفاده کن.
Streaming: برای داده‌های بزرگ از trainers پشتیبانی‌کننده streaming استفاده کن و از Cache اجتناب کن.
Prediction Engine Pool: در ASP.NET Core از PredictionEnginePool استفاده کن تا thread-safe و کارا باشد.
Pipelines: از Pipeline واحد استفاده کن تا Transform ها تکراری اجرا نشوند.
Schema: با ذخیره schema از محاسبه مجدد جلوگیری کن.
Run Time: در AutoML از timeout استفاده کن تا از اجرای طولانی جلوگیری شود.

مقایسه Performance دو سناریو:

روش	سرعت پیش‌بینی تک نمونه	حافظه	Thread Safety
PredictionEngine (singleton)	سریع	کم	ضعیف
PredictionEnginePool	سریع	کنترل‌شده	عالی
Model.Transform (batch)	کند برای تک نمونه	متوسط	عالی

۱۵. چک‌لیست یادگیری

سطح مبتدی

ساخت MLContext
بارگذاری داده با LoadFromEnumerable
ساخت Pipeline ساده با Concatenate و Sdca
اجرای Fit و Transform
پیش‌بینی با PredictionEngine
ذخیره و بارگذاری مدل

سطح متوسط

تقسیم Train/Test و ارزیابی با Evaluate
استفاده از FeaturizeText برای متن
اعتبارسنجی متقاطع (CrossValidate)
رفع خطاهای Missing columns / type mismatch
استفاده از PredictionEnginePool در ASP.NET Core

سطح پیشرفته

تنظیم Hyperparameter با AutoML
استفاده از TensorFlow/ONNX models
خوشه‌بندی KMeans و سناریو پیشنهاددهنده
بهینه‌سازی Performance و حافظه
پیاده‌سازی سناریوی واقعی از ابتدا تا Production

مهارت‌های عملی که باید بتوانی انجام دهی:

نوشتن یک برنامه کامل رگرسیون و طبقه‌بندی بدون کمک.
ذخیره و بارگذاری مدل در یک Web API.
ارزیابی مدل با متریک‌های درست و گزارش‌دهی.
مدیریت خطاها و داده‌های ناقص.
استفاده از AutoML برای انتخاب سریع مدل.
اعمال Transform های آموزش روی داده جدید بدون فراموشی.

پایان آموزش کامل ML.NET از صفر تا صد.

🔬 آموزش کامل یادگیری ماشین با ML.NET از صفر تا صد (آموزش عمیق)

🔬 آموزش کامل یادگیری ماشین با ML.NET از صفر تا صد (آموزش عمیق)

آموزش کامل یادگیری ماشین با ML.NET از صفر تا صد

⚡ خلاصه سریع — اصل کاری‌ها

۱. مقدمه

ML.NET چیست؟

چرا باید ML.NET را یاد بگیری؟

کجا استفاده می‌شود؟

۲. پیش‌نیازها

چه چیزهایی باید از قبل بدانی؟

ابزارهای لازم

۳. نصب و راه‌اندازی

گام ۱: نصب .NET SDK

گام ۲: ساخت پروژه جدید

گام ۳: نصب بسته Microsoft.ML

گام ۴: اولین برنامه ساده

۴. مفاهیم پایه

۴.۱ MLContext

۴.۲ IDataView

۴.۳ Transformer و Trainer

۴.۴ Pipeline

۴.۵ Fit و Transform

۴.۶ PredictionEngine

۵. مثال‌های کد ساده

۵.۱ رگرسیون خطی: پیش‌بینی قیمت خانه

۵.۲ طبقه‌بندی دودویی: تشخیص احساسات

۶. مثال واقعی و کاربردی

پروژه کوچک: تشخیص احساسات نظرات کاربران با ارزیابی و ذخیره مدل

گام ۱: ساخت پروژه و نصب بسته

گام ۲: تعریف کلاس‌ها

گام ۳: ساخت نمونه داده‌ها

گام ۴: بارگذاری داده و تقسیم آموزش/آزمون

گام ۵: ساخت Pipeline

گام ۶: آموزش و ارزیابی

گام ۷: ذخیره مدل

گام ۸: بارگذاری و استفاده در برنامه واقعی

۷. مباحث پیشرفته

۷.۱ Cross-Validation

۷.۲ Feature Engineering

۷.۳ AutoML

۷.۴ مدل‌های TensorFlow

۷.۵ بهینه‌سازی

۸. اشتباهات رایج

۹. بهترین روش‌ها (Best Practices)

۱۰. منابع و ادامه مسیر

۱۱. مرجع کامل توابع و متدها (API Deep Dive)

📌 متد: MLContext.Data.LoadFromEnumerable<T>()

📌 متد: MLContext.Data.TrainTestSplit()

📌 متد: MLContext.Transforms.Concatenate()

📌 متد: MLContext.Transforms.Text.FeaturizeText()

📌 متد: MLContext.Regression.Trainers.Sdca()

📌 متد: MLContext.BinaryClassification.Trainers.SdcaLogisticRegression()

📌 متد: IEstimator<TTransformer>.Fit()

📌 متد: MLContext.Model.CreatePredictionEngine<TSrc,TDst>()

📌 متد: PredictionEngine<TSrc,TDst>.Predict()

📌 متد: MLContext.Model.Save()

📌 متد: MLContext.Model.Load()

۱۲. مقایسه کلاس‌ها/توابع مشابه

IDataView در برابر IEnumerable/DataTable

Fit در برابر Transform

PredictionEngine در برابر Model.Transform

۱۳. سناریوهای واقعی (Real-World Scenarios)

سناریو ۱: پیش‌بینی ریزش مشتری در یک سرویس اشتراکی

سناریو ۲: سیستم پیشنهاددهنده فیلم

سناریو ۳: تشخیص کلاه‌برداری در تراکنش‌های بانکی

سناریو ۴: خوشه‌بندی مشتریان برای کمپین بازاریابی

۱۴. کارایی و Performance

نکات بهینه‌سازی

مقایسه Performance دو سناریو:

۱۵. چک‌لیست یادگیری

سطح مبتدی

سطح متوسط

سطح پیشرفته

مهارت‌های عملی که باید بتوانی انجام دهی:

📌 متد: `MLContext.Data.LoadFromEnumerable<T>()`

📌 متد: `MLContext.Data.TrainTestSplit()`

📌 متد: `MLContext.Transforms.Concatenate()`

📌 متد: `MLContext.Transforms.Text.FeaturizeText()`

📌 متد: `MLContext.Regression.Trainers.Sdca()`

📌 متد: `MLContext.BinaryClassification.Trainers.SdcaLogisticRegression()`

📌 متد: `IEstimator<TTransformer>.Fit()`

📌 متد: `MLContext.Model.CreatePredictionEngine<TSrc,TDst>()`

📌 متد: `PredictionEngine<TSrc,TDst>.Predict()`

📌 متد: `MLContext.Model.Save()`

📌 متد: `MLContext.Model.Load()`