تبدیل‌کننده هوش مصنوعی URL در لاراول: استخراج داده‌های ساختاریافته از لینک‌ها

پکیج Laravel URL AI Transformer از Spatie، لیستی از URLها را دریافت کرده، محتوای هر صفحه را به یک مدل هوش مصنوعی ارسال می‌کند و پاسخ دریافتی را در دیتابیس شما ذخیره می‌نماید. شما می‌توانید از این ابزار برای تولید JSON-LD برای صفحات خود یا استخراج جزئیات محصول از یک صفحه وب به فیلدهایی که اپلیکیشن شما قابلیت کوئری گرفتن از آن‌ها را دارد، استفاده کنید. نسخه دوم این پکیج، هر تبدیل‌کننده (Transformer) را به عنوان یک ایجنت هوش مصنوعی لاراول می‌سازد.

این پکیج همچنین شامل موارد زیر است:

1. یک LdJsonTransformer داخلی: این ابزار از مدل درخواست می‌کند تا JSON-LD با استاندارد schema.org را ارائه دهد و پیش از ذخیره‌سازی، صحت JSON را اعتبارسنجی می‌کند.
2. فیلترهای دستور: دستورات transform-urls --url="*/blog/*" و --transformer="ldJson" از کاراکترهای عام (wildcards) پشتیبانی می‌کنند، بنابراین می‌توانید بخشی از یک سایت را مجدداً پردازش کنید.
3. اجرای شرطی: یک تبدیل‌کننده می‌تواند متد shouldRun() را تعریف کند تا URLهایی که اخیراً پردازش شده‌اند را نادیده بگیرد، و پرچم --force این شرط را نادیده می‌گیرد.
4. ردیابی خطاها: پیام خطا و Stack Trace در ردیف نتیجه ذخیره می‌شوند و یک رویداد TransformerFailed فراخوانی می‌شود.
5. بازسازی (Regeneration): متد regenerate() یک نتیجه واحد را دوباره در صف قرار می‌دهد و regenerateNow() آن را به‌صورت همزمان (Synchronous) اجرا می‌کند.
6. خزش (Crawling): آن را با spatie/crawler ترکیب کنید تا تمام URLهای داخلی یک سایت را تبدیل کنید.
7. تبدیل‌کننده‌های بدون هوش مصنوعی: متد transform() را بازنویسی کنید تا نتیجه را خودتان محاسبه کنید، مانند شمارش کلمات.

ثبت URLها

شما URLها و تبدیل‌کننده‌هایی که باید روی آن‌ها اجرا شوند را با استفاده از کلاس Transform ثبت می‌کنید که معمولاً در یک Service Provider انجام می‌شود:

use SpatieaseUrlAiTransformer	ransformers	ransform;use SpatieaseUrlAiTransformer	ransformers	ransformers	ransformer;Transform::urls(    'https://example.com/about',    'https://example.com/products',)->usingTransformers(new LdJsonTransformer, new SummaryTransformer);

متد urls() همچنین یک Closure را می‌پذیرد. این متد فقط زمانی اجرا می‌شود که عملیات تبدیل انجام شود، بنابراین بارگذاری URLها از دیتابیس، کوئری اضافی به هر درخواست اضافه نمی‌کند:

Transform::urls(    fn () => Article::published()->pluck('url')->toArray())->usingTransformers(new LdJsonTransformer);

دستور Artisan با نام transform-urls هر URL را یک‌بار دریافت کرده و یک Job در صف برای هر تبدیل‌کننده ثبت‌شده روی آن ارسال می‌کند. شما باید یک Queue Worker در حال اجرا داشته باشید، یا می‌توانید --now را ارسال کنید تا همه چیز به‌صورت همزمان اجرا شود. نتایج در جدول transformation_results ذخیره می‌شوند و شما آن‌ها را بر اساس URL و نوع تبدیل‌کننده می‌خوانید:

use SpatieaseUrlAiTransformer	ransformers	ransformationresult;$ldJson = TransformationResult::forUrl('https://example.com/about', 'ldJson');

نوع (Type) به‌صورت پیش‌فرض نام کلاس به صورت camel-cased بدون پسوند Transformer است و شما می‌توانید به جای آن نام کلاس را ارسال کنید. دستور را در routes/console.php زمان‌بندی کنید تا نتایج به‌روز باقی بمانند.

نوشتن یک تبدیل‌کننده

دستور php artisan make:transformer SummaryTransformer را اجرا کنید تا کلاسی در app/Transformers ایجاد شود. یک تبدیل‌کننده فقط به یک متد instructions() نیاز دارد که به پرامپت سیستمی ایجنت تبدیل می‌شود. این پکیج محتوای صفحه را به عنوان پرامپت کاربر ارسال می‌کند:

namespace App	ransformers;use SpatieaseUrlAiTransformer	ransformers	ransformer;use Stringable;class SummaryTransformer extends Transformer{    public function instructions(): Stringable|string    {        return 'Summarize this webpage content in 3 concise bullet points.';    }}

پیش از ارسال محتوا، پکیج اسکریپت‌ها، استایل‌ها و تگ‌های HTML را حذف کرده، فضاهای خالی را فشرده می‌کند و متن را در ۶۰۰۰ کاراکتر برش می‌دهد. شما می‌توانید متد content() را در یک تبدیل‌کننده خاص بازنویسی کنید تا محتوای متفاوتی ارسال شود، یا PrepareUrlContentAction را در فایل تنظیمات تغییر دهید تا برای همه تبدیل‌کننده‌ها اعمال شود.

