ربط Groq API مع Laravel وReact خطوة بخطوة

يوضح هذا الدليل طريقة ربط Groq API مع Laravel وReact لبناء واجهة محادثة ترسل السؤال من React إلى خادم Laravel، ثم يعيد الخادم إجابة النموذج إلى الواجهة بصيغة JSON. سنضع مفتاح Groq في إعدادات الخادم، ونضيف تحققًا للمدخلات ومعالجة واضحة لأخطاء الاتصال.

الفكرة بسيطة: React لا يتصل بـ Groq مباشرة؛ بل يرسل طلبًا إلى مسار API في Laravel، وLaravel يتولى المصادقة والاتصال الخارجي. بهذه الطريقة يبقى مفتاح API خارج الشيفرة التي تصل إلى المتصفح.

• تخزين مفتاح Groq في ملف البيئة وإعدادات Laravel.
• إنشاء endpoint يستقبل السؤال ويتحقق منه.
• إرسال الطلب إلى Groq وإرجاع الإجابة إلى React.
• عرض حالة التحميل والأخطاء واختبار المسار.

المتطلبات قبل ربط Groq API مع Laravel وReact

تحتاج إلى مشروع Laravel وواجهة React تعملان، وPHP متوافق مع إصدار Laravel لديك، وحساب في GroqCloud لإنشاء مفتاح API. سنستخدم عميل HTTP المدمج في Laravel، لذلك لا تحتاج إلى مكتبة إضافية لإرسال الطلب.

1. إنشاء مفتاح Groq API واختيار النموذج

سجّل الدخول إلى لوحة GroqCloud، ثم أنشئ مفتاحًا من قسم API Keys. انسخه إلى مدير أسرار أو مكان آمن؛ لا تضعه في React أو في مستودع Git. اختر معرّف نموذج متاحًا لحسابك من قائمة نماذج Groq الرسمية؛ يستخدم المثال openai/gpt-oss-20b ويمكنك استبداله بنموذج آخر مدعوم.

2. إضافة إعدادات Groq إلى ملف .env

في جذر مشروع Laravel أضف القيم التالية، واستبدل القيمة التجريبية بمفتاحك الحقيقي. عنوان Chat Completions هو عنوان Groq المتوافق مع واجهة OpenAI:

GROQ_API_KEY=ضع_مفتاحك_هنا
GROQ_API_URL=https://api.groq.com/openai/v1/chat/completions
GROQ_MODEL=openai/gpt-oss-20b

تأكد من أن ملف .env مستثنى من Git، ولا تستخدم بادئة VITE_ لمفتاح Groq؛ فمتغيرات Vite يمكن تضمينها في ملفات الواجهة العامة.

3. تعريف إعداد Groq في Laravel

افتح config/services.php وأضف المفتاح التالي داخل المصفوفة الرئيسية، مع الحفاظ على بقية الإعدادات الموجودة:

'groq' => [
    'api_key' => env('GROQ_API_KEY'),
    'api_url' => env('GROQ_API_URL', 'https://api.groq.com/openai/v1/chat/completions'),
    'model' => env('GROQ_MODEL', 'openai/gpt-oss-20b'),
],

4. إنشاء endpoint لربط Groq API مع Laravel وReact

أنشئ وحدة التحكم من الطرفية:

php artisan make:controller GroqController

في app/Http/Controllers/GroqController.php أضف الدالة التالية. تتحقق من طول السؤال، وتقرأ بيانات الاتصال من إعدادات Laravel، وتعيد أخطاء عامة دون كشف المفتاح أو تفاصيل Groq الداخلية:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class GroqController extends Controller
{
    public function chat(Request $request)
    {
        $validated = $request->validate([
            'message' => ['required', 'string', 'max:4000'],
        ]);

        $apiKey = config('services.groq.api_key');
        if (!$apiKey) {
            Log::error('Groq API key is not configured.');
            return response()->json(['message' => 'خدمة الذكاء الاصطناعي غير مهيأة.'], 500);
        }

        try {
            $response = Http::acceptJson()
                ->withToken($apiKey)
                ->timeout(45)
                ->post(config('services.groq.api_url'), [
                    'model' => config('services.groq.model'),
                    'messages' => [
                        ['role' => 'system', 'content' => 'أجب عن المستخدم باللغة التي يكتب بها.'],
                        ['role' => 'user', 'content' => $validated['message']],
                    ],
                    'max_completion_tokens' => 500,
                ]);

            if (!$response->successful()) {
                Log::warning('Groq API request failed.', ['status' => $response->status()]);
                return response()->json(['message' => 'تعذر الحصول على إجابة من Groq.'], 502);
            }

            $answer = $response->json('choices.0.message.content');
            if (!is_string($answer) || trim($answer) === '') {
                return response()->json(['message' => 'أعاد Groq إجابة فارغة.'], 502);
            }

            return response()->json(['answer' => $answer]);
        } catch (ConnectionException) {
            Log::warning('Could not connect to Groq API.');
            return response()->json(['message' => 'تعذر الاتصال بخدمة Groq حاليًا.'], 504);
        }
    }
}

يستخدم timeout(45) حدًا زمنيًا للطلب، وتتعامل Laravel مع أخطاء التحقق تلقائيًا. راجع توثيق Laravel HTTP Client عند الحاجة إلى خيارات مثل إعادة المحاولة أو اختبار الطلبات دون الاتصال بالخدمة.

