Ai Hugging Face Platform Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require symfony/ai-hugging-face-platform
   

2. Configure API key in .env:

   HUGGINGFACE_API_KEY=hf_your_api_key_here
   

3. Initialize the platform in a service provider or controller:

   use Symfony\AI\Platform\Bridge\HuggingFace\Factory;
   use Symfony\AI\Platform\Bridge\HuggingFace\Provider;
   
   $platform = Factory::createPlatform(
       apiKey: env('HUGGINGFACE_API_KEY'),
       provider: Provider::HUGGINGFACE_INFERENCE, // Default provider
   );
   

First Use Case: Chat Completion

use Symfony\AI\Platform\Message\Message;
use Symfony\AI\Platform\Message\MessageBag;
use Symfony\AI\Platform\Bridge\HuggingFace\Task;

$messages = new MessageBag([
    Message::ofUser('Explain Laravel dependency injection in simple terms.'),
]);

$result = $platform->invoke('HuggingFaceH4/zephyr-7b-beta', $messages, [
    'task' => Task::CHAT_COMPLETION,
    'temperature' => 0.7,
]);

echo $result->asText();

Key First Steps:

1. Discover models using the CLI:

   php artisan ai:huggingface:model-list --task=chat-completion --search=zephyr
   

2. Test with a lightweight model (e.g., google/flan-t5-small) before scaling.
3. Cache API responses for frequent queries (e.g., embeddings) using Laravel’s cache.

Implementation Patterns

Core Workflow: Task Invocation

1. Define the task (e.g., Task::TEXT_GENERATION, Task::IMAGE_CLASSIFICATION).
2. Prepare input:
   • For text: Use MessageBag or raw strings.
   • For images: Use Image::fromFile() or Image::fromUri().
3. Invoke with options:

   $result = $platform->invoke(
       modelId: 'model-name',
       input: $input,
       options: [
           'task' => Task::TASK_NAME,
           'temperature' => 0.5,
           'max_new_tokens' => 100,
           // Provider-specific options (e.g., 'provider' => Provider::GROQ)
       ]
   );
   

4. Handle results:
   • Use type-safe methods like asText(), asVectors(), or asObject().
   • Example for embeddings:

     $vectors = $result->asVectors();
     $firstVector = $vectors->first()->getValues();
     

Integration with Laravel Services

1. Bind the platform to the container in AppServiceProvider:

   public function register()
   {
       $this->app->singleton('huggingface.platform', function ($app) {
           return Factory::createPlatform(
               apiKey: env('HUGGINGFACE_API_KEY'),
               provider: Provider::HUGGINGFACE_INFERENCE,
               httpClient: $app->make(\Symfony\Contracts\HttpClient\HttpClientInterface::class)
           );
       });
   }
   

2. Inject and use in controllers:

   use Illuminate\Support\Facades\App;
   
   public function generateText(Request $request)
   {
       $platform = App::make('huggingface.platform');
       $result = $platform->invoke('model-id', $request->input, ['task' => Task::TEXT_GENERATION]);
       return response()->json(['response' => $result->asText()]);
   }
   

Provider-Specific Patterns

1. Override provider per request:

   $result = $platform->invoke('model-id', $input, [
       'task' => Task::CHAT_COMPLETION,
       'provider' => Provider::GROQ, // Force Groq for low-latency
   ]);
   

2. Fallback providers: Use a default provider but allow dynamic overrides for specific models:

   $platform = Factory::createPlatform(
       apiKey: env('HUGGINGFACE_API_KEY'),
       provider: Provider::HUGGINGFACE_INFERENCE,
       // Optional: Configure fallback logic in a custom factory
   );
   

Task-Specific Patterns

1. Chat Completion:
   • Use MessageBag for multi-turn conversations.
   • Cache responses for deterministic outputs (e.g., FAQ bots).

   $messages = new MessageBag([
       Message::ofSystem('You are a helpful assistant.'),
       Message::ofUser('What is Laravel?'),
   ]);
   

2. Embeddings:
   • Batch requests for efficiency:

   $platform->invoke('model-id', ['text1', 'text2'], ['task' => Task::FEATURE_EXTRACTION]);
   

   • Store vectors in a database (e.g., PostgreSQL with vector extension) for semantic search.
3. Image/Video Tasks:
   • Stream large files to avoid memory issues:

   $image = Image::fromUri('https://example.com/large-image.jpg');
   

Error Handling

1. Retry logic: Implement exponential backoff for rate-limited requests:

   try {
       $result = $platform->invoke(...);
   } catch (\Symfony\AI\Platform\Exception\RateLimitException $e) {
       sleep(2 ** $attempt); // Exponential backoff
       retry();
   }
   

2. Fallback models: Use a secondary model if the primary fails:

   $primaryModel = 'model-a';
   $fallbackModel = 'model-b';
   
   try {
       $result = $platform->invoke($primaryModel, $input, ['task' => Task::TASK_NAME]);
   } catch (\Exception $e) {
       $result = $platform->invoke($fallbackModel, $input, ['task' => Task::TASK_NAME]);
   }
   

Testing

1. Mock the platform in unit tests:

   $mockPlatform = Mockery::mock(\Symfony\AI\Platform\PlatformInterface::class);
   $mockPlatform->shouldReceive('invoke')
       ->once()
       ->andReturn(new \Symfony\AI\Platform\Response\TextResponse('Mocked response'));
   
   $this->app->instance('huggingface.platform', $mockPlatform);
   

2. Test edge cases:
   • Empty inputs.
   • Invalid model IDs.
   • Provider-specific errors (e.g., Groq’s rate limits).

Gotchas and Tips

Pitfalls

1. Cold Start Latency:

   • Some providers (e.g., HuggingFace Inference) have cold-start delays (~5–10 seconds).
   • Mitigation:
     • Use "warm" models (filter with --warm in CLI).
     • Cache responses aggressively for static queries.
     • Prefer providers like Groq or Together for low-latency needs.

2. API Key Management:

   • Hardcoding keys in code violates security best practices.
   • Mitigation:
     • Use Laravel’s .env or a secrets manager (e.g., AWS Secrets Manager).
     • Restrict keys to specific IPs if possible.

3. Rate Limits:

   • Free tiers have strict limits (e.g., 100 requests/minute for HuggingFace Inference).
   • Mitigation:
     • Implement retry logic with exponential backoff.
     • Monitor usage with the CLI:

       ai:huggingface:model-info model-id --show-usage
       

4. Input/Output Size Limits:

   • Some models have token/image limits (e.g., 2048 tokens for text-generation).
   • Mitigation:
     • Truncate long inputs or use streaming for large outputs.
     • Check model docs via CLI:

       ai:huggingface:model-info model-id --show-limits
       

5. Provider-Specific Quirks:

   • Groq: Optimized for LLMs; may not support all tasks.
   • Cohere: Strong in embeddings but limited to text.
   • HuggingFace Inference: Supports everything but has cold starts.
   • Mitigation: Test providers for your use case before committing.

6. Type Safety:

   • Results are type-safe but require correct method calls (e.g., asText() vs. asVectors()).
   • Mitigation:
     • Use instanceof checks:

       if ($result instanceof \Symfony\AI\Platform\Response\TextResponse) {
           echo $result->getText();
       }
       

     • Log unexpected response types during development.

Debugging Tips

1. Enable HTTP Logging:

   $platform = Factory::createPlatform(
       apiKey: env('HUGGINGFACE_API_KEY'),
       httpClient: \Symfony\Contracts\HttpClient\HttpClient::create([
           'debug' => true,
       ]),
   );