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)

Źródła