Створюємо AI Chat Agent за допомогою Laravel 12, MongoDB Atlas Vector Search та Voyage AI.

Минулого тижня я зіткнувся із проблемою.

Я вивчав датасет sample_airbnb у своєму кластері MongoDB Atlas — понад 5 500 оголошень у десятках міст. Мені хотілося реалізувати пошук, який не нагадував би 2015 рік: без нескінченних спадних списків, прапорців та складних SQL-запитів на кшталт WHERE property_type = 'Apartment' AND bedrooms >= 2.

Я хотів просто написати: «Знайди мені затишне місце в Порту з гарним краєвидом» — і отримати результати, які справді відповідають моєму запиту.

Тож я створив такий інструмент на Laravel всього за кілька годин.

Це історія появи Airbnb Arena — чат-агента на базі RAG, який використовує Voyage AI embeddings, MongoDB Atlas Vector Search та Google Gemini.

Найкраще те, що мені не довелося вручну прописувати логіку API чи складні цикли виклику інструментів. Я використав новий Laravel AI SDK (laravel/ai).

Він перетворює сотні рядків коду для «промпт-інжинірингу» та HTTP-клієнтів на чисті об’єктно-орієнтовані класи PHP.

Давайте розберемося, як це працює.

# Що ми будуємо

Airbnb Arena Interface Ось повний шлях запиту:

Користувач → Chat UI → ChatController → AirbnbAgent (Laravel AI Agent)
                                      ↓
                              ListingSearchTool → Voyage AI (через SDK)
                                                      ↓
                                              MongoDB Atlas $vectorSearch
                                                      ↓
                                              Відповідні оголошення → Gemini → Відповідь

Користувач ставить запитання. AirbnbAgent (на базі Gemini) аналізує його. Якщо потрібен пошук, він звертається до ListingSearchTool. Цей інструмент використовує Embeddings API для перетворення запиту у вектор за допомогою Voyage AI, виконує $vectorSearch у MongoDB і повертає результати. Gemini формує фінальну відповідь природною мовою.

Ключові компоненти:

Laravel AI SDK: сполучна ланка між кодом, Gemini та Voyage AI.
Voyage AI: генерує векторні embeddings для оголошень та пошукових запитів.
MongoDB Atlas: зберігає дані та виконує $vectorSearch.
Google Gemini: інтелектуальне ядро, що вирішує, які інструменти використовувати.

# Чому саме цей стек?

MongoDB Atlas виконує подвійну роль: сховища документів (гнучкі дані JSON) та векторної бази даних. Вам не потрібно синхронізувати дані між різними системами — усе в одному кластері та одній колекції.

Voyage AI пропонує embeddings, оптимізовані для пошуку. Він розрізняє документи (те, що ви зберігаєте) та запити (те, що запитує користувач), що значно підвищує релевантність порівняно з універсальними моделями.

Може здатися, що підійде будь-яка сучасна модель, але Voyage-4 на MongoDB Atlas дає кілька практичних переваг для production-рішень.

1. Асиметричний пошук

Усе сімейство Voyage-4 — від large до nano — використовує єдиний векторний простір. Усі моделі сумісні між собою, тому ви можете комбінувати їх для документів і запитів без перерахунку всього корпусу даних.

Це дозволяє:

Один раз створити embeddings для Airbnb listings за допомогою voyage-4-large для максимальної якості.
Використовувати voyage-4-lite (або навіть nano) для обробки запитів, щоб зменшити затримку та вартість кожного запиту.
Згодом підвищити точність, просто перейшовши на потужнішу модель — без змін у збережених векторах.

2. Гнучка розмірність та квантування

Моделі Voyage-4 підтримують різну розмірність embeddings (від 256 до 2048) завдяки Matryoshka learning. Їх можна квантувати (наприклад, до 8-біт) майже без втрати якості.

Для Atlas це означає:

Менший розмір індексу.
Економія пам'яті та місця на диску.
Можливість балансувати між точністю та вартістю/швидкістю для кожного завдання.

3. Єдина екосистема Atlas

Завдяки Embedding and Reranking API, моделі Voyage AI інтегровані безпосередньо в екосистему Atlas як нативний serverless API.

Ви отримуєте:

Єдиний рахунок: використання Voyage відображається у вашому білінгу Atlas.
Централізований моніторинг: керування лімітами (TPM/RPM) та доступом в одному місці.
Щедрий Free Tier: доступ до нових моделей з мільйонами безкоштовних токенів під час preview.

