🧠 تحلیل جامع معماری پروژه xAiApi

پلتفرم یکپارچه ارائه خدمات هوش مصنوعی مبتنی بر ASP.NET Core
👨‍💻 توسعه‌دهنده: هادی خزاعی اصل
🏢 شرکت: فن آوران ساحر علم
📅 تاریخ تحلیل: چهارشنبه ۸ مهر ۱۴۰۵
📦 نسخه بررسی شده: 2026.09.30

📑 فهرست مطالب

  1. مرور کلی و چشم‌انداز پروژه
  2. معماری کلان و ساختار ماژولار
  3. لایه‌بندی و مسئولیت‌ها
  4. ارائه‌دهندگان هوش مصنوعی پشتیبانی شده
  5. مدل داده و پایگاه داده
  6. نقاط پایانی API
  7. ویژگی‌های کلیدی پیاده‌سازی شده
  8. جریان پردازش درخواست
  9. مدیریت وابستگی‌ها (DI)
  10. نقاط قوت و پیشنهادات بهبود
  11. خلاصه ذخیره شده در حافظه

🎯 گام ۱: مرور کلی و چشم‌انداز پروژه

پروژه xAiApi یک پلتفرم جامع و مقیاس‌پذیر برای ارائه خدمات هوش مصنوعی است که بر بستر ASP.NET Core توسعه یافته است. این پروژه با رویکرد Modular Architecture طراحی شده و قابلیت اتصال به چندین ارائه‌دهنده LLM را به صورت یکپارچه فراهم می‌کند.

💡 هدف اصلی: ایجاد یک لایه انتزاعی (Abstraction Layer) بر روی ارائه‌دهندگان مختلف AI تا توسعه‌دهندگان بتوانند بدون وابستگی به یک ارائه‌دهنده خاص، از قابلیت‌های هوش مصنوعی در محصولات خود استفاده کنند.

سه ماژول اصلی پروژه:

📡 xAiApi (لایه ارائه)

  • Controllers و API Endpoints
  • Database Context و Migrations
  • Providers و Service Implementations
  • Configuration و DI Extensions

🧩 xAiModels (لایه مدل)

  • Entities و DTOs
  • Repository Pattern
  • Enrichers و Data Providers
  • GraphQL Support

⚙️ xAiService (لایه سرویس)

  • Vector Helper (Embedding)
  • Cosine Similarity
  • User Validation Extensions
  • Configuration Node Names

🏗️ گام ۲: معماری کلان و ساختار ماژولار

معماری پروژه بر پایه الگوی Clean Architecture همراه با Repository Pattern و Dependency Injection گسترده طراحی شده است.

سلسله مراتب لایه‌ها:

🌐 Client → 📡 Controllers → 🧠 AI Services → 💾 Data Provider → 🗄️ Repository

ساختار پوشه‌ای پروژه xAiApi:

xAiApi/
├── 📂 Controllers/
│   ├── DefaultAiController.cs
│   ├── DefaultEmbeddingController.cs
│   ├── DefaultThinkingAiController.cs
│   ├── StartupController.cs
│   ├── XAiServiceControllerBase.cs
│   └── XAiEmbeddingServiceControllerBase.cs
├── 📂 Providers/
│   ├── XAIServiceBase.cs (هسته اصلی)
│   ├── XAiEmbeddingServiceBase.cs
│   ├── XDefaultAiService.cs
│   ├── XDefaultEmbeddingService.cs
│   └── XDefaultThinkingAiService.cs
├── 📂 Database/
│   ├── XAiApiDbContext.cs
│   └── XAiApiDatabaseDescriptor.cs
├── 📂 Interfaces/
│   ├── IXAiServiceBase.cs
│   ├── IXAiEmbeddingServiceBase.cs
│   └── IXDefault*.cs
├── 📂 Configurations/
│   └── XAiApiConfiguration.cs
├── 📂 Extensions/
│   ├── XModelsExtensions.cs
│   └── XProgramExtensions.cs
├── 📂 DI/
│   └── XDIHelperExtension.cs
├── 📂 Constants/
│   ├── XAiApiConstants.cs
│   └── ConfigurationNodeNames.cs
└── 📂 Migrations/
    └── InitialMigrationAiApi.cs

