---
name: rag-pgvector
description: >-
  Собирает «умную базу знаний» (RAG) на Supabase pgvector для micro-SaaS в модуле M·MAKE,
  Часть 2 «Движок». Вызывай, когда человек говорит: «сделай базу знаний», «отвечать по моим
  документам», «RAG», «векторный поиск», «поиск по смыслу», «загрузить документы и искать»,
  «чтобы ИИ отвечал по моим файлам, не выдумывая». Навык задаёт ПРАВИЛЬНЫЙ рецепт: нарезка →
  эмбеддинги OpenAI → хранение в pgvector (+HNSW) → поиск match_documents → ответ модели
  ТОЛЬКО по найденному. Для непрограммиста, промпт-онли, ключ на сервере. Строит родной агент
  через Supabase MCP — навык даёт рецепт, параметры и грабли.
---

# Навык: База знаний на pgvector (RAG) — модуль M·MAKE, Часть 2

**Как запустить:** «сделай базу знаний» / «чтобы отвечал по моим документам».

Сначала различи **два уровня** (не путать):
- **Уровень 1 — простой справочник.** Вопрос→ответ, материал→норматив, правило→действие. Это обычные **таблицы Postgres**, приложение читает нужную строку. **AI и RAG НЕ нужны.** Если у человека так — скажи прямо и не строй вектор.
- **Уровень 2 — RAG (этот навык).** Нужен, когда AI должен **отвечать по ТВОИМ документам, не выдумывая**. Только тогда векторная база.

**Модель RAG:** документы → режем на куски (чанки) → превращаем в эмбеддинги (числовые отпечатки смысла) → храним в `pgvector` → на вопрос находим похожие куски → отдаём их модели как контекст → модель отвечает **только из найденного** (меньше галлюцинаций).

---

## ⚙️ Рецепт (по нему строит агент через Supabase MCP)

### 1. Нарезка (chunking) — самое важное
- Режь **по структуре**: заголовки → абзацы → предложения. **НЕ по N символов вслепую** (иначе ответы плывут).
- Размер куска **~400–500 токенов**, перекрытие **~10–15%** (~50 токенов), **не разрывать предложения**.
- Каждый кусок **начинать с названия раздела** (сохраняем контекст).

### 2. Эмбеддинги — через OpenAI (ключ на сервере)
- Дефолт **`text-embedding-3-small`** (1536). Нужно лучше по русскому — **`text-embedding-3-large`** (3072).
- **НЕ `gte-small`** (она только английская).
- ⚠️ **Правило: размерность колонки `vector` = размерности модели.** 3-small = 1536, 3-large = 3072. Сменил модель → пересоздай колонку/индекс и **переэмбедди всю базу заново**.

### 3. Хранение и поиск (Supabase)
- Таблица, напр. `documents`: `id`, `content text`, `metadata jsonb` (источник, владелец), `embedding vector(1536)`.
- Индекс **HNSW** по `embedding` (когда документов много).
- SQL-функция **`match_documents(query_embedding, match_count, filter)`** — косинусное сходство (`<=>`), возвращает топ-N.
- Для точности можно **гибрид** (смысл + полнотекст), но начни с чистого векторного.

### 4. Два потока в Edge Functions
- **Индексация:** загрузил документ → Edge Function режет на чанки → делает эмбеддинги (OpenAI, ключ из `Deno.env.get`) → пишет строки в `documents`.
- **Ответ:** вопрос → эмбеддинг вопроса → `match_documents` топ-5 → собрать найденные куски в контекст → chat completion с инструкцией: **«Отвечай ТОЛЬКО из этого контекста. Если ответа нет — так и скажи, не выдумывай»** → показать ответ + источники.

---

## 🔒 Правила и грабли
1. **Ключ OpenAI — только на сервере** (Edge Function secrets), в чат не проси. По ключам зови навык `secrets-policy` (Проводник за руку).
2. **Изоляция:** если база знаний персональная — фильтруй по владельцу (RLS / `metadata`), иначе человек увидит чужие документы.
3. **Грабли:** нарезка вслепую · забыть HNSW-индекс · рассинхрон размерности · не поставить фильтр доступа.
4. **Строишь через Supabase MCP** (миграции, функция, Edge Functions). Аддитивно к живому — не ломай рабочие трубы.
5. Код по месту генерит родной агент; навык задаёт рецепт, параметры и правила.

## ✅ Определение готовности
Загрузил документ → задал вопрос по нему → получил верный ответ со ссылкой на источник; задал вопрос НЕ по базе → модель честно говорит «не знаю».

## Источники рецепта
Supabase Semantic Search (`supabase.com/docs/guides/ai/semantic-search`), Generate embeddings, Vector indexes; OpenAI embeddings (`text-embedding-3-*`); практики нарезки RAG 2025–2026 (Firecrawl, Weaviate).