GreenHomeBack/src/GreenHome.AI.DeepSeek/USAGE_FA.md

راهنمای سریع استفاده از سرویس DeepSeek

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

گام 1: دریافت API Key

1. به آدرس https://platform.deepseek.com بروید
2. ثبت‌نام کنید یا وارد شوید
3. از منوی API Keys یک کلید جدید بسازید
4. کلید را کپی کنید (مهم: فقط یک بار نمایش داده می‌شود!)

گام 2: تنظیم API Key

API Key خود را در فایل appsettings.json قرار دهید:

{
  "DeepSeek": {
    "ApiKey": "کلید-API-خود-را-اینجا-قرار-دهید"
  }
}

هشدار امنیتی: هرگز API Key را در Git commit نکنید!

گام 3: اجرای برنامه

cd GreenHome.Api
dotnet run

استفاده از API

سرویس روی آدرس http://localhost:5000 (یا پورت دیگری که تنظیم کرده‌اید) اجرا می‌شود.

1. پرسیدن یک سوال ساده

درخواست:

POST /api/ai/ask
Content-Type: application/json

{
  "question": "چگونه می‌توانم مصرف انرژی خانه را کاهش دهم؟"
}

پاسخ:

{
  "question": "چگونه می‌توانم مصرف انرژی خانه را کاهش دهم؟",
  "answer": "برای کاهش مصرف انرژی خانه می‌توانید از راه‌کارهای زیر استفاده کنید:\n1. از لامپ‌های LED استفاده کنید\n2. ترموستات هوشمند نصب کنید\n3. عایق‌بندی خانه را بهبود دهید...",
  "timestamp": "2025-12-16T10:30:00Z"
}

2. دریافت پیشنهادات برای خانه هوشمند

درخواست:

POST /api/ai/suggest
Content-Type: application/json

{
  "deviceContext": "دمای فعلی: 28 درجه، رطوبت: 65%، ساعت: 14:00، تعداد افراد در خانه: 2 نفر"
}

پاسخ:

{
  "suggestions": "با توجه به شرایط فعلی، پیشنهادات زیر را دارم:\n- دمای 28 درجه کمی بالا است، روشن کردن کولر با دمای 24-25 درجه توصیه می‌شود\n- رطوبت 65% در محدوده مناسب است\n- در این ساعت از روز (14:00) پرده‌ها را بکشید تا آفتاب مستقیم وارد نشود",
  "timestamp": "2025-12-16T10:30:00Z"
}

3. چت پیشرفته

درخواست:

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

سوال ساده

curl -X POST http://localhost:5000/api/ai/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"بهترین دمای کولر برای خواب چیست؟"}'

دریافت پیشنهاد

curl -X POST http://localhost:5000/api/ai/suggest \
  -H "Content-Type: application/json" \
  -d '{"deviceContext":"دمای اتاق خواب: 26 درجه، ساعت: 22:00"}'

استفاده در کد C#

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
• وب‌سایت DeepSeek: https://platform.deepseek.com
• مستندات API: https://platform.deepseek.com/api-docs