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

# Amazon-Bedrock-Treiber für das Laravel AI SDK

> Amazon-Bedrock-Treiber für das Laravel AI SDK. Unterstützt Textgenerierung, Streaming, Tool-Nutzung, strukturierte Ausgaben, Dateianhänge, Konversationsverlauf, Embeddings, Bildgenerierung, Audio (TTS) und Reranking.

## Überblick

[revolution/laravel-amazon-bedrock](https://github.com/invokable/laravel-amazon-bedrock) ist ein Treiber, mit dem Sie Amazon Bedrock im [Laravel AI SDK](https://laravel.com/docs/ai-sdk) verwenden können. Sie können die verschiedenen Bedrock-Modelle über die einheitliche API des Laravel AI SDK ansprechen.

| Funktion                        | Nur mit Bedrock-API-Key nutzbar | Unterstützte Modelle / Dienste                                                                                     |
| ------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Textgenerierung / Streaming     | ✅                               | Anthropic Claude, Amazon Nova und die meisten weiteren Bedrock-Modelle (alle über die Converse API)                |
| Tool-Nutzung (Function Calling) | ✅                               |                                                                                                                    |
| Strukturierte Ausgaben          | ✅                               |                                                                                                                    |
| Dateianhänge                    | ✅                               | Bilder, Dokumente, Audio und Video werden über die Converse API angehängt (unterstützte Formate je nach Modell)    |
| Bildgenerierung                 | ✅                               | Stability AI (Standard), Amazon Nova Canvas (deprecated)                                                           |
| Audio (TTS)                     | ⚠️                              | Amazon Polly (Engines generative / neural / long-form / standard)                                                  |
| Transkription (STT)             | ❌                               | Nicht unterstützt                                                                                                  |
| Embeddings                      | ✅                               | Amazon Titan Embeddings V2 (Standard), Cohere Embed English/Multilingual V3, Cohere Embed V4 (Batch-Unterstützung) |
| Reranking                       | ⚠️                              | Cohere Rerank 3.5, Amazon Rerank 1.0                                                                               |
| Files                           | ✅                               | Lokale Dateianhänge für Textgenerierung. Server-seitige Uploads oder `fromId()` werden nicht unterstützt.          |

<Info>
  Das `⚠️` in der Tabelle bedeutet nicht, dass die Funktion selbst nicht unterstützt wird, sondern dass sie nicht allein mit einem Bedrock-API-Key genutzt werden kann.
</Info>

<Info>
  In Laravel AI SDK v0.6.3 wurde die offizielle Unterstützung für Text, Bild und Embeddings über den Bedrock-API-Key ergänzt. Da dieses Paket auch Funktionen wie Audio (TTS) über Amazon Polly und Reranking abdeckt, die in der offiziellen Integration nicht verfügbar sind, wird es weiterhin veröffentlicht.
</Info>

Die wichtigsten Merkmale:

* **Authentifizierung**: Sie können zwischen Bedrock-API-Key, AWS IAM-Credentials (SigV4) und der Default AWS Credentials Chain (IAM-Rollen, Instance Profiles etc.) wählen.
* **Failover**: Unterstützt das Multi-Provider-Failover des AI SDK. Rate Limits (429), Overloads (503, 529) und Credit-bezogene Fehler werden auf failover-fähige Exceptions abgebildet.
* **Cache Control**: Für System-Prompts der [Bedrock Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html) ist der ephemere Cache stets aktiviert.
* **Einheitliche API**: Alle Modelle wie Anthropic Claude, Amazon Nova, Meta Llama, Mistral usw. werden über die Bedrock Converse API mit einer einheitlichen Schnittstelle angesprochen.

## Voraussetzungen

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

## Installation

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

  <Step title="Konfiguration des AI SDK veröffentlichen">
    ```bash theme={null}
    php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
    ```
  </Step>
</Steps>

## Konfiguration

Fügen Sie in `config/ai.php` den Provider `amazon-bedrock` hinzu. Bei Bedarf setzen Sie den Standard-Provider ebenfalls auf 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: Bedrock-API-Key

```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
```

Sie erhalten den Bedrock-API-Key über die AWS Management Console.

<Warning>
  Der Bedrock-API-Key ist ausschließlich für die Bedrock Runtime API bestimmt. Für Reranking über `bedrock-agent-runtime` sowie für Amazon Polly (TTS) kann er nicht verwendet werden. Nutzen Sie in diesen Fällen SigV4 oder die Default AWS Credentials Chain.
</Warning>

### Option 2: AWS IAM-Credentials (SigV4)

Verwendet AWS Access Key und Secret Key mit Signierung nach [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= # optional (für temporäre STS-Credentials)
AWS_DEFAULT_REGION=us-east-1
```

<Info>
  `AWS_SESSION_TOKEN` wird nur gesetzt, wenn temporäre Credentials (STS) verwendet werden.
</Info>

### Option 3: Default AWS Credentials Chain (IAM-Rolle)

In Umgebungen mit IAM-Rollen wie EC2 / ECS / Lambda können Sie `key` und `secret` weglassen und die [Default AWS Credentials Provider Chain](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) nutzen.

```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
```

Die Default Credentials Chain löst Credentials automatisch aus Umgebungsvariablen, dem Shared-Credentials-File (`~/.aws/credentials`), ECS-Task-Rollen, EC2-Instance-Profiles usw. auf.

### Optionale Konfigurationsschlüssel

| Schlüssel                      | Beschreibung                    | Standardwert                                      |
| ------------------------------ | ------------------------------- | ------------------------------------------------- |
| `secret`                       | AWS Secret Access Key (SigV4)   | —                                                 |
| `token`                        | AWS Session Token (SigV4)       | —                                                 |
| `timeout`                      | HTTP-Request-Timeout (Sekunden) | 30                                                |
| `max_tokens`                   | Standard-max-Tokens pro Request | 8096                                              |
| `models.text.default`          | Standard-Textmodell             | `global.anthropic.claude-sonnet-4-6`              |
| `models.text.cheapest`         | Günstigstes Textmodell          | `global.anthropic.claude-haiku-4-5-20251001-v1:0` |
| `models.text.smartest`         | Leistungsstärkstes Textmodell   | `global.anthropic.claude-opus-4-7`                |
| `models.embeddings.default`    | Standard-Embedding-Modell       | `amazon.titan-embed-text-v2:0`                    |
| `models.embeddings.dimensions` | Standard-Embedding-Dimension    | `1024`                                            |
| `models.image.default`         | Standard-Bildmodell             | `stability.stable-image-core-v1:1`                |
| `models.audio.default`         | Standard-Audio- (TTS-)Engine    | `generative`                                      |
| `models.reranking.default`     | Standard-Reranking-Modell       | `cohere.rerank-v3-5:0`                            |

## Textgenerierung

### Agent-Klasse

Erzeugen Sie mit einem Artisan-Kommando eine Agent-Klasse.

```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 'Sie sind ein Experte für Softwareentwicklung.';
    }
}
```

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

$response = (new BedrockAgent)->prompt('Erklären Sie mir bitte Laravel.');

echo $response->text;
```