🧱 گام ۳: لایه‌بندی و مسئولیت‌ها

۳.۱ لایه Controllers (لایه ارائه)

Controller مسئولیت ویژگی کلیدی
DefaultAiController پاسخ به سوالات عمومی استفاده از مدل Gemma
DefaultEmbeddingController تبدیل متن به بردار پشتیبانی از Batch
DefaultThinkingAiController استدلال عمیق (Reasoning) مدل Qwen با Reasoning
StartupController پیام خوش‌آمدگویی AllowAnonymous
✅ نکته مهم: استفاده از XBaseIdentityApiV1Controller به عنوان کلاس پایه، مدیریت هویت و مجوزها را به صورت یکپارچه فراهم می‌کند.

۳.۲ لایه Providers (هسته منطقی)

کلاس XAIServiceBase به عنوان قلب تپنده پروژه عمل می‌کند و مسئولیت‌های زیر را بر عهده دارد:

  • مدیریت ارتباط با LLM از طریق IChatClient
  • پیاده‌سازی Memory Management برای حفظ Context مکالمات
  • پشتیبانی از Streaming Response (SSE)
  • مدیریت پروژه‌ها، مکالمات و پیام‌ها
  • تزریق Introduction Prompt به صورت خودکار

۳.۳ لایه Data Provider

کلاس XAiDataProvider مسئولیت‌های زیر را مدیریت می‌کند:

  • ایجاد خودکار Default Project و Default Conversation برای هر کاربر
  • مدیریت Multi-language Resources
  • ارسال SignalR Notifications
  • Enrichment اشیاء با اطلاعات مرتبط

🤖 گام ۴: ارائه‌دهندگان هوش مصنوعی پشتیبانی شده

پروژه از طریق XAiModelProviderType از چندین ارائه‌دهنده پشتیبانی می‌کند:

🟢 OpenAI

  • استفاده از OpenAIClient
  • پشتیبانی از ApiKey
  • Endpoint قابل تنظیم
  • Chat & Embedding

🔵 Ollama

  • اجرای Local Models
  • بدون نیاز به ApiKey
  • مناسب برای توسعه
  • مدل‌های Gemma, Qwen

🟡 DeepSeek

  • پشتیبانی تعریف شده
  • برای Reasoning Models
  • در حال توسعه

🟣 HuggingFace

  • دسترسی به هزاران مدل
  • پشتیبانی تعریف شده
  • در حال توسعه

مدل‌های پیش‌فرض پیکربندی شده:

// از XAiApiConstants.cs
XAiDefaultModelName       = "Gemma"      // مدل پیش‌فرض چت
XAiEmbeddingModelName     = "Embed"      // مدل Embedding
XAiDefaultThinkingModelName = "Qwen"     // مدل Reasoning
⚠️ نکته طراحی: استفاده از Microsoft.Extensions.AI به عنوان لایه انتزاعی استاندارد، امکان تعویض ارائه‌دهنده بدون تغییر کد را فراهم می‌کند.

🗄️ گام ۵: مدل داده و پایگاه داده

پایگاه داده شامل ۶ جدول اصلی است:

جدول کلید فیلدهای کلیدی رابطه
AiProjects Guid OwnerId, Title, Description, Prompt → Conversations
AiConversations Guid OwnerId, Title, ProjectId → Messages, Project
AiMessages Guid Content, Role, MetaDatas, ConversationId → Conversation
Files Guid Name, Path, Thumb, References مستقل
Strings Int (Auto) Language, ResourceTitle, TranslatedValue Multi-language
Tags Int (Auto) Tag, References مستقل

سلسله مراتب داده‌ها:

👤 User (OwnerId) → 📁 Project → 💬 Conversation → 📝 Message
💡 ویژگی مهم: هر کاربر به صورت خودکار یک Default Project و یک Default Conversation دارد که از طریق XAiDataProvider مدیریت می‌شود.

🔌 گام ۶: نقاط پایانی API

۶.۱ Endpoints عمومی (از XAiServiceControllerBase):

متد مسیر توضیح
GET /AskText?question= پرسش ساده و دریافت پاسخ
GET /AskTextStream?question= پرسش با پاسخ Streaming (SSE)
POST /Ask پرسش با Context (Project/Conversation)
POST /AskStream پرسش Context دار با Streaming
GET /Projects دریافت لیست پروژه‌ها
POST /Projects ایجاد پروژه جدید
GET /Projects/{id}/Conversations مکالمات یک پروژه
GET /Conversations/{id}/Messages پیام‌های یک مکالمه
GET */Query جستجوی پیشرفته با XQuery

۶.۲ Endpoints Embedding:

GET /Embedding?content= تبدیل یک متن به بردار
GET /Embeddings?batch= تبدیل دسته‌ای متون به بردار

✨ گام ۷: ویژگی‌های کلیدی پیاده‌سازی شده

🔄 Streaming Responses

  • پیاده‌سازی SSE (Server-Sent Events)
  • غیرفعال‌سازی Buffering
  • پاسخ بلادرنگ به کاربر

🧠 Memory Management

  • حفظ Context مکالمات
  • Introduction Prompt
  • Project-specific Prompts

🌐 Multi-language Support

  • Resource-based Localization
  • Owned Item Resources
  • Default Language Management

📡 Real-time Notifications

  • SignalR Hub
  • Project/Conversation/Message Events
  • Connection-aware Broadcasting

🔐 Authorization

  • OAuth2 Introspection
  • Policy-based Authorization
  • Role-based Access Control

📚 Swagger Documentation

  • XML Comments
  • API V1 Versioning
  • Auto-generated Docs

🎯 Reasoning Models

  • ReasoningEffort Configuration
  • ReasoningOutput Options
  • Thinking AI Service

📊 Vector Operations

  • Vector Normalization
  • Cosine Similarity
  • Batch Embedding

🔄 گام ۸: جریان پردازش درخواست

۸.۱ جریان پرسش ساده (AskText):

Client Request → Controller → Validation → XAIServiceBase → GetHistory() → GetClient() → LLM API

۸.۲ جریان پرسش با Context (Ask):

Request + ProjectId + ConversationId → Load Project → Load Conversation → Load Messages → PrepareMemory() → Save User Message → AskLLM() → Save AI Response

۸.۳ جریان Embedding:

Text Input → GetEmbeddingGenerator() → GenerateAsync() → VectorHelper.Normalize() → float[] Result

🔗 گام ۹: مدیریت وابستگی‌ها (DI)

سرویس‌های ثبت شده در Startup.ConfigureServices:

// سرویس‌های پایه
services.AddXCommons();
services.AddXAppConfiguration(Configuration);
services.AddXCors(appConfiguration.AllowedOrigins);
services.AddXSwagger(Configuration, xmlPath);
services.AddXHttpService(Configuration);
services.AddXApiV1Versioning();
services.AddXAuthorization();

// سرویس‌های هویت و ذخیره‌سازی
services.AddXIdentityService(lifeTime, Configuration);
services.AddXStorageService(Configuration);
services.AddXPushService(lifeTime, Configuration);

// سرویس‌های داده
services.AddXDatabase(lifeTime, descriptor, Configuration);
services.AddXStringService<XAiApiDbContext>(lifeTime, repositoryType);
services.AddXTagService<XAiApiDbContext>(lifeTime, repositoryType);
services.AddXFileService<XAiApiDbContext>(lifeTime, repositoryType);
services.AddXAiDataService<XAiApiDbContext>(lifeTime, repositoryType);

