Tạo ứng dụng tác nhân AI mạnh mẽ, có trạng thái, E2E bằng Java với ADK, AlloyDB và Gemini!!

Xây dựng ứng dụng tác nhân AI mạnh mẽ, có trạng thái, E2E bằng Java với ADK, AlloyDB và Gemini!!

Thông tin về lớp học lập trình này

subjectLần cập nhật gần đây nhất: thg 5 28, 2025
account_circleTác giả: Author: Abirami Sukumaran

1. Tổng quan

Trong nhiều ngành, tính năng tìm kiếm theo bối cảnh là một chức năng quan trọng, là trung tâm của các ứng dụng. Trong một thời gian dài, tính năng Tạo sinh truy xuất đã là yếu tố thúc đẩy chính cho sự phát triển quan trọng này của công nghệ nhờ các cơ chế truy xuất dựa trên AI tạo sinh. Các mô hình tạo sinh, với cửa sổ ngữ cảnh lớn và chất lượng đầu ra ấn tượng, đang làm thay đổi AI. RAG cung cấp một cách có hệ thống để chèn ngữ cảnh vào các ứng dụng và tác nhân AI, dựa trên các cơ sở dữ liệu có cấu trúc hoặc thông tin từ nhiều phương tiện. Dữ liệu theo bối cảnh này rất quan trọng để làm rõ sự thật và độ chính xác của kết quả, nhưng những kết quả đó chính xác đến mức nào? Doanh nghiệp của bạn có phụ thuộc nhiều vào độ chính xác và mức độ liên quan của những kết quả trùng khớp theo bối cảnh này không? Vậy thì dự án này sẽ khiến bạn thích thú!

Bây giờ, hãy tưởng tượng nếu chúng ta có thể tận dụng sức mạnh của các mô hình tạo sinh và xây dựng các tác nhân tương tác có khả năng đưa ra quyết định tự động dựa trên thông tin quan trọng về ngữ cảnh và dựa trên sự thật; đó chính là những gì chúng ta sẽ xây dựng hôm nay. Chúng ta sẽ xây dựng một ứng dụng tác nhân AI toàn diện bằng cách sử dụng Bộ phát triển tác nhân (Agent Development Kit) được cung cấp bởi RAG nâng cao trong AlloyDB cho một ứng dụng phân tích bằng sáng chế.

Patent Analysis Agent (Trình phân tích bằng sáng chế) hỗ trợ người dùng tìm các bằng sáng chế phù hợp theo ngữ cảnh với văn bản tìm kiếm của họ. Khi được yêu cầu, công cụ này sẽ cung cấp nội dung giải thích rõ ràng và súc tích cũng như thông tin chi tiết bổ sung (nếu cần) về một bằng sáng chế đã chọn. Bạn đã sẵn sàng xem cách thực hiện chưa? Hãy cùng tìm hiểu nhé!

Mục tiêu

Mục tiêu rất đơn giản. Cho phép người dùng tìm kiếm bằng sáng chế dựa trên nội dung mô tả bằng văn bản, sau đó xem nội dung giải thích chi tiết về một bằng sáng chế cụ thể trong kết quả tìm kiếm. Tất cả những điều này đều được thực hiện bằng một tác nhân AI được tạo bằng Java ADK, AlloyDB, Vector Search (có chỉ mục nâng cao), Gemini và toàn bộ ứng dụng được triển khai không cần máy chủ trên Cloud Run.

Sản phẩm bạn sẽ tạo ra

Trong lớp học này, bạn sẽ:

  1. Tạo một thực thể AlloyDB và tải dữ liệu của Tập dữ liệu công khai về bằng sáng chế
  2. Triển khai tính năng Tìm kiếm vectơ nâng cao trong AlloyDB bằng cách sử dụng các tính năng đánh giá ScaNN và Recall
  3. Tạo một tác nhân bằng Java ADK
  4. Triển khai logic phía máy chủ cơ sở dữ liệu trong Cloud Functions không máy chủ Java
  5. Triển khai và kiểm thử tác nhân trong Cloud Run

Sơ đồ sau đây thể hiện luồng dữ liệu và các bước liên quan đến việc triển khai.

c22563ace65a6930.png

High level diagram representing the flow of the Patent Search Agent with AlloyDB & ADK

Yêu cầu

  • Một trình duyệt, chẳng hạn như Chrome hoặc Firefox
  • Một dự án trên Google Cloud đã bật tính năng thanh toán.

2. Trước khi bắt đầu

Tạo một dự án

  1. Trong Google Cloud Console, trên trang bộ chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
  2. Đảm bảo bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trên dự án hay không .
  3. Bạn sẽ sử dụng Cloud Shell, một môi trường dòng lệnh chạy trong Google Cloud. Nhấp vào Kích hoạt Cloud Shell ở đầu bảng điều khiển Google Cloud.

Hình ảnh nút Kích hoạt Cloud Shell

  1. Sau khi kết nối với Cloud Shell, hãy kiểm tra để đảm bảo bạn đã được xác thực và dự án được đặt thành mã dự án của bạn bằng lệnh sau:
gcloud auth list
  1. Chạy lệnh sau trong Cloud Shell để xác nhận rằng lệnh gcloud biết về dự án của bạn.
gcloud config list project
  1. Nếu dự án của bạn chưa được đặt, hãy sử dụng lệnh sau để đặt dự án:
gcloud config set project <YOUR_PROJECT_ID>
  1. Bật các API bắt buộc. Bạn có thể sử dụng lệnh gcloud trong thiết bị đầu cuối Cloud Shell:
gcloud services enable alloydb.googleapis.com compute.googleapis.com cloudresourcemanager.googleapis.com servicenetworking.googleapis.com run.googleapis.com cloudbuild.googleapis.com cloudfunctions.googleapis.com aiplatform.googleapis.com

