version 2

src/GreenHome.AI.DeepSeek/USAGE_FA.md

@@ -0,0 +1,186 @@
+# راهنمای سریع استفاده از سرویس DeepSeek
+
+## نصب و راه‌اندازی
+
+### گام 1: دریافت API Key
+
+1. به آدرس https://platform.deepseek.com بروید
+2. ثبت‌نام کنید یا وارد شوید
+3. از منوی API Keys یک کلید جدید بسازید
+4. کلید را کپی کنید (مهم: فقط یک بار نمایش داده می‌شود!)
+
+### گام 2: تنظیم API Key
+
+API Key خود را در فایل `appsettings.json` قرار دهید:
+
+```json
+{
+  "DeepSeek": {
+    "ApiKey": "کلید-API-خود-را-اینجا-قرار-دهید"
+  }
+}
+```
+
+**هشدار امنیتی:** هرگز API Key را در Git commit نکنید!
+
+### گام 3: اجرای برنامه
+
+```bash
+cd GreenHome.Api
+dotnet run
+```
+
+## استفاده از API
+
+سرویس روی آدرس `http://localhost:5000` (یا پورت دیگری که تنظیم کرده‌اید) اجرا می‌شود.
+
+### 1. پرسیدن یک سوال ساده
+
+**درخواست:**
+```http
+POST /api/ai/ask
+Content-Type: application/json
+
+{
+  "question": "چگونه می‌توانم مصرف انرژی خانه را کاهش دهم؟"
+}
+```
+
+**پاسخ:**
+```json
+{
+  "question": "چگونه می‌توانم مصرف انرژی خانه را کاهش دهم؟",
+  "answer": "برای کاهش مصرف انرژی خانه می‌توانید از راه‌کارهای زیر استفاده کنید:\n1. از لامپ‌های LED استفاده کنید\n2. ترموستات هوشمند نصب کنید\n3. عایق‌بندی خانه را بهبود دهید...",
+  "timestamp": "2025-12-16T10:30:00Z"
+}
+```
+
+### 2. دریافت پیشنهادات برای خانه هوشمند
+
+**درخواست:**
+```http
+POST /api/ai/suggest
+Content-Type: application/json
+
+{
+  "deviceContext": "دمای فعلی: 28 درجه، رطوبت: 65%، ساعت: 14:00، تعداد افراد در خانه: 2 نفر"
+}
+```
+
+**پاسخ:**
+```json
+{
+  "suggestions": "با توجه به شرایط فعلی، پیشنهادات زیر را دارم:\n- دمای 28 درجه کمی بالا است، روشن کردن کولر با دمای 24-25 درجه توصیه می‌شود\n- رطوبت 65% در محدوده مناسب است\n- در این ساعت از روز (14:00) پرده‌ها را بکشید تا آفتاب مستقیم وارد نشود",
+  "timestamp": "2025-12-16T10:30:00Z"
+}
+```
+
+### 3. چت پیشرفته
+
+**درخواست:**
+```http
+POST /api/ai/chat
+Content-Type: application/json
+
+{
+  "messages": [
+    {
+      "role": "system",
+      "content": "شما یک دستیار هوشمند خانه هوشمند هستید."
+    },
+    {
+      "role": "user",
+      "content": "دمای خانه 18 درجه است"
+    },
+    {
+      "role": "assistant",
+      "content": "درجه حرارت 18 درجه را دریافت کردم. این دما کمی پایین است."
+    },
+    {
+      "role": "user",
+      "content": "چه کار کنم؟"
+    }
+  ],
+  "temperature": 0.7
+}
+```
+
+## مثال‌های Curl
+
+### سوال ساده
+```bash
+curl -X POST http://localhost:5000/api/ai/ask \
+  -H "Content-Type: application/json" \
+  -d '{"question":"بهترین دمای کولر برای خواب چیست؟"}'
+```
+
+### دریافت پیشنهاد
+```bash
+curl -X POST http://localhost:5000/api/ai/suggest \
+  -H "Content-Type: application/json" \
+  -d '{"deviceContext":"دمای اتاق خواب: 26 درجه، ساعت: 22:00"}'
+```
+
+## استفاده در کد C#
+
+```csharp
+using GreenHome.AI.DeepSeek;
+
+public class MyService
+{
+    private readonly IDeepSeekService _ai;
+
+    public MyService(IDeepSeekService ai)
+    {
+        _ai = ai;
+    }
+
+    public async Task<string> GetAdvice()
+    {
+        var answer = await _ai.AskSimpleAsync(
+            "چگونه خانه هوشمند خود را امن‌تر کنم؟"
+        );
+        
+        return answer ?? "پاسخی دریافت نشد";
+    }
+}
+```
+
+## نکات مهم
+
+### هزینه
+- هر درخواست به API DeepSeek هزینه دارد
+- بر اساس تعداد توکن‌های استفاده شده محاسبه می‌شود
+- برای کاهش هزینه، سوالات را مختصر و مفید بپرسید
+
+### محدودیت‌ها
+- تعداد درخواست در دقیقه محدود است
+- اگر خطای 429 دریافت کردید، کمی صبر کنید
+
+### بهینه‌سازی
+- از `temperature` پایین‌تر (0.3-0.7) برای پاسخ‌های دقیق‌تر استفاده کنید
+- `maxTokens` را برای کنترل طول پاسخ تنظیم کنید
+- پاسخ‌های تکراری را cache کنید
+
+## عیب‌یابی
+
+### خطا: 401 Unauthorized
+- API Key را چک کنید
+- مطمئن شوید که در appsettings.json صحیح است
+
+### خطا: 429 Too Many Requests
+- به محدودیت تعداد درخواست رسیده‌اید
+- 1-2 دقیقه صبر کنید
+
+### خطا: Timeout
+- درخواست طولانی است
+- `maxTokens` را کاهش دهید
+- timeout را افزایش دهید
+
+## پشتیبانی
+
+برای سوالات و مشکلات:
+- مستندات کامل: [README.md](README.md)
+- وب‌سایت DeepSeek: https://platform.deepseek.com
+- مستندات API: https://platform.deepseek.com/api-docs
+