LangChain.js i Oracle AI Database: przewodnik po wyszukiwaniu wektorowym
Połącz LangChain.js z Oracle AI Database przy użyciu OracleVS, zapisuj osadzenia z metadanymi i porównaj wyszukiwanie podobieństwa, filtry metadanych oraz MMR w TypeScript.
Model językowy potrafi odpowiadać na ogólne pytania, ale nie będzie wiarygodnie odwoływał się do prywatnej bazy wiedzy, jeśli aplikacja najpierw nie pobierze odpowiednich informacji. Dla programistów JavaScript LangChain.js oferuje znajome abstrakcje dla dokumentów, osadzeń i mechanizmów wyszukiwania. Brakującym elementem jest trwałe miejsce do przechowywania i przeszukiwania powstałych wektorów.
Oracle AI Database wypełnia tę rolę dzięki integracji @oracle/langchain-oracledb. W tym przewodniku połączysz niewielki przepływ pracy w TypeScript z Oracle, zapiszesz tekst z metadanymi, uruchomisz wyszukiwanie podobieństwa i ulepszysz wyniki za pomocą filtrów oraz Maximal Marginal Relevance (MMR). Tutorial koncentruje się na przepływie wyszukiwania; towarzysząca aplikacja TypeScript dodaje tę samą integrację do interfejsu przeglądarkowego.
Na czym polega integracja LangChain.js i Oracle AI Database?
LangChain.js standaryzuje sposób pracy aplikacji z modelami osadzeń i magazynami wektorów. Pakiet integracyjny Oracle dostarcza OracleVS — implementację vector store, która zapisuje tekst dokumentów, metadane i wektorowe osadzenia w Oracle AI Database. Twoja aplikacja wywołuje metody LangChain.js zamiast ręcznie pisać SQL dla każdego zapytania podobieństwa.
Ten sam pakiet integracyjny obejmuje również OracleDocLoader, OracleTextSplitter, OracleEmbeddings i OracleSummary. To przydatne, opcjonalne klocki; poniższy przykład skupia się na OracleVS i pozostawia generowanie osadzeń osobno, aby przepływ pozostał łatwy do zrozumienia.
Ingestowanie dokumentów i wyszukiwanie z użyciem LangChain.js, OracleVS i Oracle AI Database
Kluczowe możliwości integracji
Przechowuj osadzenia razem z metadanymi dokumentów
Model osadzeń zamienia tekst na wektory liczbowe. OracleVS zapisuje te wektory wraz z tekstem źródłowym i ustrukturyzowanymi metadanymi. Metadane, takie jak kategoria dokumentu czy źródło, pomagają aplikacji zawężać wyszukiwania bez utraty przydatnego kontekstu.
Odzyskuj trafne fragmenty dzięki podobieństwu wektorowemu
W czasie zapytania ten sam model osadzeń konwertuje pytanie na wektor. Oracle porównuje go z zapisanymi wektorami, używając skonfigurowanej metryki odległości, np. cosinusowej, i zwraca najbliższe dokumenty. Wyniki pozostają obiektami Document LangChain, gotowymi do dalszego przetwarzania.
Kontroluj wyniki za pomocą filtrów i MMR
Wyszukiwanie podobieństwa odpowiada na pytanie „które elementy są najbliżej tego pytania?”. Filtr metadanych zawęża pulę kwalifikujących się dokumentów. MMR dodaje inny cel: utrzymać trafność wybranych fragmentów, jednocześnie redukując niemal duplikaty. To operacje komplementarne, a nie wymienne.
Pierwsze kroki z LangChain.js i Oracle AI Database
Wymagania wstępne
Do tego przykładu w TypeScript potrzebujesz Node.js 24.13.0, npm 11.6.2, lokalnej instancji Oracle AI Database 26ai Free z obsługą wektorów oraz schematu, który może tworzyć, wstawiać, odpytywać i usuwać tabelę demonstracyjną oraz jej indeks wektorowy. Potrzebujesz też klucza API OpenAI do przykładu z osadzeniami. OpenAIEmbeddings to zgodny z LangChain wybór, a nie wymóg OracleVS.
Dla podstawowej lokalnej ścieżki postępuj zgodnie z krótkim przewodnikiem Oracle AI Database Free. Po uruchomieniu bazy użyj usługi takiej jak localhost:1521/FREEPDB1 oraz schematu z uprawnieniami wymienionymi powyżej.
Utwórz w tym folderze plik o nazwie index.ts. Dodaj do niego wykonywalne fragmenty TypeScript poniżej, w podanej kolejności. Nie twórz osobnego pliku dla każdego fragmentu. Skopiuj tylko wykonywalne fragmenty TypeScript: bloki SQL i reprezentatywne wyniki są przykładami objaśniającymi i nie powinny być wklejane do index.ts.
Ustawienie type=module w package.json pozwala na użycie await na najwyższym poziomie w przykładach. Konfigurację pakietów Node.js opisano w oficjalnym przewodniku po pakietach Node.js.
Pakiet integracyjny Oracle implementuje vector store, @langchain/core dostarcza Document, @langchain/openai dostarcza przykładowy model osadzeń, a oracledb zarządza połączeniem z bazą. Powyższe wersje odpowiadają aplikacji towarzyszącej; tsx uruchamia przykład TypeScript bez osobnego kroku budowania.
Skonfiguruj połączenie
ORACLE_USER=your_schema
ORACLE_PASSWORD=your_password
ORACLE_CONNECT_STRING=localhost:1521/FREEPDB1
OPENAI_API_KEY=your_api_keyObsługiwane przez
Zapisz te wartości w lokalnym pliku .env i dodaj .env do .gitignore. W tym artykule podstawową konfiguracją jest lokalna Oracle AI Database Free, aby kroki były odtwarzalne. Autonomous AI Database to prawidłowa alternatywa wdrożeniowa, ale wymaga deskryptora usługi oraz konfiguracji portfela lub TLS dla tego środowiska.
Pula pozwala OracleVS ponownie wykorzystywać sesje bazy danych. Umieść wszystkie instrukcje dotyczące ingestowania, wyszukiwania i weryfikacji wewnątrz bloku try. Następny blok kodu rozpoczyna ten blok, a kolejne fragmenty go kontynuują. Pula jest zamykana dopiero po weryfikacji w sekcji sprzątania poniżej. W aplikacji serwerowej zainicjalizuj pulę raz i zamknij ją podczas łagodnego wyłączania, zamiast otwierać nowe połączenie dla każdego żądania użytkownika.
Jak zbudować wyszukiwanie dokumentów z LangChain.js
Użyjemy 10 krótkich notatek z bazy wiedzy, w tym zachodzących na siebie fragmentów. Korpus jest celowo mały, ale pozwala porównać zwykłe wyszukiwanie podobieństwa z filtrowaniem metadanych i MMR.
Zdefiniuj dokumenty wiedzy
try{const documents =[["database-guide","database","Oracle AI Database stores vector embeddings alongside application data."],["connection-pooling","operations","A connection pool reuses Oracle database sessions across requests."],["vector-indexes","performance","HNSW vector indexes can improve nearest-neighbor search as a table grows."],["metadata-filtering","retrieval","Metadata filters restrict retrieval to matching categories or sources."],["similarity-search","retrieval","Similarity search returns chunks closest to the query embedding."],["mmr-retrieval","retrieval","MMR reduces repeated content while keeping results relevant."],["retrieval-overlap-1","retrieval","Similarity search may return several near-duplicate passages when multiple notes explain the same retrieval strategy."],["retrieval-overlap-2","retrieval","Several notes about the same retrieval strategy can produce repetitive top matches; MMR selects a more diverse set while preserving relevance."],["troubleshooting","troubleshooting","For empty results, check ingestion, embeddings, and filters."],["embedding-compatibility","retrieval","Ingestion and query retrieval must use compatible dimensions."],].map(([source, category, pageContent])=>newDocument({ pageContent, metadata:{ source, category }}));Obsługiwane przez
Każdy Document ma pageContent i metadata. Pola source i category towarzyszą dokumentowi podczas ingestowania i wyszukiwania, dzięki czemu aplikacja może wyjaśnić pochodzenie wyniku i zawęzić wyszukiwanie do odpowiedniego podzbioru.
Skonfiguruj osadzenia i utwórz OracleVS
const embeddings =newOpenAIEmbeddings({
model:"text-embedding-3-small",});const vectorStore =await OracleVS.fromDocuments(documents, embeddings,{
client: pool,
tableName:"LC_JS_RAG_DEMO",
query:"Oracle AI Database document search",
distanceStrategy: DistanceStrategy.COSINE,
format: VectorElementFormat.FLOAT32,});Obsługiwane przez
OracleVS.fromDocuments() to kluczowe wywołanie integracji. Inicjalizuje vector store, generuje osadzenia dla dostarczonych dokumentów i zapisuje ich treść, wektory oraz metadane w Oracle AI Database.
Parametr query dostarcza przykładowy tekst osadzany podczas inicjalizacji w celu określenia wymiaru wektora wymaganego przez tabelę w bazie. Nie służy do przeszukiwania zapisanych dokumentów. DistanceStrategy.COSINE określa metrykę odległości wektorów, a VectorElementFormat.FLOAT32 ustawia format elementów wektora.
Przed ponownym uruchomieniem ingestowania użyj nowej nazwy tabeli demonstracyjnej lub wyczyść istniejące dane, aby uniknąć duplikatów dokumentów.
OracleVS akceptuje implementację osadzeń zgodną z LangChain, więc programiści mogą zmieniać dostawców osadzeń bez modyfikacji ogólnego przepływu vector store. Jednak osadzenia używane do ingestowania i wyszukiwania muszą pozostać zgodne z kolumną wektorową Oracle.
OracleVS określa wymiar wektora podczas inicjalizacji na podstawie skonfigurowanego modelu osadzeń. Aby sprawdzić wymiary i format przechowywania wektora już zapisanego w Oracle AI Database, uruchom następujące zapytanie SQL:
SELECT
VECTOR_DIMENSION_COUNT(embedding)AS vector_dimensions,
VECTOR_DIMENSION_FORMAT(embedding)AS vector_format
FROM LC_JS_RAG_DEMO
FETCHFIRST1ROW ONLY;Obsługiwane przez
Jeśli przełączysz się na model osadzeń o innym wymiarze, utwórz zgodną tabelę wektorową i wygeneruj osadzenia dokumentów ponownie. Nawet jeśli dwa modele tworzą wektory o tych samych wymiarach, ich przestrzenie osadzeń mogą się różnić, więc istniejące dokumenty należy ponownie osadzić przed użyciem nowego modelu do wyszukiwania.
Na przykład, poniższe wywołanie prosi vector store OracleVS o 3 najbliższe dokumenty i drukuje metadane źródła wraz z tekstem każdego fragmentu:
const retrievalQuestion ="How can vector retrieval reduce repetitive results?";const results =await vectorStore.similaritySearch(
retrievalQuestion,3);console.log(results.map((doc)=>({
source: doc.metadata.source,
text: doc.pageContent,})));Obsługiwane przez
Kod mapuje każdy Document LangChain na prosty obiekt zawierający jego source i pageContent do wyświetlenia. Poniżej przedstawiono reprezentatywny wynik; dokładna kolejność może się różnić w zależności od modelu osadzeń i zapytania:
[
{ source: "retrieval-overlap-2", text: "Several notes about the same retrieval strategy can produce repetitive top matches; MMR selects a more diverse set while preserving relevance." },
{ source: "retrieval-overlap-1", text: "Similarity search may return several near-duplicate passages when multiple notes explain the same retrieval strategy." },
{ source: "mmr-retrieval", text: "MMR reduces repeated content while keeping results relevant." }
]Obsługiwane przez
Pierwszy argument to pytanie użytkownika, a drugi to k, maksymalna liczba dokumentów do pobrania. LangChain.js używa skonfigurowanego modelu osadzeń, by zamienić pytanie na wektor, a Oracle AI Database przeprowadza wyszukiwanie podobieństwa, aby znaleźć najbliżej pasujące dokumenty.
Jeśli po zastosowaniu warunków wyszukiwania i filtrów metadanych dostępnych jest mniej niż k dokumentów, metoda zwróci tylko dostępne wyniki. Pobranie Document zawiera tekst i metadane, które można wyświetlić z atrybucją źródła lub przekazać do dalszego etapu generowania odpowiedzi.
Sprawdzaj wyniki wyszukiwania
Na przykład użyj similaritySearchWithScore, gdy chcesz sprawdzić odległość związaną z każdym pobranym dokumentem:
const scored =await vectorStore.similaritySearchWithScore("Where are document embeddings stored?",3);for(const[doc, score]of scored){console.log({
text: doc.pageContent,
source: doc.metadata.source,
score,});}Obsługiwane przez
similaritySearchWithScore zwraca odległość przy każdym dopasowaniu. Jej wartość liczbowa i kierunek zależą od wybranej metryki odległości, więc nie jest to uniwersalny procent pewności. Porównuj wyniki tylko przy tym samym modelu osadzeń i metryce oraz przejrzyj pobrany fragment przed wyborem progu.
Ogranicz wyniki filtrami metadanych
const databaseOnly =await vectorStore.similaritySearch("Where are vector embeddings stored?",3,{ category:{ $eq:"database"}});console.log(databaseOnly.map((doc)=> doc.metadata.source));Obsługiwane przez
Trzeci argument zawęża wyszukiwanie do elementów z category = database. W tym korpusie przewidywalnym wynikiem filtrowania jest ["database-guide"]. Filtr zmienia to, które dokumenty się kwalifikują; ranking wciąż opiera się na podobieństwie wektorowym.
Użyj MMR, aby zredukować powtarzalność wyników
const diverse =await vectorStore.maxMarginalRelevanceSearch(
retrievalQuestion,{
k:3,
fetchK:6,
lambda:0.5,});console.log(diverse.map((doc)=> doc.metadata.source));Obsługiwane przez
Reprezentatywny wynik dla nakładającego się korpusu (kolejność może się różnić w zależności od modeli osadzeń i uruchomień):
["retrieval-overlap-2", "mmr-retrieval", "metadata-filtering"]Obsługiwane przez
MMR najpierw rozważa pulę kandydatów (fetchK), a następnie wybiera k dokumentów, równoważąc trafność zapytania z różnorodnością. Niższe lambda silniej akcentuje różnorodność; wyższe — trafność. Przy powyższym, nakładającym się korpusie, wybrane źródła mogą różnić się od zwykłego wyszukiwania podobieństwa, co uwidacznia kompromis w wyszukiwaniu.
To punkt przekazania między wyszukiwaniem LangChain.js a wywołaniem dużego modelu językowego (LLM): aplikacja ma pytanie oraz weryfikowalne dowody, gotowe do prompta, który poprosi model o odpowiedź na podstawie tego kontekstu.
Wyszukiwanie i generowanie to odrębne odpowiedzialności. W tym momencie context jest zwykłym łańcuchem tekstowym, który model czatu może przetworzyć. Możesz teraz przekazać go do modelu z instrukcją, by odpowiadał wyłącznie na podstawie pobranych materiałów i cytował identyfikatory źródeł. Sama integracja z bazą działa nawet bez modelu czatu.
Jak zweryfikować integrację
Przydatna walidacja sprawdza ingestowanie i każdą strategię wyszukiwania osobno. Najpierw potwierdź, że vector store został utworzony bez błędu bazy. Następnie sprawdź metadane źródeł zwrócone przez wyszukiwanie podobieństwa, wynik filtrowany i wynik MMR.
const check =await vectorStore.similaritySearch("How does OracleVS connect to LangChain.js?",3);if(check.length ===0){thrownewError("No documents retrieved; inspect ingestion and filters.");}console.log({
similarity: check.map((doc)=> doc.metadata.source),
filtered: databaseOnly.map((doc)=> doc.metadata.source),
mmr: diverse.map((doc)=> doc.metadata.source),});Obsługiwane przez
Sprzątanie uruchamia się dopiero po zakończeniu ingestowania, wyszukiwania i weryfikacji. Czas drenażu daje używanym połączeniom krótkie okno na dokończenie pracy. W długo działającym serwerze utrzymuj pulę otwartą do momentu łagodnego wyłączania. Szczegóły cyklu życia znajdziesz w dokumentacji pool.close() dla node-oracledb.
W tym momencie kompletny plik index.ts możesz uruchomić poleceniem:
Dokładna kolejność podobieństwa i wartości odległości mogą się różnić w zależności od modelu i dostawcy osadzeń. Wynik filtrowany powinien zawierać database-guide, a wynik MMR powinien pokazywać zróżnicowany zestaw źródeł wyszukiwania z nakładającego się korpusu.
Wskazówki i rozwiązywanie problemów
Połączenie z bazą nie działa
Sprawdź łańcuch połączenia, dane logowania, dostępność usługi i uprawnienia schematu. Jeśli używasz Autonomous AI Database, potwierdź wymaganą konfigurację portfela lub TLS. Przetestuj połączenie z bazą niezależnie, zanim zaczniesz debugować wyszukiwanie.
Występuje niezgodność wymiaru osadzeń
Wektory utworzone podczas ingestowania i wektory zapytań muszą mieć zgodne wymiary. Używanie różnych modeli osadzeń do wstawek i zapytań może zepsuć wyszukiwanie lub pogorszyć wyniki. Utrzymuj spójny wybór modelu dla danej tabeli.
Wyszukiwanie nie zwraca dokumentów
Potwierdź, że ingestowanie wstawiło wiersze, a następnie spróbuj ponownie bez restrykcyjnych filtrów metadanych. Dla małych korpusów eksperymentuj z szerszymi zapytaniami i przejrzyj zapisane treści.
Wyniki są trafne, ale powtarzalne
Porównaj wyszukiwanie podobieństwa z MMR przy korpusie z nakładającymi się fragmentami. Stroń parametry k, fetchK i lambda, obserwując, czy różnorodność nie odbywa się kosztem pominięcia ważnych fragmentów.
Czy warto tworzyć indeks wektorowy?
Dla małego zbioru testowego zacznij od weryfikacji poprawności bez strojenia indeksowania. Wraz ze wzrostem danych rozważ indeksy wektorowe Oracle vector indexes, takie jak HNSW (Hierarchical Navigable Small World) czy IVF (Inverted File), zgodnie z wymaganiami wydajności i dokładności. Tworzenie indeksu to optymalizacja, a nie warunek wstępny zrozumienia podstawowej integracji.
Aplikacja napisana w TypeScript łączy ingestowanie dokumentów, przechowywanie wektorów, wyszukiwanie podobieństwa, filtrowanie metadanych i MMR z użyciem LangChain.js i Oracle AI Database. Zapewnia też interaktywny interfejs do eksperymentów z ustawieniami wyszukiwania, przeglądania pobranych dokumentów i zrozumienia, jak różne strategie wpływają na kontekst zwracany do aplikacji.
Repozytorium zawiera kod źródłowy i instrukcje konfiguracji, dzięki czemu możesz poznać pełną integrację i dostosować implementację do własnych projektów.
Podsumowanie i kolejne kroki
Połączyłeś LangChain.js z Oracle AI Database poprzez OracleVS, przedstawiłeś wiedzę jako obiekty Document, utworzyłeś trwałe osadzenia wektorowe oraz porównałeś wyszukiwanie podobieństwa, filtrowanie metadanych i MMR. Jako kolejny krok przeczytaj oficjalną dokumentację LangChain.js oraz oficjalny przewodnik integracji Oracle LangChain JavaScript.
Nasz kurs Retrieval Augmented Generation (RAG) z LangChain to opcjonalna kontynuacja skupiona na wyszukiwaniu; przykłady są w Pythonie, ale koncepcje przepływu pracy mają zastosowanie w tej implementacji TypeScript.
FAQ
Co się stanie, jeśli zmienię model osadzeń po zapisaniu dokumentów?⌄
Osadzenia przechowywane w tabeli wektorowej Oracle muszą być zgodne z osadzeniami używanymi do wyszukiwania. Zmiana modeli może wpłynąć zarówno na wymiary wektorów, jak i znaczenie współrzędnych wektora, dlatego po zmianie modelu osadzeń ponownie osadź i zindeksuj dokumenty. Używaj tej samej konfiguracji osadzeń dla ingestowania dokumentów i zapytań.
Czy potrzebuję modelu czatu, aby używać OracleVS?⌄
Nie. Przepływ pracy z vector store wymaga modelu osadzeń do ingestowania i zapytań. Model czatu jest opcjonalny i zwykle dodawany, gdy pobrane fragmenty mają zostać przekształcone w odpowiedź w języku naturalnym.
Czy mogę użyć innego dostawcy osadzeń niż OpenAI?⌄
Tak. OracleVS akceptuje zgodną z LangChain implementację osadzeń. Wybierz dostawcę spełniającego twoje wymagania i użyj tej samej, zgodnej konfiguracji osadzeń dla dokumentów i zapytań.
Dlaczego łączyć filtrowanie metadanych z podobieństwem wektorowym?⌄
Podobieństwo wektorowe znajduje semantycznie zbliżone treści; filtrowanie metadanych zawęża, które treści mogą zostać zwrócone, np. dokumenty w określonej kategorii lub ze wskazanego źródła.
Kiedy wybrać MMR zamiast zwykłego wyszukiwania podobieństwa?⌄
MMR pomaga, gdy najwyższe dopasowania zawierają powtarzalne fragmenty, a aplikacja korzysta z bardziej zróżnicowanych dowodów. Zwykłe wyszukiwanie podobieństwa jest prostsze, gdy najbliżsi sąsiedzi są głównym celem.
Autor
Daniela Pavlenco
Jestem Developer Advocate w Oracle, a moim celem jest pomagać deweloperom poznawać technologie AI i tworzyć praktyczne aplikacje z użyciem nowoczesnych narzędzi i frameworków. Tworzę treści techniczne, praktyczne przykłady i materiały dla programistów, które ułatwiają zrozumienie złożonych zagadnień i zastosowanie ich w projektach realizowanych w rzeczywistych warunkach.
Model językowy potrafi odpowiadać na ogólne pytania, ale nie będzie wiarygodnie odwoływał się do prywatnej bazy wiedzy, jeśli aplikacja najpierw nie pobierze odpowiednich informacji. Dla programistów JavaScript LangChain.js oferuje znajome abstrakcje dla dokumentów, osadzeń i mechanizmów wyszukiwania. Brakującym elementem jest trwałe miejsce do przechowywania i przeszukiwania powstałych wektorów.
Oracle AI Database wypełnia tę rolę dzięki integracji
@oracle/langchain-oracledb. W tym przewodniku połączysz niewielki przepływ pracy w TypeScript z Oracle, zapiszesz tekst z metadanymi, uruchomisz wyszukiwanie podobieństwa i ulepszysz wyniki za pomocą filtrów oraz Maximal Marginal Relevance (MMR). Tutorial koncentruje się na przepływie wyszukiwania; towarzysząca aplikacja TypeScript dodaje tę samą integrację do interfejsu przeglądarkowego.Szczegóły integracji znajdziesz w oficjalnym przewodniku integracji Oracle LangChain JavaScript.
Na czym polega integracja LangChain.js i Oracle AI Database?
LangChain.js standaryzuje sposób pracy aplikacji z modelami osadzeń i magazynami wektorów. Pakiet integracyjny Oracle dostarcza
OracleVS— implementację vector store, która zapisuje tekst dokumentów, metadane i wektorowe osadzenia w Oracle AI Database. Twoja aplikacja wywołuje metody LangChain.js zamiast ręcznie pisać SQL dla każdego zapytania podobieństwa.Ten sam pakiet integracyjny obejmuje również
OracleDocLoader,OracleTextSplitter,OracleEmbeddingsiOracleSummary. To przydatne, opcjonalne klocki; poniższy przykład skupia się naOracleVSi pozostawia generowanie osadzeń osobno, aby przepływ pozostał łatwy do zrozumienia.Ingestowanie dokumentów i wyszukiwanie z użyciem LangChain.js, OracleVS i Oracle AI Database
Kluczowe możliwości integracji
Przechowuj osadzenia razem z metadanymi dokumentów
Model osadzeń zamienia tekst na wektory liczbowe.
OracleVSzapisuje te wektory wraz z tekstem źródłowym i ustrukturyzowanymi metadanymi. Metadane, takie jak kategoria dokumentu czy źródło, pomagają aplikacji zawężać wyszukiwania bez utraty przydatnego kontekstu.Odzyskuj trafne fragmenty dzięki podobieństwu wektorowemu
W czasie zapytania ten sam model osadzeń konwertuje pytanie na wektor. Oracle porównuje go z zapisanymi wektorami, używając skonfigurowanej metryki odległości, np. cosinusowej, i zwraca najbliższe dokumenty. Wyniki pozostają obiektami
DocumentLangChain, gotowymi do dalszego przetwarzania.Kontroluj wyniki za pomocą filtrów i MMR
Wyszukiwanie podobieństwa odpowiada na pytanie „które elementy są najbliżej tego pytania?”. Filtr metadanych zawęża pulę kwalifikujących się dokumentów. MMR dodaje inny cel: utrzymać trafność wybranych fragmentów, jednocześnie redukując niemal duplikaty. To operacje komplementarne, a nie wymienne.
Pierwsze kroki z LangChain.js i Oracle AI Database
Wymagania wstępne
Do tego przykładu w TypeScript potrzebujesz Node.js 24.13.0, npm 11.6.2, lokalnej instancji Oracle AI Database 26ai Free z obsługą wektorów oraz schematu, który może tworzyć, wstawiać, odpytywać i usuwać tabelę demonstracyjną oraz jej indeks wektorowy. Potrzebujesz też klucza API OpenAI do przykładu z osadzeniami.
OpenAIEmbeddingsto zgodny z LangChain wybór, a nie wymógOracleVS.Zainstaluj Node.js z oficjalnej strony pobierania Node.js.
Dla podstawowej lokalnej ścieżki postępuj zgodnie z krótkim przewodnikiem Oracle AI Database Free. Po uruchomieniu bazy użyj usługi takiej jak
localhost:1521/FREEPDB1oraz schematu z uprawnieniami wymienionymi powyżej.Utwórz projekt TypeScript
Utwórz w tym folderze plik o nazwie
index.ts. Dodaj do niego wykonywalne fragmenty TypeScript poniżej, w podanej kolejności. Nie twórz osobnego pliku dla każdego fragmentu. Skopiuj tylko wykonywalne fragmenty TypeScript: bloki SQL i reprezentatywne wyniki są przykładami objaśniającymi i nie powinny być wklejane doindex.ts.Ustawienie
type=modulewpackage.jsonpozwala na użycieawaitna najwyższym poziomie w przykładach. Konfigurację pakietów Node.js opisano w oficjalnym przewodniku po pakietach Node.js.Pakiet integracyjny Oracle implementuje vector store,
@langchain/coredostarczaDocument,@langchain/openaidostarcza przykładowy model osadzeń, aoracledbzarządza połączeniem z bazą. Powyższe wersje odpowiadają aplikacji towarzyszącej;tsxuruchamia przykład TypeScript bez osobnego kroku budowania.Skonfiguruj połączenie
Zapisz te wartości w lokalnym pliku
.envi dodaj.envdo.gitignore. W tym artykule podstawową konfiguracją jest lokalna Oracle AI Database Free, aby kroki były odtwarzalne. Autonomous AI Database to prawidłowa alternatywa wdrożeniowa, ale wymaga deskryptora usługi oraz konfiguracji portfela lub TLS dla tego środowiska.Pula pozwala
OracleVSponownie wykorzystywać sesje bazy danych. Umieść wszystkie instrukcje dotyczące ingestowania, wyszukiwania i weryfikacji wewnątrz blokutry. Następny blok kodu rozpoczyna ten blok, a kolejne fragmenty go kontynuują. Pula jest zamykana dopiero po weryfikacji w sekcji sprzątania poniżej. W aplikacji serwerowej zainicjalizuj pulę raz i zamknij ją podczas łagodnego wyłączania, zamiast otwierać nowe połączenie dla każdego żądania użytkownika.Jak zbudować wyszukiwanie dokumentów z LangChain.js
Użyjemy 10 krótkich notatek z bazy wiedzy, w tym zachodzących na siebie fragmentów. Korpus jest celowo mały, ale pozwala porównać zwykłe wyszukiwanie podobieństwa z filtrowaniem metadanych i MMR.
Zdefiniuj dokumenty wiedzy
Każdy
DocumentmapageContentimetadata. Polasourceicategorytowarzyszą dokumentowi podczas ingestowania i wyszukiwania, dzięki czemu aplikacja może wyjaśnić pochodzenie wyniku i zawęzić wyszukiwanie do odpowiedniego podzbioru.Skonfiguruj osadzenia i utwórz OracleVS
OracleVS.fromDocuments()to kluczowe wywołanie integracji. Inicjalizuje vector store, generuje osadzenia dla dostarczonych dokumentów i zapisuje ich treść, wektory oraz metadane w Oracle AI Database.Parametr
querydostarcza przykładowy tekst osadzany podczas inicjalizacji w celu określenia wymiaru wektora wymaganego przez tabelę w bazie. Nie służy do przeszukiwania zapisanych dokumentów.DistanceStrategy.COSINEokreśla metrykę odległości wektorów, aVectorElementFormat.FLOAT32ustawia format elementów wektora.Przed ponownym uruchomieniem ingestowania użyj nowej nazwy tabeli demonstracyjnej lub wyczyść istniejące dane, aby uniknąć duplikatów dokumentów.
OracleVSakceptuje implementację osadzeń zgodną z LangChain, więc programiści mogą zmieniać dostawców osadzeń bez modyfikacji ogólnego przepływu vector store. Jednak osadzenia używane do ingestowania i wyszukiwania muszą pozostać zgodne z kolumną wektorową Oracle.OracleVSokreśla wymiar wektora podczas inicjalizacji na podstawie skonfigurowanego modelu osadzeń. Aby sprawdzić wymiary i format przechowywania wektora już zapisanego w Oracle AI Database, uruchom następujące zapytanie SQL:Jeśli przełączysz się na model osadzeń o innym wymiarze, utwórz zgodną tabelę wektorową i wygeneruj osadzenia dokumentów ponownie. Nawet jeśli dwa modele tworzą wektory o tych samych wymiarach, ich przestrzenie osadzeń mogą się różnić, więc istniejące dokumenty należy ponownie osadzić przed użyciem nowego modelu do wyszukiwania.
Sygnatury metod vector store i opcje wyszukiwania znajdziesz w oficjalnej dokumentacji LangChain.js VectorStore.
Wyszukuj dokumenty poprzez podobieństwo
Na przykład, poniższe wywołanie prosi vector store
OracleVSo 3 najbliższe dokumenty i drukuje metadane źródła wraz z tekstem każdego fragmentu:Kod mapuje każdy
DocumentLangChain na prosty obiekt zawierający jegosourceipageContentdo wyświetlenia. Poniżej przedstawiono reprezentatywny wynik; dokładna kolejność może się różnić w zależności od modelu osadzeń i zapytania:Pierwszy argument to pytanie użytkownika, a drugi to
k, maksymalna liczba dokumentów do pobrania. LangChain.js używa skonfigurowanego modelu osadzeń, by zamienić pytanie na wektor, a Oracle AI Database przeprowadza wyszukiwanie podobieństwa, aby znaleźć najbliżej pasujące dokumenty.Jeśli po zastosowaniu warunków wyszukiwania i filtrów metadanych dostępnych jest mniej niż
kdokumentów, metoda zwróci tylko dostępne wyniki. PobranieDocumentzawiera tekst i metadane, które można wyświetlić z atrybucją źródła lub przekazać do dalszego etapu generowania odpowiedzi.Sprawdzaj wyniki wyszukiwania
Na przykład użyj
similaritySearchWithScore, gdy chcesz sprawdzić odległość związaną z każdym pobranym dokumentem:similaritySearchWithScorezwraca odległość przy każdym dopasowaniu. Jej wartość liczbowa i kierunek zależą od wybranej metryki odległości, więc nie jest to uniwersalny procent pewności. Porównuj wyniki tylko przy tym samym modelu osadzeń i metryce oraz przejrzyj pobrany fragment przed wyborem progu.Ogranicz wyniki filtrami metadanych
Przykładowy wynik:
Trzeci argument zawęża wyszukiwanie do elementów z
category = database. W tym korpusie przewidywalnym wynikiem filtrowania jest["database-guide"]. Filtr zmienia to, które dokumenty się kwalifikują; ranking wciąż opiera się na podobieństwie wektorowym.Użyj MMR, aby zredukować powtarzalność wyników
Reprezentatywny wynik dla nakładającego się korpusu (kolejność może się różnić w zależności od modeli osadzeń i uruchomień):
MMR najpierw rozważa pulę kandydatów (
fetchK), a następnie wybierakdokumentów, równoważąc trafność zapytania z różnorodnością. Niższelambdasilniej akcentuje różnorodność; wyższe — trafność. Przy powyższym, nakładającym się korpusie, wybrane źródła mogą różnić się od zwykłego wyszukiwania podobieństwa, co uwidacznia kompromis w wyszukiwaniu.Przekaż pobrany kontekst do aplikacji AI
To punkt przekazania między wyszukiwaniem LangChain.js a wywołaniem dużego modelu językowego (LLM): aplikacja ma pytanie oraz weryfikowalne dowody, gotowe do prompta, który poprosi model o odpowiedź na podstawie tego kontekstu.
Wyszukiwanie i generowanie to odrębne odpowiedzialności. W tym momencie
contextjest zwykłym łańcuchem tekstowym, który model czatu może przetworzyć. Możesz teraz przekazać go do modelu z instrukcją, by odpowiadał wyłącznie na podstawie pobranych materiałów i cytował identyfikatory źródeł. Sama integracja z bazą działa nawet bez modelu czatu.Jak zweryfikować integrację
Przydatna walidacja sprawdza ingestowanie i każdą strategię wyszukiwania osobno. Najpierw potwierdź, że vector store został utworzony bez błędu bazy. Następnie sprawdź metadane źródeł zwrócone przez wyszukiwanie podobieństwa, wynik filtrowany i wynik MMR.
Zamknij pulę połączeń po weryfikacji
Sprzątanie uruchamia się dopiero po zakończeniu ingestowania, wyszukiwania i weryfikacji. Czas drenażu daje używanym połączeniom krótkie okno na dokończenie pracy. W długo działającym serwerze utrzymuj pulę otwartą do momentu łagodnego wyłączania. Szczegóły cyklu życia znajdziesz w dokumentacji
pool.close()dla node-oracledb.W tym momencie kompletny plik
index.tsmożesz uruchomić poleceniem:Reprezentatywny wynik walidacji to:
Dokładna kolejność podobieństwa i wartości odległości mogą się różnić w zależności od modelu i dostawcy osadzeń. Wynik filtrowany powinien zawierać
database-guide, a wynik MMR powinien pokazywać zróżnicowany zestaw źródeł wyszukiwania z nakładającego się korpusu.Wskazówki i rozwiązywanie problemów
Połączenie z bazą nie działa
Sprawdź łańcuch połączenia, dane logowania, dostępność usługi i uprawnienia schematu. Jeśli używasz Autonomous AI Database, potwierdź wymaganą konfigurację portfela lub TLS. Przetestuj połączenie z bazą niezależnie, zanim zaczniesz debugować wyszukiwanie.
Występuje niezgodność wymiaru osadzeń
Wektory utworzone podczas ingestowania i wektory zapytań muszą mieć zgodne wymiary. Używanie różnych modeli osadzeń do wstawek i zapytań może zepsuć wyszukiwanie lub pogorszyć wyniki. Utrzymuj spójny wybór modelu dla danej tabeli.
Wyszukiwanie nie zwraca dokumentów
Potwierdź, że ingestowanie wstawiło wiersze, a następnie spróbuj ponownie bez restrykcyjnych filtrów metadanych. Dla małych korpusów eksperymentuj z szerszymi zapytaniami i przejrzyj zapisane treści.
Wyniki są trafne, ale powtarzalne
Porównaj wyszukiwanie podobieństwa z MMR przy korpusie z nakładającymi się fragmentami. Stroń parametry
k,fetchKilambda, obserwując, czy różnorodność nie odbywa się kosztem pominięcia ważnych fragmentów.Czy warto tworzyć indeks wektorowy?
Dla małego zbioru testowego zacznij od weryfikacji poprawności bez strojenia indeksowania. Wraz ze wzrostem danych rozważ indeksy wektorowe Oracle vector indexes, takie jak HNSW (Hierarchical Navigable Small World) czy IVF (Inverted File), zgodnie z wymaganiami wydajności i dokładności. Tworzenie indeksu to optymalizacja, a nie warunek wstępny zrozumienia podstawowej integracji.
Więcej szczegółów o indeksach wektorowych Oracle znajdziesz w dokumentacji indeksów wektorowych.
Poznaj kompletną referencyjną implementację w TypeScript
Aby zobaczyć, jak te koncepcje łączą się w działającej aplikacji, zajrzyj do referencyjnej implementacji LangChain.js i Oracle AI Database.
Aplikacja napisana w TypeScript łączy ingestowanie dokumentów, przechowywanie wektorów, wyszukiwanie podobieństwa, filtrowanie metadanych i MMR z użyciem LangChain.js i Oracle AI Database. Zapewnia też interaktywny interfejs do eksperymentów z ustawieniami wyszukiwania, przeglądania pobranych dokumentów i zrozumienia, jak różne strategie wpływają na kontekst zwracany do aplikacji.
Repozytorium zawiera kod źródłowy i instrukcje konfiguracji, dzięki czemu możesz poznać pełną integrację i dostosować implementację do własnych projektów.
Podsumowanie i kolejne kroki
Połączyłeś LangChain.js z Oracle AI Database poprzez
OracleVS, przedstawiłeś wiedzę jako obiektyDocument, utworzyłeś trwałe osadzenia wektorowe oraz porównałeś wyszukiwanie podobieństwa, filtrowanie metadanych i MMR. Jako kolejny krok przeczytaj oficjalną dokumentację LangChain.js oraz oficjalny przewodnik integracji Oracle LangChain JavaScript.Jeśli pracujesz w innych językach, nasz tutorial Oracle AI Vector Search obejmuje te same kroki przechowywania i zapytań w Pythonie, a nasz tutorial LangChain4j buduje agenta w Javie z Oracle AI Database.
Nasz kurs Retrieval Augmented Generation (RAG) z LangChain to opcjonalna kontynuacja skupiona na wyszukiwaniu; przykłady są w Pythonie, ale koncepcje przepływu pracy mają zastosowanie w tej implementacji TypeScript.