1. Instalacja i konfiguracja
Przygotowanie środowiska – Upewnij się, że masz zainstalowany Drupal 11 oraz wymagane moduły: przede wszystkim moduł AI (Artificial Intelligence) wraz z zależnym modułem Key (do przechowywania kluczy API) oraz moduł wyszukiwania Search API
. Następnie zainstaluj moduł Milvus VDB Provider (
ai_vdb_provider_milvus) – np. za pomocą Composera:composer require drupal/ai_vdb_provider_milvus. Po instalacji włącz ten moduł (np. poleceniemdrush en ai_vdb_provider_milvuslub poprzez UI Drupal).Uruchomienie Milvus – Zapewnij działającą instancję bazy wektorowej Milvus. Możesz użyć obrazu Dockera Milvus (domyślnie nasłuchuje na porcie
19530). Jeśli korzystasz z rozwiązania DDEV, skorzystaj z przygotowanego pliku konfiguracyjnego (np.ddev-example.docker-compose.milvus.yaml) i zrestartuj DDEV, co udostępni interfejs Milvus (np. pod adresem
https://<twoj-projekt>.ddev.site:8521dla DDEV). Upewnij się, że Milvus jest uruchomiony i dostępny (np. sprawdzając logi kontenera lub otwierając panel Milvus, jeśli jest dostępny).Konfiguracja połączenia z Milvus w Drupal – Po włączeniu modułu przejdź do panelu konfiguracyjnego: Konfiguracja > AI > Vector DB Providers > Milvus (adres:
/admin/config/ai/vdb_providers/milvus). Wprowadź dane połączenia do bazy Milvus:
- Host: adres hosta Milvus (dla lokalnej instancji może to być
http://127.0.0.1lub nazwa hosta/Docker service, np.http://milvus), Port: port nasłuchu (domyślnie
19530),
API Key: pozostaw puste dla lokalnej instancji (w przypadku lokalnego Milvus nie jest wymagany klucz API
; dla usługi w chmurze Zilliz wpisz odpowiedni klucz/API token).
Inne opcje: jeśli konfiguracja przewiduje nazwę bazy danych (Database) lub inne parametry, wypełnij je zgodnie z konfiguracją Milvus (np. nazwę wcześniej utworzonej bazy w Milvus, domyślnie może to być
defaultlub utworzona przez Ciebie, np.db1).
- Zapisz konfigurację. Po zapisaniu powinna pojawić się informacja o poprawnym zapisaniu ustawień. Brak błędów oznacza, że moduł nawiązał połączenie z bazą Milvus (w razie błędu sprawdź poprawność hosta/portu oraz czy Milvus na pewno działa).
- Host: adres hosta Milvus (dla lokalnej instancji może to być
Weryfikacja działania połączenia – Aby upewnić się, że baza Milvus jest poprawnie podłączona, możesz przeprowadzić szybki test:
- Test indeksacji: (o tym więcej w kolejnym punkcie) utworzenie indeksu wektorowego i zaindeksowanie przykładowej treści pozwoli sprawdzić, czy dane trafiają do Milvus. Jeśli indeksacja przebiegnie pomyślnie (bez błędów w logach Drupala) i będzie zwracać wyniki, oznacza to, że połączenie z Milvus działa.
- Panel Milvus: jeżeli korzystasz z interfejsu Milvus (np. UI w przeglądarce lub klienta Milvus), sprawdź czy po zapisaniu konfiguracji w Drupal utworzyła się nowa kolekcja (collection) w bazie Milvus. Moduł Milvus VDB Provider tworzy kolekcję podczas konfiguracji indeksu/serwera wyszukiwania, więc na tym etapie może jej jeszcze nie być. Natomiast po utworzeniu indeksu i pierwszej indeksacji (opisanej w kolejnym kroku) powinna pojawić się kolekcja z wektorami.
Logi Drupala: w przypadku problemów zajrzyj do raportów błędów (dostępnych w Raporty > Raporty ostatnich zdarzeń). Jeżeli po zapisaniu konfiguracji pojawia się błąd lub wyjątek (np. Unexpected error), oznacza to problem z połączeniem – w takim wypadku sprawdź jeszcze raz host/port i czy instancja Milvus jest dostępna. W razie potrzeby skonsultuj dokumentację modułu na Drupal.org
.
2. Konfiguracja w module AI (asystent i RAG)
Indeksowanie treści w bazie wektorowej (Milvus) – Aby asystent AI mógł korzystać z danych z Milvus, najpierw zaindeksuj zawartość strony do bazy wektorowej. Moduł AI Search (wchodzący w skład ekosystemu AI) integruje się z Search API, pozwalając traktować Milvus jako silnik wyszukiwania wektorowego
. Wykonaj następujące kroki:
Upewnij się, że włączony jest moduł AI Search (experimental) oraz wymagane pluginy. Jeśli jeszcze tego nie zrobiłeś, włącz podmoduł AI Search i zależny moduł Search API (o ile nie był włączony wcześniej)
.
- Dodaj serwer wyszukiwania oparty o Milvus: Przejdź do Konfiguracja > Wyszukiwanie i metadane > Search API > Dodaj serwer (URL:
/admin/config/search/search-api/add-server). W formularzu dodawania serwera wybierz typ serwera związany z AI Search (np. typ „Vector database” jeżeli taki widnieje) i wskaż dostawcę Milvus. Podaj nazwę serwera (np. "Milvus"), a następnie uzupełnij szczegóły połączenia:Host i port – takie same, jak w konfiguracji modułu (np. host
milvusi port19530lublocalhost:19530w zależności od środowiska).
Nazwa bazy danych (Database name) – wpisz nazwę bazy utworzonej w Milvus (jeśli Milvus obsługuje koncepcję wielu baz, np.
db1utworzone wcześniej; w przypadku korzystania z domyślnej bazy, możesz wpisać
defaultlub pozostawić domyślną wartość sugerowaną przez moduł).- Nazwa kolekcji (Collection) – podaj nazwę kolekcji wektorów, której chcesz używać (np. "collection1"). Jeśli ta kolekcja nie istnieje, moduł utworzy ją przy pierwszym indeksowaniu.
Metryka podobieństwa – wybierz metodę porównywania wektorów (np. Cosine similarity, jeśli jest dostępna
). Cosine lub IP (iloczyn skalarny) to popularne metryki dla wyszukiwania semantycznego.
- Po wypełnieniu, zapisz nowy serwer. Uwaga: Jeśli zapis serwera się nie powiedzie (błąd), sprawdź ponownie konfigurację Milvus. Prawidłowe utworzenie serwera wskazuje, że Drupal potrafi komunikować się z Milvus.
- Skonfiguruj silnik wektorowy (AI Search) – Po dodaniu serwera, pojawią się ustawienia związane z AI Search. Wybierz odpowiedni silnik embeddingów i dostawcę AI:
Embeddings engine: ustaw OpenAI oraz konkretny model do embeddingów (np.
text-embedding-ada-002). Moduł AI może oferować listę modeli – na przykładzie dokumentacji pokazano modelOpenAI | text-embedding-3-small(co odpowiada modelowi embeddingów OpenAI; text-embedding-ada-002 ma wektor 1536-wymiarowy, co zgadza się z ustawieniem 1536 dla liczby wymiarów
).
- Tokenizer model: wybierz model tokenizujący odpowiadający embeddingom (np. również OpenAI
text-embedding-ada-002lub analogiczny, aby poprawnie dzielić tekst na tokeny przy indeksacji). Vector Database: wybierz Milvus jako bazę wektorową, z którą ma się integrować (powinien być widoczny, skoro dodaliśmy serwer Milvus)
.
- Zapisz konfigurację serwera po ustawieniu tych opcji. Teraz Drupal wie, że ma używać OpenAI do generowania wektorów i Milvus do ich przechowywania.
- Utwórz indeks Search API – Dodaj Indeks w Search API, który będzie obejmował treści do wykorzystania przez AI. Przejdź do Konfiguracja > Wyszukiwanie i metadane > Search API > Dodaj indeks (URL:
/admin/config/search/search-api/add-index). Wybierz:- Źródło danych: Treści (Content) – np. wszystkie węzły (Nodes) lub konkretne typy zawartości, które mają być dostępne dla asystenta.
Serwer: Wybierz serwer Milvus utworzony powyżej
.
- Nazwij indeks (np. "AI Content Index") i zaznacz opcję Włączony (enabled).
Tryb indeksacji: zaznacz Indeksuj elementy natychmiast (Index items immediately)
, co spowoduje, że nowe/zmienione treści będą od razu zapisywane do indeksu (i tym samym do Milvus). Alternatywnie możesz indeksować przez cron, ale tryb natychmiastowy ułatwia testowanie integracji RAG.
- Śledzenie zmian: zaznacz, aby indeks automatycznie aktualizował zmienione elementy (Track changes).
Wielkość batcha cron: Możesz zmniejszyć tę wartość (np. do 5)
, aby uniknąć przeciążenia podczas jednorazowego indeksowania wielu elementów – domyślna wartość 50 może być zbyt duża dla Milvus, co wydłuża lub utrudnia indeksację dużej liczby dokumentów naraz.
- Zapisz konfigurację indeksu.
- Dodaj pola do indeksu – Po utworzeniu indeksu, wejdź w jego konfigurację pól (sekcja Fields indeksu). Musisz wskazać, które pola treści mają być embeddingowane i przeszukiwane wektorowo. Najważniejsze jest pełne pole z treścią:
Dodaj np. pole Rendered HTML output (rendered_item) lub główne pole tekstowe (np. Body/Zawartość) w zależności od tego, co oferuje interfejs. Często używa się wyrenderowanej zawartości z określonym trybem widoku (view mode) – na przykład w dokumentacji sugerowano użycie trybu widoku „Search index” dla pełnej zawartości artykułów i stron
. Chodzi o to, by do wektoryzacji pobrać pełny tekst, jaki ma być dostępny dla AI (bez zbędnych znaczników).
Dodatkowo dodaj pola kontekstowe, takie jak Title (tytuł), data utworzenia (Authored on), typ zawartości (Content type) itp.
. Te metadane mogą zostać dołączone do każdego fragmentu tekstu podczas generowania embeddingu, co pomaga modelowi rozumieć kontekst (np. tytuł dokumentu, datę) podczas generowania odpowiedzi
.
- Po dodaniu pól, zapisz ustawienia indeksu. Teraz indeks jest gotowy do działania.
Przeprowadź indeksowanie – Wykonaj indeksację zawartości do Milvus. Jeśli wybrałeś indeksowanie natychmiastowe, możesz po prostu zapisać/zmodyfikować istniejący węzeł lub dodać nowy, a system automatycznie go zindeksuje. Alternatywnie, użyj akcji Indeksuj teraz (Re-index) dostępnej w konfiguracji indeksu Search API, aby zaindeksować wszystkie istniejące treści od razu. Podczas indeksowania moduł AI Search dzieli dłuższe treści na mniejsze chunki (fragmenty) i dla każdego generuje wektor embedding za pomocą OpenAI, po czym zapisuje te wektory w Milvus
. Po zakończeniu tego procesu Twoja baza Milvus powinna zawierać wektory reprezentujące zawartość strony.
Konfiguracja asystenta AI (chatbota) z wykorzystaniem Milvus (RAG) – Gdy treści są już zindeksowane wektorowo, skonfiguruj Asystenta AI, aby korzystał z tej bazy wiedzy przy generowaniu odpowiedzi (tj. żeby stosował technikę RAG). Wykonaj następujące kroki:
- Przejdź do Konfiguracja > AI > AI Assistants (Asystenci AI) i dodaj nowego asystenta (przycisk Add AI Assistant). Wypełnij podstawowe pola:
- Label (Etykieta): nazwa asystenta, np. "Chatbot RAG".
- Description (Opis): opcjonalnie krótki opis, np. "Asystent AI z dostępem do bazy wiedzy strony (Milvus)".
- Prompt (Prompt początkowy): kontekst roli i zadania asystenta. Domyślnie asystent jest tworzony z myślą o RAG, więc może zawierać instrukcje typu "You are an assistant that uses a vector database to answer questions about the site's content..." – dostosuj to do swoich potrzeb językowych (możesz wpisać po polsku np. "Jesteś asystentem pomagającym użytkownikom, korzystającym z wiedzy zawartej w bazie danych strony.").
- Assistant message (Wiadomość asystenta): ewentualnie ustaw domyślną wiadomość/ton wypowiedzi asystenta. Możesz pozostawić domyślne lub sformułować własne wytyczne co do stylu odpowiedzi (np. prośbę o zwięzłe odpowiedzi z ewentualnym formatowaniem).
- Włączenie trybu RAG (Retrieval-Augmented Generation): Aby asystent faktycznie korzystał z Milvus, musisz włączyć w nim akcję wyszukiwania wektorowego:
Znajdź opcję Enable Agent Actions lub podobną (umożliwiającą korzystanie z akcji AI). Zaznacz ją, aby można było skonfigurować akcje dostępne dla asystenta
.
Po włączeniu akcji, powinieneś zobaczyć listę dostępnych Agent Actions (akcji agenta) lub ustawienia dotyczące RAG. W tej liście włącz akcję RAG (może się nazywać np. "RAG Search" albo "Embedding Search")
. To właśnie ta opcja pozwoli asystentowi automatycznie przeszukiwać Twoją bazę wektorową. (Technicznie rzecz biorąc, asystent podczas rozmowy użyje tej akcji, aby znaleźć pasujące fragmenty treści w Milvus i dołączyć je jako kontekst do pytania wysyłanego do modelu językowego
).
- Ustaw parametry wyszukiwania, jeśli są udostępnione: np. liczbę wyników do pobrania albo próg trafności (relevance score threshold). Próg trafności decyduje, czy znalezione fragmenty są wystarczająco dopasowane, by je użyć – jeśli ustawisz zbyt wysoki, asystent może czasem nie znaleźć nic i zignorować bazę wiedzy. Na początek ustaw dość niski próg lub zostaw domyślny, aby maksymalnie korzystać z danych (później ewentualnie dostosujesz ten próg doświadczalnie). Z kolei liczba wyników (np. 3–5 fragmentów) określi, ile kawałków tekstu z bazy zostanie dołączone do promptu dla modelu AI.
- Zapisz konfigurację asystenta.
- Upewnienie się, że chatbox korzysta z odpowiedniego asystenta – Moduł AI Chatbot udostępnia blok lub widżet czatu, który należy powiązać z utworzonym asystentem:
Wejdź w Struktura > Bloki (Block layout) i znajdź blok AI Chatbot (może być dostępny po włączeniu podmodułu AI Chatbot). Dodaj ten blok do odpowiedniego regionu na stronie (np. Footer lub jako wyskakujące okno czatu). W konfiguracji bloku wybierz, którego asystenta ma używać – wybierz swojego nowo utworzonego asystenta RAG (o ile jest więcej niż jeden; jeśli to jedyny asystent, będzie domyślny)
.
- Zapisz rozmieszczenie bloku. Teraz na stronie powinna być dostępna interakcja z chatbotem (np. jako ikona czatu w rogu strony lub blok w wybranym miejscu).
Sprawdzenie integracji – Od tego momentu Twój chatbox będzie korzystał z asystenta, który ma dostęp do bazy Milvus. Oznacza to, że gdy użytkownik zada pytanie, asystent najpierw wykona wektorowe wyszukiwanie w Milvus, aby znaleźć powiązane informacje, a następnie przekaże pytanie wraz z tymi kontekstowymi danymi do modelu językowego (np. OpenAI GPT) w celu wygenerowania odpowiedzi
. Dzięki temu odpowiedzi powinny uwzględniać fakty z Twojej bazy wiedzy (treści Drupal), czyli asystent będzie działał w trybie RAG.
- Przejdź do Konfiguracja > AI > AI Assistants (Asystenci AI) i dodaj nowego asystenta (przycisk Add AI Assistant). Wypełnij podstawowe pola:
3. Obsługa embedowania (embeddingów)
Wykorzystanie OpenAI do generowania embeddingów – Moduł AI w Drupal umożliwia podłączenie różnych dostawców AI. W naszym przypadku używamy OpenAI do generowania wektorowych reprezentacji tekstu (embeddingów). Upewnij się, że:
Masz zainstalowany i włączony podmoduł OpenAI Provider (część modułu AI; często nazywa się
provider_openai). Jeśli korzystałeś z komendy Composer podanej wcześniej do instalacji modułu AI, powinna ona automatycznie zainstalować obsługę OpenAI
– trzeba tylko włączyć odpowiedni moduł.
- Skonfiguruj klucz API OpenAI: przejdź do Konfiguracja > AI > Providers > OpenAI (lub Klucze API, jeśli używasz modułu Key). Wpisz swój klucz API OpenAI i zapisz konfigurację. (Moduł AI korzysta z modułu Key do przechowywania kluczy – możesz utworzyć nowy klucz typu "OpenAI API Key" i wpisać tam swój sekret, a następnie w ustawieniach OpenAI Provider wskazać ten klucz). Poprawne ustawienie klucza jest niezbędne, by Drupal mógł komunikować się z usługą OpenAI.
Po konfiguracji klucza, moduł AI zazwyczaj automatycznie ustawia OpenAI jako domyślnego dostawcę do różnych zadań AI
. Możesz to zweryfikować w Konfiguracja > AI > Ustawienia – powinna tam być informacja o domyślnym dostawcy dla zadań typu generowanie tekstu, embedding itp. (OpenAI powinien widnieć jako dostawca embeddingów, o ile nic nie zmieniałeś).
W konfiguracji serwera AI Search (utworzonej w poprzedniej sekcji) wybrałeś OpenAI jako silnik embeddingów oraz odpowiedni model
. Na podstawie tego ustawienia moduł AI będzie wiedział, że ma użyć API OpenAI do wygenerowania wektora dla każdego fragmentu tekstu podczas indeksowania.
Generowanie embeddingów dla danych w Milvus – Po powyższej konfiguracji proces tworzenia embeddingów jest automatyczny:
- Gdy uruchamiasz indeksowanie treści (czy to masowo, czy pojedynczo przy zapisie węzła), moduł AI Search dla każdego indeksowanego elementu pobiera wybrane pola (np. pełny tekst artykułu, tytuł, itp.) i wysyła je do modelu OpenAI w celu uzyskania wektorowej reprezentacji (embeddingu). Dzieje się to w tle za pomocą API OpenAI – Drupal wysyła żądanie z tekstem, a OpenAI zwraca ciąg liczbowy (wektor).
- Otrzymany wektor zostaje zapisany w bazie Milvus jako część kolekcji (pod ustaloną nazwą). Innymi słowy, dla każdego dokumentu/fragmentu treści powstaje odpowiadający mu wektor w Milvus, umożliwiający późniejsze podobieństwowe wyszukiwanie.
Nie musisz ręcznie wywoływać OpenAI dla każdego artykułu – moduł robi to sam w trakcie indeksowania. Upewnij się tylko, że masz wystarczające środki na koncie OpenAI (embeddingi również kosztują, choć zazwyczaj są tańsze niż generowanie tekstu) i że ewentualnie ustawiłeś limit wykorzystania, by kontrolować koszty. W razie potrzeby możesz monitorować wykorzystanie tokenów na koncie OpenAI
.
Weryfikacja poprawności embeddingów: Po zaindeksowaniu, w tabeli
search_api_index(lub dedykowanej dla AI Search) w Drupalu powinny pojawić się odnośniki do wektorów (czasem moduł może też przechowywać embeddingi w bazie danych Drupala dla porównania, ale głównym źródłem prawdy jest Milvus). Możesz spróbować wykonać zapytanie wektorowe niezależnie (np. używając klienta Milvus lub poprzez moduł AI Explorer jeśli oferuje funkcję wyszukiwania) aby sprawdzić, czy Milvus zwraca sensowne wyniki dla znanych fraz – to potwierdzi, że embeddingi zostały prawidłowo wygenerowane przez OpenAI i zapisane.
Automatyczne zapisywanie embeddingów przy dodawaniu nowych danych – Aby nowe lub edytowane treści automatycznie trafiały do bazy wektorowej:
Skorzystaj z opcji automatycznej indeksacji w Search API. Jak wspomniano wyżej, ustawiliśmy Index items immediately (indeksuj natychmiast) dla indeksu – dzięki temu każdorazowo przy stworzeniu lub edycji węzła system wywoła proces aktualizacji indeksu
. To znaczy, że po zapisaniu np. nowego artykułu:
- Drupal przetworzy treść artykułu (podzieli na fragmenty, dołączy kontekst typu tytuł itp.).
- Dla każdego fragmentu wywoła API OpenAI w celu uzyskania embeddingu.
- Zaktualizuje kolekcję Milvus, dodając nowe wektory (lub aktualizując istniejące, jeśli edytowano treść).
- Upewnij się, że śledzenie zmian (Track changes) jest włączone dla indeksu – co już zrobiliśmy. To zapewnia, że zmiana lub usunięcie treści również odzwierciedli się w indeksie (np. jeśli usuniesz węzeł, moduł powinien usunąć powiązane wektory z Milvus).
- Weryfikacja: Przetestuj dodanie nowej treści (np. stwórz testową stronę z unikalnym tekstem) i zapisz ją. Następnie zadaj asystentowi pytanie o tę treść. Jeśli konfiguracja działa, asystent powinien natychmiast mieć dostęp do nowej informacji (dzięki świeżo dodanemu embeddingowi w Milvus) i uwzględnić ją w odpowiedzi. Jeśli odpowiedź ignoruje nową treść, sprawdź, czy indeks się zaktualizował (w panelu Search API indeks powinien mieć zwiększoną liczbę zindeksowanych elementów).
Ręczna reindeksacja: W razie gdybyś importował dużo treści jednocześnie lub zmienił ustawienia indeksu, możesz użyć opcji Reindeksuj wszystko. Spowoduje to ponowne wygenerowanie embeddingów (uwaga: może to wygenerować duży koszt, jeśli treści jest dużo, ponieważ ponownie użyje API OpenAI dla każdego fragmentu). W idealnym scenariuszu moduł powinien zastępować stare embeddingi nowymi, choć obecnie w wersji testowej zdarzało się, że duplikował fragmenty przy ponownej indeksacji zamiast je zastąpić
. Dlatego lepiej starać się unikać wielokrotnej pełnej reindeksacji tych samych danych, dopóki moduł jest w fazie beta.
4. Wykorzystanie modułu AI Agents (zarządzanie asystentem i workflow)
Moduł AI Agents nie jest bezwzględnie wymagany do realizacji prostego scenariusza RAG, ale może być przydatny, jeśli chcesz rozszerzyć możliwości asystenta. W kontekście naszego chatbota AI, AI Agents pełni rolę dostarczyciela „akcji” dla asystenta – są to zadania/operacje, które asystent może wykonać, by obsłużyć zapytanie użytkownika. Wśród takich akcji może być np. wyszukiwanie wektorowe (RAG), ale też inne czynności (np. tworzenie treści w witrynie, manipulacja konfiguracją Drupala, itp.)
. Poniżej omówiono, jak wykorzystać ten moduł w kontekście RAG:
Instalacja/aktywacja AI Agents – Jeśli jeszcze tego nie zrobiłeś, zainstaluj i włącz moduł AI Agents (
drupal/ai_agents). Wcześniej w sekcji instalacji mogliśmy go uwzględnić (jest on często instalowany razem z głównym modułem AI). AI Agents składa się z kilku podmodułów, w tym m.in. AI Assistant API i zestawu predefiniowanych agentów. Włącz te moduły zgodnie z potrzebami (np.drush en ai_agents ai_assistant_apiitd., część z nich mogła się włączyć automatycznie przy tworzeniu asystenta).Konfiguracja dostępnych akcji (Agents) dla asystenta – Edytuj konfigurację swojego asystenta AI (Configuration > AI > AI Assistants > edytuj danego asystenta). Powinieneś widzieć opcję Enable Agent Actions (jeśli nie była już zaznaczona). Upewnij się, że jest włączona, co pozwoli asystentowi korzystać z zarejestrowanych agentów. Następnie na liście akcji dostępnych dla asystenta zaznacz te, które chcesz wykorzystać. Dla naszego przypadku kluczowa jest akcja związana z wyszukiwaniem informacji w wektorowej bazie wiedzy:
RAG Search / Vector Search – ta akcja może figurować jako domyślna część asystenta lub jako jeden z agentów. Upewnij się, że jest włączona
. Dzięki temu asystent wie, że ma prawo użyć wyszukiwania wektorowego w ramach obsługi zapytania.
- Inne akcje (opcjonalnie): AI Agents dostarcza też inne „narzędzia”, np. agent do wykonania zapytań do bazy danych Drupal, agent do tworzenia widoków, edycji pól itd. (one są przydatne w scenariuszach administracyjnych, niekoniecznie w prostym Q&A). Możesz je zostawić wyłączone, jeśli Twoim celem jest wyłącznie chatbot udzielający odpowiedzi na podstawie treści (ograniczony do RAG). Włączenie zbędnych agentów może spowodować, że asystent będzie próbował wykonywać niepotrzebne akcje lub będzie miał zbyt szerokie możliwości.
- Zapisz konfigurację asystenta po dokonaniu zmian w agentach.
Zarządzanie workflow asystenta (przepływ rozmowy) – Po włączeniu odpowiednich agentów (w szczególności RAG) nie musisz ręcznie definiować kolejności ich wywołania – moduł AI sam zarządza tym, jak asystent wykorzystuje akcje. W praktyce, gdy użytkownik zada pytanie:
- Asystent najpierw sprawdzi, jakie akcje ma do dyspozycji. Ponieważ daliśmy mu akcję RAG, najpierw ją zastosuje, aby znaleźć kontekst w Milvus (chyba że pytanie tego nie wymaga, ale zazwyczaj przy każdym pytaniu tekstowym spróbuje).
Workflow RAG: Asystent formułuje tzw. Pre Action Prompt – jest to wewnętrzna instrukcja dla modelu, by wykorzystał wyniki wyszukiwania. Domyślna konfiguracja asystenta (jeśli nie zmieniałeś promptów zaawansowanych) już zakłada tryb RAG
. Oznacza to, że asystent przed wygenerowaniem odpowiedzi automatycznie dokona wyszukiwania i dołączy wyniki do promptu przekazywanego do modelu językowego.
Następnie asystent otrzymuje od Milvus znalezione fragmenty, przekazuje je (w ukrytym systemowym promptcie) do modelu OpenAI wraz z pytaniem użytkownika, a model generuje finalną odpowiedź uwzględniając dostarczony kontekst. W ten sposób workflow chatbota z RAG przebiega end-to-end: użytkownik pyta → agent RAG przeszukuje Milvus → model AI odpowiada na podstawie znalezionych treści + własnej wiedzy
.
Jeśli masz potrzebę dalszego dostosowania tego przepływu, możesz edytować zaawansowane ustawienia asystenta. Ustawienie Pre-action prompt (widoczne po włączeniu trybu zaawansowanego w konfiguracji asystenta, poprzez np. dodanie
$settings['ai_assistant_advanced_mode_enabled'] = TRUE;w settings.php) pozwala określić dokładne instrukcje dla modelu, jak ma łączyć wiedzę z RAG z generowaniem odpowiedzi. Standardowo jednak nie musisz tego zmieniać – domyślny prompt dobrze opisuje zadanie (np. informuje AI, że może korzystać z dostarczonych informacji z bazy wiedzy).
- AI Agents a RAG: Warto zauważyć, że w przypadku prostego chatbota Q&A z RAG rola AI Agents sprowadza się głównie do udostępnienia akcji wyszukiwania. Cały proces odbywa się automatycznie w ramach asystenta. Możesz oczywiście rozbudować go o inne akcje – np. jeśli chcesz, by asystent nie tylko odpowiadał, ale też wykonał jakieś operacje (jak stworzenie nowego wpisu w oparciu o odpowiedź – to już bardziej skomplikowany scenariusz wymagający dodatkowych agentów i odpowiedniego promptu).
- Podsumowując: można wykorzystać moduł AI Agents do zarządzania asystentem AI w kontekście RAG, ale nie wymaga to skomplikowanej konfiguracji – wystarczy upewnić się, że akcja RAG (wyszukiwanie wektorowe) jest aktywna i dostępna dla asystenta. Reszta (czyli pobieranie odpowiedzi z Milvus i ich użycie) odbywa się zgodnie z wewnętrzną logiką modułu AI.
5. Testowanie i debugowanie
Testowanie działania chatbota z RAG – Po dokonaniu powyższych konfiguracji przyszedł czas na przetestowanie, czy całość działa prawidłowo:
- Zadawanie pytań: Wejdź na stronę zawierającą chatbox (np. strona frontowa, jeśli tam umieściłeś blok, lub panel administracyjny – zależnie od konfiguracji) i zadaj asystentowi pytanie związane z zawartością Twojej strony. Dobrym testem jest pytanie o konkretną informację, która jest zawarta w treści strony, np. tytuł artykułu, fragment zdania ze strony lub pytanie, na które odpowiedź znajduje się w jednym z węzłów.
- Ocena odpowiedzi: Sprawdź, czy odpowiedź udzielona przez chatbota zawiera oczekiwane informacje. Jeśli chatbot rzeczywiście korzysta z RAG, powinien przytoczyć fakty lub dane z Twoich treści. Na przykład, jeśli zapytałeś o szczegół z jakiegoś artykułu, w odpowiedzi powinna pojawić się ta informacja (czasem model może ją sparafrazować). Jeśli odpowiedź jest całkowicie ogólna lub odbiega od zawartości strony, może to oznaczać, że RAG nie zadziałał (asystent oparł się wyłącznie na własnej wiedzy modelu AI). W poprawnie działającym scenariuszu RAG asystent łączy wiedzę z bazy (Milvus) z możliwościami językowymi modelu, dając odpowiedź rzeczową na podstawie Twoich danych.
- Przykładowy test: Jeśli Twoja strona ma np. artykuł o historii firmy, spróbuj zapytać "Kiedy powstała nasza firma?" – jeśli ten fakt jest w artykule, asystent powinien go podać. Jeżeli to zrobi, oznacza to, że przeszukał wektory, znalazł zdanie z datą założenia i ujął je w odpowiedzi. Jeżeli poda jakąś losową datę, to znak, że prawdopodobnie nie skorzystał z bazy (być może wystąpił problem z integracją).
Wykorzystanie AI Search w interfejsie: Dodatkowo, możesz przetestować sam mechanizm wyszukiwania wektorowego niezależnie od chatbota. Na przykład, utwórz tymczasowo Widok (View) oparty na swoim indeksie Search API (treści) i dodaj pole wyszukiwania pełnotekstowego
. Gdy wpiszesz tam zapytanie (słowa kluczowe lub zdanie), wyniki powinny pokazywać najbardziej pasujące węzły. To pomoże zweryfikować, czy indeks wektorowy działa poprawnie – jeśli tu nie otrzymujesz wyników dla oczywistych zapytań, to chatbot też ich nie znajdzie. Pamiętaj, że wyszukiwanie wektorowe działa na podobieństwie znaczeniowym, więc spróbuj różnych sformułowań.
- AI Explorer: Jeśli masz włączony moduł AI Explorer (część AI), możesz również skorzystać z sekcji AI Search w eksploratorze (o ile jest dostępna w danej wersji modułu). Pozwala ona zadawać pytania LLM-owi z wykorzystaniem wybranej bazy wektorowej w tle, co jest właściwie tym samym, co robi nasz asystent. To może pomóc w testach – z poziomu admina sprawdzisz, czy np. dla danego pytania zwracane są fragmenty z bazy (czasem eksplorator pokazuje też surowe wyniki wyszukiwania).
Debugowanie typowych problemów – Jeśli chatbot nie działa zgodnie z oczekiwaniami, oto kroki i wskazówki do diagnozy:
- Brak wyników z Milvus w odpowiedzi (chatbot ignoruje bazę):
- Upewnij się, że akcja RAG jest włączona dla asystenta. To podstawowy punkt – bez tego asystent nawet nie spróbuje szukać w Milvus.
- Sprawdź próg trafności (score threshold), jeśli go ustawiłeś. Zbyt wysoki próg może spowodować, że żaden fragment nie zostanie uznany za wystarczająco podobny i asystent pominie bazę. Dla testów możesz ustawić niższy próg lub wyłączyć filtrowanie po skorelowaniu.
- Zawartość indeksu: Zweryfikuj, czy indeks wektorowy faktycznie zawiera dane:
- Przejdź do Konfiguracja > Wyszukiwanie i metadane > Search API i sprawdź status indeksu (powinna być informacja ile elementów jest zindeksowanych). Jeśli liczba wynosi 0 lub jest bardzo niska w porównaniu do liczby węzłów, to znaczy, że indeksowanie nie zostało wykonane poprawnie. W takim wypadku spróbuj ręcznie uruchomić indeksowanie (lub zapisz kilka węzłów ponownie) i obserwuj, czy liczba rośnie.
- Jeśli liczba elementów wygląda poprawnie, spróbuj użyć wspomnianego widoku testowego lub funkcji podglądu wyników w Search API – wpisz frazę i zobacz, czy zwraca trafienia. Brak trafień sugeruje, że embeddingi mogły zostać nieprawidłowo wygenerowane lub treść w indeksie nie pokrywa zapytania (np. zapytanie dotyczy treści, której nie zindeksowano z powodu konfiguracji pól).
- Upewnij się, że pola w indeksie zostały poprawnie ustawione. Jeśli np. pominąłeś główne pole z treścią, indeks może zawierać tylko tytuły i daty, co utrudnia znalezienie czegokolwiek na pytania o zawartość. W razie potrzeby dodaj brakujące pole i zreindeksuj.
Klucz OpenAI i limity: Sprawdź, czy Twoje połączenie z OpenAI działa. Jeśli embeddingi nie zostały w ogóle wygenerowane (co wykazałby pusty indeks), możliwe że wystąpił problem z API OpenAI (np. nieprawidłowy klucz lub brak środków). Zajrzyj do logów Drupala (Raporty) – błędy typu Forbidden lub Unauthorized podczas prób komunikacji z OpenAI wskażą na problem z autoryzacją
. Upewnij się, że klucz jest poprawny, aktywny i że masz środki/prawidłowo ustawione rozliczenie w OpenAI (dla nowych kont OpenAI konieczne jest podpięcie karty i aktywne środki, inaczej API zwraca błąd nawet przy poprawnym kluczu).
- Błędy przy zapisie/pobieraniu z Milvus: Jeśli w logach widzisz błędy związane z Milvus (np. nie może utworzyć kolekcji, problemy z połączeniem), zweryfikuj konfigurację połączenia (host/port, nazwa bazy, itp.). Możesz też spróbować podłączyć się do Milvus za pomocą innego klienta (np. skryptem Python z biblioteką PyMilvus) używając tych samych danych – aby potwierdzić, że Milvus odpowiada i np. że kolekcja istnieje.
Błąd tylko dla określonych użytkowników: Jeśli zauważysz, że chatbot działa poprawnie jako administrator, ale nie zwraca wyników dla użytkownika anonimowego lub z ograniczeniami, przyczyną może być ustawienie kontroli dostępu RAG. Moduł AI ma opcję sprawdzania uprawnień do treści przy pobieraniu fragmentów (tzw. RAG access checks). W obecnej wersji zgłoszono błąd, że włączenie tej opcji powoduje brak wyników dla użytkowników nie-adminów
(prawdopodobnie wszystkie wyniki są odfiltrowane lub zwracany jest błąd dostępu). Jeśli testujesz jako niezalogowany i nic nie dostajesz, spróbuj wyłączyć tymczasowo kontrolę dostępu RAG w ustawieniach asystenta (jeśli była włączona). Oczywiście docelowo chciałbyś respektować uprawnienia (aby np. chatbot nie ujawniał treści niepublicznych), ale na razie, dopóki problem nie zostanie rozwiązany w module, lepiej tę opcję wyłączyć, by w ogóle zweryfikować działanie RAG.
Sprawdzenie logiki promptu: Czasem asystent może nie użyć poprawnie informacji z bazy z powodu niefortunnej treści promptu systemowego lub asystenta. Jeśli jesteś zaawansowanym użytkownikiem, zajrzyj do ustawień Pre-action prompt i Assistant prompt – czy nie ma tam czegoś, co mogłoby ograniczać wykorzystanie znalezionych danych. Domyślnie nie powinno, ale jeśli zmieniałeś te wartości, rozważ przywrócenie ich do domyślnych (można podejrzeć domyślny prompt w pliku
pre_action_prompt.txtmodułu ai_agents).
- Monitorowanie procesu: Włącz moduł AI Logging (jeśli dostępny) lub debugging, aby śledzić co się dzieje podczas interakcji. AI Logging może logować zapytania wysyłane do modelu i otrzymywane odpowiedzi. To pomoże sprawdzić, czy w system prompt przy wysyłaniu pytania do OpenAI pojawiły się fragmenty z bazy (powinny być dołączone jako część kontekstu). Jeżeli log pokaże, że faktycznie fragmenty zostały wysłane do modelu, a mimo to odpowiedź z nich nie korzysta – to może być kwestia samego modelu (np. zignorował kontekst). Wtedy można pokombinować z promptem, np. wyraźniej nakazać modelowi użycie dostarczonych informacji.
- Aktualizacje modułów: Ponieważ moduł AI i integracje RAG są wciąż dość świeże (wersje alpha/beta), upewnij się, że korzystasz z najnowszej dostępnej wersji. W changelogach często pojawiają się poprawki do obsługi Milvus czy RAG. Zajrzyj na stronę projektu Drupal AI i Milvus VDB Provider, czy nie ma nowszej wersji lub znanych bugów podobnych do Twojego przypadku.
- Społeczność i dokumentacja: Jeśli problem jest trudny do zdiagnozowania, sprawdź issue queue modułu AI na Drupal.org – być może ktoś już zgłosił podobny problem (np. błędy z Milvus, problemy z embeddingami, itp.). Możesz również zadać pytanie na forum Drupal (np. Drupal Slack, drupal.stackexchange lub w sekcji komentarzy modułu) opisując swoją konfigurację – społeczność pracująca nad tymi narzędziami jest dość aktywna. Czasem rozwiązaniem może być drobna zmiana konfiguracji bądź zastosowanie patcha z najnowszego commita.
- Brak wyników z Milvus w odpowiedzi (chatbot ignoruje bazę):
Na koniec, gdy uda Ci się skonfigurować całość poprawnie, będziesz mieć działający chatbot AI w Drupal 11, który wykorzystuje RAG z bazą wektorową Milvus. Taki asystent będzie odpowiadał na pytania użytkowników, bazując na treściach Twojej strony (co znacząco zmniejsza ryzyko tzw. halucynacji modelu i zwiększa trafność odpowiedzi)
. Powodzenia w implementacji!