Bazy wektorowe Noe i ich źródła

Zarządzanie bazami wektorowymi, wpisami (entries) i źródłami wiedzy (sources).

Autoryzacja: Authorization: Bearer TOKEN lub ?api_token=TOKEN Content-Type: application/json

Kontekst

Baza wektorowa (VectorDb) przechowuje zaindeksowane wpisy z różnych źródeł. Źródła to:

• Baza wiedzy (Kb::KnowledgeBase) — wpisy KB → typ entry: kb_entry
• Skrzynka mailowa (Mail::Mailbox) — emaile → typ entry: email
• Desk helpdesk (Helpdesk::Desk) — tickety → typ entry: ticket
• Widget webchat (Webchat::Widget) — wiadomości czatu → typ entry: chat_message

VectorDb — Endpoints

Metoda	Ścieżka	Opis
GET	/noe/vector_dbs.json	Lista baz wektorowych
GET	/noe/vector_dbs/:id.json	Pobranie bazy
POST	/noe/vector_dbs.json	Utworzenie bazy
PATCH	/noe/vector_dbs/:id.json	Aktualizacja bazy
DELETE	/noe/vector_dbs/:id.json	Usunięcie bazy
GET	/noe/vector_dbs/:id/search.json?q=QUERY	Wyszukiwanie wektorowe
POST	/noe/vector_dbs/:id/chat.json	RAG chat (wyszukaj + odpowiedz LLM)

Uwaga: :id może być UUID lub code bazy (np. helpdesk-desk-1).

Pola VectorDb

Pole	Typ	Wymagane	Opis
name	string	tak	Nazwa bazy
code	string	nie	Unikalny kod (slug) — automatycznie sanityzowany
description	string	nie	Opis bazy
connector_id	integer	tak	ID konektora AI (musi obsługiwać embeddingi)
chat_connector_id	integer	nie	Oddzielny konektor do chatu (fallback na connector)
system_prompt	text	nie	System prompt dla RAG chatu
context_limit	integer	nie	Limit kontekstu (domyślnie 7)

POST — Utworzenie bazy

POST /noe/vector_dbs.json

{
  "vector_db": {
    "name": "Moja baza wiedzy",
    "code": "moja-baza",
    "connector_id": 6,
    "description": "Baza do wyszukiwania kontekstu"
  }
}

PATCH — Aktualizacja bazy

PATCH /noe/vector_dbs/:id.json

{
  "vector_db": {
    "name": "Zmieniona nazwa",
    "system_prompt": "Odpowiadaj krótko i rzeczowo."
  }
}

GET — Wyszukiwanie wektorowe

GET /noe/vector_dbs/:id/search.json?q=jak+dodać+zadanie&limit=5

Zwraca najbardziej podobne wpisy (cosine distance).

POST — RAG chat

POST /noe/vector_dbs/:id/chat.json

{ "q": "Jak dodać zadanie?", "context_limit": 5 }

Wyszukuje podobne wpisy i generuje odpowiedź LLM z kontekstem.

VectorEntry — Endpoints

Metoda	Ścieżka	Opis
GET	/noe/vector_dbs/:vector_db_id/vector_entries.json	Lista wpisów
GET	/noe/vector_dbs/:vector_db_id/vector_entries/:id.json	Pobranie wpisu
POST	/noe/vector_dbs/:vector_db_id/vector_entries.json	Utworzenie wpisu
PATCH	/noe/vector_dbs/:vector_db_id/vector_entries/:id.json	Aktualizacja wpisu
DELETE	/noe/vector_dbs/:vector_db_id/vector_entries/:id.json	Usunięcie wpisu

Pola VectorEntry

Pole	Typ	Wymagane	Opis
content	text	tak	Treść wpisu — embedding generowany automatycznie
source_type	string	nie	Typ źródła (kb_entry, email, ticket, chat_message)
source_id	integer	nie	ID źródłowego obiektu
metadata	json	nie	Dodatkowe metadane (JSON)

POST — Utworzenie wpisu

POST /noe/vector_dbs/:vector_db_id/vector_entries.json

{
  "vector_entry": {
    "content": "Aby dodać zadanie, kliknij + w module Zadania.",
    "source_type": "kb_entry",
    "source_id": 123,
    "metadata": { "category": "zadania" }
  }
}

Embedding generowany automatycznie z content przy tworzeniu i aktualizacji.

PATCH — Aktualizacja wpisu

PATCH /noe/vector_dbs/:vector_db_id/vector_entries/:id.json

{
  "vector_entry": {
    "content": "Zaktualizowana treść — embedding zostanie przeliczony."
  }
}

Źródła (Sources) — Endpoints

Wszystkie endpointy w namespace /noe/vector_dbs/:vector_db_id/sources.

Metoda	Ścieżka	Opis
POST	.../sources/connect	Podłączenie źródła
DELETE	.../sources/:id/disconnect	Odłączenie źródła (kasuje wpisy z tego źródła)
POST	.../sources/add_bulk	Uruchomienie indeksowania źródła
DELETE	.../sources/remove_bulk	Usunięcie wpisów danego typu
PATCH	.../sources/:id/settings	Ustawienia źródła (auto_index, index_from_date)
POST	.../sources/:id/exclude_entry	Wykluczenie wpisu ze źródła
POST	.../sources/:id/custom_entry	Ustawienie własnej treści wpisu
DELETE	.../sources/:id/remove_entry_override	Usunięcie nadpisania wpisu

Podłączenie źródła

POST /noe/vector_dbs/:vector_db_id/sources/connect

Parametr source w formacie TYP:ID, np.:

• Kb::KnowledgeBase:1
• Mail::Mailbox:5
• Helpdesk::Desk:3
• Webchat::Widget:2

{ "source": "Kb::KnowledgeBase:1" }

Indeksowanie źródła

POST /noe/vector_dbs/:vector_db_id/sources/add_bulk

{ "source_class": "Kb::KnowledgeBase", "source_id": 1 }

Uruchamia job w tle — indeksuje wpisy ze źródła do bazy wektorowej.

Ustawienia źródła

PATCH /noe/vector_dbs/:vector_db_id/sources/:id/settings

Parametr	Typ	Opis
auto_index	"1" / "0"	Automatyczne indeksowanie nowych wpisów
index_from_date	string	Indeksuj tylko od daty "YYYY-MM-DD" (puste = wszystko)

Wykluczenie wpisu

POST /noe/vector_dbs/:vector_db_id/sources/:id/exclude_entry

{ "entry_source_type": "kb_entry", "entry_source_id": 123 }

Wyklucza wpis z indeksowania — nie zostanie ponownie zaindeksowany.

Własna treść wpisu

POST /noe/vector_dbs/:vector_db_id/sources/:id/custom_entry

{ "entry_source_type": "kb_entry", "entry_source_id": 123, "custom_content": "Moja treść" }

Nadpisuje oryginalną treść — przy następnym indeksowaniu użyta zostanie treść własna.

Usunięcie wpisów po typie

DELETE /noe/vector_dbs/:vector_db_id/sources/remove_bulk?source_type=kb_entry

Dozwolone typy: kb_entry, ticket, email, chat_message.

Powiązane

• kb_entry_api — zarządzanie wpisami bazy wiedzy
• helpdesk_desk_api — konfiguracja desków helpdesk
• common_api — wspólne zasady API (format, autoryzacja, odpowiedzi)