### Anonymer Agent

Wenn Sie schnell ohne eigene Klasse arbeiten möchten, nutzen Sie den Helper `agent()`.

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

$response = agent(
    instructions: 'Sie sind ein Experte für Softwareentwicklung.',
)->prompt('Erklären Sie mir bitte 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('Erklären Sie mir bitte Laravel.');
});
```

Sie können die Events auch manuell verarbeiten.

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

use function Laravel\Ai\agent;

$stream = agent(
    instructions: 'Sie sind ein Experte für Softwareentwicklung.',
)->stream('Erklären Sie mir bitte Laravel.');

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

### Tool-Nutzung (Function Calling)

Definieren Sie ein Tool, das während der Generierung aufgerufen wird.

```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 'Gibt das aktuelle Wetter einer Stadt zurück.';
    }

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

    public function handle(Request $request): string
    {
        // Hier die Wetter-API aufrufen
        return json_encode(['temperature' => 22, 'condition' => 'sunny']);
    }
}
```

Verwendung in einem 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 'Sie sind ein Wetter-Assistent.';
    }
}

$response = (new WeatherAgent)->prompt('Wie ist das Wetter in Tokio?');
echo $response->text;
```

Auch mit einem anonymen Agent möglich.

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

$response = agent(
    instructions: 'Sie sind ein Wetter-Assistent.',
    tools: [new GetWeather],
    maxSteps: 5,
)->prompt('Wie ist das Wetter in Tokio?');
```

Tool-Aufrufe funktionieren auch im Streaming. Das SDK führt Tools automatisch aus und setzt die Konversation fort, bis eine finale Textantwort vorliegt.

### Dateianhänge

Über den Parameter `attachments` können Sie Bilder, Dokumente, Audio- und Videodateien an einen Prompt anhängen. Die Bedrock Converse API verarbeitet die Anhang-Blöcke, welche Formate tatsächlich verwendbar sind, hängt aber vom Modell ab (z. B. unterstützt Anthropic Claude nur Bilder und Dokumente).

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

use function Laravel\Ai\agent;

// Bild von lokalem Pfad anhängen
$response = agent(
    instructions: 'Sie sind ein hilfreicher Assistent.',
)->prompt('Bitte beschreiben Sie dieses Bild.', attachments: [
    Image::fromPath('/path/to/photo.jpg'),
]);

// Dokument von einer URL anhängen
$response = agent(
    instructions: 'Sie sind ein hilfreicher Assistent.',
)->prompt('Bitte fassen Sie dieses Dokument zusammen.', attachments: [
    Document::fromUrl('https://example.com/report.pdf'),
]);

// Aus String anhängen (Format explizit angeben)
$response = agent(
    instructions: 'Sie sind ein hilfreicher Assistent.',
)->prompt('Bitte analysieren Sie diesen Text.', attachments: [
    Document::fromString($csvContent, 'text/csv')->as('data.csv'),
]);
```

