Це переказ статті Девальда Г'юго (Dewald Hugo) з блогу Origin Main. Ми зберегли структуру, код і всі технічні поради автора, але скоротили пояснення.
RAG у застосунку з кількома орендарями (multi-tenant) ламається тихо. Запит на пошук, у якому забули фільтр орендаря, повертає правдоподібні фрагменти іншого клієнта, модель переказує їх у відповіді, і жоден рядок логу не покаже чужого запису. Надійний захист має два шари: глобальний скоп (Scope) Eloquent, який тримає правильний код правильним, і політика row level security (RLS) у PostgreSQL, яка робить неправильний код нешкідливим. Нижче обидва шари на pgvector, а потім пастки, які лишаються навіть із правильною політикою: фільтровані скани індексу, пули з'єднань, воркери черг і кеш.
Стаття виходить з того, що ембединги вже зберігаються в PostgreSQL. Як це налаштувати, ми розбирали в пості «Простий векторний пошук подібності для Laravel». Імпорти у фрагментах коду пропущено.
Вибір моделі ізоляції
Це рішення варто ухвалити першим, бо воно визначає дизайн індексу, процес міграцій і те, які збої ви успадкуєте. Поширені чотири моделі, і вони обмінюють силу ізоляції на операційну вагу.
| Модель |
Гарантія ізоляції |
Поведінка векторного індексу |
Операційна вартість |
Коли доречна |
| Спільна таблиця, лише скоп у застосунку |
Залежить від того, чи кожен запит не забув фільтр |
Один індекс, фільтр після скану |
Найнижча |
Внутрішні інструменти, прототипи |
| Спільна таблиця, скоп плюс RLS |
База відхиляє читання без орендаря і запис у чужого орендаря |
Один індекс, фільтр після скану |
Низька, плюс дисципліна з ролями й пулами |
Більшість B2B SaaS |
| Партиція на орендаря (або групу) |
Як у RLS, плюс фізичне розділення |
Свій індекс на партицію, без фільтрації між орендарями |
Середня, керування партиціями в міграціях |
Кілька орендарів тримають більшість рядків |
| База даних на орендаря |
Найсильніша, окремі облікові дані |
Повністю незалежні індекси |
Висока, N міграцій і N пулів |
Розділення за договором чи регуляторними вимогами |
Для більшості B2B-продуктів автор радить починати зі спільної таблиці, скопу в застосунку та примусової RLS - і чесно називає це архітектурною думкою, а не бенчмарком. База на орендаря множить міграції, пули з'єднань і побудову індексів на кількість клієнтів, і ця вартість наздожене невелику команду значно раніше, ніж витік. Сигнал переходити до партицій - recall, а не безпека: якщо кілька орендарів володіють більшістю рядків, спільний HNSW-індекс змушує запит кожного малого орендаря продиратися крізь чужі вектори.
Якщо поруч із векторами ви тримаєте ще й повнотекстовий пошук (наприклад, Scout і Meilisearch), це другий шлях пошуку, і його фільтр орендаря - окремий контроль, який треба перевіряти так само.
Де губиться орендар на шляху пошуку
RAG-запит проходить п'ять кроків, і на кожному можна загубити орендаря:
- Вхідний запит - орендар береться з автентифікації, ніколи з даних користувача.
- Контекст орендаря - scoped-прив'язка, безпечна для Octane.
- Ембединг запитання - поза транзакцією.
- Векторний запит - скоп плюс примусова політика RLS. Це єдиний крок, який гарантує сама база.
- Складання промпту - перевірка, що всі ідентифікатори орендаря збігаються.
Межу в базі вважайте основним контролем, а решту - раннім попередженням. Скоп у застосунку обходить сирий запит, виклик withoutGlobalScopes(), доданий заради звіту, або завдання, яке забуло задати контекст. Політика RLS переживає всі три випадки. Перевірка перед складанням промпту - дешева страховка: якщо шар бази колись налаштують неправильно, ви дізнаєтесь про це раніше за модель.
Будуємо межу
Реалізація складається з чотирьох частин: контекст орендаря в межах запиту, таблиця під захистом RLS, скоп Eloquent для звичайного шляху і сервіс пошуку, що закривається при помилці. Кожне рішення підібране так, щоб забута дрібниця давала помилку чи порожній результат, але ніколи - чужі дані.
Орендар з автентифікації
Орендаря визначаємо з автентифікованого користувача, а не із заголовка, параметра маршруту чи тіла запиту, які клієнт може змінити. Так орендар лишається поза всім, на що може вплинути модель, і prompt injection не зможе його обрати. Middleware реєструється під аліасом tenant у bootstrap/app.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), щоб значення жило лише в межах транзакції, і вмикає ітеративні скани індексу тільки для неї.
// 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 про пошук.
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-команда без контексту падає голосно, а не виконує запит без фільтра.
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 - свідомий вибір: виклик провайдера лишається поза транзакцією, і його можна повторити. Винятки обмеження частоти запитів і перевантаження провайдера повторюються з короткою затримкою, а якщо не минають, доменний виняток повідомляє, що пошук недоступний. Порожній результат змусив би модель відповідати без контексту і сховав би збій.
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(), а не покладайтеся на те, що лишилося у воркері від попереднього завдання. Винятки обмеження частоти й перевантаження від виклику ембедингів тут просто валять спробу, а далі працює затримка перед повтором самого завдання.
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 цієї проблеми не має.
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 додає дисципліну з ролями й обмеження для тестів, яких немає в самого скопу. Партиції та окремі бази - це ескалація, до якої вдаються, коли цього вимагає перекіс у розмірах орендарів або договори з клієнтами.