[Intum](https://intum.fr/aide.md) / [Noe AI](https://intum.fr/aide/noe-ai.md)

# [Bazy wektorowe](https://intum.fr/aide/noe-ai/bazy-wektorowe.md) | [API](#api)

## Bazy wektorowe

Bazy wektorowe umożliwiają wyszukiwanie semantyczne — zamiast szukać po dokładnym dopasowaniu słów, system rozumie znaczenie tekstu i znajduje podobne treści.

## Jak to działa?

1. **Embedding** — każdy tekst jest konwertowany na wektor liczbowy (1536 wymiarów) przez model AI
2. **Przechowywanie** — wektory są zapisywane w bazie wraz z oryginalnym tekstem i metadanymi
3. **Wyszukiwanie** — pytanie użytkownika jest zamieniane na wektor i porównywane z zapisanymi wektorami (cosine distance)
4. **Wyniki** — system zwraca najlepiej dopasowane wpisy

## Zastosowania

- **RAG (Retrieval-Augmented Generation)** — wzbogacanie odpowiedzi AI o kontekst z bazy wiedzy
- **Wyszukiwarka semantyczna** — znajdowanie podobnych dokumentów, artykułów, FAQ
- **Chat z bazą wiedzy** — zadajesz pytanie, AI odpowiada na podstawie Twoich dokumentów

## Wymagania

Baza wektorowa wymaga connectora AI (OpenAI, Gemini lub Claude) z obsługą embeddingów do generowania wektorów.

## Wpisy

Każdy wpis w bazie wektorowej zawiera:
- Treść tekstową
- Wektor embedding
- Metadane (np. URL źródła)
- Powiązanie ze źródłem (typ + ID, np. Kb::Entry #35)
- Numer chunka (gdy tekst był dzielony)

## Dzielenie tekstu na chunki

Długie teksty są automatycznie dzielone na mniejsze fragmenty (chunki) przed generowaniem embeddingu. Każdy chunk to osobny wpis w bazie wektorowej — ale wszystkie chunki z jednego źródła (np. wpisu KB) są ze sobą powiązane.

### Opcja "Chunking włączony"

W ustawieniach bazy wektorowej można włączyć opcję dzielenia na chunki. Zmienia to zachowanie:

| Ustawienie | Rozmiar chunka | Efekt |
|---|---|---|
| **Chunking wyłączony** | max tokenów modelu (np. 8191 dla OpenAI) | Tekst dzielony tylko gdy przekracza limit modelu. Większe fragmenty, mniej wpisów |
| **Chunking włączony** | ~500 tokenów (~1-2 paragrafy) | Tekst zawsze dzielony na małe fragmenty. Precyzyjniejsze wyszukiwanie |

### Kiedy włączyć chunking

- **Włącz** gdy źródło ma długie dokumenty (artykuły, regulaminy, dokumentacja) i zależy ci na precyzji wyszukiwania — mały chunk lepiej dopasowuje się do konkretnego pytania
- **Zostaw wyłączony** gdy wpisy są krótkie (FAQ, pojedyncze pytania/odpowiedzi) — dzielenie krótkich tekstów nie ma sensu

### Jak działa dzielenie

1. System rozpoznaje strukturę tekstu — nagłówki markdown (`## Sekcja`), paragrafy, listy HTML
2. Nowa sekcja (nagłówek) to naturalna granica chunka
3. Każdy chunk dostaje prefix z nagłówkiem sekcji, do której należy — dzięki temu nie traci kontekstu
4. Jeśli tekst jest w HTML — system konwertuje go na structured text zachowując nagłówki i paragrafy
5. Tokeny liczone dokładnie przez tiktoken (tokenizer OpenAI) — nie zgaduje po znakach

### Limity per model

Każdy model embeddingowy ma inny limit tokenów na jedno wywołanie. System automatycznie pobiera limit z connectora:

| Model | Max tokenów | Efekt z chunking OFF | Efekt z chunking ON |
|---|---|---|---|
| OpenAI text-embedding-3-small | 8 191 | chunki do ~7 800 tokenów | chunki do 500 tokenów |
| Cohere embed-v4 (Bedrock) | 128 000 | praktycznie bez dzielenia | chunki do 500 tokenów |
| Gemini embedding | 2 048 | chunki do ~1 900 tokenów | chunki do 500 tokenów |

Przy przełączeniu connectora (np. z OpenAI na Cohere) limity dostosowują się automatycznie — nie trzeba nic zmieniać w ustawieniach bazy.

---

## API

### Ogólne API

# Intum API

Dokumentacja API platformy [Intum](https://intum.pl) - system operacyjny firmy.

## Host

Host jest zawsze taki sam jak adres konta: `xxxx.intum.com` lub `xxx.intum.pl` (w zależności od ustawień konta)

## Autoryzacja

Wszystkie requesty API wymagają `api_token`:
- header: `Authorization: Bearer TOKEN`

Token możesz wygenerować w **Ustawienia Konta** → **Tokeny API**

# Bazy wektorowe — API

**Autoryzacja:** `Authorization: Bearer TOKEN`
**Content-Type:** `application/json`

## Endpoints bazy wektorowej

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/noe/vector_dbs.json` | Lista baz wektorowych |
| GET | `/noe/vector_dbs/:id.json` | Szczegóły 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` | Wyszukiwanie wpisów (RAG) |
| GET/POST | `/noe/vector_dbs/:id/chat` | Chat RAG (wyszukaj + odpowiedź LLM) |

## Pola bazy wektorowej

| Pole | Typ | Wymagane | Opis |
|------|-----|----------|------|
| `name` | string | tak | Nazwa bazy |
| `code` | string | tak | Kod unikalny (per konto) |
| `description` | string | nie | Opis |
| `connector_id` | integer | tak | ID konektora AI (musi wspierać embeddingi) |
| `dimensions` | integer | nie | Wymiar embeddingu (default: 1536) |
| `embedding_model` | string | nie | Model embeddingu (default: text-embedding-3-small) |
| `context_limit` | integer | nie | Limit wyników wyszukiwania (default: 7) |
| `system_prompt` | text | nie | Prompt systemowy dla RAG |
| `knowledge_base_id` | integer | nie | ID powiązanej bazy wiedzy |

## POST — Utworzenie

```json
POST /noe/vector_dbs.json

{
  "vector_db": {
    "name": "FAQ",
    "code": "faq",
    "connector_id": 123,
    "context_limit": 5,
    "system_prompt": "Odpowiadaj na podstawie podanego kontekstu."
  }
}
```

## Wyszukiwanie i Chat RAG

```
GET /noe/vector_dbs/faq/search.json?q=jak+zmienić+hasło
GET /noe/vector_dbs/faq/chat?q=jak+zmienić+hasło&context_limit=3
```

## Endpoints wpisów wektorowych

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/noe/vector_dbs/:id/vector_entries.json` | Lista wpisów |
| POST | `/noe/vector_dbs/:id/vector_entries.json` | Tworzenie wpisu |
| PATCH | `/noe/vector_dbs/:id/vector_entries/:id.json` | Aktualizacja wpisu |
| DELETE | `/noe/vector_dbs/:id/vector_entries/:id.json` | Usunięcie wpisu |

## Pola wpisu wektorowego

| Pole | Typ | Wymagane | Opis |
|------|-----|----------|------|
| `content` | text | tak | Treść wpisu |
| `metadata` | jsonb | nie | Metadane wpisu |
| `kb_entry_id` | integer | nie | ID powiązanego wpisu KB |

Embedding jest generowany automatycznie przy tworzeniu/edycji.

## POST — Tworzenie wpisu

```json
POST /noe/vector_dbs/faq/vector_entries.json

{
  "vector_entry": {
    "content": "Aby zmienić hasło, przejdź do ustawień...",
    "metadata": { "category": "security" }
  }
}
```

---

## Powiązane

- [Zasilanie bazy wiedzy z ticketów helpdesku](https://intum.fr/aide/baza-wiedzy/zasilanie-bazy-wiedzy-z-ticketow.md)
- [Analiza ticketów do bazy wiedzy](https://intum.fr/aide/helpdesk/analiza-ticketow-do-bazy-wiedzy.md)
- [Źródła wiedzy dla agenta AI](https://intum.fr/aide/noe-ai/zrodla-wiedzy-dla-agenta-ai.md)
- [Noe AI w Intum](https://intum.fr/aide/noe-ai/noe-ai.md)