Bạn có thể sử dụng bảng điều khiển để tìm kiếm từng sản phẩm hoặc sử dụng đường liên kết này thay cho lệnh gcloud.

Tham khảo tài liệu để biết các lệnh và cách sử dụng gcloud.

3. Thiết lập cơ sở dữ liệu

Trong lớp học lập trình này, chúng ta sẽ sử dụng AlloyDB làm cơ sở dữ liệu cho dữ liệu về bằng sáng chế. Máy chủ này sử dụng các cụm để lưu giữ tất cả tài nguyên, chẳng hạn như cơ sở dữ liệu và nhật ký. Mỗi cụm có một phiên bản chính cung cấp điểm truy cập vào dữ liệu. Bảng sẽ chứa dữ liệu thực tế.

Hãy tạo một cụm, thực thể và bảng AlloyDB nơi tập dữ liệu về bằng sáng chế sẽ được tải.

Tạo cụm và thực thể

  1. Chuyển đến trang AlloyDB trong Cloud Console. Bạn có thể dễ dàng tìm thấy hầu hết các trang trong Cloud Console bằng cách tìm kiếm các trang đó thông qua thanh tìm kiếm của bảng điều khiển.
  2. Chọn CREATE CLUSTER (TẠO CHUỖI) trên trang đó:

f76ff480c8c889aa.png

  1. Bạn sẽ thấy một màn hình như màn hình bên dưới. Tạo một cụm và thực thể với các giá trị sau (Đảm bảo các giá trị khớp với nhau trong trường hợp bạn đang nhân bản mã ứng dụng từ kho lưu trữ):
  • mã cụm: "vector-cluster"
  • mật khẩu: "alloydb"
  • PostgreSQL 15 / đề xuất sử dụng phiên bản mới nhất
  • Vùng: "us-central1"
  • Mạng: "default"

538dba58908162fb.png

  1. Khi chọn mạng mặc định, bạn sẽ thấy một màn hình như dưới đây.

Chọn THIẾT LẬP KẾT NỐI.
7939bbb6802a91bf.png

  1. Tại đó, hãy chọn "Sử dụng dải IP được phân bổ tự động" rồi chọn Tiếp tục. Sau khi xem lại thông tin, hãy chọn TẠO KẾT NỐI. 768ff5210e79676f.png
  2. Sau khi thiết lập mạng, bạn có thể tiếp tục tạo cụm. Nhấp vào CREATE CLUSTER (TẠO CLUSTER) để hoàn tất việc thiết lập cụm như minh hoạ bên dưới:

e06623e55195e16e.png

Hãy nhớ thay đổi mã phiên bản (bạn có thể tìm thấy mã này tại thời điểm định cấu hình cụm / phiên bản) thành

vector-instance. Nếu bạn không thể thay đổi giá trị này, hãy nhớ sử dụng mã nhận dạng thực thể trong tất cả các tệp tham chiếu sắp tới.

Xin lưu ý rằng quá trình tạo cụm sẽ mất khoảng 10 phút. Sau khi tạo thành công, bạn sẽ thấy một màn hình hiển thị thông tin tổng quan về cụm bạn vừa tạo.

4. Nhập dữ liệu

Bây giờ, đã đến lúc thêm một bảng chứa dữ liệu về cửa hàng. Chuyển đến AlloyDB, chọn cụm chính rồi chọn AlloyDB Studio:

847e35f1bf8a8bd8.png

Bạn có thể phải đợi thực thể của mình hoàn tất quá trình tạo. Sau khi hoàn tất, hãy đăng nhập vào AlloyDB bằng thông tin xác thực mà bạn đã tạo khi tạo cụm. Sử dụng dữ liệu sau để xác thực với PostgreSQL:

  • Tên người dùng : "postgres"
  • Cơ sở dữ liệu : "postgres"
  • Mật khẩu : "alloydb"

Sau khi bạn xác thực thành công vào AlloyDB Studio, các lệnh SQL sẽ được nhập vào Trình chỉnh sửa. Bạn có thể thêm nhiều cửa sổ Trình chỉnh sửa bằng biểu tượng dấu cộng ở bên phải cửa sổ cuối cùng.

91a86d9469d499c4.png

Bạn sẽ nhập các lệnh cho AlloyDB trong cửa sổ trình chỉnh sửa, sử dụng các tuỳ chọn Run (Chạy), Format (Định dạng) và Clear (Xoá) nếu cần.

Bật tiện ích

Để xây dựng ứng dụng này, chúng ta sẽ sử dụng các tiện ích pgvector và google_ml_integration. Tiện ích pgvector cho phép bạn lưu trữ và tìm kiếm các vectơ nhúng. Tiện ích google_ml_integration cung cấp các hàm mà bạn sử dụng để truy cập vào các điểm cuối dự đoán của Vertex AI nhằm nhận thông tin dự đoán trong SQL. Bật các tiện ích này bằng cách chạy các DDL sau:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

Nếu bạn muốn kiểm tra các tiện ích đã được bật trên cơ sở dữ liệu, hãy chạy lệnh SQL sau:

select extname, extversion from pg_extension;

Tạo bảng

Bạn có thể tạo bảng bằng cách sử dụng câu lệnh DDL bên dưới trong AlloyDB Studio:

CREATE TABLE patents_data ( id VARCHAR(25), type VARCHAR(25), number VARCHAR(20), country VARCHAR(2), date VARCHAR(20), abstract VARCHAR(300000), title VARCHAR(100000), kind VARCHAR(5), num_claims BIGINT, filename VARCHAR(100), withdrawn BIGINT, abstract_embeddings vector(768)) ;

Cột abstract_embeddings sẽ cho phép lưu trữ các giá trị vectơ của văn bản.

Cấp quyền

Chạy câu lệnh bên dưới để cấp quyền thực thi trên hàm "nhúng":

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Cấp VAI TRÒ Người dùng Vertex AI cho tài khoản dịch vụ AlloyDB

