مقدمه: چرا OpenAI در ASP.NET اهمیت دارد؟

در دنیای امروز، هوش مصنوعی دیگر یک اختیار نیست؛ بلکه یک ضرورت رقابتی است. اگر یک توسعه‌دهنده ASP.NET هستی و هنوز OpenAI را به پروژه‌هایت اضافه نکرده‌ای، باید بدانی که رقبایت دارند با سرعت نور جلو می‌روند.

در این مقاله، به صورت کاملاً عملی و قدم‌به‌قدم یاد می‌گیریم چطور API هوش مصنوعی OpenAI را در یک پروژه ASP.NET Core پیاده‌سازی کنیم. از نصب پکیج تا نوشتن کنترلر، از مدیریت خطا تا بهینه‌سازی هزینه — همه چیز اینجاست.

OpenAI API چیست و چرا باید از آن استفاده کنیم؟

OpenAI یک شرکت تحقیقاتی هوش مصنوعی است که مدل‌های پیشرفته‌ای مثل GPT-4o، GPT-4، GPT-3.5 Turbo و DALL·E را ارائه می‌دهد. این مدل‌ها از طریق یک REST API در دسترس هستند و می‌توانی در هر پلتفرمی — از جمله ASP.NET — از آن‌ها استفاده کنی.

کاربردهای اصلی OpenAI در پروژه‌های وب شامل موارد زیر می‌شود:

• چت‌بات هوشمند: ساخت ربات پشتیبانی و مشاوره برای سایت
• تولید محتوا: خودکارسازی تولید متن، توضیحات محصول و مقالات
• تحلیل متن: دسته‌بندی نظرات کاربران و تحلیل احساسات
• ترجمه هوشمند: ترجمه محتوا با حفظ معنا و لحن
• خلاصه‌سازی: خلاصه کردن اسناد طولانی
• کد نویسی: کمک به توسعه‌دهندگان برای تولید و بررسی کد

پیش‌نیازهای پیاده‌سازی OpenAI در ASP.NET

قبل از شروع کدنویسی، باید مطمئن شوی این موارد را داری:

• دات نت ۶ یا بالاتر (.NET 6/7/8)
• ویژوال استودیو ۲۰۲۲ یا VS Code با اکستنشن C#
• حساب کاربری OpenAI و دریافت API Key
• آشنایی پایه با ASP.NET Core و مفهوم کنترلر و سرویس

دریافت API Key از OpenAI

برای دریافت کلید API مراحل زیر را انجام بده:

1. به سایت platform.openai.com برو و ثبت‌نام کن
2. از منوی بالا سمت راست، گزینه API Keys را انتخاب کن
3. روی دکمه Create new secret key کلیک کن
4. کلید را کپی و در جای امنی ذخیره کن — دیگر نمایش داده نمی‌شود!

روش اول: استفاده از پکیج رسمی OpenAI برای دات‌نت

نصب پکیج NuGet

مایکروسافت و OpenAI هر دو پکیج‌های رسمی برای دات‌نت دارند. بهترین گزینه در سال ۲۰۲۵ پکیج OpenAI است که به صورت رسمی توسط OpenAI نگهداری می‌شود:

dotnet add package OpenAI

یا اگر می‌خوای از پکیج مایکروسافت Azure OpenAI استفاده کنی:

dotnet add package Azure.AI.OpenAI

تنظیم appsettings.json

برای امنیت بیشتر، هرگز کلید API را مستقیماً در کد ننویس. از فایل تنظیمات استفاده کن:

{

“OpenAI”: {

“ApiKey”: “sk-your-api-key-here”,

“Model”: “gpt-4o-mini”,

“MaxTokens”: 1000

}

}

ساخت سرویس OpenAI

ابتدا یک کلاس تنظیمات می‌سازیم:

public class OpenAISettings

{

public string ApiKey { get; set; } = string.Empty;

public string Model { get; set; } = “gpt-4o-mini”;

public int MaxTokens { get; set; } = 1000;

}

حالا یک اینترفیس و سرویس برای مدیریت تمام ارتباطات با OpenAI می‌نویسیم:

public interface IOpenAIService

{

Task GetChatCompletionAsync(string userMessage, string? systemPrompt = null);

Task SummarizeTextAsync(string text);

Task TranslateTextAsync(string text, string targetLanguage);

}

public class OpenAIService : IOpenAIService

{

private readonly OpenAIClient _client;

private readonly OpenAISettings _settings;

private readonly ILogger _logger;

public OpenAIService(

IOptions settings,

ILogger logger)

{

_settings = settings.Value;

_logger = logger;

_client = new OpenAIClient(_settings.ApiKey);

}

public async Task GetChatCompletionAsync(

string userMessage,

string? systemPrompt = null)

{

try

{

var chatClient = _client.GetChatClient(_settings.Model);

var messages = new List();

if (!string.IsNullOrEmpty(systemPrompt))

messages.Add(new SystemChatMessage(systemPrompt));

messages.Add(new UserChatMessage(userMessage));

var options = new ChatCompletionOptions

{

MaxOutputTokenCount = _settings.MaxTokens

};

ChatCompletion completion = await chatClient

.CompleteChatAsync(messages, options);

return completion.Content[0].Text;

}

catch (Exception ex)

{

_logger.LogError(ex, “خطا در ارتباط با OpenAI API”);

throw;

}

}

public async Task SummarizeTextAsync(string text)

{

var systemPrompt = “تو یک متخصص خلاصه‌سازی هستی. متن زیر را به فارسی خلاصه کن.”;

return await GetChatCompletionAsync(text, systemPrompt);

}

public async Task TranslateTextAsync(string text, string targetLanguage)

{

var systemPrompt = $“متن زیر را به {targetLanguage} ترجمه کن.”;

return await GetChatCompletionAsync(text, systemPrompt);

}

}