Unterstützte Anhangstypen sind `Image`, `Document` und `Audio` aus `Laravel\Ai\Files\*`. Videos können über `Illuminate\Http\UploadedFile` angehängt werden.

<Info>
  Server-seitige Datei-Uploads (`Document::fromPath()->put()`) und die Wiederverwendung über ID (`Document::fromId()`) werden von Bedrock nicht unterstützt.
</Info>

### Konversationsverlauf

Um Mehrfach-Turn-Konversationen zu erhalten, implementieren Sie in der Agent-Klasse das Interface `Conversational`. Wenn `messages()` frühere Nachrichten zurückgibt, werden diese jedem Prompt automatisch hinzugefügt.

```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 'Sie sind ein hilfreicher Assistent.';
    }

    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('Worüber haben wir letztes Mal gesprochen?');
```

#### Automatisches Speichern mit `RemembersConversations`

Wenn Sie `messages()` nicht selbst implementieren möchten, können Sie das vollständig automatische Speichern von Konversationen über den Trait `RemembersConversations` nutzen. Da die Datenbanktabellen des AI SDK benötigt werden, führen Sie zuvor `php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider" && php artisan migrate` aus.

```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 'Sie sind ein hilfreicher Assistent.';
    }
}
```

Eine neue Konversation starten.

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

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

Eine bestehende Konversation fortsetzen.

```php theme={null}
$response = (new ChatAgent)
    ->continue($conversationId, as: $user)
    ->prompt('Bitte erklären Sie das genauer.');
```

Der Bedrock-Treiber fügt Konversationsverlauf automatisch in Bedrock-Converse-API-Anfragen ein, sodass Mehrfach-Turn-Kontext für alle unterstützten Modelle nutzbar ist.

### Strukturierte Ausgaben

Wenn Sie das Interface `HasStructuredOutput` implementieren, können Sie typisierte Antworten erhalten.

