Getting Started

Minimal Steps to First Use

Install Dependencies:

composer require symfony/ai-platform codewithkyrian/transformers

Ensure your system has Python 3.8+ and the transformers library installed:

pip install transformers torch

Configure Symfony AI in Laravel: Add to config/ai.php:

'providers' => [
    TransformersPhpProvider::class => [
        'model_path' => storage_path('app/models/distilbert'),
        'options' => [
            'device' => 'cpu', // or 'cuda' if available
            'quantization' => 'int8', // optional for smaller models
        ],
    ],
],

Download a Model: Use the transformers-php CLI or Python to download a model (e.g., distilbert-base-uncased) to the configured path. Example:

python -c "from transformers import AutoModel; AutoModel.from_pretrained('distilbert-base-uncased').save_pretrained('storage/app/models/distilbert')"

First Usage in Laravel: Register the Symfony AI service in AppServiceProvider:

public function register()
{
    $this->app->register(\Symfony\Component\AI\Bridge\Laravel\AIServiceProvider::class);
}

Use in a controller or service:

use Symfony\Component\AI\Platform\AIPlatformInterface;

public function generateEmbedding(AIPlatformInterface $ai)
{
    $model = $ai->getModel('distilbert');
    $embedding = $model->embed('Sample text to embed');
    return response()->json($embedding);
}

Test Locally: Call the endpoint and verify the response. Check logs for Python/FFI errors.

Where to Look First

Symfony AI Documentation: Core concepts for providers and model routing.
TransformersPHP Docs: Model loading, quantization, and device management.
Laravel Service Container: How to extend Symfony AI’s services into Laravel’s DI system.
storage_path(): Default location for model files (customize via config).

First Use Case: Semantic Search Embeddings

Configure a Sentence Transformer Model:

'providers' => [
    TransformersPhpProvider::class => [
        'model_path' => storage_path('app/models/all-MiniLM-L6-v2'),
        'options' => ['device' => 'cpu'],
    ],
],

Generate Embeddings for Search:

public function index(AIPlatformInterface $ai)
{
    $model = $ai->getModel('all-MiniLM-L6-v2');
    $products = Product::all();
    $embeddings = $products->map(fn ($product) =>
        $model->embed($product->description)
    );
    // Store embeddings in a vector DB (e.g., FAISS, Weaviate).
}

Query Embeddings:

public function search(AIPlatformInterface $ai, Request $request)
{
    $queryEmbedding = $ai->getModel('all-MiniLM-L6-v2')->embed($request->query);
    // Compare with stored embeddings (e.g., cosine similarity).
}

Implementation Patterns

Core Workflows

1. Model Lifecycle Management

Download Models: Use a Laravel command to fetch models from Hugging Face:

use Symfony\Component\Process\Process;
use Symfony\Component\Process\Exception\ProcessFailedException;

public function handle()
{
    $process = new Process(['python', '-m', 'transformers', 'download', 'distilbert-base-uncased', '--output', storage_path('app/models')]);
    $process->run();
    if (!$process->isSuccessful()) {
        throw new ProcessFailedException($process);
    }
}

Cache Models: Store models in storage/app/models and clear cache on updates:

public function clearModelCache()
{
    File::cleanDirectory(storage_path('app/models'));
}

2. Provider Routing

Leverage Symfony AI’s Provider Abstraction to route requests:

// config/ai.php
'providers' => [
    TransformersPhpProvider::class => [
        'model_path' => storage_path('app/models/distilbert'),
        'priority' => 1, // Higher priority = preferred provider
    ],
    HuggingFaceProvider::class => [ // Hypothetical cloud fallback
        'api_key' => env('HUGGINGFACE_API_KEY'),
        'priority' => 2,
    ],
],

In code:

$ai = app(AIPlatformInterface::class);
$embedding = $ai->getModel('distilbert')->embed('text'); // Uses highest-priority provider.

3. Batch Processing

Process multiple inputs efficiently:

public function batchEmbed(AIPlatformInterface $ai, array $texts)
{
    $model = $ai->getModel('distilbert');
    return array_map(fn ($text) => $model->embed($text), $texts);
}

4. Fallback to Cloud

Implement a fallback for critical paths:

public function safeEmbed(AIPlatformInterface $ai, string $text)
{
    try {
        return $ai->getModel('distilbert')->embed($text);
    } catch (ModelLoadException $e) {
        // Fallback to cloud (e.g., Hugging Face API).
        $client = new \GuzzleHttp\Client();
        $response = $client->post('https://api-inference.huggingface.co/models/...', [
            'json' => ['inputs' => $text],
        ]);
        return json_decode($response->getBody(), true);
    }
}

Integration Tips

Laravel-Specific Patterns

Service Container Binding: Bind Symfony AI’s services to Laravel’s container:

public function register()
{
    $this->app->bind(AIPlatformInterface::class, function ($app) {
        return new \Symfony\Component\AI\Platform\AIPlatform(
            $app['config']['ai.providers']
        );
    });
}

Artisan Commands: Create commands for model management:

php artisan ai:download-model distilbert-base-uncased
php artisan ai:list-models

Event Listeners: Trigger events for model loading/errors:
```
event(new ModelLoaded($modelName));
```

Caching: Cache embeddings or model outputs:

$cacheKey = "embedding:{$text}";
return Cache::remember($cacheKey, now()->addHours(1), function () use ($ai, $text) {
    return $ai->getModel('distilbert')->embed($text);
});

Performance Optimization

Quantization: Use int8 or int4 quantization for smaller models:

'options' => [
    'device' => 'cpu',
    'quantization' => 'int8',
],

Batching: Process inputs in batches to reduce overhead:

$model = $ai->getModel('distilbert');
$batchSize = 32;
$batches = array_chunk($texts, $batchSize);
$results = [];
foreach ($batches as $batch) {
    $results[] = $model->batchEmbed($batch);
}

GPU Acceleration: Enable CUDA if available:

'options' => [
    'device' => 'cuda',
],

Security

Input Validation: Sanitize inputs to prevent prompt injection:

use Illuminate\Support\Facades\Validator;

$validator = Validator::make(['text' => $request->input('text')], [
    'text' => 'required|string|max:5000',
]);

Model Isolation: Run models in a separate process or container to limit impact of crashes.

Gotchas and Tips

Pitfalls

Python Dependency Hell:
- Issue: TransformersPHP requires Python 3.8+ and specific library versions. Conflicts can arise if multiple projects use different Python environments.
- Fix: Use Docker or a virtual environment:
```
FROM python:3.8-slim
RUN pip install transformers torch
```
  Or isolate with pyenv:
```
pyenv install 3.8.18
pyenv local 3.8.18
```
FFI Crashes:
- Issue: PHP’s Foreign Function Interface (FFI) can crash if Python/C extensions are misconfigured.
- Fix:
  - Ensure `php-

Ai Transformers Php Platform Laravel Package