Driver Amazon Bedrock per Laravel AI SDK

Panoramica

revolution/laravel-amazon-bedrock è un driver per usare Amazon Bedrock con Laravel AI SDK. Ti permette di gestire più modelli di Bedrock tramite l’API unificata di Laravel AI SDK.

Funzionalità	Utilizzabile solo con Bedrock API key	Modelli / servizi supportati
Generazione di testo / streaming	✅	Anthropic Claude, Amazon Nova e la maggior parte degli altri modelli Bedrock (tutti tramite Converse API)
Uso di strumenti (Function Calling)	✅
Output strutturato	✅
Allegati di file	✅	Immagini, documenti, audio e video allegati tramite Converse API (i formati supportati variano da modello a modello)
Generazione di immagini	✅	Stability AI (predefinito), Amazon Nova Canvas (deprecato)
Audio (TTS)	⚠️	Amazon Polly (motori generative / neural / long-form / standard)
Trascrizione (STT)	❌	Non supportata
Embedding	✅	Amazon Titan Embeddings V2 (predefinito), Cohere Embed English/Multilingual V3, Cohere Embed V4 (batch)
Reranking	⚠️	Cohere Rerank 3.5, Amazon Rerank 1.0
File	✅	Nella generazione di testo è supportato l’allegato di file locali. Upload sul server e `fromId()` non supportati

Il simbolo ⚠️ in tabella non significa “funzionalità non supportata” ma “non utilizzabile con la sola Bedrock API key”.

Laravel AI SDK v0.6.3 ha aggiunto il supporto ufficiale per Text, Image ed Embeddings usando le Bedrock API key. Questo pacchetto continua a essere pubblicato perché supporta anche funzionalità non disponibili nell’integrazione ufficiale, come l’audio (TTS) con Amazon Polly e il reranking.

Le caratteristiche principali sono le seguenti.

Autenticazione: puoi scegliere tra Bedrock API key, credenziali AWS IAM (SigV4) e la catena di credenziali AWS predefinita (ruoli IAM, instance profile, ecc.).
Failover: supporta il failover multi-provider dell’AI SDK. Rate limiting (429), sovraccarico (503, 529) ed errori legati al credito vengono mappati su eccezioni gestibili con failover.
Controllo della cache: la cache ephemeral è sempre attiva sui system prompt della Bedrock Converse API.
API unificata: tutti i modelli, come Anthropic Claude, Amazon Nova, Meta Llama e Mistral, sono gestibili tramite Bedrock Converse API con un’interfaccia uniforme.

Requisiti

PHP >= 8.3
Laravel >= 12.x

Installazione

Installa il pacchetto

composer require revolution/laravel-amazon-bedrock

Pubblica la configurazione dell'AI SDK

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

Configurazione

Aggiungi il provider amazon-bedrock in config/ai.php. Se necessario, imposta Bedrock anche come provider predefinito.

'default' => 'amazon-bedrock',
'default_for_images' => 'amazon-bedrock',
'default_for_audio' => 'amazon-bedrock',
'default_for_embeddings' => 'amazon-bedrock',
'default_for_reranking' => 'amazon-bedrock',

Opzione 1: Bedrock API key

'providers' => [
    'amazon-bedrock' => [
        'driver' => 'amazon-bedrock',
        'key'    => env('AWS_BEDROCK_API_KEY', ''),
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    ],
],

AWS_BEDROCK_API_KEY=your_api_key
AWS_DEFAULT_REGION=us-east-1

La Bedrock API key si ottiene dalla console di gestione AWS.

La Bedrock API key è utilizzabile solo con la Bedrock Runtime API. Non è utilizzabile per il reranking o per Amazon Polly (TTS), che usano bedrock-agent-runtime. Per queste funzionalità usa SigV4 o la catena di credenziali AWS predefinita.

Opzione 2: credenziali AWS IAM (SigV4)

Usa la chiave di accesso e la chiave segreta AWS con firma Signature Version 4.

'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'),
    ],
],

AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=wJalr...
AWS_SESSION_TOKEN= # opzionale (per credenziali temporanee STS)
AWS_DEFAULT_REGION=us-east-1