5. إضافة مسار API واختبار وجوده

إذا لم يكن ملف routes/api.php موجودًا في مشروعك، فعّل إعداد API مرة واحدة:

php artisan install:api

بعد ذلك أضف المسار إلى routes/api.php. تضع Laravel بادئة /api تلقائيًا لمسارات هذا الملف:

<?php

use App\Http\Controllers\GroqController;
use Illuminate\Support\Facades\Route;

Route::post('/ai/chat', [GroqController::class, 'chat'])
    ->middleware('throttle:10,1');

يمرر المحدد throttle:10,1 حدًا أوليًا للطلبات؛ عدّله بما يناسب التطبيق والمستخدمين، وأضف المصادقة إذا كان المسار مخصصًا لمستخدمين مسجلين. ثم افحص تسجيل المسار:

php artisan optimize:clear
php artisan route:list --path=api/ai

6. ربط Groq API مع Laravel وReact: إرسال السؤال وعرض الإجابة

في المكوّن التالي يستدعي React مسار Laravel فقط، ويتعامل مع حالة الإرسال ورسالة الخطأ. عند تشغيل React على نطاق مختلف أثناء التطوير، اضبط VITE_API_URL على عنوان الخادم مثل http://127.0.0.1:8000 وأتح هذا النطاق في إعداد CORS الخاص بـ Laravel. في الإنتاج، يفضّل استخدام نطاق واحد أو إعداد proxy مناسب.

import { useState } from "react";

export default function GroqChat() {
  const [message, setMessage] = useState("");
  const [answer, setAnswer] = useState("");
  const [error, setError] = useState("");
  const [loading, setLoading] = useState(false);

  async function sendMessage(event) {
    event.preventDefault();
    if (!message.trim() || loading) return;

    setLoading(true);
    setError("");
    setAnswer("");

    const baseUrl = import.meta.env.VITE_API_URL;
    const endpoint = baseUrl ? baseUrl.replace(/\/$/, "") + "/api/ai/chat" : "/api/ai/chat";

    try {
      const response = await fetch(endpoint, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Accept: "application/json",
        },
        body: JSON.stringify({ message: message.trim() }),
      });
      const data = await response.json();
      if (!response.ok) throw new Error(data.message || "تعذر إكمال الطلب.");
      setAnswer(data.answer);
    } catch (err) {
      setError(err.message || "تعذر الاتصال بالخادم.");
    } finally {
      setLoading(false);
    }
  }

  return (
    <form onSubmit={sendMessage}>
      <textarea
        value={message}
        onChange={(event) => setMessage(event.target.value)}
        maxLength={4000}
        required
        placeholder="اكتب سؤالك هنا..."
      />
      <button type="submit" disabled={loading || !message.trim()}>
        {loading ? "جارٍ الإرسال..." : "إرسال السؤال"}
      </button>
      {error && <p role="alert">{error}</p>}
      {answer && <div className="answer">{answer}</div>}
    </form>
  );
}

قيمة VITE_API_URL ليست سرًا؛ فهي عنوان الخادم فقط. لا تضف مفتاح Groq إليها ولا ترسل ترويسة Authorization الخاصة بـ Groq من المتصفح.

7. اختبار التكامل وحل المشكلات الشائعة

1. أعد تشغيل خادم Laravel بعد تعديل .env، ثم نفّذ php artisan optimize:clear.
2. تأكد من ظهور POST api/ai/chat في نتيجة route:list.
3. أرسل سؤالًا قصيرًا من نموذج React وتحقق من ظهور الإجابة في الواجهة.
4. عند ظهور 401 أو 403، تحقق من مفتاح Groq وصلاحية النموذج؛ وعند ظهور 429 راجع حدود الاستخدام.
5. إذا فشل طلب المتصفح بين نطاقين محليين، راجع إعداد CORS وعنوان الخادم في VITE_API_URL.

للتوسع في بناء التطبيقات، يمكنك متابعة شرح Laravel مع Inertia وReact على onemoka، والرجوع إلى سلسلة REST API في Laravel لفهم تنظيم واجهات API. يعتمد المثال هنا على طلب JSON مستقل، ويمكن دمجه مع بنية مشروعك بحسب طريقة تشغيل الواجهة.

ملاحظات أمان عند استخدام Groq مع React

• احتفظ بـ GROQ_API_KEY في الخادم فقط، ولا تضعه في React أو المستودع.
• استخدم HTTPS في الإنتاج، ولا تسجل المفتاح أو نصوصًا حساسة في السجلات.
• تحقق من مدخلات المستخدم وحدّ من الطلبات، وفكّر في المصادقة وحصص الاستخدام قبل إتاحة المسار للعامة.
• راقب ردود API وسجلات Laravel من دون إرجاع تفاصيل داخلية إلى المتصفح.

الخلاصة

بهذه الخطوات أصبح لديك مسار واضح لـ ربط Groq API مع Laravel وReact: تحفظ Laravel المفتاح وتتصل بالنموذج، بينما تتولى React جمع السؤال وعرض النتيجة. اختبر التكامل أولًا في بيئة تطوير، ثم اضبط CORS والمصادقة وحدود الطلبات قبل استخدامه في الإنتاج.