> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Pilote Amazon Bedrock pour Laravel AI SDK

> Pilote Amazon Bedrock pour Laravel AI SDK. Prend en charge la génération de texte, le streaming, l'utilisation d'outils, la sortie structurée, les pièces jointes, l'historique de conversation, les embeddings, la génération d'images, la synthèse vocale (TTS) et le reranking.

## Vue d'ensemble

[revolution/laravel-amazon-bedrock](https://github.com/invokable/laravel-amazon-bedrock) est un pilote permettant d'utiliser Amazon Bedrock avec [Laravel AI SDK](https://laravel.com/docs/ai-sdk). Il expose plusieurs modèles Bedrock via l'API unifiée de Laravel AI SDK.

| Fonctionnalité                          | Utilisable avec la seule clé API Bedrock | Modèles / services pris en charge                                                                                          |
| --------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Génération de texte / streaming         | ✅                                        | Anthropic Claude, Amazon Nova et la plupart des autres modèles Bedrock (tous via l'API Converse)                           |
| Utilisation d'outils (Function Calling) | ✅                                        |                                                                                                                            |
| Sortie structurée                       | ✅                                        |                                                                                                                            |
| Pièces jointes                          | ✅                                        | Images, documents, audio et vidéo joints via l'API Converse (les formats varient selon le modèle)                          |
| Génération d'images                     | ✅                                        | Stability AI (par défaut), Amazon Nova Canvas (déprécié)                                                                   |
| Synthèse vocale (TTS)                   | ⚠️                                       | Amazon Polly (moteurs generative / neural / long-form / standard)                                                          |
| Reconnaissance vocale (STT)             | ❌                                        | Non pris en charge                                                                                                         |
| Embeddings                              | ✅                                        | Amazon Titan Embeddings V2 (par défaut), Cohere Embed English/Multilingual V3, Cohere Embed V4 (batch)                     |
| Reranking                               | ⚠️                                       | Cohere Rerank 3.5, Amazon Rerank 1.0                                                                                       |
| Fichiers                                | ✅                                        | Pièces jointes de fichiers locaux pour la génération de texte. Téléversement côté serveur et `fromId()` non pris en charge |

<Info>
  Le symbole `⚠️` du tableau signifie non pas que la fonctionnalité est absente, mais qu'elle n'est pas utilisable avec la seule clé API Bedrock.
</Info>

<Info>
  La prise en charge officielle du Text, de l'Image et des Embeddings via une clé API Bedrock a été ajoutée dans Laravel AI SDK v0.6.3. Ce package couvre également des fonctionnalités absentes de l'intégration officielle, comme la synthèse vocale (TTS) via Amazon Polly ou le reranking, et continue donc d'être publié.
</Info>

Ses principales caractéristiques :

* **Authentification** : au choix, clé API Bedrock, identifiants AWS IAM (SigV4) ou chaîne d'identifiants AWS par défaut (rôle IAM, profil d'instance, etc.).
* **Basculement (failover)** : compatible avec le failover multi-provider de l'AI SDK. Les erreurs de limitation (429), de surcharge (503, 529) et les erreurs liées aux crédits sont mappées sur des exceptions permettant le basculement.
* **Contrôle du cache** : cache éphémère toujours activé sur le prompt système via l'[API Bedrock Converse](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html).
* **API unifiée** : tous les modèles (Anthropic Claude, Amazon Nova, Meta Llama, Mistral, etc.) sont exposés via une interface unique grâce à l'API Bedrock Converse.

## Prérequis

* PHP >= 8.3
* Laravel >= 12.x

## Installation

<Steps>
  <Step title="Installer le package">
    ```bash theme={null}
    composer require revolution/laravel-amazon-bedrock
    ```
  </Step>

  <Step title="Publier la configuration d'AI SDK">
    ```bash theme={null}
    php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
    ```
  </Step>
</Steps>

## Configuration

Ajoutez le provider `amazon-bedrock` dans `config/ai.php`. Basculez éventuellement les providers par défaut vers Bedrock.

```php theme={null}
'default' => 'amazon-bedrock',
'default_for_images' => 'amazon-bedrock',
'default_for_audio' => 'amazon-bedrock',
'default_for_embeddings' => 'amazon-bedrock',
'default_for_reranking' => 'amazon-bedrock',
```

### Option 1 : clé API Bedrock

```php theme={null}
'providers' => [
    'amazon-bedrock' => [
        'driver' => 'amazon-bedrock',
        'key'    => env('AWS_BEDROCK_API_KEY', ''),
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    ],
],
```

```dotenv theme={null}
AWS_BEDROCK_API_KEY=your_api_key
AWS_DEFAULT_REGION=us-east-1
```

Récupérez la clé API Bedrock depuis la console de gestion AWS.

<Warning>
  La clé API Bedrock est réservée à l'API Bedrock Runtime. Elle n'est pas utilisable pour le reranking (qui passe par `bedrock-agent-runtime`) ni pour Amazon Polly (TTS). Utilisez alors SigV4 ou la chaîne d'identifiants AWS par défaut.
</Warning>

### Option 2 : identifiants AWS IAM (SigV4)

Utilisez une access key et une secret key AWS signées avec [Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).

```php theme={null}
'providers' => [
    'amazon-bedrock' => [
        'driver' => 'amazon-bedrock',
        'key'    => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'token'  => env('AWS_SESSION_TOKEN'),
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    ],
],
```

```dotenv theme={null}
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=wJalr...
AWS_SESSION_TOKEN= # Facultatif (identifiants temporaires STS)
AWS_DEFAULT_REGION=us-east-1
```

<Info>
  Ne renseignez `AWS_SESSION_TOKEN` que si vous utilisez des identifiants temporaires (STS).
</Info>

### Option 3 : chaîne d'identifiants AWS par défaut (rôle IAM)

Dans les environnements disposant d'un rôle IAM (EC2 / ECS / Lambda, etc.), vous pouvez omettre `key` et `secret` et utiliser la [chaîne de fournisseurs d'identifiants AWS par défaut](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html).