Trên bảng điều khiển IAM của Google Cloud, hãy cấp cho tài khoản dịch vụ AlloyDB (có dạng như sau: service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com) quyền truy cập vào vai trò "Người dùng Vertex AI". PROJECT_NUMBER sẽ có số dự án của bạn.

Ngoài ra, bạn có thể chạy lệnh dưới đây từ Dấu nhắc dòng lệnh Cloud Shell:

PROJECT_ID=$(gcloud config get-value project)


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

Tải dữ liệu bằng sáng chế vào cơ sở dữ liệu

Tập dữ liệu công khai về bằng sáng chế của Google trên BigQuery sẽ được dùng làm tập dữ liệu của chúng tôi. Chúng ta sẽ sử dụng AlloyDB Studio để chạy các truy vấn. Dữ liệu được lấy vào tệp insert_scripts.sql này và chúng ta sẽ chạy tệp này để tải dữ liệu về bằng sáng chế.

  1. Trong Google Cloud Console, hãy mở trang AlloyDB.
  2. Chọn cụm mới tạo và nhấp vào thực thể.
  3. Trong trình đơn Điều hướng AlloyDB, hãy nhấp vào AlloyDB Studio. Đăng nhập bằng thông tin xác thực của bạn.
  4. Mở một thẻ mới bằng cách nhấp vào biểu tượng Thẻ mới ở bên phải.
  5. Sao chép câu lệnh truy vấn insert từ tập lệnh insert_scripts.sql được đề cập ở trên vào trình chỉnh sửa. Bạn có thể sao chép 10 đến 50 câu lệnh chèn để xem nhanh trường hợp sử dụng này.
  6. Nhấp vào Chạy. Kết quả truy vấn sẽ xuất hiện trong bảng Kết quả.

5. Tạo nội dung nhúng cho dữ liệu bằng sáng chế

Trước tiên, hãy kiểm thử hàm nhúng bằng cách chạy truy vấn mẫu sau:

SELECT embedding('text-embedding-005', 'AlloyDB is a managed, cloud-hosted SQL database service.');

Thao tác này sẽ trả về vectơ nhúng, trông giống như một mảng số thực, cho văn bản mẫu trong truy vấn. Có dạng như sau:

25a1d7ef0e49e91e.png

Cập nhật trường Vector abstract_embeddings

Chạy DML bên dưới để cập nhật bản tóm tắt bằng sáng chế trong bảng bằng các nội dung nhúng tương ứng:

UPDATE patents_data set abstract_embeddings = embedding( 'text-embedding-005', abstract);

6. Tìm kiếm vectơ

Bây giờ, bảng, dữ liệu, nội dung nhúng đã sẵn sàng, hãy thực hiện Tìm kiếm vectơ theo thời gian thực cho văn bản tìm kiếm của người dùng. Bạn có thể kiểm thử việc này bằng cách chạy truy vấn bên dưới:

SELECT id || ' - ' || title as title FROM patents_data ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;

Trong truy vấn này,

  1. Văn bản mà người dùng tìm kiếm là: "Phân tích cảm xúc".
  2. Chúng ta sẽ chuyển đổi văn bản này thành văn bản nhúng trong phương thức nhúng() bằng cách sử dụng mô hình: text-embedding-005.
  3. "<=>" thể hiện việc sử dụng phương thức khoảng cách COSINE SIMILARITY.
  4. Chúng ta đang chuyển đổi kết quả của phương thức nhúng thành loại vectơ để tương thích với các vectơ được lưu trữ trong cơ sở dữ liệu.
  5. LIMIT 10 cho biết chúng ta đang chọn 10 kết quả phù hợp nhất với văn bản tìm kiếm.

AlloyDB đưa RAG Tìm kiếm vectơ lên một tầm cao mới:

Có rất nhiều tính năng được giới thiệu. Hai trong số các tính năng tập trung vào nhà phát triển là:

  1. Lọc cùng dòng
  2. Trình đánh giá thu hồi

Lọc cùng dòng

Trước đây, với tư cách là nhà phát triển, bạn phải thực hiện truy vấn Tìm kiếm vectơ và phải xử lý việc lọc và gọi lại. Trình tối ưu hoá truy vấn AlloyDB đưa ra lựa chọn về cách thực thi truy vấn bằng bộ lọc. Lọc cùng dòng là một kỹ thuật tối ưu hoá truy vấn mới cho phép trình tối ưu hoá truy vấn AlloyDB đánh giá cả điều kiện lọc siêu dữ liệu và tìm kiếm vectơ cùng lúc, tận dụng cả chỉ mục vectơ và chỉ mục trên các cột siêu dữ liệu. Điều này đã làm tăng hiệu suất gợi nhắc, cho phép nhà phát triển tận dụng những gì AlloyDB cung cấp ngay từ đầu.

Lọc cùng dòng phù hợp nhất với các trường hợp có độ chọn lọc trung bình. Khi tìm kiếm thông qua chỉ mục vectơ, AlloyDB chỉ tính toán khoảng cách cho các vectơ khớp với điều kiện lọc siêu dữ liệu (các bộ lọc chức năng trong truy vấn thường được xử lý trong mệnh đề WHERE). Điều này giúp cải thiện đáng kể hiệu suất cho các truy vấn này, bổ sung cho các ưu điểm của lọc sau hoặc lọc trước.

  1. Cài đặt hoặc cập nhật tiện ích pgvector
CREATE EXTENSION IF NOT EXISTS vector WITH VERSION '0.8.0.google-3';

Nếu bạn đã cài đặt tiện ích pgvector, hãy nâng cấp tiện ích vectơ lên phiên bản 0.8.0.google-3 trở lên để có được các tính năng của trình đánh giá gợi nhắc.

ALTER EXTENSION vector UPDATE TO '0.8.0.google-3';