ثبت سرویس در Program.cs

var builder = WebApplication.CreateBuilder(args);

// تنظیم OpenAI

builder.Services.Configure(

builder.Configuration.GetSection(“OpenAI”));

// ثبت سرویس

builder.Services.AddScoped();

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();

builder.Services.AddSwaggerGen();

var app = builder.Build();

// ادامه تنظیمات…

ساخت کنترلر API برای OpenAI

حالا یک کنترلر می‌سازیم که درخواست‌های کاربر را دریافت و به OpenAI ارسال کند:

[ApiController]

[Route(“api/[controller]”)]

public class ChatController : ControllerBase

{

private readonly IOpenAIService _openAIService;

private readonly ILogger _logger;

public ChatController(

IOpenAIService openAIService,

ILogger logger)

{

_openAIService = openAIService;

_logger = logger;

}

[HttpPost(“message”)]

public async Task SendMessage(

[FromBody] ChatRequest request)

{

if (string.IsNullOrWhiteSpace(request.Message))

return BadRequest(“پیام نمی‌تواند خالی باشد.”);

var response = await _openAIService

.GetChatCompletionAsync(

request.Message,

request.SystemPrompt);

return Ok(new ChatResponse

{

Reply = response,

Timestamp = DateTime.UtcNow

});

}

[HttpPost(“summarize”)]

public async Task Summarize(

[FromBody] TextRequest request)

{

var summary = await _openAIService

.SummarizeTextAsync(request.Text);

return Ok(new { Summary = summary });

}

[HttpPost(“translate”)]

public async Task Translate(

[FromBody] TranslateRequest request)

{

var translation = await _openAIService

.TranslateTextAsync(request.Text, request.TargetLanguage);

return Ok(new { Translation = translation });

}

}

public record ChatRequest(string Message, string? SystemPrompt);

public record ChatResponse

{

public string Reply { get; init; } = string.Empty;

public DateTime Timestamp { get; init; }

}

public record TextRequest(string Text);

public record TranslateRequest(string Text, string TargetLanguage);

پیاده‌سازی Streaming برای پاسخ‌های بلادرنگ

یکی از بهترین ویژگی‌های OpenAI، Streaming است؛ یعنی پاسخ به صورت زنده و کلمه‌به‌کلمه نمایش داده می‌شود (مثل ChatGPT). این کار تجربه کاربری را فوق‌العاده بهتر می‌کند:

[HttpPost(“stream”)]

public async Task StreamMessage([FromBody] ChatRequest request)

{

Response.Headers.Add(“Content-Type”, “text/event-stream”);

Response.Headers.Add(“Cache-Control”, “no-cache”);

Response.Headers.Add(“Connection”, “keep-alive”);

var chatClient = _openAIClient.GetChatClient(“gpt-4o-mini”);

var messages = new List

{

new UserChatMessage(request.Message)

};

await foreach (var update in chatClient.CompleteChatStreamingAsync(messages))

{

foreach (var part in update.ContentUpdate)

{

var data = $“data: {part.Text}

”;

await Response.WriteAsync(data);

await Response.Body.FlushAsync();

}

}

}

مدیریت خطا و Retry در OpenAI API

یکی از مهم‌ترین بخش‌ها در پیاده‌سازی حرفه‌ای، مدیریت خطاست. OpenAI API گاهی خطاهای Rate Limit یا Timeout می‌دهد. با Polly می‌توانیم Retry خودکار اضافه کنیم:

// نصب پکیج

// dotnet add package Microsoft.Extensions.Http.Polly

// در Program.cs

builder.Services.AddHttpClient()

.AddTransientHttpErrorPolicy(p =>

p.WaitAndRetryAsync(3,

retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt))));

بهینه‌سازی هزینه استفاده از OpenAI API

OpenAI بر اساس تعداد Token هزینه می‌گیرد. برای کنترل هزینه‌ها به این نکات توجه کن:

• از مدل مناسب استفاده کن: برای کارهای ساده، gpt-4o-mini بسیار ارزان‌تر و کافی است
• MaxTokens را محدود کن: حد بالای توکن خروجی را تعیین کن
• کش کردن پاسخ‌ها: برای سوالات تکراری، از IMemoryCache استفاده کن
• System Prompt را کوتاه کن: System Prompt هم توکن مصرف می‌کند

// نمونه کش کردن پاسخ‌ها

public class CachedOpenAIService : IOpenAIService