```php theme={null}
'providers' => [
    'amazon-bedrock' => [
        'driver' => 'amazon-bedrock',
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    ],
],
```

```dotenv theme={null}
AWS_DEFAULT_REGION=us-east-1
```

La chaîne par défaut résout automatiquement les identifiants depuis les variables d'environnement, le fichier partagé (`~/.aws/credentials`), le rôle de tâche ECS, le profil d'instance EC2, etc.

### Clés de configuration facultatives

| Clé                            | Description                                 | Valeur par défaut                                 |
| ------------------------------ | ------------------------------------------- | ------------------------------------------------- |
| `secret`                       | AWS secret access key (SigV4)               | —                                                 |
| `token`                        | AWS session token (SigV4)                   | —                                                 |
| `timeout`                      | Délai d'expiration HTTP (secondes)          | 30                                                |
| `max_tokens`                   | Max tokens par requête (par défaut)         | 8096                                              |
| `models.text.default`          | Modèle texte par défaut                     | `global.anthropic.claude-sonnet-4-6`              |
| `models.text.cheapest`         | Modèle texte le moins cher                  | `global.anthropic.claude-haiku-4-5-20251001-v1:0` |
| `models.text.smartest`         | Modèle texte le plus performant             | `global.anthropic.claude-opus-4-7`                |
| `models.embeddings.default`    | Modèle d'embeddings par défaut              | `amazon.titan-embed-text-v2:0`                    |
| `models.embeddings.dimensions` | Nombre de dimensions d'embedding par défaut | `1024`                                            |
| `models.image.default`         | Modèle d'image par défaut                   | `stability.stable-image-core-v1:1`                |
| `models.audio.default`         | Moteur TTS par défaut                       | `generative`                                      |
| `models.reranking.default`     | Modèle de reranking par défaut              | `cohere.rerank-v3-5:0`                            |

