Transformers Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require codewithkyrian/transformers
   

   Ensure PHP ≥ 8.4 (due to nullable deprecations in this release) and php-ml extension is installed (required for core ML operations).

2. First Use Case: Text Classification

   use CodeWithKyrian\Transformers\Pipeline;
   use CodeWithKyrian\Transformers\Tasks\ClassificationTask;
   
   $pipeline = Pipeline::create('distilbert-base-uncased-finetuned-sst-2-english');
   $result = $pipeline->forward(['text' => 'This product is amazing!']);
   // Output: ['label' => 'POSITIVE', 'scores' => ['NEGATIVE' => 0.05, 'POSITIVE' => 0.95]]
   

3. Key Files to Explore

   • config/transformers.php: Updated model configurations, API endpoints, and Symfony 8 compatibility settings.
   • src/Tasks/: Predefined tasks (e.g., TextGenerationTask, TranslationTask).
   • src/Pipeline.php: Core pipeline logic with PHP 8.4 nullable type fixes.
   • src/Console/: New CLI command registration fixes (if using artisan commands).

Implementation Patterns

1. Task-Specific Workflows

Text Classification

$task = new ClassificationTask('bert-base-uncased');
$task->setText('The service was terrible.');
$predictions = $task->predict(); // Returns labeled probabilities

Text Generation

$generator = new TextGenerationTask('gpt2');
$generator->setPrompt('Once upon a time');
$output = $generator->generate(); // Returns generated text

Translation

$translator = new TranslationTask('Helsinki-NLP/opus-mt-en-fr');
$translation = $translator->translate('Hello', 'fr'); // 'Bonjour'

2. Pipeline Customization

• Chaining Tasks:

  $pipeline = Pipeline::create('text2text-generation')
      ->setTask(new TextGenerationTask('t5-small'))
      ->setTask(new PostProcessTask()); // Custom post-processing
  

• Dynamic Model Loading:

  $pipeline = Pipeline::create('custom-model')
      ->setModelPath(storage_path('models/custom.pt'))
      ->setTask(new CustomTask());
  

3. Integration with Laravel

Service Provider Binding

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->singleton(Pipeline::class, function ($app) {
        return Pipeline::create('distilbert-base-uncased');
    });
}

API Route Example

Route::post('/analyze-sentiment', function (Request $request) {
    $pipeline = app(Pipeline::class);
    $result = $pipeline->forward(['text' => $request->text]);
    return response()->json($result);
});

Queue Jobs for Async Processing

// app/Jobs/ProcessTextJob.php
public function handle()
{
    $pipeline = Pipeline::create('text-generation');
    $this->text->content = $pipeline->forward(['text' => $this->text->prompt]);
    $this->text->save();
}

4. Caching Responses

$pipeline = Pipeline::create('bert-base-uncased')
    ->setCacheTTL(3600); // Cache for 1 hour
$result = $pipeline->forward(['text' => 'Cached example']);

5. CLI Integration (New in 0.6.2)

If using artisan commands, ensure proper CLI registration:

php artisan transformers:task --help  # Example command (if applicable)

Gotchas and Tips

Pitfalls

1. PHP 8.4 Nullable Deprecations

   • This release fixes nullable type deprecations, but ensure your custom tasks extend base classes correctly.
   • Fix: Update custom tasks to use non-nullable types where applicable.

2. Symfony 8 Compatibility

   • The package now supports Symfony 8 components. If integrating with Symfony, verify dependency conflicts.
   • Fix: Update composer.json to align with Symfony 8 requirements if needed.

3. Namespace Conflicts

   • Fixed in 0.6.2, but avoid naming custom classes Transformers to prevent conflicts.
   • Fix: Use unique namespaces (e.g., App\Tasks\CustomTask).

4. Model Size Limits

   • Large models (e.g., gpt-3.5-turbo) require significant RAM. Use smaller variants (e.g., distilbert) for production.
   • Fix: Monitor memory usage with memory_get_usage() and offload to a microservice if needed.

5. API Rate Limits

   • Hugging Face API has request quotas. Cache responses aggressively.
   • Fix: Implement a Cache::remember wrapper around Pipeline::forward().

6. Tokenization Errors

   • Long inputs may exceed token limits (e.g., 512 tokens for BERT).
   • Fix: Truncate text or use a model with a larger context window (e.g., bigscience/bloom).

7. GPU Acceleration

   • CPU inference is slow. Ensure CUDA/cuDNN is installed for GPU support.
   • Fix: Set config/transformers.php:

     'device' => 'cuda',
     

Debugging Tips

• Log Pipeline Inputs/Outputs:

  $pipeline->setLogger(function ($log) {
      \Log::debug('Transformer Log:', ['event' => $log]);
  });
  

• Validate Model Outputs:

  if (!$pipeline->isValid()) {
      \Log::error('Invalid model output:', $pipeline->getErrors());
  }
  

Extension Points

1. Custom Tasks

   // app/Tasks/CustomTask.php
   class CustomTask extends Task
   {
       public function predict(array $inputs): array
       {
           // Implement custom logic (e.g., ensemble models)
           return ['custom_result' => true];
       }
   }
   

2. Pre/Post-Processing

   $pipeline->setPreProcess(function ($inputs) {
       return ['cleaned_text' => strtolower($inputs['text'])];
   });
   
   $pipeline->setPostProcess(function ($output) {
       return ['formatted' => ucfirst($output['label'])];
   });
   

3. Model Fine-Tuning

   • Use the HuggingFace\Transformers PHP bindings to fine-tune models locally, then load them via:

     $pipeline->setModelPath('/path/to/fine-tuned-model');
     

Configuration Quirks

• API Endpoint Overrides:

  // config/transformers.php
  'api_endpoint' => env('TRANSFORMERS_API_URL', 'https://api-inference.huggingface.co'),
  

• Environment-Specific Models:

  $model = config('transformers.models.'.env('APP_ENV'));
  $pipeline = Pipeline::create($model);
  

Performance Optimization

• Batch Processing:

  $results = $pipeline->batchForward([
      ['text' => 'Sample 1'],
      ['text' => 'Sample 2'],
  ]);
  

• Lazy Loading:

  $pipeline = Pipeline::lazy('text-generation'); // Loads model on first use
  

Symfony 8 Integration

• If using Symfony 8, ensure your composer.json includes compatible dependencies:

  "require": {
      "symfony/*": "^6.4 || ^8.0"
  }
  

Breaking Changes in 0.6.2

• PHP 8.4 Requirement: Upgrade PHP to 8.4 to avoid nullable type deprecation warnings.
• Namespace Fixes: Avoid naming classes Transformers to prevent conflicts.
• CLI Command Registration: Updated to work with Symfony 8 (if applicable).