Bạn chỉ cần thực hiện bước này nếu tiện ích vectơ của bạn là <0.8.0.google-3.

Lưu ý quan trọng: Nếu số lượng hàng ít hơn 100, bạn sẽ không cần tạo chỉ mục ScaNN vì chỉ mục này sẽ không áp dụng cho ít hàng hơn. Trong trường hợp đó, vui lòng bỏ qua các bước sau.

  1. Để tạo chỉ mục ScaNN, hãy cài đặt tiện ích alloydb_scann.
CREATE EXTENSION IF NOT EXISTS alloydb_scann;
  1. Trước tiên, hãy chạy Truy vấn tìm kiếm vectơ mà không có chỉ mục và không bật Bộ lọc nội tuyến:
SELECT id || ' - ' || title as title FROM patents_data 
WHERE num_claims >= 15 
ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;

Kết quả sẽ tương tự như:

6989de0fc3f0f753.png

  1. Chạy tính năng Phân tích giải thích trên trang đó: (không có chỉ mục hoặc tính năng Lọc cùng dòng)

908dcf87c7f00ed4.png

Thời gian thực thi là 2,4 mili giây

  1. Hãy tạo một chỉ mục thông thường trên trường num_claims để chúng ta có thể lọc theo trường này:
CREATE INDEX idx_patents_data_num_claims ON patents_data (num_claims);
  1. Hãy tạo chỉ mục ScaNN cho ứng dụng Tìm kiếm bằng sáng chế. Chạy mã sau trong AlloyDB Studio:
CREATE INDEX patent_index ON patents_data 
USING scann (abstract_embeddings cosine)
WITH (num_leaves=32);

Lưu ý quan trọng: (num_leaves=32) áp dụng cho tổng tập dữ liệu của chúng ta có hơn 1000 hàng. Nếu số lượng hàng ít hơn 100, bạn không cần tạo chỉ mục vì chỉ mục sẽ không áp dụng cho ít hàng.

  1. Đặt tính năng Lọc cùng dòng được bật trên Chỉ mục ScaNN:
SET scann.enable_inline_filtering = on
  1. Bây giờ, hãy chạy cùng một truy vấn có bộ lọc và Tìm kiếm vectơ:
SELECT id || ' - ' || title as title FROM patents_data 
WHERE num_claims >= 15 
ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;

aa54cba2b2ada2cb.png

Như bạn có thể thấy, thời gian thực thi giảm đáng kể cho cùng một Tìm kiếm vectơ. Chế độ Lọc cùng dòng đã truyền chỉ mục ScaNN vào Tìm kiếm vectơ để thực hiện việc này!!!

Tiếp theo, hãy đánh giá khả năng gợi nhắc cho Tìm kiếm vectơ có hỗ trợ ScaNN này.

Trình đánh giá thu hồi

Mức độ gợi nhắc trong tính năng tìm kiếm theo mức độ tương đồng là tỷ lệ phần trăm số lượng thực thể có liên quan được truy xuất từ một lượt tìm kiếm, tức là số lượng kết quả dương tính thật. Đây là chỉ số phổ biến nhất dùng để đo lường chất lượng của kết quả tìm kiếm. Một nguồn gây tổn thất về tỷ lệ gợi nhắc đến từ sự khác biệt giữa thuật toán tìm kiếm gần đúng bằng thuật toán kề cận nhất (aNN) và thuật toán tìm kiếm k (chính xác) bằng thuật toán kề cận nhất (kNN). Các chỉ mục vectơ như ScaNN của AlloyDB triển khai các thuật toán aNN, cho phép bạn tăng tốc độ tìm kiếm vectơ trên các tập dữ liệu lớn để đổi lấy một mức độ đánh đổi nhỏ về khả năng gợi nhắc. Giờ đây, AlloyDB cho phép bạn đo lường sự đánh đổi này ngay trong cơ sở dữ liệu cho từng truy vấn và đảm bảo rằng sự đánh đổi này ổn định theo thời gian. Bạn có thể cập nhật các tham số truy vấn và chỉ mục để phản hồi thông tin này nhằm đạt được kết quả và hiệu suất tốt hơn.

Bạn có thể tìm thấy tỷ lệ thu hồi cho một truy vấn vectơ trên chỉ mục vectơ cho một cấu hình nhất định bằng cách sử dụng hàm evaluate_query_recall. Hàm này cho phép bạn điều chỉnh các tham số để đạt được kết quả truy vấn vectơ mà bạn muốn. Mức độ gợi nhắc là chỉ số dùng để đánh giá chất lượng tìm kiếm và được xác định là tỷ lệ phần trăm kết quả trả về gần nhất một cách khách quan với các vectơ truy vấn. Hàm evaluate_query_recall được bật theo mặc định.

Lưu ý quan trọng:

Nếu bạn gặp lỗi từ chối cấp quyền trên chỉ mục HNSW trong các bước sau, hãy bỏ qua toàn bộ phần đánh giá khả năng gợi nhắc này. Điều này có thể liên quan đến các hạn chế về quyền truy cập tại thời điểm này vì phiên bản này mới được phát hành tại thời điểm lớp học lập trình này được ghi lại.

  1. Đặt cờ Bật tính năng quét chỉ mục trên chỉ mục ScaNN và chỉ mục HNSW:
SET scann.enable_indexscan = on
SET hnsw.enable_index_scan = on
  1. Chạy truy vấn sau trong AlloyDB Studio:
SELECT
  *
FROM
  evaluate_query_recall($$
  SELECT
    id || ' - ' || title AS title,
    abstract
  FROM
    patents_data
    where num_claims >= 15
  ORDER BY
    abstract_embeddings <=> embedding('text-embedding-005',
      'sentiment analysis')::vector
  LIMIT 25 $$,
    '{"scann.num_leaves_to_search":1, "scann.pre_reordering_num_neighbors":10}',
    ARRAY['scann']);