## Génération de texte

### Classe Agent

Créez une classe Agent avec une commande Artisan.

```bash theme={null}
php artisan make:agent BedrockAgent
```

```php theme={null}
<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

class BedrockAgent implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'Vous êtes un expert en développement logiciel.';
    }
}
```

```php theme={null}
use App\Ai\Agents\BedrockAgent;

$response = (new BedrockAgent)->prompt('Parlez-moi de Laravel.');

echo $response->text;
```

### Agent anonyme

Pour une utilisation rapide sans créer de classe, utilisez le helper `agent()`.

```php theme={null}
use function Laravel\Ai\agent;

$response = agent(
    instructions: 'Vous êtes un expert en développement logiciel.',
)->prompt('Parlez-moi de Laravel.');

echo $response->text;
```

### Streaming

```php theme={null}
use App\Ai\Agents\BedrockAgent;
use Illuminate\Support\Facades\Route;

Route::get('/stream', function () {
    return (new BedrockAgent)->stream('Parlez-moi de Laravel.');
});
```

Vous pouvez également gérer les événements manuellement.

```php theme={null}
use Laravel\Ai\Streaming\Events\TextDelta;

use function Laravel\Ai\agent;

$stream = agent(
    instructions: 'Vous êtes un expert en développement logiciel.',
)->stream('Parlez-moi de Laravel.');

foreach ($stream as $event) {
    if ($event instanceof TextDelta) {
        echo $event->delta;
    }
}
```

### Utilisation d'outils (Function Calling)

Définissez un outil qui pourra être appelé pendant la génération.

```php theme={null}
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;

class GetWeather implements Tool
{
    public function description(): string
    {
        return 'Renvoie la météo actuelle d\'une ville.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'city' => $schema->string()->required()->description('Nom de la ville'),
        ];
    }

    public function handle(Request $request): string
    {
        // Appeler ici l'API météo
        return json_encode(['temperature' => 22, 'condition' => 'sunny']);
    }
}
```

Utilisez-le depuis un Agent.

```php theme={null}
use App\Ai\Tools\GetWeather;
use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

#[MaxSteps(5)]
class WeatherAgent implements Agent, HasTools
{
    use Promptable;

    public function tools(): array
    {
        return [new GetWeather];
    }

    public function instructions(): string
    {
        return 'Vous êtes un assistant météo.';
    }
}

$response = (new WeatherAgent)->prompt('Quel temps fait-il à Tokyo ?');
echo $response->text;
```

Vous pouvez également l'utiliser avec un agent anonyme.

```php theme={null}
use function Laravel\Ai\agent;

$response = agent(
    instructions: 'Vous êtes un assistant météo.',
    tools: [new GetWeather],
    maxSteps: 5,
)->prompt('Quel temps fait-il à Tokyo ?');
```

Les appels d'outils fonctionnent également en streaming. Le SDK exécute automatiquement les outils et poursuit la conversation jusqu'à obtenir la réponse texte finale.

### Pièces jointes

Le paramètre `attachments` permet de joindre à un prompt des fichiers image, document, audio ou vidéo. L'API Bedrock Converse traite les blocs de pièces jointes, mais les formats réellement acceptés dépendent du modèle (par exemple Anthropic Claude ne gère que les images et les documents).

```php theme={null}
use Laravel\Ai\Files\Document;
use Laravel\Ai\Files\Image;

use function Laravel\Ai\agent;

// Joindre une image depuis un chemin local
$response = agent(
    instructions: 'Vous êtes un assistant utile.',
)->prompt('Décrivez cette image.', attachments: [
    Image::fromPath('/path/to/photo.jpg'),
]);

// Joindre un document depuis une URL
$response = agent(
    instructions: 'Vous êtes un assistant utile.',
)->prompt('Résumez ce document.', attachments: [
    Document::fromUrl('https://example.com/report.pdf'),
]);

// Pièce jointe depuis une chaîne (format explicite)
$response = agent(
    instructions: 'Vous êtes un assistant utile.',
)->prompt('Analysez ce texte.', attachments: [
    Document::fromString($csvContent, 'text/csv')->as('data.csv'),
]);
```