Laravel AI SDK стає справжнім game changer. Замість того, щоб вручну описувати JSON-схеми інструментів, ви просто створюєте PHP-клас із методом description(). SDK бере на себе серіалізацію, виклик методів та передачу результатів моделі.

# Налаштування фундаменту

Створіть новий проект:

composer create-project laravel/laravel airbnb-arena
cd airbnb-arena

Встановіть драйвер MongoDB та Laravel AI SDK:

pecl install mongodb
composer require mongodb/laravel-mongodb:5.x-dev laravel/ai

Опублікуйте конфігурацію:

php artisan ai:install

Також вам знадобиться кластер MongoDB Atlas із завантаженим Sample Dataset.

Налаштуйте файл .env та оновіть config/ai.php, щоб встановити значення за замовчуванням:

// config/ai.php
'default' => 'gemini',
'default_for_embeddings' => 'voyageai',

# Модель та сервіс Embeddings

Створимо модель для оголошень Airbnb:

namespace App\Models;
 
use MongoDB\Laravel\Eloquent\Model;
 
class Listing extends Model
{
    protected $connection = 'mongodb';
    protected $table = 'listingsAndReviews';
 
    protected $fillable = [
        'name', 'summary', 'description', 'property_type',
        'room_type', 'accommodates', 'bedrooms', 'beds',
        'price', 'amenities', 'address', 'review_scores',
        'embedding', // Вектор зберігається тут
    ];
 
    public function toEmbeddingText(): string
    {
        $market = $this->address['market'] ?? $this->address['country'] ?? '';
 
        return implode('. ', array_filter([
            $this->name,
            $this->summary,
            $this->property_type ? "Property type: {$this->property_type}" : null,
            $market ? "Location: {$market}" : null,
        ]));
    }
}

Тепер створимо сервіс для генерації embeddings через Laravel AI SDK:

namespace App\Services;
 
use Laravel\Ai\Embeddings;
 
class EmbeddingService
{
    private int $dimensions = 1024;
 
    public function embedQuery(string $query): array
    {
        $response = Embeddings::for([$query])
            ->dimensions($this->dimensions)
            ->generate(provider: 'voyageai');
 
        return $response->embeddings[0];
    }
}

# Створення інструменту пошуку

З Laravel AI замість величезних JSON-схем ви просто створюєте клас, що реалізує інтерфейс Tool.

namespace App\Tools;
 
use App\Models\Listing;
use App\Services\EmbeddingService;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
 
class ListingSearchTool implements Tool
{
    private array $lastResults = [];
 
    public function __construct(private EmbeddingService $embeddingService) {}
 
    public function description(): string
    {
        return 'Пошук оголошень Airbnb за допомогою семантичного векторного пошуку.';
    }
 
    public function handle(Request $request): string
    {
        $query = $request->string('query');
        $queryEmbedding = $this->embeddingService->embedQuery($query);
 
        $results = Listing::vectorSearch(
            index: 'vector_index',
            path: 'embedding',
            queryVector: $queryEmbedding,
            numCandidates: 50,
            limit: 5,
        );
        
        // Обробка результатів...
        return "Знайдено оголошення...";
    }
}

# Агент

Агент — це «персона» з набором інструкцій та інструментів. SDK автоматично керує циклом «міркування» моделі:

#[MaxSteps(10)]
class AirbnbAgent implements Agent, HasTools
{
    use Promptable;
 
    public function instructions(): string
    {
        return "Ви — Airbnb Arena Host, професійний консьєрж. Допомагайте користувачам знаходити житло, використовуючи інструмент пошуку. Не вигадуйте об'єкти самостійно.";
    }
 
    public function tools(): iterable
    {
        return [
            app(ListingSearchTool::class),
            new ListingDetailsTool(),
        ];
    }
}

# Контролер

Виклик агента в контролері максимально лаконічний:

public function chat(Request $request)
{
    $userMessage = $request->input('message');
    $agent = AirbnbAgent::make();
    $response = $agent->prompt($userMessage, provider: 'gemini');
 
    return response()->json([
        'reply' => (string) $response,
        'success' => true,
    ]);
}

# Підсумок

Ми створили повноцінного RAG-агента з векторним пошуком та автономним використанням інструментів. Laravel AI SDK значно спрощує цей процес, дозволяючи зосередитися на бізнес-логіці, а не на нюансах роботи з LLM.

Використання MongoDB Atlas для даних та векторів разом із Voyage AI для якісних embeddings забезпечує надійну базу для інтелектуальних систем пошуку.

Повний код проекту доступний на GitHub.