1. Tổng quan
Trong lớp học lập trình này, bạn sẽ tạo Neighbor Loop, một ứng dụng chia sẻ hàng hoá dư thừa bền vững, coi trí thông minh là một thành phần quan trọng của lớp dữ liệu.
Bằng cách tích hợp Gemini 3.0 Flash và tính năng tích hợp ML của Cloud SQL, bạn sẽ chuyển từ bộ nhớ cơ bản sang lĩnh vực Trí tuệ trong cơ sở dữ liệu. Bạn sẽ tìm hiểu cách thực hiện phân tích mặt hàng đa phương thức và khám phá ngữ nghĩa ngay trong SQL.
Sản phẩm bạn sẽ tạo ra
Một ứng dụng web "vuốt để ghép" hiệu suất cao để chia sẻ đồ dùng dư thừa trong cộng đồng.
Kiến thức bạn sẽ học được
- Cung cấp bằng một lần nhấp: Cách thiết lập Cloud SQL và phiên bản được thiết kế cho khối lượng công việc AI.
- Nhúng trong cơ sở dữ liệu: Tạo vectơ text-embedding-005 ngay trong câu lệnh INSERT.
- Lý luận đa phương thức: Sử dụng Gemini 3.0 Flash để "nhìn" các mục và tự động tạo tiểu sử theo phong cách hẹn hò một cách dí dỏm.
- Khám phá ngữ nghĩa: Thực hiện "kiểm tra cảm xúc" dựa trên logic trong các truy vấn SQL bằng cách sử dụng hàm ai.if() để lọc kết quả dựa trên ngữ cảnh, chứ không chỉ dựa trên toán học.
Kiến trúc
Neighbor Loop bỏ qua các điểm tắc nghẽn truyền thống ở lớp ứng dụng. Thay vì trích xuất dữ liệu để xử lý, chúng tôi sử dụng:
- Cloud SQL + Tích hợp ML: Để tạo và lưu trữ các vectơ theo thời gian thực.
- Google Cloud Storage: Để lưu trữ hình ảnh
- Gemini 3.0 Flash: Để thực hiện suy luận dưới một giây về dữ liệu hình ảnh và văn bản trực tiếp thông qua SQL.
- Cloud Run: Để lưu trữ một phụ trợ Flask nhẹ, có một tệp duy nhất.
Yêu cầu
2. Trước khi bắt đầu
Tạo dự án
- Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
- Đả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 một dự án hay không.
- 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.
- Sau khi kết nối với Cloud Shell, bạn có thể kiểm tra để đảm bảo rằng 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
- 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
- Nếu bạn chưa đặt dự án, hãy dùng lệnh sau để đặt:
gcloud config set project <YOUR_PROJECT_ID>
- Bật các API bắt buộc: Truy cập vào đường liên kết rồi bật các API.
Ngoài ra, bạn có thể dùng lệnh gcloud cho việc này. Tham khảo tài liệu để biết các lệnh và cách sử dụng gcloud.
Các lỗi thường gặp và cách khắc phục sự cố
Hội chứng "Dự án ma" | Bạn đã chạy |
Rào chắn thanh toán | Bạn đã bật dự án nhưng quên tài khoản thanh toán. Cloud SQL sẽ không khởi động nếu thông tin thanh toán trống. |
Độ trễ truyền API | Bạn đã nhấp vào "Bật API", nhưng dòng lệnh vẫn hiển thị |
3. Thiết lập cơ sở dữ liệu
Trong phòng thí nghiệm này, chúng ta sẽ sử dụng Cloud SQL cho PostgreSQL làm cơ sở dữ liệu cho dữ liệu kiểm thử.
Hãy tạo một phiên bản Cloud SQL để tải tập dữ liệu kiểm thử.
- Nhấp vào nút hoặc Sao chép đường liên kết bên dưới vào trình duyệt mà bạn đã đăng nhập người dùng Google Cloud Console.
- Sau khi hoàn tất bước này, kho lưu trữ sẽ được sao chép vào trình chỉnh sửa Cloud Shell cục bộ và bạn có thể chạy lệnh bên dưới từ thư mục dự án (bạn cần đảm bảo rằng bạn đang ở trong thư mục dự án):
sh run.sh
- Bây giờ, hãy sử dụng giao diện người dùng (nhấp vào đường liên kết trong thiết bị đầu cuối hoặc nhấp vào đường liên kết "xem trước trên web" trong thiết bị đầu cuối.
- Nhập thông tin chi tiết về mã dự án và tên phiên bản để bắt đầu.
- Hãy đi lấy một tách cà phê trong khi nhật ký cuộn và bạn có thể đọc về cách nhật ký thực hiện việc này ở chế độ nền tại đây.
Các lỗi thường gặp và cách khắc phục sự cố
Khu vực không khớp | Nếu đã bật API trong |
Thời gian chờ của Cloud Shell | Nếu bạn giải lao uống cà phê trong 30 phút, Cloud Shell có thể chuyển sang chế độ ngủ và ngắt kết nối quy trình |
4. Cung cấp giản đồ
Sau khi bạn chạy phiên bản Cloud SQL, hãy chuyển đến trình chỉnh sửa SQL của Cloud SQL Studio để bật các tiện ích AI và cung cấp giản đồ.
Bạn có thể phải đợi phiên bản của mình được tạo xong. Sau khi tạo, hãy đăng nhập vào phiên bản Cloud SQL bằng thông tin đăng nhập mà bạn đã tạo khi tạo phiên bản đó. 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 : "
cloudsql" (hoặc mật khẩu bạn đặt tại thời điểm tạo)
Sau khi bạn xác thực thành công vào Cloud SQL 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 cách nhấp vào dấu cộng ở bên phải cửa sổ cuối cùng.
Bạn sẽ nhập các lệnh cho Cloud SQL trong cửa sổ trình chỉnh sửa, sử dụng các lựa chọn Chạy, Định dạng và Xoá khi cần.
Bật tiện ích
Để tạo ứ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 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 bằng 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;
Tạo bảng
Bạn có thể tạo một bảng bằng câu lệnh DDL bên dưới trong Cloud SQL Studio:
-- Items Table (The "Profile" you swipe on)
CREATE TABLE items (
item_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
owner_id UUID,
provider_name TEXT,
provider_phone TEXT,
title TEXT,
bio TEXT,
category TEXT,
image_url TEXT,
item_vector VECTOR(768),
status TEXT DEFAULT 'available',
created_at TIMESTAMP DEFAULT NOW()
);
-- Swipes Table (The Interaction)
CREATE TABLE swipes (
swipe_id SERIAL PRIMARY KEY,
swiper_id UUID,
item_id UUID REFERENCES items(item_id),
direction TEXT CHECK (direction IN ('left', 'right')),
is_match BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP DEFAULT NOW()
);
Cột item_vector 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 cho hàm "embedding":
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Bật tính năng tích hợp ML
Để tận dụng các tính năng học máy ngay trong cơ sở dữ liệu, bạn cần bật cờ tích hợp ML.
Bạn có thể chạy lệnh bên dưới từ Cloud Shell Terminal:
INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"
gcloud sql instances patch $INSTANCE_NAME --tier=db-custom-1-3840
gcloud sql instances patch $INSTANCE_NAME \
--database-flags=cloudsql.enable_google_ml_integration=on
gcloud sql instances patch $INSTANCE_NAME --enable-google-ml-integration
Cấp VAI TRÒ Người dùng Vertex AI cho tài khoản dịch vụ Cloud SQL
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ụ Cloud SQL (có dạng như sau: service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.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 bên dưới trong Cloud Shell Terminal:
INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"
PROJECT_ID=$(gcloud config get-value project)
SA_EMAIL=$(gcloud sql instances describe $INSTANCE_NAME --format='value(serviceAccountEmailAddress)')
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SA_EMAIL" \
--role="roles/aiplatform.user"
Đăng ký mô hình Gemini 3 Flash trong Cloud SQL
Chạy câu lệnh SQL bên dưới trong Trình chỉnh sửa truy vấn Cloud SQL
CALL google_ml.create_model(
model_id => 'gemini-3-flash-preview',
model_request_url => 'https://aiplatform.googleapis.com/v1/projects/<<YOUR_PROJECT_ID>>/locations/global/publishers/google/models/gemini-3-flash-preview:generateContent',
model_qualified_name => 'gemini-3-flash-preview',
model_provider => 'google',
model_type => 'generic',
model_auth_type => 'cloudsql_service_agent_iam'
);
--replace <<YOUR_PROJECT_ID>> with your project id.
Các lỗi thường gặp và cách khắc phục sự cố
Vòng lặp "Quên mật khẩu" | Nếu bạn sử dụng chế độ thiết lập "Một lần nhấp" và không nhớ mật khẩu, hãy chuyển đến trang Thông tin cơ bản về phiên bản trong bảng điều khiển rồi nhấp vào "Chỉnh sửa" để đặt lại mật khẩu |
Lỗi "Không tìm thấy tiện ích" | Nếu |
Khoảng trống lan truyền IAM | Bạn đã chạy lệnh IAM |
Kích thước vectơ không khớp | Bảng |
Lỗi chính tả mã dự án | Trong lệnh gọi |
Đã tắt tính năng tích hợp Vertex AI | Chạy |
5. Lưu trữ hình ảnh (Google Cloud Storage)
Để lưu trữ ảnh của các mặt hàng dư thừa, chúng tôi sử dụng một vùng lưu trữ GCS. Đối với mục đích của ứng dụng minh hoạ này, chúng ta muốn hình ảnh có thể truy cập công khai để hiển thị ngay lập tức trong thẻ vuốt.
- Tạo một nhóm lưu trữ: Tạo một nhóm lưu trữ mới trong dự án GCP của bạn (ví dụ: neighborloop-images), tốt nhất là trong cùng khu vực với cơ sở dữ liệu và ứng dụng của bạn.
- Định cấu hình quyền truy cập công khai: * Chuyển đến thẻ Quyền của nhóm.
- Thêm đối tượng chính allUsers.
- Chỉ định vai trò Storage Object Viewer (để mọi người có thể xem ảnh) và vai trò Storage Object Creator (cho mục đích tải bản minh hoạ lên).
Phương án thay thế (Tài khoản dịch vụ): Nếu không muốn sử dụng quyền truy cập công khai, hãy đảm bảo Tài khoản dịch vụ của ứng dụng được cấp toàn quyền truy cập vào Cloud SQL và các vai trò Storage cần thiết để quản lý các đối tượng một cách an toàn.
Nếu bạn muốn chạy lệnh và cấp quyền truy cập công khai. Chạy các lệnh bên dưới trong Cloud Shell Terminal:
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
Các lỗi thường gặp và cách khắc phục sự cố
The Region Drag | Nếu cơ sở dữ liệu của bạn nằm trong |
Tính duy nhất của tên bộ chứa | Tên bộ chứa là một không gian tên chung. Nếu bạn cố gắng đặt tên cho nhóm của mình là |
Nhầm lẫn giữa "Nhà sáng tạo" và "Người xem" | Nhầm lẫn giữa "Người tạo" và "Người xem": Nếu bạn chỉ thêm "Người xem", ứng dụng của bạn sẽ gặp sự cố khi người dùng cố gắng liệt kê một mục mới vì ứng dụng không có quyền ghi tệp. Bạn cần cả hai để thiết lập bản minh hoạ cụ thể này. |
6. Hãy tạo ứng dụng
Sao chép kho lưu trữ này vào dự án của bạn và hãy xem qua kho lưu trữ này.
- Để sao chép dự án này, hãy chạy lần lượt các lệnh sau trong Cloud Shell Terminal (trong thư mục gốc hoặc bất cứ nơi nào bạn muốn tạo dự án này):
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
Thao tác này sẽ tạo dự án và bạn có thể xác minh dự án đó trong Cloud Shell Editor.
- Cách lấy Khoá Gemini API
- Truy cập Google AI Studio: Truy cập vào aistudio.google.com.
- Đăng nhập: Sử dụng cùng Tài khoản Google mà bạn đang dùng cho dự án trên Google Cloud.
- Tạo khoá API:
- Trên thanh bên bên trái, hãy nhấp vào "Lấy khoá API".
- Nhấp vào nút "Tạo khoá API trong dự án mới".
- Sao chép khoá: Sau khi khoá được tạo, hãy nhấp vào biểu tượng sao chép.
- Bây giờ, hãy thiết lập các biến môi trường trong tệp .env
GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>
DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<HOST_IP>>:<<PORT>>/postgres
GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Thay thế các giá trị cho phần giữ chỗ <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.
Các lỗi thường gặp và cách khắc phục sự cố
Nhầm lẫn về nhiều tài khoản | Nếu bạn đăng nhập vào nhiều Tài khoản Google (Tài khoản cá nhân và Tài khoản do nơi làm việc cấp), thì AI Studio có thể mặc định chọn nhầm tài khoản. Kiểm tra hình đại diện ở góc trên cùng bên phải để đảm bảo hình đại diện đó khớp với tài khoản Dự án GCP của bạn. |
Đạt hạn mức "Bậc miễn phí" | Nếu bạn đang sử dụng gói Miễn phí, thì sẽ có hạn mức về tốc độ (RPM – Số yêu cầu mỗi phút). Nếu "vuốt" quá nhanh trong Vòng kết nối hàng xóm, bạn có thể gặp lỗi |
Bảo mật khoá bị lộ | Nếu bạn vô tình |
7. Hãy kiểm tra mã
"Hồ sơ hẹn hò" cho đồ đạc của bạn
Khi tải ảnh của một mặt hàng lên, người dùng không cần phải viết nội dung mô tả dài. Tôi dùng Gemini 3 Flash để "xem" mặt hàng và viết trang thông tin cho họ.
Ở phần phụ trợ, người dùng chỉ cần cung cấp tiêu đề và ảnh. Gemini sẽ lo phần còn lại:
prompt = """
You are a witty community manager for NeighborLoop.
Analyze this surplus item and return JSON:
{
"bio": "First-person witty dating-style profile bio for the product, not longer than 2 lines",
"category": "One-word category",
"tags": ["tag1", "tag2"]
}
"""
response = genai_client.models.generate_content(
model="gemini-3-flash-preview",
contents=[types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"), prompt],
config=types.GenerateContentConfig(response_mime_type="application/json")
)
Mục nhúng trong cơ sở dữ liệu theo thời gian thực
Một trong những tính năng thú vị nhất của Cloud SQL là khả năng tạo các mục nhúng mà không cần rời khỏi ngữ cảnh SQL. Thay vì gọi một mô hình nhúng trong Python và gửi vectơ trở lại DB, tôi thực hiện tất cả trong một câu lệnh INSERT bằng cách sử dụng hàm embedding():
INSERT INTO items (owner_id, provider_name, provider_phone, title, bio, category, image_url, status, item_vector)
VALUES (
:owner, :name, :phone, :title, :bio, :cat, :url, 'available',
embedding('text-embedding-005', :title || ' ' || :bio)::vector
)
Điều này đảm bảo rằng mọi mục đều có thể "tìm kiếm" theo ý nghĩa của mục đó ngay khi được đăng. Xin lưu ý rằng đây là phần đề cập đến tính năng "liệt kê sản phẩm" của ứng dụng Neighbor Loop.
Tính năng Tìm kiếm vectơ nâng cao và Lọc thông minh bằng Gemini 3.0
Tính năng tìm kiếm từ khoá tiêu chuẩn bị hạn chế. Nếu bạn tìm kiếm "cái gì đó để sửa ghế của tôi", thì một cơ sở dữ liệu truyền thống có thể không trả về kết quả nào nếu từ "ghế" không có trong tiêu đề. Neighbor Loop giải quyết vấn đề này bằng tính năng tìm kiếm vectơ nâng cao của AI Cloud SQL.
Bằng cách sử dụng tiện ích pgvector và bộ nhớ được tối ưu hoá của Cloud SQL, chúng ta có thể thực hiện các tìm kiếm tương tự cực kỳ nhanh chóng. Nhưng "phép màu" thực sự xảy ra khi chúng ta kết hợp khoảng cách vectơ với logic dựa trên LLM.
SELECT item_id, title, bio, category, image_url,
1 - (item_vector <=> embedding('text-embedding-005', :query)::vector) as score
FROM items
WHERE status = 'available'
AND item_vector IS NOT NULL
ORDER BY score DESC
LIMIT 5
Truy vấn này thể hiện một bước chuyển đổi lớn về cấu trúc: chúng ta đang chuyển logic sang dữ liệu. Thay vì kéo hàng nghìn kết quả vào mã ứng dụng để lọc, Gemini 3 Flash sẽ thực hiện "kiểm tra cảm xúc" bên trong công cụ cơ sở dữ liệu. Điều này giúp giảm độ trễ, giảm chi phí đầu ra và đảm bảo rằng kết quả không chỉ tương tự về mặt toán học mà còn phù hợp theo ngữ cảnh.
Vòng lặp "Vuốt để ghép"
Giao diện người dùng là một bộ bài tiêu chuẩn.
Vuốt sang trái: Loại bỏ.
Vuốt sang phải: Bạn đã tìm được người phù hợp!
Khi bạn vuốt sang phải, hệ thống phụ trợ sẽ ghi lại lượt tương tác trong bảng vuốt của chúng tôi và đánh dấu mục đó là đã được ghép. Giao diện người dùng ngay lập tức kích hoạt một phương thức hiển thị thông tin liên hệ của nhà cung cấp để bạn có thể sắp xếp việc đến lấy.
8. Hãy triển khai ứng dụng này lên Cloud Run
- Triển khai ứng dụng đó trên Cloud Run bằng cách chạy lệnh sau từ Cloud Shell Terminal (nơi dự án được sao chép) và đảm bảo bạn đang ở trong thư mục gốc của dự án.
Chạy lệnh này trong cửa sổ dòng lệnh Cloud Shell:
gcloud run deploy neighbor-loop-cloud-sql \
--source . \
--region=us-central1 \
--allow-unauthenticated \
--network=easy-cloudsql-vpc \
--subnet=easy-cloudsql-subnet \
--vpc-egress=private-ranges-only \
--set-env-vars GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>,DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<PRIVATE_IP_HOST>>:5432/postgres,GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Thay thế các giá trị cho phần giữ chỗ <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>
Sau khi hoàn tất, lệnh này sẽ xuất ra một URL dịch vụ. Sao chép.
Bây giờ, hãy sử dụng URL dịch vụ (điểm cuối Cloud Run mà bạn đã sao chép trước đó) và kiểm thử ứng dụng. Tải ảnh của dụng cụ điện cũ đó lên và để Gemini làm phần việc còn lại!
Các lỗi thường gặp và cách khắc phục sự cố
Vòng lặp "Bản sửa đổi không thành công" | Nếu quá trình triển khai hoàn tất nhưng URL trả về |
9. Khắc phục sự cố ở cấp cao
10. Bản minh hoạ
Bạn có thể sử dụng điểm cuối cho các bài kiểm tra.
Tuy nhiên, để minh hoạ trong vài ngày, bạn có thể thử dùng mã này:
11. Dọn dẹp
Sau khi hoàn tất bài thực hành này, đừng quên xoá phiên bản Cloud SQL.
12. Xin chúc mừng
Bạn đã tạo thành công ứng dụng Neighbor Loop cho các cộng đồng bền vững bằng Google Cloud. Bằng cách di chuyển logic nhúng và logic AI của Gemini 3 Flash vào Cloud SQL, ứng dụng này có tốc độ cực kỳ nhanh (tuỳ thuộc vào chế độ cài đặt triển khai) và mã rất gọn gàng. Chúng tôi không chỉ lưu trữ dữ liệu mà còn lưu trữ ý định.
Sự kết hợp giữa tốc độ của Gemini 3 Flash và khả năng xử lý vectơ được tối ưu hoá của Cloud SQL thực sự là bước tiến tiếp theo cho các nền tảng dựa vào cộng đồng.