Les types de pièces jointes pris en charge sont `Image`, `Document` et `Audio` dans `Laravel\Ai\Files\*`. Les vidéos peuvent être jointes via `Illuminate\Http\UploadedFile`.

<Info>
  Le téléversement de fichiers côté serveur (`Document::fromPath()->put()`) et la réutilisation via un identifiant (`Document::fromId()`) ne sont pas pris en charge par Bedrock.
</Info>

### Historique de conversation

Pour maintenir une conversation multi-tours, implémentez l'interface `Conversational` dans votre classe Agent. Les messages retournés par `messages()` seront automatiquement inclus dans chaque prompt.

```php theme={null}
<?php

namespace App\Ai\Agents;

use App\Models\ChatHistory;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Messages\Message;
use Laravel\Ai\Promptable;

class ChatAgent implements Agent, Conversational
{
    use Promptable;

    public function __construct(public int $userId) {}

    public function instructions(): string
    {
        return 'Vous êtes un assistant utile.';
    }

    public function messages(): iterable
    {
        return ChatHistory::where('user_id', $this->userId)
            ->latest()
            ->limit(20)
            ->get()
            ->reverse()
            ->map(fn ($m) => new Message($m->role, $m->content))
            ->all();
    }
}
```

```php theme={null}
$response = (new ChatAgent(auth()->id()))->prompt('De quoi parlions-nous la dernière fois ?');
```

#### Sauvegarde automatique avec `RemembersConversations`

Si vous ne souhaitez pas implémenter vous-même `messages()`, le trait `RemembersConversations` fournit une sauvegarde entièrement automatique des conversations. Une table de base de données de l'AI SDK est nécessaire ; exécutez d'abord `php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider" && php artisan migrate`.

```php theme={null}
<?php

namespace App\Ai\Agents;

use Laravel\Ai\Concerns\RemembersConversations;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Promptable;

class ChatAgent implements Agent, Conversational
{
    use Promptable, RemembersConversations;

    public function instructions(): string
    {
        return 'Vous êtes un assistant utile.';
    }
}
```

Démarrer une nouvelle conversation :

```php theme={null}
$response = (new ChatAgent)->forUser($user)->prompt('Bonjour !');

$conversationId = $response->conversationId;
```

Poursuivre une conversation existante :

```php theme={null}
$response = (new ChatAgent)
    ->continue($conversationId, as: $user)
    ->prompt('Donnez-moi plus de détails.');
```

Le pilote Bedrock inclut automatiquement l'historique de conversation dans les requêtes à l'API Bedrock Converse, ce qui permet d'exploiter le contexte multi-tours pour tous les modèles pris en charge.

### Sortie structurée

En implémentant l'interface `HasStructuredOutput`, vous pouvez obtenir une réponse typée.

```php theme={null}
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Promptable;

class ExtractPerson implements Agent, HasStructuredOutput
{
    use Promptable;

    public function instructions(): string
    {
        return 'Extrayez les informations relatives à la personne à partir du texte fourni.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'name' => $schema->string()->description('Nom complet de la personne'),
            'age' => $schema->integer()->description('Âge'),
            'occupation' => $schema->string()->description('Profession'),
        ];
    }
}

$response = (new ExtractPerson)->prompt('John est un ingénieur logiciel de 30 ans.');

echo $response['name'];       // "John"
echo $response['age'];        // 30
echo $response['occupation']; // "software engineer"
```

La sortie structurée fonctionne également avec un agent anonyme.

