ویرگول
ورودثبت نام
آرش فدائی
آرش فدائیتوسعه‌دهنده ارشد وب و متخصص PHP
آرش فدائی
آرش فدائی
خواندن ۷ دقیقه·۳ ماه پیش

نحوه استفاده از یک AI SDK در Laravel

Laravel محیط بسیار مناسبی برای پیاده‌سازی قابلیت‌های هوش مصنوعی است؛ از تولید پیش‌نویس و خلاصه‌سازی تیکت‌ها گرفته تا دسته‌بندی پیام‌های پشتیبانی یا ساخت یک دستیار داخلی.

اما چالش اصلی صرفاً ارسال یک درخواست به مدل هوش مصنوعی نیست. مسئله مهم این است که SDK را به شکلی در Laravel پیاده‌سازی کنیم که:

  • کلیدهای API امن باقی بمانند.

  • درخواست‌های طولانی باعث مسدود شدن کاربران نشوند.

  • خروجی مدل قبل از استفاده یا ذخیره‌سازی اعتبارسنجی شود.

  • خطاها و عملکرد درخواست‌ها به‌درستی ثبت و مدیریت شوند.

در این آموزش، یک الگوی عملی برای استفاده از یک AI SDK در پروژه Laravel پیاده‌سازی می‌کنیم.

چیزی که در این آموزش می‌سازید

در پایان، موارد زیر را خواهید داشت:

  • یک AI Client که در Service Container لاراول ثبت شده است.

  • یک سرویس سبک برای Chat و تولید متن.

  • یک Job در Queue برای درخواست‌های زمان‌بر.

  • اعتبارسنجی و Logging پایه برای خروجی مدل هوش مصنوعی.

پیش‌نیازها

برای اجرای این مثال‌ها به موارد زیر نیاز دارید:

  • Laravel 10 یا 11

  • PHP 8.1 یا بالاتر

  • API Key از ارائه‌دهنده سرویس هوش مصنوعی

  • یک Queue Driver برای محیط Production مانند database یا redis


مرحله ۱: ذخیره صحیح Secretها

هرگز API Key را مستقیماً داخل کد قرار ندهید.

کلیدهای API باید در فایل .env قرار بگیرند و سپس از طریق فایل‌های config/ در اختیار برنامه قرار داده شوند:

AI_API_KEY= AI_BASE_URL=https://api.openai.com/v1 AI_MODEL=gpt-4.1-mini AI_TIMEOUT=30

سپس در فایل config/services.php تنظیمات مربوط به سرویس AI را اضافه کنید:

'ai' => [ 'key' => env('AI_API_KEY'), 'base_url' => env('AI_BASE_URL'), 'model' => env('AI_MODEL', 'gpt-4.1-mini'), 'timeout' => (int) env('AI_TIMEOUT', 30), ],

به این ترتیب، اطلاعات حساس مستقیماً داخل سورس‌کد قرار نمی‌گیرند و می‌توانید تنظیمات مربوط به مدل، آدرس API و Timeout را از طریق Environment مدیریت کنید.


مرحله ۲: نصب و ثبت SDK

نام دقیق پکیج‌ها بسته به Provider مورد استفاده شما متفاوت است. نکته مهم این است که یک Application Service واحد داشته باشید که Client مربوط به Vendor را در خود قرار دهد.

برای مثال، برای SDK مربوط به OpenAI می‌توانید از دستورهای زیر استفاده کنید:

composer require openai-php/laravel php artisan vendor:publish --provider="OpenAI\Laravel\ServiceProvider"

سپس یک سرویس برای تولید متن ایجاد کنید:

namespace App\Services\AI; use OpenAI\Client; class TextGenerator { public function __construct( private Client $client, private string $model ) {} public function complete(string $system, string $user): string { $response = $this->client->chat()->create([ 'model' => $this->model, 'messages' => [ ['role' => 'system', 'content' => $system], ['role' => 'user', 'content' => $user], ], 'temperature' => 0.3, ]); return trim((string) ($response->choices[0]->message->content ?? '')); } }

حالا در AppServiceProvider این سرویس را در Service Container ثبت کنید:

$this->app->singleton(TextGenerator::class, function () { return new TextGenerator( client: \OpenAI::client(config('services.ai.key')), model: config('services.ai.model'), ); });

ساخت Client را متناسب با SDK انتخابی خود تنظیم کنید.

نکته مهم این است که فقط یک Binding برای این سرویس داشته باشید تا Controllerها مجبور نباشند هر بار به‌صورت دستی Client مربوط به AI را ایجاد کنند.

این کار باعث می‌شود ساختار برنامه تمیزتر و تغییر Provider یا SDK در آینده بسیار ساده‌تر شود.


مرحله ۳: فراخوانی AI از Controller

برای درخواست‌های کوتاه و سریع می‌توانید مستقیماً از Controller با سرویس AI ارتباط برقرار کنید.

به عنوان مثال، یک Endpoint برای خلاصه‌سازی متن:

use App\Services\AI\TextGenerator; use Illuminate\Http\Request; public function summarize(Request $request, TextGenerator $ai) { $data = $request->validate([ 'text' => ['required', 'string', 'max:8000'], ]); $summary = $ai->complete( 'Summarize the text in 3 bullet points. No fluff.', $data['text'] ); abort_if($summary === '', 502, 'Empty model response'); return response()->json(['summary' => $summary]); }

در این مثال ابتدا ورودی کاربر اعتبارسنجی می‌شود.

سپس متن به مدل ارسال شده و نتیجه دریافت می‌شود.

در نهایت نیز بررسی می‌کنیم که مدل پاسخ خالی برنگردانده باشد.

چه زمانی از درخواست مستقیم استفاده کنیم؟

فقط زمانی از درخواست Synchronous استفاده کنید که زمان پاسخ قابل قبول باشد.

اگر درخواست ممکن است چند ثانیه یا بیشتر طول بکشد، بهتر است آن را به Queue منتقل کنید.


مرحله ۴: انتقال عملیات طولانی به Job

برای عملیات زمان‌بر بهتر است از Laravel Queue استفاده کنید.

ابتدا یک Job ایجاد کنید:

php artisan make:job GenerateArticleDraft

سپس Job را به شکل زیر پیاده‌سازی کنید:

namespace App\Jobs; use App\Models\Post; use App\Services\AI\TextGenerator; use Illuminate\Bus\Queueable; use Illuminate\Contracts\Queue\ShouldQueue; use Illuminate\Foundation\Bus\Dispatchable; use Illuminate\Queue\InteractsWithQueue; use Illuminate\Queue\SerializesModels; class GenerateArticleDraft implements ShouldQueue { use Dispatchable, InteractsWithQueue, Queueable, SerializesModels; public int $tries = 3; public int $timeout = 90; public function __construct(public Post $post) {} public function handle(TextGenerator $ai): void { $draft = $ai->complete( 'Write a clear technical article draft in Markdown.', 'Topic: ' . $this->post->title ); $this->post->update([ 'content' => $draft, 'status' => 'draft', ]); } }

حالا می‌توانید Job را Dispatch کنید:

GenerateArticleDraft::dispatch($post);

در این حالت، کاربر مجبور نیست منتظر پاسخ AI بماند.

Laravel عملیات تولید محتوا را در Queue قرار می‌دهد و Worker در پس‌زمینه آن را اجرا می‌کند.

این روش برای مواردی مانند:

  • تولید مقاله

  • خلاصه‌سازی تعداد زیادی متن

  • پردازش فایل‌ها

  • تولید توضیحات محصولات

  • تحلیل داده‌ها

  • پردازش گروهی درخواست‌های AI

مناسب‌تر است.


مرحله ۵: اعتبارسنجی خروجی مدل

یکی از نکات بسیار مهم این است که خروجی LLM را ورودی قابل اعتماد در نظر نگیرید.

مدل هوش مصنوعی ممکن است خروجی ناقص، اشتباه یا حتی با فرمت غیرمنتظره تولید کند.

بنابراین قبل از ذخیره یا استفاده از خروجی، آن را اعتبارسنجی کنید.

حداقل اقدامات پیشنهادی:

  • پاسخ خالی را رد کنید.

  • حداکثر طول خروجی را محدود کنید.

  • اگر خروجی قرار است در HTML نمایش داده شود، HTML را Sanitize یا Escape کنید.

  • برای وظایف ساختاریافته، از JSON استفاده کرده و آن را اعتبارسنجی کنید.

برای مثال:

$json = $ai->complete( 'Return JSON only with keys title and outline (array of strings).', $topic ); $data = json_decode($json, true); abort_if(! is_array($data), 422, 'Invalid AI JSON'); $validated = validator($data, [ 'title' => ['required', 'string', 'max:160'], 'outline' => ['required', 'array', 'min:3'], 'outline.*' => ['string', 'max:200'], ])->validate();

در اینجا از مدل خواسته‌ایم فقط JSON برگرداند.

سپس:

  1. JSON Decode می‌شود.

  2. بررسی می‌کنیم که خروجی واقعاً یک Array باشد.

  3. ساختار داده با Laravel Validator اعتبارسنجی می‌شود.

  4. فقط در صورت معتبر بودن، می‌توانیم از داده استفاده یا آن را ذخیره کنیم.


بهترین روش‌ها

هنگام ساخت قابلیت‌های AI در Laravel، نکات زیر را رعایت کنید:

۱. Promptها را متمرکز نگه دارید

Promptها را در Controllerهای مختلف پراکنده نکنید.

بهتر است آن‌ها را در:

  • Serviceها

  • Classهای اختصاصی

  • فایل‌های Configuration

قرار دهید.

این کار مدیریت و تغییر Promptها را ساده‌تر می‌کند.

۲. Logging داشته باشید

مواردی مانند:

  • نام مدل

  • زمان پاسخ

  • وضعیت درخواست

  • دلیل خطا

  • تعداد Retryها

را Log کنید.

اما هرگز Secretها و API Keyها را در Log ذخیره نکنید.

۳. برای Endpointهای عمومی Rate Limit قرار دهید