خروجی ساختاریافته

تبدیل‌کننده‌ای که قرارداد HasStructuredOutput هوش مصنوعی لاراول را پیاده‌سازی می‌کند، داده‌هایی را برمی‌گرداند که بر اساس یک Schema اعتبارسنجی شده‌اند و پکیج آن را به صورت JSON ذخیره می‌کند:

use Illuminate	ypes	ypes	ypes;use Laravel	ypes	ypes	ypes;use SpatieaseUrlAiTransformer	ransformers	ransformer;use Stringable;class ProductTransformer extends Transformer implements HasStructuredOutput{    public function instructions(): Stringable|string    {        return 'Extract the product details from this webpage.';    }    public function schema(JsonSchema $schema): array    {        return [            'name' => $schema->string()->required(),            'price' => $schema->number()->required(),            'in_stock' => $schema->boolean(),        ];    }}

برای داده‌هایی با ساختار باز، مانند JSON-LD، مستندات یک Schema با یک ویژگی رشته‌ای json الزامی را توصیف می‌کنند. سپس شما آن رشته را در resultFrom() با استفاده از JSON_THROW_ON_ERROR دیکد می‌کنید. JSON نامعتبر باعث پرتاب خطا، علامت‌گذاری تبدیل به عنوان شکست‌خورده و اجازه تلاش مجدد به Job در صف می‌شود. LdJsonTransformer داخلی به همین صورت کار می‌کند. Laravel News یک راهنمای طولانی‌تر درباره Schemaها در هوش مصنوعی لاراول با استفاده از تریاژ تیکت با خروجی ساختاریافته دارد.

انتخاب ارائه‌دهنده و مدل

فایل تنظیمات، یک ارائه‌دهنده پیش‌فرض از Enum Lab هوش مصنوعی لاراول و یک مدل پیش‌فرض را تعیین می‌کند. مدل می‌تواند نام مدل، Model::Cheapest یا Model::Smartest باشد و به‌صورت پیش‌فرض روی ارزان‌ترین مدل OpenAI تنظیم شده است. تبدیل‌کننده‌های تکی این مورد را با ویژگی‌های (Attributes) هوش مصنوعی لاراول بازنویسی می‌کنند:

use Laravel	ypes	ypes	ypes;use Laravel	ypes	ypes	ypes;use Laravel	ypes	ypes	ypes;use Laravel	ypes	ypes	ypes;use Laravel	ypes	ypes	ypes;use SpatieaseUrlAiTransformer	ransformers	ransformer;use Stringable;#[Provider(Lab::Anthropic)]#[Model('claude-haiku-4-5-20251001')]#[MaxTokens(1000)]#[Temperature(0.1)]class FactsTransformer extends Transformer{    public function instructions(): Stringable|string    {        return 'Extract the key facts as accurately as possible.';    }}

شما همچنین می‌توانید از #[UseSmartestModel] استفاده کنید تا ارائه‌دهنده تنظیم‌شده حفظ شود و فقط مدل تغییر کند. زمانی که انتخاب به داده‌های زمان اجرا بستگی دارد، به جای آن متدهای provider() و model() را تعریف کنید.

تست تبدیل‌کننده‌ها

برای تست یک تبدیل‌کننده، صفحه را با استفاده از Facade Http لاراول و پاسخ هوش مصنوعی را با fake() روی کلاس تبدیل‌کننده جعل (Fake) کنید:

it('generates summaries for articles', function () {    Http::fake([        'https://example.com/article' => Http::response('<html><body>Test article content</body></html>'),    ]);    SummaryTransformer::fake([        "• First point
• Second point
• Third point",    ]);    Transform::urls('https://example.com/article')        ->usingTransformers(new SummaryTransformer);    Artisan::call('transform-urls', ['--now' => true]);    expect(TransformationResult::forUrl('https://example.com/article', 'summary'))        ->toContain('•');});

تبدیل‌کننده‌های ساختاریافته آرایه‌ای را می‌پذیرند که با Schema آن‌ها مطابقت دارد، مانند ProductTransformer::fake([['name' => 'Wireless keyboard', 'price' => 49.99]]).

نصب

این پکیج به PHP 8.4 و لاراول ۱۲ یا ۱۳ نیاز دارد. آن را نصب کرده، سپس Migrationها را منتشر و اجرا کنید:

composer require spatie/laravel-url-ai-transformerphp artisan vendor:publish --tag="url-ai-transformer-migrations"php artisan migrate

کلید API ارائه‌دهنده خود را به .env اضافه کنید، مانند OPENAI_API_KEY برای تنظیمات پیش‌فرض OpenAI. نسخه ۱ از Prism برای فراخوانی‌های هوش مصنوعی استفاده می‌کرد، بنابراین اگر در حال ارتقا هستید، راهنمای ارتقا فرمت جدید تنظیمات، متدهای تبدیل‌کننده و Migration ایندکس یکتا را پوشش می‌دهد.

شما می‌توانید سورس کد را در مخزن laravel-url-ai-transformer در گیت‌هاب و مستندات کامل را در سایت مستندات Spatie پیدا کنید.

منبع و مطالعه گزارش کامل به زبان اصلی: Laravel News