{

private readonly IOpenAIService _inner;

private readonly IMemoryCache _cache;

public CachedOpenAIService(IOpenAIService inner, IMemoryCache cache)

{

_inner = inner;

_cache = cache;

}

public async Task GetChatCompletionAsync(

string userMessage, string? systemPrompt = null)

{

var cacheKey = $“openai_{userMessage.GetHashCode()}”;

if (_cache.TryGetValue(cacheKey, out string? cachedResponse))

return cachedResponse!;

var response = await _inner

.GetChatCompletionAsync(userMessage, systemPrompt);

_cache.Set(cacheKey, response,

TimeSpan.FromMinutes(30));

return response;

}

}

پیاده‌سازی Function Calling در OpenAI

Function Calling یکی از قدرتمندترین قابلیت‌های OpenAI است که به مدل اجازه می‌دهد توابع تعریف‌شده شما را فراخوانی کند. برای مثال، می‌توانی به GPT بگویی هر وقت کاربر درخواست آب‌وهوا کرد، تابع getWeather() را صدا بزند:

var tools = new List

{

ChatTool.CreateFunctionTool(

functionName: “get_weather”,

functionDescription: “Get current weather for a city”,

functionParameters: BinaryData.FromString(“”"

{

“type”: “object”,

“properties”: {

“city”: {

“type”: “string”,

“description”: “The city name”

}

},

“required”: [“city”]

}

“”")

)

};

var options = new ChatCompletionOptions();

foreach (var tool in tools)

options.Tools.Add(tool);

var completion = await chatClient

.CompleteChatAsync(messages, options);

if (completion.FinishReason == ChatFinishReason.ToolCalls)

{

foreach (var toolCall in completion.ToolCalls)

{

if (toolCall.FunctionName == “get_weather”)

{

var args = JsonDocument.Parse(toolCall.FunctionArguments);

var city = args.RootElement

.GetProperty(“city”).GetString();

// اینجا تابع واقعی آب‌وهوا را صدا بزن

}

}

}

امنیت در پیاده‌سازی OpenAI

امنیت در پیاده‌سازی OpenAI API بسیار مهم است. این نکات را رعایت کن:

• کلید API را هرگز در کد ننویس؛ از Environment Variables یا Azure Key Vault استفاده کن
• Rate Limiting اضافه کن تا کاربران سوءاستفاده نکنند
• ورودی کاربر را اعتبارسنجی کن قبل از ارسال به API
• لاگ هزینه‌ها را پایش کن تا از هزینه‌های غیرمنتظره جلوگیری شود
• Content Moderation اعمال کن تا محتوای نامناسب فیلتر شود

// خواندن API Key از Environment Variable

var apiKey = Environment.GetEnvironmentVariable(“OPENAI_API_KEY”)

?? throw new InvalidOperationException(

“OPENAI_API_KEY is not set”);

// یا در appsettings.Development.json

// و استفاده از User Secrets در محیط توسعه:

// dotnet user-secrets set “OpenAI:ApiKey” “sk-…”

یکپارچه‌سازی با Minimal API در دات‌نت ۸

اگر از Minimal API در دات‌نت ۸ استفاده می‌کنی، پیاده‌سازی حتی ساده‌تر است:

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure(

builder.Configuration.GetSection(“OpenAI”));

builder.Services.AddScoped();

builder.Services.AddMemoryCache();

var app = builder.Build();

app.MapPost(“/api/chat”, async (

ChatRequest request,

IOpenAIService openAIService) =>

{

var response = await openAIService

.GetChatCompletionAsync(request.Message);

return Results.Ok(new { Reply = response });

});

app.MapPost(“/api/summarize”, async (

TextRequest request,

IOpenAIService openAIService) =>

{

var summary = await openAIService

.SummarizeTextAsync(request.Text);

return Results.Ok(new { Summary = summary });

});

app.Run();

تست واحد سرویس OpenAI

برای نوشتن Unit Test روی سرویس OpenAI، از Mock استفاده کن تا نیازی به فراخوانی واقعی API نباشد:

[Fact]

public async Task GetChatCompletion_ReturnsResponse_WhenSuccessful()

{

// Arrange

var mockService = new Mock();

mockService

.Setup(s => s.GetChatCompletionAsync(

It.IsAny(),

It.IsAny()))

.ReturnsAsync(“سلام! چطور می‌توانم کمک کنم؟”);

var controller = new ChatController(

mockService.Object,

Mock.Of>());

// Act

var result = await controller

.SendMessage(new ChatRequest(“سلام”, null));

// Assert

var okResult = Assert.IsType(result);

Assert.NotNull(okResult.Value);

}

چک‌لیست نهایی پیاده‌سازی OpenAI در ASP.NET

• ✅ پکیج OpenAI نصب شده
• ✅ API Key در تنظیمات امن ذخیره شده
• ✅ سرویس با DI ثبت شده
• ✅ مدیریت خطا پیاده‌سازی شده
• ✅ Rate Limiting اعمال شده
• ✅ کش‌کردن پاسخ‌های تکراری
• ✅ لاگ‌گذاری مناسب
• ✅ تست واحد نوشته شده

سوالات متداول (FAQ)