Hàm evaluate_query_recall nhận truy vấn làm tham số và trả về khả năng gợi nhắc của truy vấn đó. Tôi đang sử dụng cùng một truy vấn mà tôi đã dùng để kiểm tra hiệu suất làm truy vấn đầu vào của hàm. Tôi đã thêm SCaNN làm phương thức lập chỉ mục. Để biết thêm các tuỳ chọn tham số, hãy tham khảo tài liệu.

Kết quả gợi nhắc cho cụm từ tìm kiếm Tìm kiếm vectơ mà chúng ta đã sử dụng:

c98f38fbe6a0b6c5.png

Tôi thấy RECALL (LƯỢT NHẬN LẠI) là 70%. Bây giờ, tôi có thể sử dụng thông tin này để thay đổi các tham số chỉ mục, phương thức và tham số truy vấn, đồng thời cải thiện khả năng gợi nhắc cho Tìm kiếm vectơ này!

Tôi đã sửa đổi số lượng hàng trong tập hợp kết quả thành 7 (từ 10 trước đó) và tôi thấy RECALL (TỶ LỆ LẠI NHẬN) cải thiện một chút, tức là 86%.

c12f7b92b8481ceb.png

Điều này có nghĩa là theo thời gian thực, tôi có thể thay đổi số lượng kết quả trùng khớp mà người dùng nhìn thấy để cải thiện mức độ liên quan của các kết quả trùng khớp đó theo ngữ cảnh tìm kiếm của người dùng.

Được rồi! Đã đến lúc triển khai logic cơ sở dữ liệu và chuyển sang tác nhân!!!

7. Chuyển logic cơ sở dữ liệu sang web mà không cần máy chủ

Bạn đã sẵn sàng đưa ứng dụng này lên web chưa? Hãy làm theo các bước sau:

  1. Chuyển đến phần Hàm Cloud Run trong Google Cloud Console để TẠO một Hàm Cloud Run mới hoặc sử dụng đường liên kết: https://console.cloud.google.com/functions/add.
  2. Chọn Môi trường là "Hàm Cloud Run". Cung cấp Tên hàm "patent-search" và chọn Khu vực là "us-central1". Đặt Authentication (Xác thực) thành "Allow unauthenticated invocations" (Cho phép các lệnh gọi chưa xác thực) rồi nhấp vào NEXT (TIẾP THEO). Chọn Java 17 làm môi trường thời gian chạy và Trình chỉnh sửa cùng dòng cho mã nguồn.
  3. Theo mặc định, lớp này sẽ đặt Điểm truy cập thành "gcfv2.HelloHttpFunction". Thay thế mã phần giữ chỗ trong HelloHttpFunction.java và pom.xml của Hàm chạy trên đám mây bằng mã từ " PatentSearch.java" và " pom.xml" tương ứng. Thay đổi tên tệp lớp thành PatentSearch.java.
  4. Hãy nhớ thay đổi phần giữ chỗ ************* và thông tin xác thực kết nối AlloyDB bằng các giá trị của bạn trong tệp Java. Thông tin xác thực AlloyDB là những thông tin mà chúng ta đã sử dụng ở đầu lớp học lập trình này. Nếu bạn đã sử dụng các giá trị khác, vui lòng sửa đổi các giá trị đó trong tệp Java.
  5. Nhấp vào Triển khai.

BƯỚC QUAN TRỌNG:

Sau khi triển khai, để cho phép Hàm trên đám mây truy cập vào thực thể cơ sở dữ liệu AlloyDB, chúng ta sẽ tạo trình kết nối VPC.

Sau khi thiết lập để triển khai, bạn sẽ có thể thấy các hàm trong bảng điều khiển Google Cloud Run Functions. Tìm hàm mới tạo (patent-search), nhấp vào hàm đó, sau đó nhấp vào EDIT AND DEPLOY NEW REVISIONS (CHỈNH SỬA VÀ TRIỂN KHAI BẢN SỬA ĐỔI MỚI) (được xác định bằng biểu tượng EDIT (bút) ở đầu bảng điều khiển Cloud Run Functions) rồi thay đổi những nội dung sau:

  1. Chuyển đến thẻ Kết nối mạng:

828cd861864d99ea.png

  1. Chọn "Kết nối với VPC cho lưu lượng truy cập đi", sau đó chọn "Sử dụng trình kết nối Quyền truy cập VPC không máy chủ"
  2. Trong trình đơn thả xuống Network (Mạng), hãy nhấp vào trình đơn thả xuống Network (Mạng) rồi chọn tuỳ chọn "Add New VPC Connector" (Thêm trình kết nối VPC mới) (nếu bạn chưa định cấu hình trình kết nối mặc định) và làm theo hướng dẫn bạn thấy trên hộp thoại bật lên:

6559ccfd10e597f2.png

  1. Đặt tên cho Trình kết nối VPC và đảm bảo khu vực giống với phiên bản của bạn. Giữ nguyên giá trị Mạng là mặc định và đặt Mạng con thành Dải IP tuỳ chỉnh với dải IP là 10.8.0.0 hoặc một dải IP tương tự có sẵn.
  2. Mở rộng phần Hiển thị chế độ cài đặt điều chỉnh theo tỷ lệ và đảm bảo bạn đã thiết lập cấu hình chính xác như sau:

199b0ccd80215004.png

  1. Nhấp vào CREATE (TẠO) và trình kết nối này sẽ xuất hiện trong phần cài đặt đầu ra.
  2. Chọn trình kết nối mới tạo.
  3. Chọn định tuyến tất cả lưu lượng truy cập thông qua trình kết nối VPC này.
  4. Nhấp vào TIẾP THEO rồi nhấp vào TRÌNH DƯƠNG.
  5. Sau khi triển khai Hàm trên đám mây đã cập nhật, bạn sẽ thấy điểm cuối được tạo. Sao chép và thay thế trong lệnh sau:
PROJECT_ID=$(gcloud config get-value project)

curl -X POST <<YOUR_ENDPOINT>> \
  -H 'Content-Type: application/json' \
  -d '{"search":"Sentiment Analysis"}'

Vậy là xong! Bạn có thể thực hiện một Tìm kiếm vectơ tương đồng theo bối cảnh nâng cao bằng cách sử dụng mô hình Nhúng trên dữ liệu AlloyDB một cách đơn giản như vậy.

8. Hãy xây dựng tác nhân bằng Java ADK

Trước tiên, hãy bắt đầu với dự án Java trong trình chỉnh sửa.

  1. Chuyển đến Cửa sổ dòng lệnh Cloud Shell

https://shell.cloud.google.com/?fromcloudshell=true&show=ide%2Cterminal

  1. Uỷ quyền khi được nhắc
  2. Chuyển sang Trình chỉnh sửa Cloud Shell bằng cách nhấp vào biểu tượng trình chỉnh sửa ở đầu bảng điều khiển Cloud Shell

f913b886324e5196.png

  1. Trong bảng điều khiển Cloud Shell Editor (Trình chỉnh sửa Cloud Shell) xuất hiện, hãy tạo một thư mục mới và đặt tên là "adk-agents"

Nhấp vào tạo thư mục mới trong thư mục gốc của màn hình shell trên đám mây như minh hoạ dưới đây:

94c9804697614a94.png

Đặt tên là "adk-agents":

37445dc1fe08f74c.png

  1. Tạo cấu trúc thư mục sau và các tệp trống có tên tệp tương ứng trong cấu trúc bên dưới:
adk-agents/
 └—— pom.xml
 └—— src/ 
     └—— main/
         └—— java/
             └—— agents/
                 └—— App.java
  1. Mở kho lưu trữ github trong một thẻ riêng và sao chép mã nguồn cho các tệp App.java và pom.xml.
  2. Nếu đã mở trình chỉnh sửa trong một thẻ mới bằng biểu tượng "Mở trong thẻ mới" ở góc trên cùng bên phải, thì bạn có thể mở thiết bị đầu cuối ở cuối trang. Bạn có thể mở song song cả trình chỉnh sửa và dòng lệnh để có thể thao tác một cách tự do.
  3. Sau khi sao chép, hãy chuyển về bảng điều khiển Trình chỉnh sửa Cloud Shell
  4. Vì chúng ta đã tạo Hàm Cloud Run, nên bạn không cần sao chép các tệp hàm Cloud Run từ thư mục kho lưu trữ.

Bắt đầu sử dụng SDK ADK Java

Cách thực hiện khá đơn giản. Trước tiên, bạn cần đảm bảo rằng các bước sau đây được đề cập trong bước sao chép:

  1. Thêm phần phụ thuộc:

Thêm các cấu phần phần mềm google-adk và google-adk-dev (dành cho giao diện người dùng web) vào pom.xml.

<!-- The ADK core dependency -->
        <dependency>
            <groupId>com.google.adk</groupId>
            <artifactId>google-adk</artifactId>
            <version>0.1.0</version>
        </dependency>
        <!-- The ADK dev web UI to debug your agent -->
        <dependency>
            <groupId>com.google.adk</groupId>
            <artifactId>google-adk-dev</artifactId>
            <version>0.1.0</version>
        </dependency>

Hãy nhớ tham chiếu pom.xml từ kho lưu trữ nguồn vì có các phần phụ thuộc và cấu hình khác cần thiết để ứng dụng có thể chạy.

  1. Định cấu hình dự án:

Đảm bảo rằng phiên bản Java (nên dùng phiên bản 17 trở lên) và chế độ cài đặt trình biên dịch Maven được định cấu hình chính xác trong pom.xml. Bạn có thể định cấu hình dự án theo cấu trúc dưới đây:

adk-agents/
 └—— pom.xml
 └—— src/ 
     └—— main/
         └—— java/
             └—— agents/
                 └—— App.java
  1. Xác định tác nhân và các công cụ của tác nhân (App.java):

Đây là điểm mạnh của SDK Java ADK. Chúng ta xác định tác nhân, chức năng (hướng dẫn) và các công cụ mà tác nhân có thể sử dụng.

Tìm phiên bản đơn giản của một số đoạn mã của lớp tác nhân chính tại đây. Để biết toàn bộ dự án, hãy tham khảo kho lưu trữ dự án tại đây.

// App.java (Simplified Snippets)
package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.InvocationContext;
import com.google.adk.tools.Annotations.Schema;
import com.google.adk.tools.FunctionTool;
// ... other imports

public class App {

    static FunctionTool searchTool = FunctionTool.create(App.class, "getPatents");
    static FunctionTool explainTool = FunctionTool.create(App.class, "explainPatent");

    public static BaseAgent ROOT_AGENT = initAgent();

    public static BaseAgent initAgent() {
        return LlmAgent.builder()
            .name("patent-search-agent")
            .description("Patent Search agent")
            .model("gemini-2.0-flash-001") // Specify your desired Gemini model
            .instruction(
                """
                You are a helpful patent search assistant capable of 2 things:
                // ... complete instructions ...
                """)
            .tools(searchTool, explainTool)
            .outputKey("patents") // Key to store tool output in session state
            .build();
    }

    // --- Tool: Get Patents ---
    public static Map<String, String> getPatents(
        @Schema(name="searchText",description = "The search text for which the user wants to find matching patents")
        String searchText) {
        try {
            String patentsJson = vectorSearch(searchText); // Calls our Cloud Run Function
            return Map.of("status", "success", "report", patentsJson);
        } catch (Exception e) {
            // Log error
            return Map.of("status", "error", "report", "Error fetching patents.");
        }
    }