Imposta AWS_SESSION_TOKEN solo se stai usando credenziali temporanee (STS).

Opzione 3: catena di credenziali AWS predefinita (ruoli IAM)

In ambienti con ruoli IAM (EC2 / ECS / Lambda), puoi omettere key e secret e usare la catena di provider di credenziali AWS predefinita.

'providers' => [
    'amazon-bedrock' => [
        'driver' => 'amazon-bedrock',
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    ],
],

AWS_DEFAULT_REGION=us-east-1

La catena di credenziali predefinita risolve automaticamente da variabili d’ambiente, file di credenziali condivise (~/.aws/credentials), ruoli di attività ECS, instance profile EC2 e altro.

Chiavi di configurazione opzionali

Chiave	Descrizione	Valore predefinito
`secret`	AWS secret access key (SigV4)	—
`token`	AWS session token (SigV4)	—
`timeout`	Timeout richiesta HTTP (secondi)	30
`max_tokens`	max tokens predefinito per richiesta	8096
`models.text.default`	Modello di testo predefinito	`global.anthropic.claude-sonnet-4-6`
`models.text.cheapest`	Modello di testo più economico	`global.anthropic.claude-haiku-4-5-20251001-v1:0`
`models.text.smartest`	Modello di testo più performante	`global.anthropic.claude-opus-4-7`
`models.embeddings.default`	Modello di embedding predefinito	`amazon.titan-embed-text-v2:0`
`models.embeddings.dimensions`	Numero di dimensioni di embedding predefinito	`1024`
`models.image.default`	Modello di immagine predefinito	`stability.stable-image-core-v1:1`
`models.audio.default`	Motore audio (TTS) predefinito	`generative`
`models.reranking.default`	Modello di reranking predefinito	`cohere.rerank-v3-5:0`

Generazione di testo

Classe Agent

Crea una classe Agent con un comando Artisan.

php artisan make:agent BedrockAgent

<?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 'Sei un esperto di sviluppo software.';
    }
}

use App\Ai\Agents\BedrockAgent;

$response = (new BedrockAgent)->prompt('Parlami di Laravel.');

echo $response->text;

Agent anonimo

Se vuoi usare l’SDK rapidamente senza creare una classe, usa l’helper agent().

use function Laravel\Ai\agent;

$response = agent(
    instructions: 'Sei un esperto di sviluppo software.',
)->prompt('Parlami di Laravel.');

echo $response->text;

Streaming

use App\Ai\Agents\BedrockAgent;
use Illuminate\Support\Facades\Route;

Route::get('/stream', function () {
    return (new BedrockAgent)->stream('Parlami di Laravel.');
});

Puoi anche gestire manualmente gli eventi.

use Laravel\Ai\Streaming\Events\TextDelta;

use function Laravel\Ai\agent;

$stream = agent(
    instructions: 'Sei un esperto di sviluppo software.',
)->stream('Parlami di Laravel.');

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

Uso di strumenti (Function Calling)

Definisci gli strumenti da invocare durante la generazione.

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;

class GetWeather implements Tool
{
    public function description(): string
    {
        return 'Restituisce il meteo attuale di una città.';
    }

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

    public function handle(Request $request): string
    {
        // Qui invochi l'API del meteo
        return json_encode(['temperature' => 22, 'condition' => 'sunny']);
    }
}

Utilizzalo dall’Agent.

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 'Sei un assistente meteo.';
    }
}

$response = (new WeatherAgent)->prompt('Che tempo fa a Tokyo?');
echo $response->text;

Funziona anche con un Agent anonimo.

use function Laravel\Ai\agent;

$response = agent(
    instructions: 'Sei un assistente meteo.',
    tools: [new GetWeather],
    maxSteps: 5,
)->prompt('Che tempo fa a Tokyo?');

Le chiamate di strumento funzionano anche in streaming. L’SDK esegue automaticamente lo strumento e continua la conversazione finché non produce una risposta testuale finale.

Allegati di file