```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 'Bitte extrahieren Sie Personendaten aus dem gegebenen Text.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'name' => $schema->string()->description('Vollständiger Name der Person'),
            'age' => $schema->integer()->description('Alter'),
            'occupation' => $schema->string()->description('Beruf'),
        ];
    }
}

$response = (new ExtractPerson)->prompt('John ist 30 Jahre alt und Softwareentwickler.');

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

Strukturierte Ausgaben funktionieren auch mit anonymen Agents.

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

$response = agent(
    instructions: 'Bitte extrahieren Sie Personendaten aus dem gegebenen Text.',
    schema: fn (JsonSchema $schema) => [
        'name' => $schema->string()->description('Vollständiger Name der Person'),
        'age' => $schema->integer()->description('Alter'),
    ],
)->prompt('Alice is 25 years old.');

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

Intern wird ein synthetisches Tool (`output_structured_data`) erzeugt, das Werte gemäß dem Schema zurückgeben lässt. Dieser Ansatz ist über die Converse API mit allen Bedrock-Modellen kompatibel.

### Converse API (alle Modelle)

Sämtliche Textgenerierung und Streaming erfolgt über die [Bedrock Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html). Auch Anthropic Claude ist einheitlich integriert. Sie können Modelle wie Amazon Nova, Meta Llama, Mistral, Cohere, DeepSeek usw. auf Bedrock über dieselbe Schnittstelle ansprechen.

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

// Anthropic Claude (über Converse API)
$response = agent(
    instructions: 'Sie sind ein Experte für Softwareentwicklung.',
    model: 'global.anthropic.claude-sonnet-4-6',
)->prompt('Erklären Sie mir bitte Laravel.');

// Amazon Nova
$response = agent(
    instructions: 'Sie sind ein hilfreicher Assistent.',
    model: 'amazon.nova-pro-v1:0',
)->prompt('Erklären Sie mir bitte AWS.');

// Meta Llama
$response = agent(
    instructions: 'Sie sind ein hilfreicher Assistent.',
    model: 'meta.llama3-1-70b-instruct-v1:0',
)->prompt('Bitte erklären Sie Quantencomputing.');

// Mistral
$response = agent(
    instructions: 'Sie sind ein hilfreicher Assistent.',
    model: 'mistral.mistral-large-2402-v1:0',
)->prompt('Bitte schreiben Sie ein Haiku über das Programmieren.');

// Cohere Command R+
$response = agent(
    instructions: 'Sie sind ein hilfreicher Assistent.',
    model: 'cohere.command-r-plus-v1:0',
)->prompt('Bitte fassen Sie diesen Text zusammen.');

// DeepSeek R1
$response = agent(
    instructions: 'Sie sind ein hilfreicher Assistent.',
    model: 'deepseek.r1-v1:0',
)->prompt('Bitte lösen Sie diese Mathematik-Aufgabe.');
```

Streaming, Tool-Nutzung, strukturierte Ausgaben und Dateianhänge funktionieren mit den Modellen, die sie jeweils unterstützen. Details finden Sie in der [Liste der von Bedrock unterstützten Modelle](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html).

### Provider Options

Um Bedrock-spezifische Optionen wie `anthropic_version` zu übergeben, implementieren Sie `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 'Sie sind ein Experte für Softwareentwicklung.';
    }

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

Unterstützte Provider Options:

| Option                         | Beschreibung                                       | Standardwert |
| ------------------------------ | -------------------------------------------------- | ------------ |
| `top_k`                        | Top-K-Sampling-Parameter                           | —            |
| `top_p`                        | Top-P- (Nucleus-)Sampling-Parameter                | —            |
| `additionalModelRequestFields` | Modellspezifische Zusatzparameter der Converse API | —            |

### Konfigurations-Attribute für Agents

Über PHP-Attribute können Sie Optionen für die Textgenerierung setzen.

```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;

    // ...
}
```

## Bildgenerierung

Erzeugen Sie Bilder mit Stability-AI-Modellen (Standard) oder Amazon Nova Canvas.

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

// Standardmäßig wird Stability AI Stable Image Core verwendet
$response = Image::of('ein niedlicher Steampunk-Roboter')->generate(provider: Bedrock::KEY);

// Erstes Bild abrufen
$image = $response->firstImage();

// Auf Disk speichern
$response->store('images', 's3');

// Als HTML-`<img>`-Tag ausgeben
echo $response->toHtml('Steampunk-Roboter');
```

Verfügbare Stability-AI-Modelle (alle erfordern die Region `us-west-2`):

```php theme={null}
// Stable Image Core – schnell und kostengünstig (Standard)
$response = Image::of('Landschaft')
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-core-v1:1');

// Stable Diffusion 3.5 Large – hohe Qualität, große Volumina
$response = Image::of('Porträt')
    ->generate(provider: Bedrock::KEY, model: 'stability.sd3-5-large-v1:0');

// Stable Image Ultra – ultrarealistisch, höchste Qualität
$response = Image::of('hochwertiges Produkt')
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-ultra-v1:1');
```

<Info>
  Die Bildmodelle von Stability AI sind nur in `us-west-2` verfügbar. Setzen Sie `AWS_DEFAULT_REGION=us-west-2`, wenn Sie diese Modelle verwenden.
