Ai Azure Platform Laravel Package

Getting Started

Minimal Steps

1. Install the Package:

   composer require symfony/ai-azure-platform symfony/http-client
   

2. Configure Azure Credentials in .env:

   AZURE_OPENAI_API_KEY=your_api_key_here
   AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
   AZURE_FOUNDRY_ENDPOINT=https://your-foundry-resource.azure.com
   

3. Register the Service in config/services.php:

   'azure_ai' => [
       'api_key' => env('AZURE_OPENAI_API_KEY'),
       'endpoint' => env('AZURE_OPENAI_ENDPOINT'),
       'foundry_endpoint' => env('AZURE_FOUNDRY_ENDPOINT'),
   ],
   

4. Bind the Client in AppServiceProvider:

   use Symfony\Component\AI\Azure\ModelClient;
   use Symfony\Contracts\HttpClient\HttpClientInterface;
   
   public function register()
   {
       $this->app->bind(ModelClient::class, function ($app) {
           return new ModelClient(
               $app->make(HttpClientInterface::class),
               $app['config']['services.azure_ai']
           );
       });
   }
   

5. First Use Case: Chat Completion

   use Symfony\Component\AI\Azure\ModelClient;
   
   public function generateResponse(ModelClient $client)
   {
       $response = $client->complete(
           "Explain Laravel dependency injection in simple terms",
           ['model' => 'gpt-35-turbo']
       );
       return response()->json($response);
   }
   

Where to Look First

• README.md: Focus on the Azure Documentation links for API specifics.
• Symfony AI Docs: Symfony AI Overview for core concepts like ClientInterface.
• Release Notes: v0.8.0’s Provider abstraction is critical for multi-model routing.

Implementation Patterns

Usage Patterns

1. Basic Chat Completions

// Using Responses API (v0.6.0+)
$response = $client->complete(
    "Summarize this text: {$userInput}",
    [
        'model' => 'gpt-4',
        'temperature' => 0.7,
        'max_tokens' => 100,
    ]
);

2. Structured Outputs (v0.7.0 Fix)

$response = $client->complete(
    "Extract entities from: 'Apple is looking at buying U.K. startup for $1 billion'",
    [
        'model' => 'gpt-35-turbo',
        'structuredOutput' => [
            'schema' => [
                'type' => 'object',
                'properties' => [
                    'companies' => ['type' => 'array', 'items' => ['type' => 'string']],
                    'amount' => ['type' => 'number'],
                ],
            ],
        ],
    ]
);
// Parse with Laravel Validator or spatie/laravel-array-to-object

3. Model Routing (v0.8.0 Provider Abstraction)

// config/ai.php
'providers' => [
    'azure_openai' => [
        'class' => \Symfony\Component\AI\Azure\Provider\AzureOpenAIProvider::class,
        'config' => config('services.azure_ai'),
        'models' => ['gpt-35-turbo', 'gpt-4'],
    ],
    'azure_foundry' => [
        'class' => \Symfony\Component\AI\Azure\Provider\AzureFoundryProvider::class,
        'config' => config('services.azure_foundry'),
        'models' => ['llama-2-70b'],
    ],
];

// In a service:
$provider = app(\Symfony\Component\AI\Azure\Provider\AzureOpenAIProvider::class);
$response = $provider->getModel('gpt-4')->complete($prompt);

4. Foundry Serverless Deployments

$foundryClient = new \Symfony\Component\AI\Azure\ModelClient(
    $httpClient,
    config('services.azure_foundry')
);
$response = $foundryClient->complete(
    "Run this Python code: print('hello')",
    ['model' => 'llama-2-70b', 'deployment' => 'my-llama-deployment']
);

Workflows

1. AI-Powered API Endpoint

use Illuminate\Http\Request;
use Symfony\Component\AI\Azure\ModelClient;

public function aiEndpoint(Request $request, ModelClient $client)
{
    $prompt = $request->input('prompt');
    $response = $client->complete($prompt, [
        'model' => config('ai.default_model'),
        'temperature' => $request->input('temperature', 0.7),
    ]);
    return response()->json($response);
}

2. Queued AI Processing

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Symfony\Component\AI\Azure\ModelClient;

class AiGenerationJob implements ShouldQueue
{
    use Queueable;

    public function handle(ModelClient $client)
    {
        $response = $client->complete($this->prompt);
        // Store in DB or broadcast
    }
}

3. Laravel Blade Integration

// Helper function
function aiGenerate($prompt)
{
    return app(ModelClient::class)->complete($prompt);
}

// In Blade
@php
    $aiResponse = aiGenerate("Write a blog intro about Laravel");
@endphp
<div>{{ $aiResponse['choices'][0]['message']['content'] }}</div>

Integration Tips

• Leverage Laravel’s HTTP Client: Wrap Symfony’s HttpClientInterface for consistency:

  $this->app->bind(HttpClientInterface::class, function () {
      return \Illuminate\Support\Facades\Http::client();
  });
  

• Cache Responses: Reduce Azure API calls for static prompts:

  $response = cache()->remember("ai_{$prompt}", now()->addHours(1), function () use ($client, $prompt) {
      return $client->complete($prompt);
  });
  

• Use Laravel Events: Dispatch AI events for logging/auditing:

  use Symfony\Component\AI\Event\AiEvent;
  
  $dispatcher->dispatch(new AiEvent($response));
  

• Validate Structured Outputs: Enforce schemas with Laravel’s Validator:

  $validator = Validator::make($response, [
      'data' => 'required|array',
      'data.*.text' => 'string|max:500',
  ]);
  

Gotchas and Tips

Pitfalls

1. String Payload Errors (v0.6.0 Fix)

   • Issue: Passing a string payload directly to ModelClient throws InvalidArgumentException.
   • Fix: Ensure payload is an array:

     // Wrong:
     $client->complete("Hello"); // Fails
     
     // Right:
     $client->complete("Hello", []); // Works
     

2. Deployment Name Required for Foundry (v0.7.0 Fix)

   • Issue: Foundry deployments require a deployment parameter.
   • Fix: Specify the deployment name:

     $client->complete($prompt, ['deployment' => 'my-llama-deployment']);
     

3. Structured Output Parsing

   • Issue: Azure’s structured outputs may return nested arrays/objects that Laravel’s json_decode doesn’t handle gracefully.
   • Fix: Use spatie/laravel-array-to-object or custom accessors:

     use Spatie\ArrayToObject\ArrayToObject;
     
     $structuredData = ArrayToObject::convert($response['data']);
     

4. Rate Limiting

   • Issue: Azure enforces usage quotas. Exceeding limits returns 429 errors.
   • Fix: Implement retry logic with spatie/laravel-retryable:

     use Spatie\Retryable\Retryable;
     
     Retryable::retryIf(function () use ($client, $prompt) {
         return $client->complete($prompt);
     }, 3, function ($e) {
         return $e->getCode() === 429;
     });
     

5. Cold Start Latency

   • Issue: Serverless Foundry deployments may have high initial latency.
   • Fix: Use Laravel’s cache()->rememberForever()