---
title: "RAG у Laravel для кількох орендарів: ізоляція даних у pgvector"
url: https://laravelukraine.com/blog/rag-u-laravel-dlia-kilkox-orendariv-izoliaciia-danix-u-pgvector
date: 2026-11-19
source: https://origin-main.com/vector-search/laravel-multi-tenant-rag-pgvector/
---

# RAG у Laravel для кількох орендарів: ізоляція даних у pgvector

Це переказ статті Девальда Г'юго (Dewald Hugo) з блогу Origin Main. Ми зберегли структуру, код і всі технічні поради автора, але скоротили пояснення.

RAG у застосунку з кількома орендарями (multi-tenant) ламається тихо. Запит на пошук, у якому забули фільтр орендаря, повертає правдоподібні фрагменти іншого клієнта, модель переказує їх у відповіді, і жоден рядок логу не покаже чужого запису. Надійний захист має два шари: глобальний скоп (Scope) Eloquent, який тримає правильний код правильним, і політика row level security (RLS) у PostgreSQL, яка робить неправильний код нешкідливим. Нижче обидва шари на pgvector, а потім пастки, які лишаються навіть із правильною політикою: фільтровані скани індексу, пули з'єднань, воркери черг і кеш.

Стаття виходить з того, що ембединги вже зберігаються в PostgreSQL. Як це налаштувати, ми розбирали в пості [«Простий векторний пошук подібності для Laravel»](https://laravelukraine.com/blog/prostii-vektornii-posuk-za-sxozistiu-dlia-laravel). Імпорти у фрагментах коду пропущено.

### Вибір моделі ізоляції

Це рішення варто ухвалити першим, бо воно визначає дизайн індексу, процес міграцій і те, які збої ви успадкуєте. Поширені чотири моделі, і вони обмінюють силу ізоляції на операційну вагу.

| Модель | Гарантія ізоляції | Поведінка векторного індексу | Операційна вартість | Коли доречна |
|---|---|---|---|---|
| Спільна таблиця, лише скоп у застосунку | Залежить від того, чи кожен запит не забув фільтр | Один індекс, фільтр після скану | Найнижча | Внутрішні інструменти, прототипи |
| Спільна таблиця, скоп плюс RLS | База відхиляє читання без орендаря і запис у чужого орендаря | Один індекс, фільтр після скану | Низька, плюс дисципліна з ролями й пулами | Більшість B2B SaaS |
| Партиція на орендаря (або групу) | Як у RLS, плюс фізичне розділення | Свій індекс на партицію, без фільтрації між орендарями | Середня, керування партиціями в міграціях | Кілька орендарів тримають більшість рядків |
| База даних на орендаря | Найсильніша, окремі облікові дані | Повністю незалежні індекси | Висока, N міграцій і N пулів | Розділення за договором чи регуляторними вимогами |

Для більшості B2B-продуктів автор радить починати зі спільної таблиці, скопу в застосунку та примусової RLS - і чесно називає це архітектурною думкою, а не бенчмарком. База на орендаря множить міграції, пули з'єднань і побудову індексів на кількість клієнтів, і ця вартість наздожене невелику команду значно раніше, ніж витік. Сигнал переходити до партицій - recall, а не безпека: якщо кілька орендарів володіють більшістю рядків, спільний HNSW-індекс змушує запит кожного малого орендаря продиратися крізь чужі вектори.

Якщо поруч із векторами ви тримаєте ще й повнотекстовий пошук (наприклад, Scout і Meilisearch), це другий шлях пошуку, і його фільтр орендаря - окремий контроль, який треба перевіряти так само.

### Де губиться орендар на шляху пошуку

RAG-запит проходить п'ять кроків, і на кожному можна загубити орендаря:

1. **Вхідний запит** - орендар береться з автентифікації, ніколи з даних користувача.
2. **Контекст орендаря** - scoped-прив'язка, безпечна для Octane.
3. **Ембединг запитання** - поза транзакцією.
4. **Векторний запит** - скоп плюс примусова політика RLS. Це єдиний крок, який гарантує сама база.
5. **Складання промпту** - перевірка, що всі ідентифікатори орендаря збігаються.

Межу в базі вважайте основним контролем, а решту - раннім попередженням. Скоп у застосунку обходить сирий запит, виклик `withoutGlobalScopes()`, доданий заради звіту, або завдання, яке забуло задати контекст. Політика RLS переживає всі три випадки. Перевірка перед складанням промпту - дешева страховка: якщо шар бази колись налаштують неправильно, ви дізнаєтесь про це раніше за модель.

### Будуємо межу

Реалізація складається з чотирьох частин: контекст орендаря в межах запиту, таблиця під захистом RLS, скоп Eloquent для звичайного шляху і сервіс пошуку, що закривається при помилці. Кожне рішення підібране так, щоб забута дрібниця давала помилку чи порожній результат, але ніколи - чужі дані.

#### Орендар з автентифікації

Орендаря визначаємо з автентифікованого користувача, а не із заголовка, параметра маршруту чи тіла запиту, які клієнт може змінити. Так орендар лишається поза всім, на що може вплинути модель, і prompt injection не зможе його обрати. `Middleware` реєструється під аліасом `tenant` у `bootstrap/app.php`.

```php
// app/Http/Middleware/ResolveTenant.php
final class ResolveTenant
{
  public function __construct(private TenantContext $tenant) {}

  public function handle(Request $request, Closure $next): Response
  {
    $tenantId = $request->user()?->tenant_id;

    abort_if($tenantId === null, 403, 'No tenant on this identity.');

    $this->tenant->set((int) $tenantId);

    return $next($request);
  }
}
```

`TenantContext` прив'язується через `scoped()`, а не `singleton()`. Синглтон переживає кілька запитів у довгоживучому воркері (Octane), тож застарілий орендар був би на відстані одного пропущеного `set()` від витоку. Scoped-прив'язка створюється заново для кожного запиту.

Метод `scoped()` самого контексту - єдина точка доступу до бази. Він відкриває коротку транзакцію, задає `app.tenant_id` через `set_config(..., true)`, щоб значення жило лише в межах транзакції, і вмикає ітеративні скани індексу тільки для неї.

```php
// AppServiceProvider::register()
$this->app->scoped(TenantContext::class);

final class TenantContext
{
  private ?int $tenantId = null;

  public function set(int $tenantId): void
  {
    $this->tenantId = $tenantId;
  }

  public function id(): int
  {
    return $this->tenantId
      ?? throw new RuntimeException('No tenant context is active.');
  }

  public function scoped(Closure $callback): mixed
  {
    $maxScan = (int) config('rag.max_scan_tuples', 20000);

    return DB::transaction(function () use ($callback, $maxScan) {
      DB::select("select set_config('app.tenant_id', ?, true)", [(string) $this->id()]);
      DB::statement('SET LOCAL hnsw.iterative_scan = relaxed_order');
      DB::statement("SET LOCAL hnsw.max_scan_tuples = {$maxScan}");

      return $callback();
    });
  }
}
```

#### Схема, скоп і політика RLS

Міграція створює векторний стовпець з HNSW-індексом, звичайний індекс на `tenant_id` і саму політику. Хелпери для векторних стовпців описані в [документації Laravel про пошук](https://laravel.com/docs/13.x/search).

```php
public function up(): void
{
  Schema::ensureVectorExtensionExists();

  Schema::create('knowledge_chunks', function (Blueprint $table) {
    $table->id();
    $table->foreignId('tenant_id')->constrained()->cascadeOnDelete();
    $table->text('content');
    $table->vector('embedding', dimensions: 1536)->index(); // match your embedding provider
    $table->timestamps();
    $table->index('tenant_id');
  });

  DB::statement('ALTER TABLE knowledge_chunks ENABLE ROW LEVEL SECURITY');
  DB::statement('ALTER TABLE knowledge_chunks FORCE ROW LEVEL SECURITY');

  DB::statement(<<<'SQL'
    CREATE POLICY tenant_isolation ON knowledge_chunks
    USING (tenant_id = NULLIF(current_setting('app.tenant_id', true), '')::bigint)
    WITH CHECK (tenant_id = NULLIF(current_setting('app.tenant_id', true), '')::bigint)
    SQL);
}
```

Політика читає орендаря з налаштування рівня транзакції, і тут важливі дві деталі. Перша: `NULLIF(..., '')` захищає від налаштування, яке існує, але порожнє - так буває на з'єднанні, де його вже задавали раніше. Приведення порожнього рядка до `bigint` кинуло б помилку замість того, щоб нічого не знайти. Без орендаря порівняння дає NULL, політика не пропускає жодного рядка, і таблиця закривається. Друга: `WITH CHECK` застосовує те саме правило до вставок і оновлень, тож завдання не зможе записати фрагмент іншому орендарю навіть помилково.

`FORCE ROW LEVEL SECURITY` - рядок, який найчастіше забувають. Власник таблиці за замовчуванням обходить політики, тож застосунок, що підключається як власник, просто їх ігнорував би. FORCE закриває цю діру, але суперкористувачі та ролі з `BYPASSRLS` все одно пропускають RLS. На практиці запускайте міграції через окреме привілейоване підключення (`php artisan migrate --database=...`), а застосунку дайте роль, яка нічим не володіє, не має `BYPASSRLS` і отримала лише DML-права. Обидва підключення описуються в `config/database.php`.

Шар Eloquent - швидка й читабельна перша лінія оборони. Скоп викликає `id()`, який кидає виняток, коли орендаря не задано, тож завдання в черзі чи Artisan-команда без контексту падає голосно, а не виконує запит без фільтра.

```php
trait BelongsToTenant
{
  protected static function bootBelongsToTenant(): void
  {
    static::addGlobalScope('tenant', function (Builder $query) {
      $query->where(
        $query->getModel()->qualifyColumn('tenant_id'),
        app(TenantContext::class)->id(),
      );
    });

    static::creating(function (Model $model) {
      $model->tenant_id ??= app(TenantContext::class)->id();
    });
  }
}

final class KnowledgeChunk extends Model
{
  use BelongsToTenant;

  protected $guarded = [];

  protected function casts(): array
  {
    return ['embedding' => 'array'];
  }
}
```

#### Сервіс пошуку, що закривається при помилці

Сервіс спершу рахує ембединг запитання через офіційний SDK `laravel/ai` і тільки потім входить у транзакцію орендаря. Явний ембединг замість рядка у `whereVectorSimilarTo` - свідомий вибір: виклик провайдера лишається поза транзакцією, і його можна повторити. Винятки обмеження частоти запитів і перевантаження провайдера повторюються з короткою затримкою, а якщо не минають, доменний виняток повідомляє, що пошук недоступний. Порожній результат змусив би модель відповідати без контексту і сховав би збій.

```php
final class TenantRetriever
{
  public function __construct(private TenantContext $tenant) {}

  public function retrieve(string $question, int $limit = 6): Collection
  {
    $vector = $this->embed($question);

    $chunks = $this->tenant->scoped(fn () => KnowledgeChunk::query()
      ->whereVectorSimilarTo('embedding', $vector, minSimilarity: 0.4)
      ->limit($limit)
      ->get());

    if ($chunks->contains(fn ($chunk) => (int) $chunk->tenant_id !== $this->tenant->id())) {
      throw new TenantLeakDetected('Retrieval returned a foreign chunk.');
    }

    return $chunks;
  }

  private function embed(string $text): array
  {
    try {
      return retry(
        [250, 1000],
        fn () => Embeddings::for([$text])->generate()->embeddings[0],
        when: fn (Throwable $e) => $e instanceof RateLimitedException
          || $e instanceof ProviderOverloadedException,
      );
    } catch (RateLimitedException|ProviderOverloadedException $e) {
      Log::warning('Embedding provider unavailable', ['tenant' => $this->tenant->id()]);

      throw new RetrievalUnavailable(previous: $e);
    }
  }
}
```

Перевірка після запиту не мала б спрацьовувати ніколи. Вона існує на той день, коли хтось підключить застосунок на staging як суперкористувача. Під'єднайте `TenantLeakDetected` до алертингу, щоб він будив людей, а не губився в логах.

### Пастки, які лишаються з правильною політикою

Правильна політика не робить пошук правильним. Ось випадки, коли ізоляція тримається, але поведінка все одно хибна, або коли сусідній шар знову відкриває діру.

#### Фільтрований векторний пошук повертає замало рядків

pgvector застосовує фільтри після наближеного скану індексу. За документацією pgvector, зі стандартним `hnsw.ef_search` = 40 умова, під яку підпадає 10% рядків, лишає в середньому близько чотирьох результатів. У спільній таблиці фільтр орендаря - саме така умова, і для орендаря з крихітною часткою рядків результатів може не лишитися зовсім.

У pgvector 0.8.0 з'явилися ітеративні скани індексу: вони продовжують сканувати, доки достатньо рядків не пройде фільтр або не буде досягнуто `hnsw.max_scan_tuples` (за замовчуванням 20 000). Після цієї межі запит усе одно повертає менше рядків, ніж ліміт. Тому `scoped()` вмикає їх для кожної транзакції. Режим `relaxed_order` обрано тому, що RAG бере кілька найкращих фрагментів і рідко потребує строгого порядку за відстанню; якщо вам він потрібен, є `strict_order`.

Політика RLS доходить до планувальника як ще одна умова фільтра, тож автор очікує тієї ж поведінки, але радить не припускати, а перевірити `EXPLAIN (ANALYZE)` на реалістичному розподілі розмірів орендарів. Коли підняття `max_scan_tuples` перестає допомагати, документація радить збільшити `hnsw.scan_mem_multiplier`. Далі проблему структурно розв'язують часткові HNSW-індекси для найбільших орендарів або партиції.

> **Підступно в продакшні.** Короткий чи порожній результат пошуку непомітний: модель відповідає із загальних знань, і відповідь виглядає так само впевнено. Логуйте кількість фрагментів на орендаря і ставте алерт, коли частка порожніх пошуків в одного орендаря відривається від решти.

#### Пули з'єднань і довгі транзакції

За PgBouncer у режимі транзакцій сесійний `SET` може лишитися на серверному з'єднанні після кінця вашої транзакції і дістатися наступному клієнту. Саме тому `scoped()` використовує `set_config(..., true)` і `SET LOCAL`: обидва зникають разом із транзакцією.

Друге правило випливає з першого: транзакція має бути короткою. Ембединг запитання рахуйте до входу в `scoped()`, а модель викликайте після виходу. Транзакція, що висить кілька секунд на виклику провайдера, весь цей час тримає серверне з'єднання з пулу. Автор чесно зазначає, що це міркування про механіку пулів, а не вимір з його систем, але розмір пулу варто планувати з цим на увазі.

#### Воркери черг, Octane і кеш

У завдання з черги немає HTTP-запиту, тож орендаря за вас ніхто не задасть. Серіалізуйте ідентифікатор орендаря в завдання і першим ділом викликайте `set()`, а не покладайтеся на те, що лишилося у воркері від попереднього завдання. Винятки обмеження частоти й перевантаження від виклику ембедингів тут просто валять спробу, а далі працює затримка перед повтором самого завдання.

```php
final class IngestDocumentChunks implements ShouldQueue
{
  use Queueable;

  public int $tries = 3;

  public function __construct(
    public readonly int $tenantId,
    public readonly int $documentId,
  ) {}

  public function backoff(): array
  {
    return [30, 120, 600];
  }

  public function handle(TenantContext $tenant): void
  {
    $tenant->set($this->tenantId);

    $body = $tenant->scoped(fn () => Document::query()->findOrFail($this->documentId)->body);

    $pieces = ChunkText::split($body); // your chunking strategy
    $vectors = Embeddings::for($pieces)->generate()->embeddings;

    $tenant->scoped(function () use ($pieces, $vectors) {
      foreach ($pieces as $i => $piece) {
        KnowledgeChunk::query()->create(['content' => $piece, 'embedding' => $vectors[$i]]);
      }
    });
  }
}
```

З кешем те саме правило. Будь-який семантичний кеш чи кеш ембедингів із ключем за текстом запитання мусить містити в ключі ідентифікатор орендаря. Інакше орендар B отримає закешовану відповідь орендаря A, і жодного запиту до бази, який міг би це зловити, не буде. Так само з пам'яттю агентів, яку ви зберігаєте між розмовами: це такий самий контекст для моделі, як і фрагменти, і йому потрібна та сама межа.

### Тест на витік

Тест створює двох орендарів і перевіряє дві речі: пошук для орендаря A ніколи не містить рядків орендаря B, а запит без контексту орендаря не повертає нічого. Чи має тест сенс, вирішують дві деталі середовища.

> **Підступно в продакшні.** Запускайте тести від обмеженої ролі застосунку. Від суперкористувача чи ролі з `BYPASSRLS` політика пропускається, і тест проходить з хибної причини. Це найпоширеніший спосіб, у який налаштування RLS виглядає правильним, але таким не є.

> **Точка збою.** Не використовуйте тут `RefreshDatabase`. Він загортає кожен тест у транзакцію, тож `scoped()` стає savepoint, а налаштування рівня транзакції живе до кінця зовнішньої транзакції. Перевірка «без контексту нічого не видно» тоді побачить попереднього орендаря. `DatabaseTruncation` цієї проблеми не має.

```php
uses(DatabaseTruncation::class);

it('never returns another tenant chunk and fails closed without context', function () {
  $a = Tenant::factory()->create();
  $b = Tenant::factory()->create();
  $context = app(TenantContext::class);
  $vector = array_fill(0, 1536, 0.02);

  foreach ([$a, $b] as $tenant) {
    $context->set($tenant->id);
    $context->scoped(fn () => KnowledgeChunk::query()->create([
      'content' => "private to tenant {$tenant->id}",
      'embedding' => $vector,
    ]));
  }

  $context->set($a->id);
  $results = $context->scoped(fn () => KnowledgeChunk::query()
    ->whereVectorSimilarTo('embedding', $vector, minSimilarity: 0.1)
    ->get());

  expect($results)->toHaveCount(1)
    ->and((int) $results->first()->tenant_id)->toBe($a->id);

  // Outside scoped(), the policy must match nothing.
  expect(DB::select('select count(*) as total from knowledge_chunks')[0]->total)->toBe(0);
});
```

### Підсумок

RAG для кількох орендарів - це спершу задача про межі, а вже потім про пошук. Визначайте орендаря з автентифікації, тримайте його в scoped-контексті і застосовуйте двічі: скоп Eloquent для коректності і примусову RLS для безпеки. Утретє перевірте перед складанням промпту. Усі звернення до бази, що залежать від орендаря, пускайте через один хелпер із транзакційними налаштуваннями, щоб пули з'єднань, ітеративні скани і контекст орендаря завжди узгоджувалися.

Компроміси справжні. Спільна таблиця найдешевша в експлуатації, але показує проблеми з recall для малих орендарів, а RLS додає дисципліну з ролями й обмеження для тестів, яких немає в самого скопу. Партиції та окремі бази - це ескалація, до якої вдаються, коли цього вимагає перекіс у розмірах орендарів або договори з клієнтами.