```php theme={null}
use function Laravel\Ai\agent;

$response = agent(
    instructions: 'Extrayez les informations relatives à la personne à partir du texte fourni.',
    schema: fn (JsonSchema $schema) => [
        'name' => $schema->string()->description('Nom complet de la personne'),
        'age' => $schema->integer()->description('Âge'),
    ],
)->prompt('Alice is 25 years old.');

echo $response['name']; // "Alice"
echo $response['age'];  // 25
```

En interne, un outil synthétique (`output_structured_data`) est créé pour forcer une valeur conforme au schéma. Cette approche est compatible avec tous les modèles disponibles sur Bedrock via l'API Converse.

### API Converse (tous les modèles)

Toute la génération de texte et le streaming passent par l'[API Bedrock Converse](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html). L'interface est unifiée, y compris pour Anthropic Claude, et vous pouvez utiliser Amazon Nova, Meta Llama, Mistral, Cohere, DeepSeek ou d'autres modèles Bedrock via la même interface.

```php theme={null}
use function Laravel\Ai\agent;

// Anthropic Claude (via API Converse)
$response = agent(
    instructions: 'Vous êtes un expert en développement logiciel.',
    model: 'global.anthropic.claude-sonnet-4-6',
)->prompt('Parlez-moi de Laravel.');

// Amazon Nova
$response = agent(
    instructions: 'Vous êtes un assistant utile.',
    model: 'amazon.nova-pro-v1:0',
)->prompt('Parlez-moi d\'AWS.');

// Meta Llama
$response = agent(
    instructions: 'Vous êtes un assistant utile.',
    model: 'meta.llama3-1-70b-instruct-v1:0',
)->prompt('Expliquez l\'informatique quantique.');

// Mistral
$response = agent(
    instructions: 'Vous êtes un assistant utile.',
    model: 'mistral.mistral-large-2402-v1:0',
)->prompt('Écrivez un haïku sur le code.');

// Cohere Command R+
$response = agent(
    instructions: 'Vous êtes un assistant utile.',
    model: 'cohere.command-r-plus-v1:0',
)->prompt('Résumez ce texte.');

// DeepSeek R1
$response = agent(
    instructions: 'Vous êtes un assistant utile.',
    model: 'deepseek.r1-v1:0',
)->prompt('Résolvez ce problème de mathématiques.');
```

Le streaming, l'utilisation d'outils, la sortie structurée et les pièces jointes fonctionnent sur les modèles qui les prennent en charge. Voir la [liste des modèles Bedrock pris en charge](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html) pour plus de détails.

### Provider Options

Pour transmettre des options spécifiques à Bedrock telles que `anthropic_version`, implémentez `HasProviderOptions`.

```php theme={null}
<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasProviderOptions;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

class BedrockAgent implements Agent, HasProviderOptions
{
    use Promptable;

    public function instructions(): string
    {
        return 'Vous êtes un expert en développement logiciel.';
    }

    public function providerOptions(Lab|string $provider): array
    {
        return [
            'top_p' => 0.9,
        ];
    }
}
```

Provider Options pris en charge :

| Option                         | Description                                                          | Valeur par défaut |
| ------------------------------ | -------------------------------------------------------------------- | ----------------- |
| `top_k`                        | Paramètre d'échantillonnage Top-K                                    | —                 |
| `top_p`                        | Paramètre d'échantillonnage Top-P (nucleus)                          | —                 |
| `additionalModelRequestFields` | Paramètres supplémentaires spécifiques au modèle pour l'API Converse | —                 |

### Attributs de configuration d'Agent

Les attributs PHP permettent de configurer les options de génération de texte.

```php theme={null}
use Laravel\Ai\Attributes\MaxTokens;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Attributes\Timeout;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

#[MaxTokens(4096)]
#[Temperature(0.7)]
#[Timeout(120)]
class BedrockAgent implements Agent
{
    use Promptable;

    // ...
}
```

## Génération d'images

Générez des images avec les modèles Stability AI (par défaut) ou Amazon Nova Canvas.