</Info>

### Bildbearbeitung mit Stability AI

Auch die Editing-Modelle der Stability AI Image Services lassen sich über die Methode `attachments()` verwenden. Übergeben Sie ein Eingangsbild, das dann vom Editing-Modell umgewandelt wird.

```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 – Bereich per Maske oder Alphakanal ersetzen
$response = Image::of('Bitte den Hintergrund durch einen Wald ersetzen')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-inpaint-v1:0');

// Erase – unerwünschte Elemente entfernen
$response = Image::of('')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-erase-object-v1:0');

// Hintergrund entfernen und nur das Motiv freistellen
$response = Image::of('')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-remove-background-v1:0');

// Search and Replace – im Prompt angegebenes Objekt ersetzen
$response = Image::of('Katze')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-search-replace-v1:0');

// Style Transfer – Stil aus dem Prompt anwenden
$response = Image::of('Ölgemälde-Stil')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-style-transfer-v1:0');
```

Verfügbare Editing-Modelle von Stability AI (alle in `us-east-1`, `us-east-2` und `us-west-2` verfügbar):

| Model ID                                        | Beschreibung                                   |
| ----------------------------------------------- | ---------------------------------------------- |
| `stability.stable-image-inpaint-v1:0`           | Inpaint – ausgewählten Bereich neu ausfüllen   |
| `stability.stable-outpaint-v1:0`                | Outpaint – Bild über den Rand hinaus erweitern |
| `stability.stable-image-erase-object-v1:0`      | Erase – Objekte entfernen                      |
| `stability.stable-image-remove-background-v1:0` | Hintergrund entfernen                          |
| `stability.stable-image-search-replace-v1:0`    | Search and Replace – Objekte ersetzen          |
| `stability.stable-image-search-recolor-v1:0`    | Search and Recolor – Farbe von Objekten ändern |
| `stability.stable-image-style-guide-v1:0`       | Style Guide – Stil anhand eines Referenzbildes |
| `stability.stable-style-transfer-v1:0`          | Style Transfer – Stil übertragen               |
| `stability.stable-image-control-sketch-v1:0`    | Control Sketch – aus einer Skizze generieren   |
| `stability.stable-image-control-structure-v1:0` | Control Structure – gemäß Struktur generieren  |
| `stability.stable-creative-upscale-v1:0`        | Creative Upscale – ergänzende Hochskalierung   |
| `stability.stable-conservative-upscale-v1:0`    | Conservative Upscale – Details bewahren        |
| `stability.stable-fast-upscale-v1:0`            | Fast Upscale – leichte 4-fache Hochskalierung  |

Amazon Nova Canvas wird ebenfalls unterstützt, wird von AWS aber schrittweise als „deprecated" gekennzeichnet.

```php theme={null}
// Nova Canvas (deprecated. Verfügbar in us-east-1, ap-northeast-1, eu-west-1)
$response = Image::of('Sonnenuntergang')
    ->size('3:2')           // '1:1', '3:2', '2:3'
    ->quality('high')       // 'low', 'medium', 'high' (nur Nova Canvas)
    ->generate(provider: Bedrock::KEY, model: 'amazon.nova-canvas-v1:0');
```

## Audio (TTS)

