LangChain.js và Oracle AI Database: Hướng dẫn Tìm kiếm Vector
Kết nối LangChain.js với Oracle AI Database bằng OracleVS, lưu embedding kèm metadata, và so sánh tìm kiếm độ tương đồng, bộ lọc metadata và MMR trong TypeScript.
Một mô hình ngôn ngữ có thể trả lời các câu hỏi chung, nhưng sẽ không thể tra cứu đáng tin cậy một kho tri thức riêng tư trừ khi ứng dụng truy xuất trước được thông tin liên quan. Với nhà phát triển JavaScript, LangChain.js cung cấp các trừu tượng quen thuộc cho tài liệu, embedding và truy xuất. Mảnh ghép còn thiếu là một nơi lưu trữ bền vững để lưu và tìm kiếm các vector kết quả.
Oracle AI Database đảm nhiệm vai trò đó thông qua tích hợp @oracle/langchain-oracledb. Trong hướng dẫn này, bạn sẽ kết nối một quy trình TypeScript nhỏ với Oracle, lưu văn bản kèm metadata, chạy tìm kiếm độ tương đồng, và cải thiện truy xuất với bộ lọc và maximal marginal relevance (MMR). Bài hướng dẫn tập trung vào quy trình truy xuất; ứng dụng TypeScript đi kèm bổ sung cùng tích hợp này vào giao diện trình duyệt tương tác.
Tích hợp LangChain.js và Oracle AI Database là gì?
LangChain.js tiêu chuẩn hóa cách một ứng dụng làm việc với mô hình embedding và kho vector. Gói tích hợp Oracle cung cấp OracleVS, một hiện thực vector store lưu bền văn bản tài liệu, metadata và vector embedding trong Oracle AI Database. Ứng dụng của bạn gọi các phương thức LangChain.js thay vì tự viết SQL thủ công cho từng truy vấn độ tương đồng.
Cùng gói tích hợp này còn có OracleDocLoader, OracleTextSplitter, OracleEmbeddings và OracleSummary. Đây là các khối xây dựng tùy chọn hữu ích; ví dụ dưới đây tập trung vào OracleVS và tách riêng phần sinh embedding để luồng xử lý dễ hiểu hơn.
Nạp và truy xuất tài liệu bằng LangChain.js, OracleVS và Oracle AI Database
Các tính năng chính của tích hợp
Lưu embeddings cùng metadata của tài liệu
Một mô hình embedding biến văn bản thành các vector số. OracleVS lưu các vector này cùng văn bản nguồn và metadata có cấu trúc. Metadata như danh mục tài liệu hoặc nguồn giúp ứng dụng giới hạn phạm vi tìm kiếm mà không loại bỏ bối cảnh hữu ích.
Truy xuất đoạn phù hợp bằng độ tương đồng vector
Ở thời điểm truy vấn, cùng mô hình embedding sẽ chuyển câu hỏi thành một vector. Oracle so sánh nó với các vector đã lưu bằng chiến lược khoảng cách được cấu hình, như cosine, và trả về các tài liệu gần nhất. Kết quả vẫn là các đối tượng Document của LangChain, sẵn sàng cho các bước xử lý tiếp theo.
Kiểm soát kết quả bằng lọc và MMR
Tìm kiếm độ tương đồng trả lời “mục nào gần câu hỏi này nhất?”. Bộ lọc metadata thu hẹp các tài liệu đủ điều kiện. MMR bổ sung một mục tiêu khác: giữ các đoạn được chọn phù hợp trong khi giảm kết quả trùng lặp gần nhau. Hai thao tác này bổ trợ, không thể thay thế cho nhau.
Bắt đầu với LangChain.js và Oracle AI Database
Yêu cầu tiên quyết
Với ví dụ TypeScript này, bạn cần Node.js 24.13.0, npm 11.6.2, một bản cài đặt cục bộ Oracle AI Database 26ai Free có hỗ trợ vector, và một schema có thể tạo, chèn, truy vấn và xóa bảng minh họa cùng chỉ mục vector của nó. Bạn cũng cần khóa API OpenAI cho ví dụ embedding. OpenAIEmbeddings là lựa chọn tương thích LangChain, không phải yêu cầu của OracleVS.
Với phương án cục bộ chính, hãy làm theo hướng dẫn nhanh Oracle AI Database Free của Oracle. Sau khi cơ sở dữ liệu chạy, hãy dùng một service như localhost:1521/FREEPDB1 và một schema có các quyền nêu trên.
Tạo tệp tên index.ts trong thư mục này. Thêm các đoạn TypeScript có thể thực thi dưới đây vào cùng tệp, theo đúng thứ tự. Không tạo tệp riêng cho từng đoạn. Chỉ sao chép các đoạn TypeScript thực thi: các khối SQL và kết quả mẫu chỉ để giải thích và không nên dán vào index.ts.
Thiết lập type=module trong package.json cho phép dùng await ở cấp cao nhất như trong ví dụ. Cấu hình gói Node.js được mô tả trong hướng dẫn gói Node.js chính thức.
Gói tích hợp Oracle hiện thực vector store, @langchain/core cung cấp Document, @langchain/openai cung cấp mô hình embedding ví dụ, và oracledb quản lý kết nối cơ sở dữ liệu. Các phiên bản trên khớp với ứng dụng đi kèm; tsx chạy trực tiếp ví dụ TypeScript mà không cần bước build riêng.
Cấu hình kết nối
ORACLE_USER=your_schema
ORACLE_PASSWORD=your_password
ORACLE_CONNECT_STRING=localhost:1521/FREEPDB1
OPENAI_API_KEY=your_api_keyĐược hỗ trợ bởi
Lưu các giá trị này vào tệp .env cục bộ và thêm .env vào .gitignore. Bài viết dùng Oracle AI Database Free cục bộ làm thiết lập chính để các bước có thể tái lập. Autonomous AI Database là lựa chọn triển khai hợp lệ, nhưng yêu cầu descriptor dịch vụ và cấu hình ví hoặc TLS phù hợp môi trường đó.
Pool cho phép OracleVS tái sử dụng phiên cơ sở dữ liệu. Giữ toàn bộ các câu lệnh nạp, truy xuất và xác minh bên trong khối try. Khối mã tiếp theo bắt đầu khối đó, và các đoạn sau sẽ tiếp tục nó. Pool chỉ được đóng sau phần xác minh trong mục dọn dẹp bên dưới. Trong ứng dụng máy chủ, khởi tạo pool một lần và đóng nó khi tắt dịch vụ có kiểm soát thay vì mở kết nối mới cho mỗi yêu cầu.
Cách xây dựng tìm kiếm tài liệu với LangChain.js
Chúng ta sẽ dùng 10 ghi chú ngắn trong kho tri thức, bao gồm các đoạn truy xuất chồng lắp. Tập dữ liệu có chủ đích nhỏ để có thể so sánh tìm kiếm độ tương đồng thông thường với lọc metadata và MMR.
Định nghĩa tài liệu tri thức
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 }}));Được hỗ trợ bởi
Mỗi Document có pageContent và metadata. Trường source và category đi cùng tài liệu trong suốt quá trình nạp và truy xuất, giúp ứng dụng giải thích nguồn gốc kết quả và giới hạn tìm kiếm vào một tập con phù hợp.
Cấu hình embedding và tạo 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,});Được hỗ trợ bởi
OracleVS.fromDocuments() là lời gọi tích hợp trung tâm. Nó khởi tạo vector store, tạo embedding cho các tài liệu đã cung cấp, và lưu nội dung, vector cùng metadata của chúng trong Oracle AI Database.
Tham số query cung cấp văn bản mẫu sẽ được embed trong quá trình khởi tạo để xác định chiều vector cần cho bảng trong cơ sở dữ liệu. Nó không được dùng để tìm kiếm các tài liệu đã lưu. DistanceStrategy.COSINE chỉ định số đo khoảng cách vector, trong khi VectorElementFormat.FLOAT32 đặt định dạng phần tử vector.
Trước khi chạy lại quá trình nạp, hãy dùng tên bảng minh họa mới hoặc xóa dữ liệu hiện có để tránh chèn trùng tài liệu.
OracleVS chấp nhận một hiện thực embedding tương thích LangChain, nên nhà phát triển có thể đổi nhà cung cấp embedding mà không cần thay đổi quy trình vector store tổng thể. Tuy nhiên, embedding dùng cho nạp và truy xuất phải tương thích với cột vector của Oracle.
OracleVS xác định chiều vector trong quá trình khởi tạo dựa trên mô hình embedding đã cấu hình. Để kiểm tra chiều và định dạng lưu trữ của một vector đã được lưu trong Oracle AI Database, chạy câu lệnh SQL sau:
SELECT
VECTOR_DIMENSION_COUNT(embedding)AS vector_dimensions,
VECTOR_DIMENSION_FORMAT(embedding)AS vector_format
FROM LC_JS_RAG_DEMO
FETCHFIRST1ROW ONLY;Được hỗ trợ bởi
Nếu bạn chuyển sang mô hình embedding có chiều khác, hãy tạo một bảng vector tương thích và tạo lại embedding tài liệu. Ngay cả khi hai mô hình tạo vector cùng số chiều, không gian embedding có thể khác nhau, vì vậy tài liệu hiện có nên được embed lại trước khi dùng mô hình mới cho truy xuất.
Ví dụ, lời gọi sau yêu cầu vector store OracleVS trả về 3 tài liệu gần nhất và in metadata nguồn cùng văn bản của mỗi đoạn:
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,})));Được hỗ trợ bởi
Mã chuyển mỗi Document của LangChain thành một đối tượng thuần chứa source và pageContent để hiển thị. Một kết quả đại diện được hiển thị bên dưới; thứ tự chính xác có thể khác nhau tùy mô hình embedding và truy vấn:
[
{ 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." }
]Được hỗ trợ bởi
Đối số thứ nhất là câu hỏi người dùng, đối số thứ hai là k, số tài liệu tối đa cần truy xuất. LangChain.js dùng mô hình embedding đã cấu hình để chuyển câu hỏi thành vector, và Oracle AI Database thực hiện tìm kiếm độ tương đồng để tìm các tài liệu khớp gần nhất.
Nếu có ít hơn k tài liệu sau khi áp dụng điều kiện tìm kiếm và bộ lọc metadata, phương thức chỉ trả về số kết quả sẵn có. Các đối tượng Document truy xuất được chứa văn bản và metadata có thể hiển thị kèm nguồn hoặc chuyển tới bước tạo câu trả lời sau đó.
Kiểm tra điểm số truy xuất
Ví dụ, dùng similaritySearchWithScore khi bạn muốn xem khoảng cách gắn với mỗi tài liệu truy xuất:
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,});}Được hỗ trợ bởi
similaritySearchWithScore trả về một khoảng cách cùng mỗi kết quả khớp. Giá trị số và chiều của nó phụ thuộc vào chiến lược khoảng cách đã cấu hình, nên không phải là phần trăm độ tin cậy phổ quát. Chỉ so sánh điểm khi dùng cùng mô hình embedding và chiến lược khoảng cách, và hãy xem xét đoạn truy xuất trước khi chọn ngưỡng.
Giới hạn kết quả bằng bộ lọc metadata
const databaseOnly =await vectorStore.similaritySearch("Where are vector embeddings stored?",3,{ category:{ $eq:"database"}});console.log(databaseOnly.map((doc)=> doc.metadata.source));Được hỗ trợ bởi
Đối số thứ ba giới hạn tìm kiếm vào các mục có category = database. Với tập này, kết quả đã lọc dễ đoán là ["database-guide"]. Bộ lọc thay đổi những tài liệu nào đủ điều kiện; độ tương đồng vector vẫn xếp hạng các tài liệu đủ điều kiện.
Dùng MMR để giảm kết quả lặp lại
const diverse =await vectorStore.maxMarginalRelevanceSearch(
retrievalQuestion,{
k:3,
fetchK:6,
lambda:0.5,});console.log(diverse.map((doc)=> doc.metadata.source));Được hỗ trợ bởi
Kết quả đại diện từ một tập có chồng lắp (thứ tự có thể khác nhau giữa các mô hình embedding và lần chạy):
["retrieval-overlap-2", "mmr-retrieval", "metadata-filtering"]Được hỗ trợ bởi
MMR trước tiên xem xét một tập ứng viên (fetchK) rồi chọn k tài liệu bằng cách cân bằng mức liên quan với tính đa dạng. lambda thấp nhấn mạnh tính đa dạng hơn; giá trị cao nhấn mạnh mức liên quan hơn. Với tập chồng lắp ở trên, các nguồn được chọn có thể khác với tìm kiếm độ tương đồng thông thường, giúp thấy rõ đánh đổi trong truy xuất.
Đây là điểm bàn giao giữa truy xuất LangChain.js và lời gọi mô hình ngôn ngữ lớn (LLM): ứng dụng đã có câu hỏi cùng bằng chứng có thể kiểm tra, sẵn sàng cho prompt yêu cầu mô hình trả lời dựa trên ngữ cảnh đó.
Truy xuất và sinh (generation) là hai trách nhiệm riêng. Lúc này, context là chuỗi văn bản thuần mà một mô hình chat có thể dùng. Bạn có thể cung cấp nó cho mô hình với hướng dẫn chỉ trả lời từ tài liệu đã truy xuất và trích dẫn định danh nguồn. Bản thân tích hợp cơ sở dữ liệu vẫn hoạt động ngay cả khi không có mô hình chat.
Cách xác minh tích hợp
Một kiểm thử hữu ích là kiểm tra riêng quá trình nạp và từng chiến lược truy xuất. Trước tiên, xác nhận vector store được tạo mà không có lỗi cơ sở dữ liệu. Sau đó kiểm tra metadata nguồn do tìm kiếm độ tương đồng trả về, kết quả đã lọc và kết quả 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),});Được hỗ trợ bởi
Phần dọn dẹp chỉ chạy sau khi nạp, truy xuất và xác minh hoàn tất. Thời gian chờ cho phép các kết nối đang dùng có một khoảng ngắn để hoàn thành. Trong máy chủ chạy lâu dài, giữ pool mở đến khi tắt dịch vụ có kiểm soát. Xem tài liệu pool.close() của node-oracledb để biết chi tiết vòng đời.
Ở thời điểm này, tệp index.ts hoàn chỉnh có thể được thực thi với:
Thứ tự độ tương đồng và giá trị khoảng cách chính xác có thể khác theo mô hình và nhà cung cấp embedding. Kết quả đã lọc nên chứa database-guide, trong khi kết quả MMR nên cho thấy tập nguồn truy xuất đa dạng từ tập chồng lắp.
Mẹo và xử lý sự cố
Kết nối cơ sở dữ liệu thất bại
Hãy xác minh chuỗi kết nối, thông tin xác thực, dịch vụ có thể truy cập và quyền schema. Nếu bạn dùng Autonomous AI Database, xác nhận thiết lập ví hoặc TLS bắt buộc. Kiểm thử kết nối cơ sở dữ liệu độc lập trước khi gỡ lỗi truy xuất.
Xảy ra lỗi lệch chiều embedding
Các vector tạo trong quá trình nạp và vector truy vấn phải có chiều tương thích. Dùng các mô hình embedding khác nhau cho chèn và truy vấn có thể làm hỏng tìm kiếm hoặc giảm chất lượng kết quả. Giữ lựa chọn mô hình nhất quán cho một bảng.
Tìm kiếm không trả về tài liệu
Xác nhận quá trình nạp đã chèn dòng, sau đó thử lại mà không có bộ lọc metadata hạn chế. Với tập nhỏ, hãy thử các truy vấn rộng hơn và kiểm tra nội dung đã lưu.
Kết quả phù hợp nhưng lặp lại
So sánh tìm kiếm độ tương đồng với MMR bằng một tập có các đoạn chồng lắp. Tinh chỉnh k, fetchK và lambda đồng thời kiểm tra xem tính đa dạng có đánh đổi bằng việc bỏ sót các đoạn quan trọng không.
Có nên tạo chỉ mục vector?
Với tập dữ liệu mẫu nhỏ, hãy bắt đầu bằng việc xác minh tính đúng đắn mà không tinh chỉnh chỉ mục. Khi dữ liệu tăng, đánh giá chỉ mục vector của Oracle như Hierarchical Navigable Small World (HNSW) hoặc Inverted File (IVF) tùy theo yêu cầu hiệu năng và độ chính xác của bạn. Tạo chỉ mục là một tối ưu hóa, không phải điều kiện tiên quyết để hiểu tích hợp cơ bản.
Để biết chi tiết hơn về chỉ mục vector của Oracle, hãy xem tài liệu chỉ mục vector của Oracle.
Khám phá bản triển khai tham chiếu TypeScript hoàn chỉnh
Ứng dụng được xây dựng bằng TypeScript, tập hợp quy trình nạp tài liệu, lưu trữ vector, tìm kiếm độ tương đồng, lọc metadata và MMR bằng LangChain.js và Oracle AI Database. Ứng dụng cũng cung cấp giao diện tương tác để thử nghiệm thiết lập truy xuất, kiểm tra tài liệu truy xuất và hiểu cách các chiến lược tìm kiếm khác nhau ảnh hưởng đến ngữ cảnh trả về cho ứng dụng.
Kho lưu trữ bao gồm mã nguồn và hướng dẫn thiết lập, cho phép bạn khám phá trọn vẹn tích hợp và điều chỉnh bản triển khai cho dự án của riêng bạn.
Kết luận và bước tiếp theo
Bạn đã kết nối LangChain.js với Oracle AI Database qua OracleVS, biểu diễn tri thức dưới dạng đối tượng Document, tạo embedding vector bền vững, và so sánh tìm kiếm độ tương đồng, lọc metadata cùng MMR. Bước tiếp theo, hãy đọc tài liệu LangChain.js chính thức và hướng dẫn tích hợp Oracle LangChain JavaScript chính thức.
Khóa học Retrieval Augmented Generation (RAG) với LangChain của chúng tôi là phần tiếp theo tùy chọn tập trung vào truy xuất; ví dụ bằng Python, nhưng các khái niệm quy trình áp dụng cho bản triển khai TypeScript này.
Câu hỏi thường gặp
Điều gì xảy ra nếu tôi thay đổi mô hình embedding sau khi đã lưu tài liệu?⌄
Embedding lưu trong bảng vector của Oracle phải tương thích với embedding dùng cho tìm kiếm. Việc đổi mô hình có thể thay đổi cả số chiều vector và ý nghĩa của các tọa độ vector, nên hãy embed lại và lập chỉ mục lại tài liệu khi bạn thay đổi mô hình embedding. Dùng cùng cấu hình embedding cho quá trình nạp tài liệu và truy xuất truy vấn.
Tôi có cần mô hình chat để dùng OracleVS không?⌄
Không. Quy trình vector store cần một mô hình embedding cho nạp và truy vấn. Mô hình chat là tùy chọn và thường được thêm vào khi cần biến các đoạn truy xuất thành phản hồi ngôn ngữ tự nhiên.
Tôi có thể dùng nhà cung cấp embedding khác ngoài OpenAI không?⌄
Có. OracleVS chấp nhận một hiện thực embedding tương thích LangChain. Hãy chọn nhà cung cấp đáp ứng yêu cầu của bạn và dùng cùng thiết lập embedding tương thích cho tài liệu và truy vấn.
Vì sao dùng lọc metadata cùng với độ tương đồng vector?⌄
Độ tương đồng vector tìm nội dung gần gũi về ngữ nghĩa; lọc metadata thu hẹp nội dung có thể được trả về, chẳng hạn tài liệu trong một danh mục hoặc nguồn cụ thể.
Khi nào tôi nên chọn MMR thay vì tìm kiếm độ tương đồng thông thường?⌄
MMR hữu ích khi các kết quả hàng đầu chứa các đoạn lặp lại và ứng dụng hưởng lợi từ bằng chứng đa dạng hơn. Tìm kiếm độ tương đồng thuần đơn giản hơn khi các láng giềng gần nhất là mục tiêu chính.
Tác giả
Daniela Pavlenco
Tôi là Chuyên gia Vận động Phát triển tại Oracle, tập trung hỗ trợ các nhà phát triển khám phá công nghệ AI và xây dựng ứng dụng thực tiễn với những công cụ, framework hiện đại. Công việc của tôi bao gồm tạo nội dung kỹ thuật, ví dụ thực hành và tài nguyên cho nhà phát triển nhằm giúp những khái niệm phức tạp trở nên dễ hiểu và dễ áp dụng trong các dự án thực tế.
Một mô hình ngôn ngữ có thể trả lời các câu hỏi chung, nhưng sẽ không thể tra cứu đáng tin cậy một kho tri thức riêng tư trừ khi ứng dụng truy xuất trước được thông tin liên quan. Với nhà phát triển JavaScript, LangChain.js cung cấp các trừu tượng quen thuộc cho tài liệu, embedding và truy xuất. Mảnh ghép còn thiếu là một nơi lưu trữ bền vững để lưu và tìm kiếm các vector kết quả.
Oracle AI Database đảm nhiệm vai trò đó thông qua tích hợp
@oracle/langchain-oracledb. Trong hướng dẫn này, bạn sẽ kết nối một quy trình TypeScript nhỏ với Oracle, lưu văn bản kèm metadata, chạy tìm kiếm độ tương đồng, và cải thiện truy xuất với bộ lọc và maximal marginal relevance (MMR). Bài hướng dẫn tập trung vào quy trình truy xuất; ứng dụng TypeScript đi kèm bổ sung cùng tích hợp này vào giao diện trình duyệt tương tác.Với chi tiết tích hợp, hãy xem hướng dẫn tích hợp Oracle LangChain JavaScript chính thức.
Tích hợp LangChain.js và Oracle AI Database là gì?
LangChain.js tiêu chuẩn hóa cách một ứng dụng làm việc với mô hình embedding và kho vector. Gói tích hợp Oracle cung cấp
OracleVS, một hiện thực vector store lưu bền văn bản tài liệu, metadata và vector embedding trong Oracle AI Database. Ứng dụng của bạn gọi các phương thức LangChain.js thay vì tự viết SQL thủ công cho từng truy vấn độ tương đồng.Cùng gói tích hợp này còn có
OracleDocLoader,OracleTextSplitter,OracleEmbeddingsvàOracleSummary. Đây là các khối xây dựng tùy chọn hữu ích; ví dụ dưới đây tập trung vàoOracleVSvà tách riêng phần sinh embedding để luồng xử lý dễ hiểu hơn.Nạp và truy xuất tài liệu bằng LangChain.js, OracleVS và Oracle AI Database
Các tính năng chính của tích hợp
Lưu embeddings cùng metadata của tài liệu
Một mô hình embedding biến văn bản thành các vector số.
OracleVSlưu các vector này cùng văn bản nguồn và metadata có cấu trúc. Metadata như danh mục tài liệu hoặc nguồn giúp ứng dụng giới hạn phạm vi tìm kiếm mà không loại bỏ bối cảnh hữu ích.Truy xuất đoạn phù hợp bằng độ tương đồng vector
Ở thời điểm truy vấn, cùng mô hình embedding sẽ chuyển câu hỏi thành một vector. Oracle so sánh nó với các vector đã lưu bằng chiến lược khoảng cách được cấu hình, như cosine, và trả về các tài liệu gần nhất. Kết quả vẫn là các đối tượng
Documentcủa LangChain, sẵn sàng cho các bước xử lý tiếp theo.Kiểm soát kết quả bằng lọc và MMR
Tìm kiếm độ tương đồng trả lời “mục nào gần câu hỏi này nhất?”. Bộ lọc metadata thu hẹp các tài liệu đủ điều kiện. MMR bổ sung một mục tiêu khác: giữ các đoạn được chọn phù hợp trong khi giảm kết quả trùng lặp gần nhau. Hai thao tác này bổ trợ, không thể thay thế cho nhau.
Bắt đầu với LangChain.js và Oracle AI Database
Yêu cầu tiên quyết
Với ví dụ TypeScript này, bạn cần Node.js 24.13.0, npm 11.6.2, một bản cài đặt cục bộ Oracle AI Database 26ai Free có hỗ trợ vector, và một schema có thể tạo, chèn, truy vấn và xóa bảng minh họa cùng chỉ mục vector của nó. Bạn cũng cần khóa API OpenAI cho ví dụ embedding.
OpenAIEmbeddingslà lựa chọn tương thích LangChain, không phải yêu cầu củaOracleVS.Cài đặt Node.js từ trang tải Node.js chính thức.
Với phương án cục bộ chính, hãy làm theo hướng dẫn nhanh Oracle AI Database Free của Oracle. Sau khi cơ sở dữ liệu chạy, hãy dùng một service như
localhost:1521/FREEPDB1và một schema có các quyền nêu trên.Tạo dự án TypeScript
Tạo tệp tên
index.tstrong thư mục này. Thêm các đoạn TypeScript có thể thực thi dưới đây vào cùng tệp, theo đúng thứ tự. Không tạo tệp riêng cho từng đoạn. Chỉ sao chép các đoạn TypeScript thực thi: các khối SQL và kết quả mẫu chỉ để giải thích và không nên dán vàoindex.ts.Thiết lập
type=moduletrongpackage.jsoncho phép dùngawaitở cấp cao nhất như trong ví dụ. Cấu hình gói Node.js được mô tả trong hướng dẫn gói Node.js chính thức.Gói tích hợp Oracle hiện thực vector store,
@langchain/corecung cấpDocument,@langchain/openaicung cấp mô hình embedding ví dụ, vàoracledbquản lý kết nối cơ sở dữ liệu. Các phiên bản trên khớp với ứng dụng đi kèm;tsxchạy trực tiếp ví dụ TypeScript mà không cần bước build riêng.Cấu hình kết nối
Lưu các giá trị này vào tệp
.envcục bộ và thêm.envvào.gitignore. Bài viết dùng Oracle AI Database Free cục bộ làm thiết lập chính để các bước có thể tái lập. Autonomous AI Database là lựa chọn triển khai hợp lệ, nhưng yêu cầu descriptor dịch vụ và cấu hình ví hoặc TLS phù hợp môi trường đó.Pool cho phép
OracleVStái sử dụng phiên cơ sở dữ liệu. Giữ toàn bộ các câu lệnh nạp, truy xuất và xác minh bên trong khốitry. Khối mã tiếp theo bắt đầu khối đó, và các đoạn sau sẽ tiếp tục nó. Pool chỉ được đóng sau phần xác minh trong mục dọn dẹp bên dưới. Trong ứng dụng máy chủ, khởi tạo pool một lần và đóng nó khi tắt dịch vụ có kiểm soát thay vì mở kết nối mới cho mỗi yêu cầu.Cách xây dựng tìm kiếm tài liệu với LangChain.js
Chúng ta sẽ dùng 10 ghi chú ngắn trong kho tri thức, bao gồm các đoạn truy xuất chồng lắp. Tập dữ liệu có chủ đích nhỏ để có thể so sánh tìm kiếm độ tương đồng thông thường với lọc metadata và MMR.
Định nghĩa tài liệu tri thức
Mỗi
DocumentcópageContentvàmetadata. Trườngsourcevàcategoryđi cùng tài liệu trong suốt quá trình nạp và truy xuất, giúp ứng dụng giải thích nguồn gốc kết quả và giới hạn tìm kiếm vào một tập con phù hợp.Cấu hình embedding và tạo OracleVS
OracleVS.fromDocuments()là lời gọi tích hợp trung tâm. Nó khởi tạo vector store, tạo embedding cho các tài liệu đã cung cấp, và lưu nội dung, vector cùng metadata của chúng trong Oracle AI Database.Tham số
querycung cấp văn bản mẫu sẽ được embed trong quá trình khởi tạo để xác định chiều vector cần cho bảng trong cơ sở dữ liệu. Nó không được dùng để tìm kiếm các tài liệu đã lưu.DistanceStrategy.COSINEchỉ định số đo khoảng cách vector, trong khiVectorElementFormat.FLOAT32đặt định dạng phần tử vector.Trước khi chạy lại quá trình nạp, hãy dùng tên bảng minh họa mới hoặc xóa dữ liệu hiện có để tránh chèn trùng tài liệu.
OracleVSchấp nhận một hiện thực embedding tương thích LangChain, nên nhà phát triển có thể đổi nhà cung cấp embedding mà không cần thay đổi quy trình vector store tổng thể. Tuy nhiên, embedding dùng cho nạp và truy xuất phải tương thích với cột vector của Oracle.OracleVSxác định chiều vector trong quá trình khởi tạo dựa trên mô hình embedding đã cấu hình. Để kiểm tra chiều và định dạng lưu trữ của một vector đã được lưu trong Oracle AI Database, chạy câu lệnh SQL sau:Nếu bạn chuyển sang mô hình embedding có chiều khác, hãy tạo một bảng vector tương thích và tạo lại embedding tài liệu. Ngay cả khi hai mô hình tạo vector cùng số chiều, không gian embedding có thể khác nhau, vì vậy tài liệu hiện có nên được embed lại trước khi dùng mô hình mới cho truy xuất.
Với chữ ký phương thức vector store và các tùy chọn truy xuất, hãy xem tài liệu tham khảo VectorStore của LangChain.js chính thức.
Truy xuất tài liệu bằng tìm kiếm độ tương đồng
Ví dụ, lời gọi sau yêu cầu vector store
OracleVStrả về 3 tài liệu gần nhất và in metadata nguồn cùng văn bản của mỗi đoạn:Mã chuyển mỗi
Documentcủa LangChain thành một đối tượng thuần chứasourcevàpageContentđể hiển thị. Một kết quả đại diện được hiển thị bên dưới; thứ tự chính xác có thể khác nhau tùy mô hình embedding và truy vấn:Đối số thứ nhất là câu hỏi người dùng, đối số thứ hai là
k, số tài liệu tối đa cần truy xuất. LangChain.js dùng mô hình embedding đã cấu hình để chuyển câu hỏi thành vector, và Oracle AI Database thực hiện tìm kiếm độ tương đồng để tìm các tài liệu khớp gần nhất.Nếu có ít hơn
ktài liệu sau khi áp dụng điều kiện tìm kiếm và bộ lọc metadata, phương thức chỉ trả về số kết quả sẵn có. Các đối tượngDocumenttruy xuất được chứa văn bản và metadata có thể hiển thị kèm nguồn hoặc chuyển tới bước tạo câu trả lời sau đó.Kiểm tra điểm số truy xuất
Ví dụ, dùng
similaritySearchWithScorekhi bạn muốn xem khoảng cách gắn với mỗi tài liệu truy xuất:similaritySearchWithScoretrả về một khoảng cách cùng mỗi kết quả khớp. Giá trị số và chiều của nó phụ thuộc vào chiến lược khoảng cách đã cấu hình, nên không phải là phần trăm độ tin cậy phổ quát. Chỉ so sánh điểm khi dùng cùng mô hình embedding và chiến lược khoảng cách, và hãy xem xét đoạn truy xuất trước khi chọn ngưỡng.Giới hạn kết quả bằng bộ lọc metadata
Kết quả ví dụ:
Đối số thứ ba giới hạn tìm kiếm vào các mục có
category = database. Với tập này, kết quả đã lọc dễ đoán là["database-guide"]. Bộ lọc thay đổi những tài liệu nào đủ điều kiện; độ tương đồng vector vẫn xếp hạng các tài liệu đủ điều kiện.Dùng MMR để giảm kết quả lặp lại
Kết quả đại diện từ một tập có chồng lắp (thứ tự có thể khác nhau giữa các mô hình embedding và lần chạy):
MMR trước tiên xem xét một tập ứng viên (
fetchK) rồi chọnktài liệu bằng cách cân bằng mức liên quan với tính đa dạng.lambdathấp nhấn mạnh tính đa dạng hơn; giá trị cao nhấn mạnh mức liên quan hơn. Với tập chồng lắp ở trên, các nguồn được chọn có thể khác với tìm kiếm độ tương đồng thông thường, giúp thấy rõ đánh đổi trong truy xuất.Chuyển ngữ cảnh truy xuất tới ứng dụng AI
Đây là điểm bàn giao giữa truy xuất LangChain.js và lời gọi mô hình ngôn ngữ lớn (LLM): ứng dụng đã có câu hỏi cùng bằng chứng có thể kiểm tra, sẵn sàng cho prompt yêu cầu mô hình trả lời dựa trên ngữ cảnh đó.
Truy xuất và sinh (generation) là hai trách nhiệm riêng. Lúc này,
contextlà chuỗi văn bản thuần mà một mô hình chat có thể dùng. Bạn có thể cung cấp nó cho mô hình với hướng dẫn chỉ trả lời từ tài liệu đã truy xuất và trích dẫn định danh nguồn. Bản thân tích hợp cơ sở dữ liệu vẫn hoạt động ngay cả khi không có mô hình chat.Cách xác minh tích hợp
Một kiểm thử hữu ích là kiểm tra riêng quá trình nạp và từng chiến lược truy xuất. Trước tiên, xác nhận vector store được tạo mà không có lỗi cơ sở dữ liệu. Sau đó kiểm tra metadata nguồn do tìm kiếm độ tương đồng trả về, kết quả đã lọc và kết quả MMR.
Đóng pool kết nối sau khi xác minh
Phần dọn dẹp chỉ chạy sau khi nạp, truy xuất và xác minh hoàn tất. Thời gian chờ cho phép các kết nối đang dùng có một khoảng ngắn để hoàn thành. Trong máy chủ chạy lâu dài, giữ pool mở đến khi tắt dịch vụ có kiểm soát. Xem tài liệu
pool.close()của node-oracledb để biết chi tiết vòng đời.Ở thời điểm này, tệp
index.tshoàn chỉnh có thể được thực thi với:Một đầu ra xác minh đại diện là:
Thứ tự độ tương đồng và giá trị khoảng cách chính xác có thể khác theo mô hình và nhà cung cấp embedding. Kết quả đã lọc nên chứa
database-guide, trong khi kết quả MMR nên cho thấy tập nguồn truy xuất đa dạng từ tập chồng lắp.Mẹo và xử lý sự cố
Kết nối cơ sở dữ liệu thất bại
Hãy xác minh chuỗi kết nối, thông tin xác thực, dịch vụ có thể truy cập và quyền schema. Nếu bạn dùng Autonomous AI Database, xác nhận thiết lập ví hoặc TLS bắt buộc. Kiểm thử kết nối cơ sở dữ liệu độc lập trước khi gỡ lỗi truy xuất.
Xảy ra lỗi lệch chiều embedding
Các vector tạo trong quá trình nạp và vector truy vấn phải có chiều tương thích. Dùng các mô hình embedding khác nhau cho chèn và truy vấn có thể làm hỏng tìm kiếm hoặc giảm chất lượng kết quả. Giữ lựa chọn mô hình nhất quán cho một bảng.
Tìm kiếm không trả về tài liệu
Xác nhận quá trình nạp đã chèn dòng, sau đó thử lại mà không có bộ lọc metadata hạn chế. Với tập nhỏ, hãy thử các truy vấn rộng hơn và kiểm tra nội dung đã lưu.
Kết quả phù hợp nhưng lặp lại
So sánh tìm kiếm độ tương đồng với MMR bằng một tập có các đoạn chồng lắp. Tinh chỉnh
k,fetchKvàlambdađồng thời kiểm tra xem tính đa dạng có đánh đổi bằng việc bỏ sót các đoạn quan trọng không.Có nên tạo chỉ mục vector?
Với tập dữ liệu mẫu nhỏ, hãy bắt đầu bằng việc xác minh tính đúng đắn mà không tinh chỉnh chỉ mục. Khi dữ liệu tăng, đánh giá chỉ mục vector của Oracle như Hierarchical Navigable Small World (HNSW) hoặc Inverted File (IVF) tùy theo yêu cầu hiệu năng và độ chính xác của bạn. Tạo chỉ mục là một tối ưu hóa, không phải điều kiện tiên quyết để hiểu tích hợp cơ bản.
Để biết chi tiết hơn về chỉ mục vector của Oracle, hãy xem tài liệu chỉ mục vector của Oracle.
Khám phá bản triển khai tham chiếu TypeScript hoàn chỉnh
Để xem các khái niệm này kết hợp như thế nào trong một ứng dụng hoạt động, hãy khám phá bản triển khai tham chiếu LangChain.js và Oracle AI Database.
Ứng dụng được xây dựng bằng TypeScript, tập hợp quy trình nạp tài liệu, lưu trữ vector, tìm kiếm độ tương đồng, lọc metadata và MMR bằng LangChain.js và Oracle AI Database. Ứng dụng cũng cung cấp giao diện tương tác để thử nghiệm thiết lập truy xuất, kiểm tra tài liệu truy xuất và hiểu cách các chiến lược tìm kiếm khác nhau ảnh hưởng đến ngữ cảnh trả về cho ứng dụng.
Kho lưu trữ bao gồm mã nguồn và hướng dẫn thiết lập, cho phép bạn khám phá trọn vẹn tích hợp và điều chỉnh bản triển khai cho dự án của riêng bạn.
Kết luận và bước tiếp theo
Bạn đã kết nối LangChain.js với Oracle AI Database qua
OracleVS, biểu diễn tri thức dưới dạng đối tượngDocument, tạo embedding vector bền vững, và so sánh tìm kiếm độ tương đồng, lọc metadata cùng MMR. Bước tiếp theo, hãy đọc tài liệu LangChain.js chính thức và hướng dẫn tích hợp Oracle LangChain JavaScript chính thức.Nếu bạn làm việc với ngôn ngữ khác, hướng dẫn Oracle AI Vector Search của chúng tôi trình bày cùng các bước lưu trữ và truy vấn bằng Python, và hướng dẫn LangChain4j xây dựng một agent Java với Oracle AI Database.
Khóa học Retrieval Augmented Generation (RAG) với LangChain của chúng tôi là phần tiếp theo tùy chọn tập trung vào truy xuất; ví dụ bằng Python, nhưng các khái niệm quy trình áp dụng cho bản triển khai TypeScript này.