    // --- Tool: Explain Patent (Leveraging InvocationContext) ---
    public static Map<String, String> explainPatent(
        @Schema(name="patentId",description = "The patent id for which the user wants to get more explanation for, from the database") 
    String patentId, 
    @Schema(name="ctx",description = "The list of patent abstracts from the database from which the user can pick the one to get more explanation for") 
    InvocationContext ctx) { // Note the InvocationContext
        try {
            // Retrieve previous patent search results from session state
            String previousResults = (String) ctx.session().state().get("patents");
            if (previousResults != null && !previousResults.isEmpty()) {
// Logic to find the specific patent abstract from 'previousResults' by 'patentId'
                String[] patentEntries = previousResults.split("\n\n\n\n"); 
                for (String entry : patentEntries) {
                    if (entry.contains(patentId)) { // Simplified check
       // The agent will then use its instructions to summarize this 'report'
                        return Map.of("status", "success", "report", entry);
                    }
                }
            }
            return Map.of("status", "error", "report", "Patent ID not found in previous search.");
        } catch (Exception e) {
            // Log error
            return Map.of("status", "error", "report", "Error explaining patent.");
        }
    }

    public static void main(String[] args) throws Exception {
        InMemoryRunner runner = new InMemoryRunner(ROOT_AGENT);
        // ... (Session creation and main input loop - shown in your source)
    }
}

Các thành phần chính của mã Java ADK được làm nổi bật:

  1. LlmAgent.builder(): API Fluent để định cấu hình tác nhân.
  2. .instruction(...): Cung cấp câu lệnh và nguyên tắc cốt lõi cho LLM, bao gồm cả thời điểm sử dụng công cụ nào.
  3. FunctionTool.create(App.class, "methodName"): Dễ dàng đăng ký các phương thức Java làm công cụ mà tác nhân có thể gọi. Chuỗi tên phương thức phải khớp với một phương thức tĩnh công khai thực tế.
  4. @Schema(description = ...): Chú thích các tham số công cụ, giúp LLM hiểu được dữ liệu đầu vào mà mỗi công cụ mong đợi. Nội dung mô tả này rất quan trọng để lựa chọn công cụ và điền thông số chính xác.
  5. InvocationContext ctx: Được tự động chuyển đến các phương thức công cụ, cấp quyền truy cập vào trạng thái phiên (ctx.session().state()), thông tin người dùng và nhiều thông tin khác.
  6. .outputKey("patents"): Khi một công cụ trả về dữ liệu, ADK có thể tự động lưu trữ dữ liệu đó trong trạng thái phiên theo khoá này. Đây là cách explainPatent có thể truy cập vào kết quả từ getPatents.
  7. VECTOR_SEARCH_ENDPOINT: Đây là biến chứa logic chức năng cốt lõi cho phần Hỏi và đáp theo bối cảnh dành cho người dùng trong trường hợp sử dụng tìm kiếm bằng sáng chế.
  8. Mục hành động tại đây: Bạn cần đặt giá trị điểm cuối đã triển khai mới nhất sau khi triển khai bước Hàm chạy trên đám mây Java trong phần trước.
  9. searchTool: Công cụ này tương tác với người dùng để tìm các kết quả trùng khớp về bằng sáng chế phù hợp theo ngữ cảnh trong cơ sở dữ liệu bằng sáng chế cho văn bản tìm kiếm của người dùng.
  10. explainTool: Yêu cầu người dùng cung cấp một bằng sáng chế cụ thể để tìm hiểu sâu. Sau đó, ứng dụng này sẽ tóm tắt bản tóm tắt bằng sáng chế và có thể trả lời thêm câu hỏi của người dùng dựa trên thông tin chi tiết về bằng sáng chế mà ứng dụng có.

Lưu ý quan trọng: Hãy nhớ thay thế biến VECTOR_SEARCH_ENDPOINT bằng điểm cuối CRF đã triển khai.

Tận dụng InvocationContext cho các hoạt động tương tác có trạng thái

Một trong những tính năng quan trọng để xây dựng các tác nhân hữu ích là quản lý trạng thái trong nhiều lượt của một cuộc trò chuyện. InvocationContext của ADK giúp bạn thực hiện việc này một cách dễ dàng.

Trong App.java:

  1. Khi xác định initAgent(), chúng ta sử dụng .outputKey("patents"). Thao tác này cho ADK biết rằng khi một công cụ (chẳng hạn như getPatents) trả về dữ liệu trong trường báo cáo, dữ liệu đó phải được lưu trữ trong trạng thái phiên theo khoá "patents".
  2. Trong phương thức công cụ explainPatent, chúng ta chèn InvocationContext ctx:
public static Map<String, String> explainPatent(
    @Schema(description = "...") String patentId, InvocationContext ctx) {
    String previousResults = (String) ctx.session().state().get("patents");
    // ... use previousResults ...
}

Điều này cho phép công cụ explainPatent truy cập vào danh sách bằng sáng chế do công cụ getPatents tìm nạp ở lượt trước, giúp cuộc trò chuyện có trạng thái và nhất quán.

9. Kiểm thử CLI cục bộ

Xác định biến môi trường

Bạn cần xuất hai biến môi trường:

  1. Khoá Gemini mà bạn có thể lấy từ AI Studio:

Để làm việc đó, hãy truy cập vào https://aistudio.google.com/apikey để lấy Khoá API cho Dự án Google Cloud đang hoạt động mà bạn đang triển khai ứng dụng này và lưu khoá ở một nơi nào đó:

ae2db169e6a94e4a.png

  1. Sau khi bạn nhận được khoá, hãy mở Cloud Shell Terminal và chuyển đến thư mục mới mà chúng ta vừa tạo adk-agents bằng cách chạy lệnh sau:
cd adk-agents
  1. Một biến để chỉ định rằng chúng ta không sử dụng Vertex AI lần này.