Con il parametro attachments puoi allegare a un prompt immagini, documenti, audio e video. La Bedrock Converse API gestisce i blocchi allegati, ma quali formati siano effettivamente utilizzabili dipende dal modello (ad esempio, Anthropic Claude supporta solo immagini e documenti).

use Laravel\Ai\Files\Document;
use Laravel\Ai\Files\Image;

use function Laravel\Ai\agent;

// Allega un'immagine da percorso locale
$response = agent(
    instructions: 'Sei un assistente utile.',
)->prompt('Descrivi questa immagine.', attachments: [
    Image::fromPath('/path/to/photo.jpg'),
]);

// Allega un documento tramite URL
$response = agent(
    instructions: 'Sei un assistente utile.',
)->prompt('Riassumi questo documento.', attachments: [
    Document::fromUrl('https://example.com/report.pdf'),
]);

// Allega da stringa (specificando esplicitamente il formato)
$response = agent(
    instructions: 'Sei un assistente utile.',
)->prompt('Analizza questo testo.', attachments: [
    Document::fromString($csvContent, 'text/csv')->as('data.csv'),
]);

I tipi di allegato supportati sono Image, Document e Audio in Laravel\Ai\Files\*. I video si possono allegare tramite Illuminate\Http\UploadedFile.

L’upload di file lato server (Document::fromPath()->put()) e il riutilizzo tramite ID (Document::fromId()) non sono supportati da Bedrock.

Cronologia conversazioni

Per mantenere conversazioni multi-turno, implementa l’interfaccia Conversational nella classe Agent. Restituendo i messaggi passati da messages(), verranno inclusi automaticamente in ogni prompt.

<?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 'Sei un assistente 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();
    }
}

$response = (new ChatAgent(auth()->id()))->prompt('Di cosa stavamo parlando l\'ultima volta?');

Salvataggio automatico con `RemembersConversations`

Se non vuoi implementare messages() da solo, puoi usare il trait RemembersConversations per un salvataggio conversazioni completamente automatico. Sono necessarie le tabelle del database dell’AI SDK, quindi esegui prima php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider" && php artisan migrate.

<?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 'Sei un assistente utile.';
    }
}

Avvia una nuova conversazione.

$response = (new ChatAgent)->forUser($user)->prompt('Ciao!');

$conversationId = $response->conversationId;

Continua una conversazione esistente.

$response = (new ChatAgent)
    ->continue($conversationId, as: $user)
    ->prompt('Dimmi di più.');

Il driver Bedrock include automaticamente la cronologia della conversazione nelle richieste Bedrock Converse API, così puoi sfruttare il contesto multi-turno con tutti i modelli supportati.

Output strutturato

Implementando l’interfaccia HasStructuredOutput puoi ottenere risposte tipizzate.

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 'Estrai le informazioni sulla persona dal testo fornito.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'name' => $schema->string()->description('Nome completo della persona'),
            'age' => $schema->integer()->description('Età'),
            'occupation' => $schema->string()->description('Professione'),
        ];
    }
}

$response = (new ExtractPerson)->prompt('John è un ingegnere del software di 30 anni.');

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

L’output strutturato è disponibile anche con Agent anonimi.

use function Laravel\Ai\agent;

$response = agent(
    instructions: 'Estrai le informazioni sulla persona dal testo fornito.',
    schema: fn (JsonSchema $schema) => [
        'name' => $schema->string()->description('Nome completo della persona'),
        'age' => $schema->integer()->description('Età'),
    ],
)->prompt('Alice is 25 years old.');

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

Internamente viene creato uno strumento sintetico (output_structured_data) che forza a restituire valori conformi allo schema. Questo approccio è compatibile con tutti i modelli su Bedrock tramite Converse API.

Converse API (tutti i modelli)

Tutta la generazione di testo e lo streaming vengono eseguiti tramite la Bedrock Converse API. È tutto unificato, incluso Anthropic Claude, e puoi usare con la stessa interfaccia i vari modelli disponibili su Bedrock come Amazon Nova, Meta Llama, Mistral, Cohere e DeepSeek.

use function Laravel\Ai\agent;