```php theme={null}
use Laravel\Ai\Image;
use Revolution\Amazon\Bedrock\Bedrock;

// Utilise Stability AI Stable Image Core par défaut
$response = Image::of('un adorable robot steampunk')->generate(provider: Bedrock::KEY);

// Récupérer la première image
$image = $response->firstImage();

// Enregistrer sur un disque
$response->store('images', 's3');

// Émettre une balise HTML <img>
echo $response->toHtml('robot steampunk');
```

Modèles Stability AI disponibles (tous nécessitent la région `us-west-2`) :

```php theme={null}
// Stable Image Core — rapide et peu coûteux (par défaut)
$response = Image::of('paysage')
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-core-v1:1');

// Stable Diffusion 3.5 Large — haute qualité, génération massive
$response = Image::of('portrait')
    ->generate(provider: Bedrock::KEY, model: 'stability.sd3-5-large-v1:0');

// Stable Image Ultra — ultra-réaliste, qualité maximale
$response = Image::of('produit haut de gamme')
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-ultra-v1:1');
```

<Info>
  Les modèles d'image Stability AI ne sont disponibles qu'en `us-west-2`. Définissez `AWS_DEFAULT_REGION=us-west-2` pour les utiliser.
</Info>

### Édition d'images avec Stability AI

Les modèles d'édition de Stability AI Image Services sont également accessibles via la méthode `attachments()`. Passez l'image d'entrée et transformez-la avec un modèle d'édition.

```php theme={null}
use Laravel\Ai\Files\Image as ImageFile;
use Laravel\Ai\Image;
use Revolution\Amazon\Bedrock\Bedrock;

$inputImage = ImageFile::fromPath('/path/to/photo.jpg');

// Inpaint — repeint une zone via masque ou canal alpha
$response = Image::of('remplacez l\'arrière-plan par une forêt')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-inpaint-v1:0');

// Erase — supprime des éléments indésirables
$response = Image::of('')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-erase-object-v1:0');

// Détoure le sujet en supprimant l'arrière-plan
$response = Image::of('')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-remove-background-v1:0');

// Search and Replace — remplace l'objet indiqué par le prompt
$response = Image::of('chat')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-search-replace-v1:0');

// Style Transfer — applique le style demandé
$response = Image::of('style peinture à l\'huile')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-style-transfer-v1:0');
```

Modèles d'édition Stability AI disponibles (tous accessibles en `us-east-1`, `us-east-2`, `us-west-2`) :

| Model ID                                        | Description                                                    |
| ----------------------------------------------- | -------------------------------------------------------------- |
| `stability.stable-image-inpaint-v1:0`           | Inpaint — repeint une zone sélectionnée                        |
| `stability.stable-outpaint-v1:0`                | Outpaint — étend l'image au-delà de ses bords                  |
| `stability.stable-image-erase-object-v1:0`      | Erase — supprime un objet                                      |
| `stability.stable-image-remove-background-v1:0` | Suppression de l'arrière-plan                                  |
| `stability.stable-image-search-replace-v1:0`    | Search and Replace — remplacement d'objets                     |
| `stability.stable-image-search-recolor-v1:0`    | Search and Recolor — recoloration d'objets                     |
| `stability.stable-image-style-guide-v1:0`       | Style Guide — applique un style depuis une image de référence  |
| `stability.stable-style-transfer-v1:0`          | Style Transfer — transfère un style graphique                  |
| `stability.stable-image-control-sketch-v1:0`    | Control Sketch — génération à partir d'un croquis              |
| `stability.stable-image-control-structure-v1:0` | Control Structure — génération selon une structure             |
| `stability.stable-creative-upscale-v1:0`        | Creative Upscale — mise à l'échelle avec complétion créative   |
| `stability.stable-conservative-upscale-v1:0`    | Conservative Upscale — mise à l'échelle préservant les détails |
| `stability.stable-fast-upscale-v1:0`            | Fast Upscale — mise à l'échelle 4x légère                      |