Erzeugen Sie mit [Amazon Polly](https://docs.aws.amazon.com/polly/latest/dg/what-is.html) Sprache aus Text.

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

$response = Audio::of('Ich liebe es, mit Laravel zu programmieren.')->generate(provider: Bedrock::KEY);

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

Sie können männliche oder weibliche Stimmen wählen.

```php theme={null}
$response = Audio::of('Ich liebe es, mit Laravel zu programmieren.')
    ->female()
    ->generate(provider: 'bedrock');

$response = Audio::of('Ich liebe es, mit Laravel zu programmieren.')
    ->male()
    ->generate(provider: Bedrock::KEY);
```

Sie können eine bestimmte [Polly-Stimme](https://docs.aws.amazon.com/polly/latest/dg/voicelist.html) angeben.

```php theme={null}
$response = Audio::of('Ich liebe es, mit Laravel zu programmieren.')
    ->voice('Joanna')
    ->generate(provider: Bedrock::KEY);
```

Das generierte Audio speichern.

```php theme={null}
$response = Audio::of('Ich liebe es, mit Laravel zu programmieren.')->generate(provider: Bedrock::KEY);

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

Sie können auch die Engine (das Modell) angeben.

```php theme={null}
// generative (Standard), neural, long-form, standard
$response = Audio::of('Ich liebe es, mit Laravel zu programmieren.')
    ->generate(provider: Bedrock::KEY, model: 'neural');
```

**Standardstimmen:** `default-female` → Ruth, `default-male` → Matthew (beide unterstützen die generative Engine).

<Warning>
  Amazon Polly ist ein von Bedrock separater AWS-Dienst. Der Bedrock-API-Key (Bearer-Token) kann nicht mit Polly verwendet werden. Nutzen Sie stattdessen AWS-IAM-Credentials (SigV4) oder die Default AWS Credentials Chain.
</Warning>

## Embeddings

Erzeugen Sie Vektor-Embeddings mit 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);

// Erster Embedding-Vektor
$vector = $response->first();

// Alle Embeddings iterieren
foreach ($response as $embedding) {
    // $embedding ist ein Array aus Floats
}

echo $response->tokens; // Gesamtanzahl Tokens
```

Sie können die Dimension angeben (Titan Embeddings V2: 256, 512, 1024).

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

Beispiel für ein benutzerdefiniertes Modell:

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

### Cohere-Embed-Modelle

Cohere-Embed-Modelle werden automatisch erkannt und verwenden die Batch-API. Während Titan pro Eingabe eine HTTP-Anfrage sendet, fasst Cohere alle Eingaben zu einer einzigen Anfrage zusammen und ist damit bei mehreren Texten effizienter.

```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 (Ausgabedimensionen von 256 bis 1536 einstellbar)
$response = Embeddings::for(['Hello world'])
    ->dimensions(512)
    ->generate(provider: Bedrock::KEY, model: 'cohere.embed-v4');
```

<Info>
  Cohere-Embed-Modelle liefern keine Token-Anzahl zurück, `$response->tokens` ist daher stets `0`.
</Info>

## Reranking

Mit Cohere Rerank 3.5 oder Amazon Rerank 1.0 können Sie Dokumente nach Relevanz zu einer Query sortieren.

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

$response = Reranking::of([
    'Laravel ist ein PHP-Web-Framework.',
    'Python ist eine Programmiersprache.',
    'Laravel bietet elegante Syntax für die Web-Entwicklung.',
])->rerank(query: 'Was ist Laravel?', provider: Bedrock::KEY);

// Das relevanteste Dokument
echo $response->first()->document;
echo $response->first()->score;

// Alle in sortierter Reihenfolge abrufen
foreach ($response as $result) {
    echo "{$result->index}: {$result->document} ({$result->score})\n";
}

// Anzahl begrenzen
$response = Reranking::of([...])
    ->limit(2)
    ->rerank(query: 'Was ist Laravel?', provider: Bedrock::KEY);
```

Beispiel für ein benutzerdefiniertes Modell:

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

<Info>
  Die Reranking-API verwendet den Endpunkt `bedrock-agent-runtime` (nicht `bedrock-runtime`). Da Amazon Rerank 1.0 in `us-east-1` nicht verfügbar ist, nutzen Sie in dieser Region Cohere Rerank 3.5.
</Info>

## Tests

Die üblichen Testfunktionen des AI SDK können unverändert verwendet werden.

Zwar nicht in der offiziellen Dokumentation aufgeführt, aber anonyme Agents, die mit dem Helper `agent()` erzeugt wurden, können Sie mit `AnonymousAgent::fake()` mocken, die strukturierte Variante mit `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: 'Sie sind ein Experte für Softwareentwicklung.',
    )->prompt('Erklären Sie mir bitte Laravel.');

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

<Info>
  Aktuelle Informationen finden Sie im [GitHub-Repository](https://github.com/invokable/laravel-amazon-bedrock).
</Info>


## Related topics

- [Bot-Tutorial - Laravel Bluesky](/de/packages/laravel-bluesky/bot-tutorial.md)
- [Einen eigenen Provider für das AI SDK erstellen](/de/advanced/ai-sdk-custom-provider.md)
- [Laravel AI SDK](/de/ai-sdk.md)
- [Cache](/de/cache.md)
- [Core-Paket und eigene Treiber - Feedable](/de/packages/feedable/core.md)