// Anthropic Claude (tramite Converse API)
$response = agent(
    instructions: 'Sei un esperto di sviluppo software.',
    model: 'global.anthropic.claude-sonnet-4-6',
)->prompt('Parlami di Laravel.');

// Amazon Nova
$response = agent(
    instructions: 'Sei un assistente utile.',
    model: 'amazon.nova-pro-v1:0',
)->prompt('Parlami di AWS.');

// Meta Llama
$response = agent(
    instructions: 'Sei un assistente utile.',
    model: 'meta.llama3-1-70b-instruct-v1:0',
)->prompt('Spiegami il quantum computing.');

// Mistral
$response = agent(
    instructions: 'Sei un assistente utile.',
    model: 'mistral.mistral-large-2402-v1:0',
)->prompt('Scrivi un haiku sulla programmazione.');

// Cohere Command R+
$response = agent(
    instructions: 'Sei un assistente utile.',
    model: 'cohere.command-r-plus-v1:0',
)->prompt('Riassumi questo testo.');

// DeepSeek R1
$response = agent(
    instructions: 'Sei un assistente utile.',
    model: 'deepseek.r1-v1:0',
)->prompt('Risolvi questo problema di matematica.');

Streaming, uso di strumenti, output strutturato e allegati di file funzionano con i modelli che li supportano. Per maggiori dettagli consulta l’elenco dei modelli supportati da Bedrock.

Provider Options

Per passare opzioni specifiche di Bedrock come anthropic_version, implementa HasProviderOptions.

<?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 'Sei un esperto di sviluppo software.';
    }

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

Provider Options supportate:

Opzione	Descrizione	Valore predefinito
`top_k`	Parametro di sampling Top-K	—
`top_p`	Parametro di sampling Top-P (nucleus)	—
`additionalModelRequestFields`	Parametri aggiuntivi specifici del modello (Converse)	—

Attributi di configurazione dell’Agent

Puoi impostare le opzioni di generazione del testo tramite attributi PHP.

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;

    // ...
}

Generazione di immagini

Genera immagini con i modelli Stability AI (predefiniti) o con Amazon Nova Canvas.

use Laravel\Ai\Image;
use Revolution\Amazon\Bedrock\Bedrock;

// Per impostazione predefinita usa Stability AI Stable Image Core
$response = Image::of('Un simpatico robot steampunk')->generate(provider: Bedrock::KEY);

// Ottieni la prima immagine
$image = $response->firstImage();

// Salva su disco
$response->store('images', 's3');

// Emetti come tag HTML <img>
echo $response->toHtml('robot steampunk');

Modelli Stability AI disponibili (tutti richiedono la regione us-west-2):

// Stable Image Core — veloce, costo ridotto (predefinito)
$response = Image::of('paesaggio')
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-core-v1:1');

// Stable Diffusion 3.5 Large — alta qualità, generazione massiva
$response = Image::of('ritratto')
    ->generate(provider: Bedrock::KEY, model: 'stability.sd3-5-large-v1:0');

// Stable Image Ultra — ultra-realistico, massima qualità
$response = Image::of('prodotto premium')
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-ultra-v1:1');

I modelli di immagine Stability AI sono disponibili solo in us-west-2. Quando usi questi modelli, imposta AWS_DEFAULT_REGION=us-west-2.

Editing di immagini con Stability AI

Anche i modelli di editing di Stability AI Image Services sono utilizzabili tramite il metodo attachments(). Passi un’immagine di input e la trasformi con un modello di editing.

use Laravel\Ai\Files\Image as ImageFile;
use Laravel\Ai\Image;
use Revolution\Amazon\Bedrock\Bedrock;

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

// Inpaint — sostituzione di aree tramite maschera o canale alpha
$response = Image::of('sostituisci lo sfondo con una foresta')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-inpaint-v1:0');

// Erase — rimuovi elementi indesiderati
$response = Image::of('')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-erase-object-v1:0');

// Rimuovi lo sfondo e ritaglia solo il soggetto
$response = Image::of('')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-remove-background-v1:0');

// Search and Replace — sostituisci l'oggetto indicato nel prompt
$response = Image::of('gatto')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-search-replace-v1:0');

