[Intum Pomoc](https://intum.pl/pomoc.md) / [API](https://intum.pl/pomoc/noe/api.md)

# [Bazy wektorowe Noe i ich źródła](https://intum.pl/pomoc/noe/api/bazy-wektorowe.md)

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

```json
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

```json
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

```json
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

```json
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

```json
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`

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

### Indeksowanie źródła

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

```json
{ "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
```

```json
{ "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
```

```json
{ "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](https://app.intum.pl/noe/prompt/kb_entry_api.md) — zarządzanie wpisami bazy wiedzy
- [helpdesk_desk_api](https://app.intum.pl/noe/prompt/helpdesk_desk_api.md) — konfiguracja desków helpdesk
- [common_api](https://app.intum.pl/noe/prompt/common_api.md) — wspólne zasady API (format, autoryzacja, odpowiedzi)