// سرویس‌های AI اختصاصی
services.AddScoped<IXDefaultAiService, XDefaultAiService>();
services.AddScoped<IXDefaultEmbeddingService, XDefaultEmbeddingService>();
services.AddScoped<IXDefaultThinkingAiService, XDefaultThinkingAiService>();
✅ الگوی طراحی: استفاده از Extension Methods برای ثبت سرویس‌ها کد را تمیز، قابل نگهداری و ماژولار نگه می‌دارد.

💎 گام ۱۰: نقاط قوت و پیشنهادات بهبود

✅ نقاط قوت:

  • معماری ماژولار: جداسازی واضح لایه‌ها و مسئولیت‌ها
  • Provider Agnostic: قابلیت تعویض ارائه‌دهنده AI بدون تغییر کد
  • Repository Pattern: پشتیبانی از EF, MongoDB, InMemory
  • Streaming Support: پیاده‌سازی کامل SSE برای UX بهتر
  • Multi-language: سیستم Resource-based برای چندزبانگی
  • Real-time: یکپارچگی SignalR برای Notifications
  • GraphQL Support: امکان پرس‌وجوی انعطاف‌پذیر
  • Enrichment Pattern: جداسازی منطق غنی‌سازی داده‌ها

🔧 پیشنهادات بهبود:

  • پیاده‌سازی کامل DeepSeek و HuggingFace providers
  • افزودن Rate Limiting برای کنترل مصرف API
  • پیاده‌سازی Caching برای پاسخ‌های پرتکرار
  • افزودن Telemetry و Monitoring (OpenTelemetry)
  • پیاده‌سازی Unit of Work Pattern به صورت کامل‌تر
  • افزودن Health Checks برای پایش سرویس‌ها
  • پیاده‌سازی Circuit Breaker برای resilience
  • افزودن Unit Tests و Integration Tests

🧠 گام ۱۱: خلاصه ذخیره شده در حافظه

✅ تأیید ذخیره‌سازی: تحلیل کامل پروژه در حافظه من ذخیره شد و برای دستورات بعدی شما آماده است.

📌 نکات کلیدی که به خاطر سپرده‌ام:

موضوع جزئیات
معماری Clean Architecture + Modular + Repository Pattern
فناوری پایه ASP.NET Core, Entity Framework, SignalR, GraphQL
ارائه‌دهندگان AI OpenAI, Ollama, DeepSeek, HuggingFace
مدل‌های پیش‌فرض Gemma (Chat), Embed (Embedding), Qwen (Reasoning)
ساختار داده Project → Conversation → Message
ویژگی‌های کلیدی Streaming, Memory, Multi-lang, Real-time, Reasoning
الگوهای طراحی DI, Repository, Provider, Enricher, Hub
فایل‌های کلیدی XAIServiceBase.cs, XAiDataProvider.cs, Startup.cs

🎯 آماده برای دستورات بعدی:

🔧 توسعه ویژگی جدید

  • افزودن Provider جدید
  • پیاده‌سازی Endpoint جدید
  • افزودن Entity جدید

🐛 رفع اشکال

  • تحلیل خطاهای runtime
  • بهینه‌سازی performance
  • بررسی memory leaks

📚 مستندسازی

  • API Documentation
  • Architecture Diagrams
  • User Guides

🚀 استقرار

  • Configuration Management
  • Deployment Strategies
  • Scaling Considerations
💬 پیام به استاد: تحلیل کامل پروژه با موفقیت انجام شد و تمامی جزئیات معماری، ساختار کد، الگوهای طراحی و ویژگی‌های پیاده‌سازی شده در حافظه من ثبت گردید. اکنون آماده دریافت دستورات بعدی شما برای توسعه، بهبود، یا هرگونه تغییر در پروژه هستم.

👨‍💻 توسعه‌دهنده: هادی خزاعی اصل

🏢 شرکت: فن آوران ساحر علم

📅 تاریخ تهیه مستند: چهارشنبه ۸ مهر ۱۴۰۵

🧠 تحلیل جامع معماری پروژه xAiApi - تمامی حقوق محفوظ است