// Style Transfer — applica lo stile indicato nel prompt
$response = Image::of('stile pittura a olio')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-style-transfer-v1:0');

Modelli di editing Stability AI disponibili (tutti in us-east-1, us-east-2, us-west-2):

Model ID	Descrizione
`stability.stable-image-inpaint-v1:0`	Inpaint — sostituzione dell’area selezionata
`stability.stable-outpaint-v1:0`	Outpaint — espande l’immagine oltre i bordi
`stability.stable-image-erase-object-v1:0`	Erase — elimina oggetti
`stability.stable-image-remove-background-v1:0`	Rimozione dello sfondo
`stability.stable-image-search-replace-v1:0`	Search and Replace — sostituzione di oggetti
`stability.stable-image-search-recolor-v1:0`	Search and Recolor — ricolorazione di oggetti
`stability.stable-image-style-guide-v1:0`	Style Guide — applica uno stile da un’immagine di riferimento
`stability.stable-style-transfer-v1:0`	Style Transfer — trasferimento di stile artistico
`stability.stable-image-control-sketch-v1:0`	Control Sketch — generazione a partire da uno schizzo
`stability.stable-image-control-structure-v1:0`	Control Structure — generazione seguendo una struttura
`stability.stable-creative-upscale-v1:0`	Creative Upscale — upscaling con integrazione creativa
`stability.stable-conservative-upscale-v1:0`	Conservative Upscale — preserva i dettagli
`stability.stable-fast-upscale-v1:0`	Fast Upscale — upscaling 4x leggero

È supportato anche Amazon Nova Canvas, che però AWS sta progressivamente deprecando.

// Nova Canvas (deprecato. Disponibile in us-east-1, ap-northeast-1, eu-west-1)
$response = Image::of('tramonto')
    ->size('3:2')           // '1:1', '3:2', '2:3'
    ->quality('high')       // 'low', 'medium', 'high' (solo Nova Canvas)
    ->generate(provider: Bedrock::KEY, model: 'amazon.nova-canvas-v1:0');

Audio (TTS)

Genera audio da testo con Amazon Polly.

use Laravel\Ai\Audio;
use Revolution\Amazon\Bedrock\Bedrock;

$response = Audio::of('Adoro programmare con Laravel.')->generate(provider: Bedrock::KEY);

$rawContent = (string) $response;

Puoi specificare una voce maschile o femminile.

$response = Audio::of('Adoro programmare con Laravel.')
    ->female()
    ->generate(provider: 'bedrock');

$response = Audio::of('Adoro programmare con Laravel.')
    ->male()
    ->generate(provider: Bedrock::KEY);

Puoi specificare una voce Polly specifica.

$response = Audio::of('Adoro programmare con Laravel.')
    ->voice('Joanna')
    ->generate(provider: Bedrock::KEY);

Salva l’audio generato.

$response = Audio::of('Adoro programmare con Laravel.')->generate(provider: Bedrock::KEY);

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

Puoi anche specificare il motore (modello).

// generative (predefinito), neural, long-form, standard
$response = Audio::of('Adoro programmare con Laravel.')
    ->generate(provider: Bedrock::KEY, model: 'neural');

Voci predefinite: default-female → Ruth, default-male → Matthew (entrambe supportano il motore generative).

Amazon Polly è un servizio AWS distinto da Bedrock. La Bedrock API key (bearer token) non funziona con Polly. Usa le credenziali AWS IAM (SigV4) o la catena di credenziali AWS predefinita.

Embedding

Genera embedding vettoriali con Amazon Titan Embeddings V2.

use Laravel\Ai\Embeddings;
use Revolution\Amazon\Bedrock\Bedrock;

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

// Primo vettore di embedding
$vector = $response->first();

// Itera tutti gli embedding
foreach ($response as $embedding) {
    // $embedding è un array di float
}

echo $response->tokens; // Totale dei token

Puoi specificare il numero di dimensioni (Titan Embeddings V2 supporta 256, 512, 1024).

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

Esempio con modello personalizzato.

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

Modelli Cohere Embed