export GOOGLE_GENAI_USE_VERTEXAI=FALSE
export GOOGLE_API_KEY=AIzaSyDF...
  1. Chạy tác nhân đầu tiên trên CLI

Để chạy tác nhân đầu tiên này, hãy sử dụng lệnh Maven sau trong dòng lệnh:

mvn compile exec:java -DmainClass="agents.App"

Bạn sẽ thấy câu trả lời tương tác của tác nhân trong thiết bị đầu cuối.

10. Triển khai lên Cloud Run

Việc triển khai tác nhân Java ADK cho Cloud Run cũng tương tự như triển khai bất kỳ ứng dụng Java nào khác:

  1. Dockerfile: Tạo Dockerfile để đóng gói ứng dụng Java.
  2. Tạo và đẩy hình ảnh Docker: Sử dụng Google Cloud Build và Artifact Registry.
  3. Bạn có thể thực hiện bước trên và triển khai lên Cloud Run chỉ bằng một lệnh:
gcloud run deploy --source . --set-env-vars GOOGLE_API_KEY=<<Your_Gemini_Key>>

Tương tự, bạn sẽ triển khai Hàm chạy trên đám mây Java (gcfv2.PatentSearch). Ngoài ra, bạn có thể tạo và triển khai Hàm Cloud Run Java cho logic cơ sở dữ liệu ngay trong bảng điều khiển Hàm Cloud Run.

11. Kiểm thử bằng giao diện người dùng web

ADK đi kèm với một giao diện người dùng Web tiện dụng để kiểm thử và gỡ lỗi cục bộ cho tác nhân của bạn. Khi bạn chạy App.java cục bộ (ví dụ: mvn exec:java -Dexec.mainClass="agents.App" nếu được định cấu hình hoặc chỉ chạy phương thức chính), ADK thường khởi động một máy chủ web cục bộ.

Giao diện người dùng ADK Web cho phép bạn:

  1. Gửi tin nhắn cho nhân viên hỗ trợ.
  2. Xem các sự kiện (thông báo của người dùng, lệnh gọi công cụ, phản hồi của công cụ, phản hồi của LLM).
  3. Kiểm tra trạng thái phiên.
  4. Xem nhật ký và dấu vết.

Thông tin này rất có giá trị trong quá trình phát triển để hiểu cách trợ lý xử lý các yêu cầu và sử dụng các công cụ của trợ lý. Điều này giả định mainClass trong pom.xml được đặt thành com.google.adk.web.AdkWebServer và tác nhân của bạn được đăng ký với mainClass đó, hoặc bạn đang chạy một trình chạy kiểm thử cục bộ hiển thị điều này.

Khi chạy App.java bằng InMemoryRunner và Scanner cho dữ liệu đầu vào của bảng điều khiển, bạn đang kiểm thử logic của tác nhân cốt lõi. Giao diện người dùng web là một thành phần riêng biệt để mang lại trải nghiệm gỡ lỗi trực quan hơn, thường được dùng khi ADK phân phát tác nhân của bạn qua HTTP.

Bạn có thể sử dụng lệnh Maven sau từ thư mục gốc để khởi chạy máy chủ cục bộ SpringBoot:

mvn compile exec:java -Dexec.args="--adk.agents.source-dir=src/main/java/ --logging.level.com.google.adk.dev=TRACE --logging.level.com.google.adk.demo.agents=TRACE"

Bạn thường có thể truy cập vào giao diện này tại URL mà lệnh trên trả về. Nếu ứng dụng đó đã được triển khai trên Cloud Run, thì bạn có thể truy cập vào ứng dụng đó từ đường liên kết đã triển khai trên Cloud Run.

Bạn sẽ thấy kết quả trong một giao diện tương tác.

Hãy xem video bên dưới để biết thông tin về Đại diện bằng sáng chế mà chúng tôi đã triển khai:

Bản minh hoạ về một đại lý kiểm soát chất lượng bằng sáng chế bằng tính năng Tìm kiếm nội tuyến và Đánh giá khả năng gợi nhắc của AlloyDB!

ca7b0fc4fe571dd6.png

12. Dọn dẹp

Để tránh bị tính phí cho tài khoản Google Cloud của bạn đối với các tài nguyên được sử dụng trong bài đăng này, hãy làm theo các bước sau:

  1. Trong Google Cloud Console, hãy chuyển đến https://console.cloud.google.com/cloud-resource-manager?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog
  2. Trang https://console.cloud.google.com/cloud-resource-manager?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog.
  3. Trong danh sách dự án, hãy chọn dự án mà bạn muốn xoá, rồi nhấp vào Xoá.
  4. Trong hộp thoại, hãy nhập mã dự án, sau đó nhấp vào Shut down (Tắt) để xoá dự án.

13. Xin chúc mừng

Xin chúc mừng! Bạn đã xây dựng thành công Tác nhân phân tích bằng sáng chế trong Java bằng cách kết hợp các tính năng của ADK, https://cloud.google.com/alloydb/docs?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog, Vertex AI và Tìm kiếm vectơ. Ngoài ra, chúng tôi đã tiến một bước dài trong việc tạo ra các nội dung tìm kiếm tương đồng theo ngữ cảnh, mang tính biến đổi, hiệu quả và thực sự có ý nghĩa.

Bắt đầu ngay hôm nay!

Tài liệu về ADK: [Đường liên kết đến Tài liệu chính thức về ADK Java]

Mã nguồn của Tác nhân phân tích bằng sáng chế: [Đường liên kết đến Kho lưu trữ GitHub (hiện đã công khai) của bạn]

Tác nhân mẫu Java: [đường liên kết đến kho lưu trữ adk-samples]

Tham gia Cộng đồng ADK: https://www.reddit.com/r/agentdevelopmentkit/

Chúc bạn xây dựng nhân viên hỗ trợ vui vẻ!

bug_report Báo cáo lỗi