اگر قابلیت AI از طریق API عمومی در اختیار کاربران قرار دارد، حتماً Rate Limiting اضافه کنید.

در غیر این صورت ممکن است یک کاربر با ارسال تعداد زیادی درخواست، هزینه API شما را به‌شدت افزایش دهد.

۴. ابتدا Draft تولید کنید

برای محتوای تولیدشده توسط AI بهتر است ابتدا آن را به‌صورت Draft ذخیره کنید.

سپس کاربر یا ادمین بتواند آن را بررسی و تأیید کند.

۵. برای تست از Fake Client استفاده کنید

در تست‌های CI نباید هر بار واقعاً به API سرویس AI متصل شوید.

بهتر است Client مربوط به AI را Fake کنید تا تست‌ها:

  • سریع‌تر باشند.

  • هزینه API ایجاد نکنند.

  • به اینترنت وابسته نباشند.

  • نتایج قابل پیش‌بینی داشته باشند.


اشتباهات رایج

قرار دادن API Key در Repository

قرار دادن API Key در سورس‌کد یا Git Repository یک اشتباه امنیتی جدی است.

کلیدهای API را در .env قرار دهید و مطمئن شوید .env در Git Commit نمی‌شود.

اجرای مستقیم مدل داخل Web Request

اگر مدل چندین ثانیه زمان نیاز دارد، نباید کاربر را مجبور کنید تا پایان درخواست منتظر بماند.

در این شرایط از Queue استفاده کنید.

ذخیره HTML خام تولیدشده توسط AI

اگر مدل HTML تولید می‌کند، نباید آن را بدون بررسی مستقیماً در سایت نمایش دهید.

ابتدا باید خروجی را Sanitize یا Escape کنید تا از مشکلات امنیتی جلوگیری شود.

نداشتن Timeout و Retry

ارتباط با سرویس‌های خارجی همیشه ممکن است با خطا یا Timeout مواجه شود.

بنابراین باید برای درخواست‌ها Timeout و در صورت نیاز Retry Strategy مناسب داشته باشید.

استفاده از یک Prompt بسیار بزرگ

به جای ساخت یک Prompt عظیم که قرار است «همه کارها» را انجام دهد، بهتر است وظایف را به عملیات کوچک‌تر تقسیم کنید.

برای مثال:

Generate Title ↓ Generate Outline ↓ Generate Content ↓ Validate ↓ Save Draft

این ساختار معمولاً قابل کنترل‌تر، قابل تست‌تر و قابل نگهداری‌تر است.


جمع‌بندی

استفاده از یک AI SDK در Laravel بیشتر از آنکه یک مسئله پیچیده مربوط به هوش مصنوعی باشد، یک مسئله مربوط به مهندسی نرم‌افزار صحیح است.

یک معماری مناسب باید شامل موارد زیر باشد:

Config برای مدیریت Secretها

Service Boundary برای جدا کردن Vendor SDK

Queue برای عملیات زمان‌بر

Validation برای بررسی خروجی مدل

با ایجاد این ساختار پایه، اضافه کردن قابلیت‌های مختلف هوش مصنوعی بسیار ساده‌تر می‌شود.

همچنین اگر در آینده تصمیم بگیرید مدل یا Provider خود را تغییر دهید، به جای بازنویسی کل پروژه، فقط بخش کوچکی از سیستم را تغییر خواهید داد.


سوالات متداول

کدام AI SDK را انتخاب کنم؟

بهتر است از SDK رسمی یا یک Client معتبر و به‌خوبی نگهداری‌شده برای Provider مورد نظر خود استفاده کنید.

با این حال، توصیه می‌شود برنامه شما مستقیماً به کلاس‌های Vendor وابسته نباشد.

به جای آن، یک Abstraction مانند:

TextGenerator

ایجاد کنید و Controllerها و سایر بخش‌های برنامه را به این سرویس وابسته کنید.

در این صورت تغییر Provider یا مدل در آینده بسیار ساده‌تر خواهد بود.

آیا می‌توانم در Laravel پاسخ‌های AI را Stream کنم؟

بله.

بسیاری از SDKها از Streaming پشتیبانی می‌کنند.

Streaming برای رابط‌های Chat بسیار مناسب است، زیرا کاربر می‌تواند پاسخ را هم‌زمان با تولید شدن مشاهده کند.

اما برای پردازش‌های گروهی و Batch Generation همچنان بهتر است از Queue و Job استفاده کنید.

آیا حتماً به Redis نیاز دارم؟

خیر.

برای شروع می‌توانید از Queue مبتنی بر database استفاده کنید.

با افزایش تعداد درخواست‌های AI، حجم پردازش و تعداد Retryها، Redis می‌تواند انتخاب مناسب‌تری برای Queue باشد.

در نتیجه، می‌توانید با Database Queue شروع کنید و در صورت افزایش بار سیستم، زیرساخت Queue را به Redis منتقل کنید.

هوش مصنوعیaiلاراولآموزش لاراول
۰
۰
آرش فدائی
آرش فدائی
توسعه‌دهنده ارشد وب و متخصص PHP
شاید از این پست‌ها خوشتان بیاید