Amazon Nova Canvas est également pris en charge, bien que son abandon soit en cours chez AWS.

```php theme={null}
// Nova Canvas (déprécié. Disponible en us-east-1, ap-northeast-1, eu-west-1)
$response = Image::of('coucher de soleil')
    ->size('3:2')           // '1:1', '3:2', '2:3'
    ->quality('high')       // 'low', 'medium', 'high' (Nova Canvas uniquement)
    ->generate(provider: Bedrock::KEY, model: 'amazon.nova-canvas-v1:0');
```

## Synthèse vocale (TTS)

Générez de la parole à partir de texte avec [Amazon Polly](https://docs.aws.amazon.com/polly/latest/dg/what-is.html).

```php theme={null}
use Laravel\Ai\Audio;
use Revolution\Amazon\Bedrock\Bedrock;

$response = Audio::of('J\'adore coder avec Laravel.')->generate(provider: Bedrock::KEY);

$rawContent = (string) $response;
```

Vous pouvez choisir une voix masculine ou féminine.

```php theme={null}
$response = Audio::of('J\'adore coder avec Laravel.')
    ->female()
    ->generate(provider: 'bedrock');

$response = Audio::of('J\'adore coder avec Laravel.')
    ->male()
    ->generate(provider: Bedrock::KEY);
```

Vous pouvez également préciser une [voix Polly](https://docs.aws.amazon.com/polly/latest/dg/voicelist.html) spécifique.

```php theme={null}
$response = Audio::of('J\'adore coder avec Laravel.')
    ->voice('Joanna')
    ->generate(provider: Bedrock::KEY);
```

Enregistrer l'audio généré :

```php theme={null}
$response = Audio::of('J\'adore coder avec Laravel.')->generate(provider: Bedrock::KEY);

$path = $response->store();
$path = $response->storeAs('audio.mp3');
```

Vous pouvez aussi spécifier le moteur (modèle).

```php theme={null}
// generative (par défaut), neural, long-form, standard
$response = Audio::of('J\'adore coder avec Laravel.')
    ->generate(provider: Bedrock::KEY, model: 'neural');
```

**Voix par défaut :** `default-female` → Ruth, `default-male` → Matthew (toutes deux compatibles avec le moteur generative).

<Warning>
  Amazon Polly est un service AWS distinct de Bedrock. La clé API Bedrock (bearer token) ne fonctionne pas avec Polly. Utilisez des identifiants AWS IAM (SigV4) ou la chaîne d'identifiants AWS par défaut.
</Warning>

## Embeddings

Générez des vecteurs d'embedding avec Amazon Titan Embeddings V2.

```php theme={null}
use Laravel\Ai\Embeddings;
use Revolution\Amazon\Bedrock\Bedrock;

$response = Embeddings::for(['Hello world', 'Foo bar'])->generate(provider: Bedrock::KEY);

// Premier vecteur d'embedding
$vector = $response->first();

// Itérer sur tous les embeddings
foreach ($response as $embedding) {
    // $embedding est un tableau de float
}

echo $response->tokens; // Total de tokens
```

Vous pouvez spécifier le nombre de dimensions (Titan Embeddings V2 prend 256, 512 ou 1024).

```php theme={null}
$response = Embeddings::for(['Hello world'])->dimensions(512)->generate(provider: Bedrock::KEY);
```

Exemple avec un modèle personnalisé.

```php theme={null}
$response = Embeddings::for(['Hello world'])
    ->dimensions(1024)
    ->generate(provider: Bedrock::KEY, model: 'amazon.titan-embed-text-v2:0');
```

### Modèles Cohere Embed

Les modèles Cohere Embed sont détectés automatiquement et utilisent l'API batch. Alors que Titan envoie une requête HTTP par entrée, Cohere regroupe toutes les entrées en une seule requête, ce qui est efficace pour traiter plusieurs textes.

```php theme={null}
// Cohere Embed English V3
$response = Embeddings::for(['Hello world', 'Foo bar'])
    ->dimensions(1024)
    ->generate(provider: Bedrock::KEY, model: 'cohere.embed-english-v3');

// Cohere Embed Multilingual V3
$response = Embeddings::for(['Hello', 'こんにちは'])
    ->dimensions(1024)
    ->generate(provider: Bedrock::KEY, model: 'cohere.embed-multilingual-v3');

// Cohere Embed V4 (dimensions de sortie configurables de 256 à 1536)
$response = Embeddings::for(['Hello world'])
    ->dimensions(512)
    ->generate(provider: Bedrock::KEY, model: 'cohere.embed-v4');
```

<Info>
  Les modèles Cohere Embed ne renvoient pas de nombre de tokens ; `$response->tokens` vaut donc toujours `0`.
</Info>

## Reranking

Réordonnez des documents selon leur pertinence par rapport à une requête avec Cohere Rerank 3.5 ou Amazon Rerank 1.0.

```php theme={null}
use Laravel\Ai\Reranking;
use Revolution\Amazon\Bedrock\Bedrock;

$response = Reranking::of([
    'Laravel est un framework web PHP.',
    'Python est un langage de programmation.',
    'Laravel offre une syntaxe élégante pour le développement web.',
])->rerank(query: 'Qu\'est-ce que Laravel ?', provider: Bedrock::KEY);

// Document le plus pertinent
echo $response->first()->document;
echo $response->first()->score;

// Récupérer tous les résultats dans l'ordre de pertinence
foreach ($response as $result) {
    echo "{$result->index}: {$result->document} ({$result->score})\n";
}

// Limiter le nombre de résultats
$response = Reranking::of([...])
    ->limit(2)
    ->rerank(query: 'Qu\'est-ce que Laravel ?', provider: Bedrock::KEY);
```

Exemple avec un modèle personnalisé.

```php theme={null}
$response = Reranking::of([...])
    ->rerank(query: 'requête de recherche', provider: Bedrock::KEY, model: 'amazon.rerank-v1:0');
```

<Info>
  L'API de reranking utilise l'endpoint `bedrock-agent-runtime` (et non `bedrock-runtime`). Amazon Rerank 1.0 n'étant pas disponible en `us-east-1`, utilisez Cohere Rerank 3.5 dans cette région.
</Info>

## Tests

Les fonctionnalités de test standard de l'AI SDK sont utilisables telles quelles.

Bien que non documenté officiellement, les agents anonymes créés via le helper `agent()` peuvent être mockés avec `AnonymousAgent::fake()`, et leur variante à sortie structurée avec `StructuredAnonymousAgent::fake()`.

```php theme={null}
use Laravel\Ai\AnonymousAgent;
use Laravel\Ai\Prompts\AgentPrompt;

use function Laravel\Ai\agent;

it('can generate text', function () {
    AnonymousAgent::fake();

    $response = agent(
        instructions: 'Vous êtes un expert en développement logiciel.',
    )->prompt('Parlez-moi de Laravel.');

    AnonymousAgent::assertPrompted(function (AgentPrompt $prompt) {
        return $prompt->contains('Laravel');
    });
});
```

<Info>
  Pour les informations les plus récentes, reportez-vous au [dépôt GitHub](https://github.com/invokable/laravel-amazon-bedrock).
</Info>


## Related topics

- [Tutoriel bot - Laravel Bluesky](/fr/packages/laravel-bluesky/bot-tutorial.md)
- [Créer un fournisseur personnalisé pour l'AI SDK](/fr/advanced/ai-sdk-custom-provider.md)
- [Socialite (LINE Login) - LINE SDK for Laravel](/fr/packages/laravel-line-sdk/socialite.md)
- [Package core et pilotes personnalisés - Feedable](/fr/packages/feedable/core.md)
- [Laravel AI SDK](/fr/ai-sdk.md)