I modelli Cohere Embed vengono rilevati automaticamente e usano l’API batch. Mentre Titan invia una richiesta HTTP per ogni input, Cohere raggruppa tutti gli input in una sola richiesta, risultando più efficiente quando si elaborano più testi.

// 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 (dimensioni di output configurabili da 256 a 1536)
$response = Embeddings::for(['Hello world'])
    ->dimensions(512)
    ->generate(provider: Bedrock::KEY, model: 'cohere.embed-v4');

I modelli Cohere Embed non restituiscono il numero di token, quindi $response->tokens è sempre 0.

Reranking

Usa Cohere Rerank 3.5 o Amazon Rerank 1.0 per riordinare i documenti in base alla rilevanza rispetto a una query.

use Laravel\Ai\Reranking;
use Revolution\Amazon\Bedrock\Bedrock;

$response = Reranking::of([
    'Laravel è un framework web per PHP.',
    'Python è un linguaggio di programmazione.',
    'Laravel offre una sintassi elegante per lo sviluppo web.',
])->rerank(query: 'Cos\'è Laravel?', provider: Bedrock::KEY);

// Documento più rilevante
echo $response->first()->document;
echo $response->first()->score;

// Ottieni tutto in ordine
foreach ($response as $result) {
    echo "{$result->index}: {$result->document} ({$result->score})\n";
}

// Limita il numero di risultati
$response = Reranking::of([...])
    ->limit(2)
    ->rerank(query: 'Cos\'è Laravel?', provider: Bedrock::KEY);

Esempio con modello personalizzato.

$response = Reranking::of([...])
    ->rerank(query: 'query di ricerca', provider: Bedrock::KEY, model: 'amazon.rerank-v1:0');

L’API di reranking utilizza l’endpoint bedrock-agent-runtime (non bedrock-runtime). Amazon Rerank 1.0 non è disponibile in us-east-1, quindi in quella regione usa Cohere Rerank 3.5.

Testing

Puoi usare direttamente le funzionalità di test standard di AI SDK. Non è documentato ufficialmente, ma gli Agent anonimi creati con l’helper agent() possono essere mockati con AnonymousAgent::fake() e la variante con output strutturato con StructuredAnonymousAgent::fake().

use Laravel\Ai\AnonymousAgent;
use Laravel\Ai\Prompts\AgentPrompt;

use function Laravel\Ai\agent;

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

    $response = agent(
        instructions: 'Sei un esperto di sviluppo software.',
    )->prompt('Parlami di Laravel.');

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

Per le informazioni più aggiornate consulta la repository su GitHub.

​Panoramica

​Requisiti

​Installazione

​Configurazione

​Opzione 1: Bedrock API key

​Opzione 2: credenziali AWS IAM (SigV4)

​Opzione 3: catena di credenziali AWS predefinita (ruoli IAM)

​Chiavi di configurazione opzionali

​Generazione di testo

​Classe Agent

​Agent anonimo

​Streaming

​Uso di strumenti (Function Calling)

​Allegati di file

​Cronologia conversazioni

​Salvataggio automatico con RemembersConversations

​Output strutturato

​Converse API (tutti i modelli)

​Provider Options

​Attributi di configurazione dell’Agent

​Generazione di immagini

​Editing di immagini con Stability AI

​Audio (TTS)

​Embedding

​Modelli Cohere Embed

​Reranking

​Testing

Panoramica

Requisiti

Installazione

Configurazione

Opzione 1: Bedrock API key

Opzione 2: credenziali AWS IAM (SigV4)

Opzione 3: catena di credenziali AWS predefinita (ruoli IAM)

Chiavi di configurazione opzionali

Generazione di testo

Classe Agent

Agent anonimo

Streaming

Uso di strumenti (Function Calling)

Allegati di file

Cronologia conversazioni

Salvataggio automatico con `RemembersConversations`

Output strutturato

Converse API (tutti i modelli)

Provider Options

Attributi di configurazione dell’Agent

Generazione di immagini

Editing di immagini con Stability AI

Audio (TTS)

Embedding

Modelli Cohere Embed

Reranking

Testing