Xây dựng chuỗi cung ứng tự động bằng Gemini 3 Flash và AlloyDB AI

1. Tổng quan

Thời đại của "Chatbot có thể đọc" đang kết thúc. Chúng ta đang bước vào kỷ nguyên của Agentic Vision (Thị giác dựa trên tác nhân).

Trong Lớp học lập trình này, chúng ta sẽ triển khai Kỹ thuật AI có tính xác định – một phương pháp xây dựng các hệ thống AI không đoán. Các mô hình AI tiêu chuẩn thường "ảo tưởng" (đoán) khi được yêu cầu đếm các mục trong một hình ảnh phức tạp. Trong chuỗi cung ứng, việc đoán chừng là rất nguy hiểm. Nếu AI đoán bạn có 12 mặt hàng trong khi thực tế bạn có 15 mặt hàng, thì điều này sẽ gây ra những lỗi tốn kém.

Chúng ta sẽ xây dựng một Tác nhân chuỗi cung ứng tự động bằng cách sử dụng vòng lặp Tư duy, Hành động, Quan sát mới trong Gemini 3 Flash. Không chỉ quan sát, mà còn điều tra.

Kiến trúc tất định

Chúng ta sẽ bắt đầu với một hệ thống "mù" và "mất trí nhớ". Bạn sẽ phải tự "đánh thức" từng giác quan của nó:

The Eyes (Tác nhân thị giác): Chúng tôi trang bị Gemini 3 Flash cho Tính năng thực thi mã. Thay vì dự đoán các mã thông báo để đoán một số, mô hình này sẽ viết mã Python (OpenCV) để đếm số lượng pixel một cách xác định.
Bộ nhớ (Tác nhân nhà cung cấp): Chúng tôi bật AI AlloyDB bằng ScaNN (Tìm kiếm lân cận có thể mở rộng). Điều này cho phép tác nhân nhớ lại chính xác nhà cung cấp của một bộ phận trong số hàng triệu lựa chọn chỉ trong vài mili giây.
Cái bắt tay (Giao thức A2A): Chúng tôi cho phép giao tiếp Giữa các tác nhân bằng cách sử dụng tệp agent_card.json được chuẩn hoá , cho phép Tác nhân thị giác tự động đặt hàng từ Tác nhân nhà cung cấp.

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

Một Tác nhân thị giác thực hiện "phép toán thị giác" trên nguồn cấp dữ liệu camera.
Tác nhân nhà cung cấp được hỗ trợ bởi AlloyDB ScaNN để tìm kiếm vectơ tốc độ cao.
Giao diện người dùng Control Tower có các bản cập nhật WebSocket theo thời gian thực để trực quan hoá vòng lặp tự động.

Kiến thức bạn sẽ học được

Cách thiết lập AlloyDB bằng các giá trị nhúng vectơ và chỉ mục ScaNN.
Cách bật Agentic Vision bằng gemini-3-flash-preview thông qua Gemini API.
Cách triển khai tính năng tìm kiếm vectơ bằng toán tử <=> (khoảng cách cosine) trong AlloyDB.
Cách kết nối các tác nhân với AlloyDB bằng Trình kết nối Python AlloyDB.
Cách sử dụng Giao thức A2A để khám phá tác nhân động.

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.
Khoá Gemini API (cấp miễn phí có tại Google AI Studio) cho Vision Agent.

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 rằng 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 Cloud.

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

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

Thiết lập cơ sở dữ liệu [AlloyDB]

Trước khi làm bất cứ việc gì khác, hãy cung cấp cơ sở dữ liệu – việc này mất khoảng 15 phút, vì vậy, chúng ta sẽ bắt đầu trước.

Nhấp vào nút bên dưới để mở công cụ thiết lập AlloyDB trong Cloud Shell:

Chạy chương trình thiết lập:

Sh run.sh

Sử dụng Web Preview (Xem trước trên cổng 8080) để mở giao diện người dùng thiết lập.
Nhập mã dự án, chọn một khu vực (ví dụ: us-central1) và tạo mật khẩu cơ sở dữ liệu.

⚠️ LƯU MẬT KHẨU NÀY – bạn sẽ cần mật khẩu này khi tập lệnh thiết lập yêu cầu.

Nhấp vào Start Deployment (Bắt đầu triển khai) và đợi khoảng 15 phút để cụm được cung cấp.

Nhận mã

Trong khi AlloyDB đang được cấp phép (hoặc sau khi hoàn tất), hãy mở kho lưu trữ lớp học lập trình trong Cloud Shell:

⚠️ QUAN TRỌNG: Khi nhấp vào nút này, bạn sẽ thấy một hộp thoại bảo mật. Đánh dấu vào ô "Tin tưởng kho lưu trữ" rồi nhấp vào "Xác nhận".

Hoặc sao chép theo cách thủ công:

git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git

cd visual-commerce-gemini-3-alloydb

Thiết lập dự án

Trong thiết bị đầu cuối Cloud Shell này, hãy xác nhận rằng dự án của bạn đã được thiết lập:

gcloud config set project <YOUR_PROJECT_ID>

Bật IP công khai trên AlloyDB

Sau khi quá trình cung cấp AlloyDB hoàn tất, hãy bật IP công khai để Trình kết nối Python có thể kết nối từ Cloud Shell:

Chuyển đến Bảng điều khiển AlloyDB
Nhấp vào cụm của bạn → nhấp vào phiên bản chính
Nhấp vào Chỉnh sửa
Di chuyển đến phần Kết nối IP công khai rồi đánh dấu vào mục Bật IP công khai
Nhấp vào Cập nhật đối tượng

💡 Lưu ý: Trình kết nối AlloyDB Python xử lý việc xác thực và mã hoá. Bạn không cần thêm bất kỳ mạng bên ngoài nào được uỷ quyền.

Cấp quyền cho Vertex AI

Tài khoản dịch vụ AlloyDB cần có quyền truy cập vào Vertex AI để tạo các mục nhúng. Chạy lệnh này trong cùng một cửa sổ 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"

Chạy tập lệnh thiết lập

Bây giờ, hãy chạy tập lệnh thiết lập. Tập lệnh này sẽ tự động phát hiện phiên bản AlloyDB của bạn:

sh setup.sh

Những việc mà tập lệnh này thực hiện:

Xác thực gcloud CLI, hoạt động xác thực, dự án và Python 3
Kiểm tra và bật các API bắt buộc (AlloyDB, Vertex AI, Compute, Service Networking)
Câu lệnh cho khoá Gemini API
Tự động phát hiện thực thể AlloyDB của bạn và trích xuất tên vùng, cụm và thực thể
Yêu cầu mật khẩu cơ sở dữ liệu của bạn
Tạo tệp cấu hình .env
Cài đặt các phần phụ thuộc Python

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

AlloyDB cho PostgreSQL là cốt lõi của ứng dụng. Chúng tôi sẽ sử dụng các chức năng vectơ mạnh mẽ và chỉ mục ScaNN của công cụ này để cho phép tìm kiếm ngữ nghĩa gần như theo thời gian thực, giúp các nhân viên của chúng tôi tìm thấy các mặt hàng phù hợp trong hàng nghìn bản ghi chỉ trong vài mili giây.

Trong phần này, bạn sẽ cung cấp giản đồ, dữ liệu ban đầu và tạo các mục nhúng – tất cả đều từ AlloyDB Studio.

Kết nối với AlloyDB Studio

Chuyển đến phiên bản AlloyDB của bạn trong Bảng điều khiển AlloyDB
Nhấp vào AlloyDB Studio trong bảng điều hướng bên trái
Xác thực bằng:
Tên người dùng: postgres
Cơ sở dữ liệu: postgres
Mật khẩu: Mật khẩu bạn đặt trong quá trình tạo cụm

Bật tiện ích

AlloyDB cung cấp các tiện ích tích hợp cho vectơ và AI. Chạy SQL sau trong AlloyDB Studio:

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

google_ml_integration: Cho phép hàm ai.embedding() gọi Vertex AI trực tiếp từ SQL.
vector: Lưu trữ và truy vấn các mục nhúng vectơ 768 chiều.
alloydb_scann: Cho phép chỉ mục ScaNN của Google tìm kiếm vectơ cực nhanh.

Tạo Bảng khoảng không quảng cáo

DROP TABLE IF EXISTS inventory;

CREATE TABLE inventory (
    id SERIAL PRIMARY KEY,
    part_name TEXT NOT NULL,
    supplier_name TEXT NOT NULL,
    description TEXT,
    stock_level INT DEFAULT 0,
    part_embedding vector(768)
);

Cột part_embedding lưu trữ các vectơ 768 chiều từ text-embedding-005. Đây là yếu tố giúp tìm kiếm ngữ nghĩa hoạt động.

Chèn dữ liệu mẫu

Chèn 20 mặt hàng trong kho hàng:

INSERT INTO inventory (part_name, supplier_name, description, stock_level) VALUES
('Cardboard Shipping Box Large', 'Packaging Solutions Inc', 'Heavy-duty corrugated cardboard shipping container, 24x18x12 inches', 250),
('Warehouse Storage Container', 'Industrial Supply Co', 'Stackable plastic storage bin with snap-lock lid, blue', 180),
('Product Shipping Boxes', 'Acme Packaging', 'Medium corrugated boxes for warehouse storage, 18x14x10 inches', 320),
('Industrial Widget X-9', 'Acme Corp', 'Heavy-duty industrial coupling for pneumatic systems', 50),
('Precision Bolt M4', 'Global Fasteners Inc', 'Stainless steel M4 allen bolt, 20mm length, grade A2-70', 200),
('Hexagonal Nut M6', 'Metro Supply Co', 'Galvanized steel hex nut M6, DIN 934 standard', 150),
('Phillips Head Screw 3x20', 'Acme Corp', 'Zinc-plated Phillips head wood screw, 3mm x 20mm', 500),
('Wooden Dowel 10mm', 'Craft Materials Ltd', 'Hardwood birch dowel rod, 10mm diameter x 300mm length', 80),
('Rubber Gasket Small', 'SealTech Industries', 'Buna-N rubber gasket, 25mm OD x 15mm ID, oil resistant', 120),
('Spring Tension 5kg', 'Mechanical Parts Co', 'Stainless steel compression spring, 5kg load capacity', 60),
('Bearing 6204', 'Bearings Direct', 'Deep groove ball bearing 6204-2RS, 20x47x14mm sealed', 45),
('Warehouse Shelf Boxes', 'Storage Systems Ltd', 'Standardized warehouse inventory boxes, corrugated, bulk pack', 400),
('Inventory Container Units', 'Supply Chain Pros', 'Modular stackable storage units for warehouse racking', 95),
('Aluminum Extrusion Bar', 'MetalWorks International', 'T-slot aluminum extrusion 20x20mm profile, 1 meter length', 110),
('Cable Tie Pack 200mm', 'ElectroParts Depot', 'Nylon cable ties, 200mm x 4.8mm, UV resistant black, pack of 100', 600),
('Hydraulic Hose 1/2 inch', 'FluidPower Systems', 'High-pressure hydraulic hose, 1/2 inch ID, 3000 PSI rated', 35),
('Safety Goggles Clear', 'WorkSafe Equipment Co', 'ANSI Z87.1 rated clear safety goggles, anti-fog coating', 275),
('Packing Tape Industrial', 'Packaging Solutions Inc', 'Heavy-duty polypropylene packing tape, 48mm x 100m, clear', 450),
('Stainless Steel Sheet 1mm', 'MetalWorks International', '304 stainless steel sheet, 1mm thickness, 300x300mm', 70),
('Silicone Sealant Tube', 'SealTech Industries', 'Industrial-grade RTV silicone sealant, 300ml cartridge, grey', 190);

Cấp quyền nhúng

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Tạo vectơ nhúng

Thao tác này sử dụng hàm ai.embedding() tích hợp của AlloyDB để gọi trực tiếp mô hình text-embedding-005 của Vertex AI từ SQL mà không cần mã Python:

UPDATE inventory
SET part_embedding = ai.embedding(
    'text-embedding-005',
    part_name || '. ' || description
)::vector
WHERE part_embedding IS NULL;

Thao tác này tạo ra các vectơ 768 chiều, nắm bắt ý nghĩa ngữ nghĩa của tên và nội dung mô tả của từng bộ phận. Chỉ mục ScaNN sẽ sử dụng các chỉ mục này để tìm kiếm sự tương đồng cực nhanh. [Bạn sẽ chỉ mất khoảng 3 đến 5 phút để hoàn thành]

Tạo chỉ mục ScaNN

SET scann.allow_blocked_operations = true;

CREATE INDEX IF NOT EXISTS idx_inventory_scann
ON inventory USING scann (part_embedding cosine)
WITH (num_leaves=5, quantizer='sq8');

Xác minh mọi thứ đã hoạt động

SELECT part_name, supplier_name, stock_level,
       (part_embedding IS NOT NULL) as has_embedding
FROM inventory
ORDER BY id;

Bạn sẽ thấy 20 hàng, tất cả đều có has_embedding = true.

4. Tìm hiểu về cấu trúc

Trước khi thực hiện các thay đổi về mã, hãy tìm hiểu cách hệ thống được tạo. Cấu trúc này tuân theo một mô hình "thức tỉnh" tiến bộ:

Ngăn xếp tác nhân

Tác nhân thị giác (agents/vision-agent/)

agent.py – Logic cốt lõi của Gemini 3 Flash. Gửi hình ảnh đến mô hình khi bật tính năng Thực thi mã để mô hình viết Python (OpenCV) nhằm đếm các mục một cách xác định.
agent_executor.py – Kết nối các yêu cầu giao thức A2A với logic của tác nhân.
main.py – Máy chủ Uvicorn A2A phân phát /.well-known/agent-card.json và xử lý các yêu cầu.

Nhân viên hỗ trợ của nhà cung cấp (agents/supplier-agent/)

inventory.py – Kết nối với AlloyDB thông qua Trình kết nối AlloyDB Python (không cần Proxy xác thực). Chứa hàm find_supplier() thực hiện tìm kiếm vectơ ScaNN.
agent_executor.py – Kết nối giao thức A2A với logic tìm kiếm khoảng không quảng cáo.
main.py – Máy chủ Uvicorn A2A có thẻ tác nhân và điểm cuối về sức khoẻ.

Control Tower (frontend/)

app.py – Máy chủ FastAPI + WebSocket phát hiện các tác nhân thông qua A2A, điều phối quy trình hình ảnh → tìm kiếm → đặt hàng và truyền trực tuyến thông tin cập nhật theo thời gian thực đến trình duyệt.

Quy trình A2A

Control Tower đọc /.well-known/agent-card.json từ mỗi tác nhân
Khám phá các chức năng (kỹ năng, điểm cuối) – không có URL được mã hoá cứng
Gửi hình ảnh đến Vision Agent → nhận số lượng mặt hàng + nội dung mô tả
Gửi nội dung mô tả dưới dạng truy vấn nhúng đến Supplier Agent → nhận được kết quả khớp một phần
Tự đặt hàng

Kết nối AlloyDB

Supplier Agent sử dụng AlloyDB Python Connector thay vì Auth Proxy truyền thống:

from google.cloud.alloydbconnector import Connector

connector = Connector()
conn = connector.connect(
    inst_uri,       # Full instance URI
    "pg8000",       # Driver
    user="postgres",
    password=DB_PASS,
    ip_type="PUBLIC",  # Cloud Shell uses Public IP
)

Thao tác này sẽ tự động xử lý quy trình xác thực IAM, SSL/TLS và định tuyến kết nối. Khi triển khai lên Cloud Run sau này, bạn chỉ cần thay đổi ip_type thành "PRIVATE" để truy cập vào VPC.

5. Bước 1: Bộ nhớ (Tác nhân nhà cung cấp)

Tác nhân nhà cung cấp ghi nhớ hàng triệu bộ phận bằng cách sử dụng AlloyDB ScaNN. Hiện tại, nó đi kèm với một truy vấn trình giữ chỗ – một truy vấn amnesiac trả về hàng đầu tiên mà nó tìm thấy, bất kể bạn tìm kiếm nội dung gì.

The Audit: The Amnesiac

Nếu bạn truy vấn Supplier Agent ngay bây giờ, nó sẽ trả về một kết quả ngẫu nhiên. Không có khái niệm về sự tương đồng. Hãy khắc phục vấn đề đó.

Khởi động Supplier Agent

Máy chủ A2A (main.py) uỷ quyền cho agent_executor.py, giúp kết nối giao thức với logic nghiệp vụ trong inventory.py.

pkill -f uvicorn #Kill all uvicorn processes

Bước 1: Chuyển đến thư mục tác nhân

cd agents/supplier-agent

Bước 2: Cài đặt các phần phụ thuộc

pip install -r requirements.txt

Bước 3: Khởi động máy chủ tác nhân

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

> /dev/null 2>&1 & chạy máy chủ ở chế độ nền và ngăn chặn đầu ra để không làm gián đoạn thiết bị đầu cuối của bạn.

Bước 4: Xác minh rằng tác nhân đang chạy (chờ 2-3 giây sau khi khởi động)

curl http://localhost:8082/.well-known/agent-card.json

Đầu ra dự kiến: JSON có cấu hình tác nhân (sẽ trả về mà không có lỗi)

Cách khắc phục: Triển khai toán tử <=>

Mở agents/supplier-agent/inventory.py và tìm hàm find_supplier() ở khoảng dòng 60-70. Bạn sẽ thấy phần giữ chỗ:

# TODO: Replace this placeholder query with ScaNN vector search

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

Thay thế 2 dòng đó bằng:

sql = """
SELECT part_name, supplier_name,
       part_embedding <=> %s::vector as distance
FROM inventory
ORDER BY part_embedding <=> %s::vector
LIMIT 1;
"""
cursor.execute(sql, (embedding_str, embedding_str))

Tác dụng của tính năng này:

<=> là toán tử khoảng cách cosin trong PostgreSQL
ORDER BY part_embedding <=> %s::vector tìm kết quả khớp gần nhất (khoảng cách thấp nhất = ý nghĩa ngữ nghĩa gần nhất)
%s::vector truyền mảng nhúng của bạn sang loại vectơ của PostgreSQL
Chỉ mục ScaNN sẽ tự động tăng tốc truy vấn này!

Bước 4: Lưu tệp (Ctrl+S hoặc Cmd+S)

Giờ đây, tác nhân sẽ sử dụng tính năng tìm kiếm ngữ nghĩa thay vì trả về kết quả ngẫu nhiên!

Xác minh

Kiểm thử tính năng khám phá A2A và khoảng không quảng cáo:

curl http://localhost:8082/.well-known/agent-card.json

python3 -c "
from inventory import find_supplier
import json
vec = [0.1]*768
r = find_supplier(vec)
if r:
    result = {'part': r[0], 'supplier': r[1]}
    if len(r) > 2:
        result['distance'] = float(r[2]) if r[2] else None
    print(json.dumps(result))
else:
    print('No result found')
"

Dự kiến: agent-card.json trả về thẻ đại lý. Đoạn mã Python này trả về một bộ phận và nhà cung cấp từ dữ liệu ban đầu.

Lỗi thường gặp:

"Không có tệp hoặc thư mục nào như vậy": Bạn không ở thư mục gốc của kho lưu trữ. Chạy cd để chuyển đến thư mục gốc, sau đó chạy cd visual-commerce-gemini-3-alloydb hoặc sử dụng pwd để tìm vị trí hiện tại của bạn.
Đang dùng cổng 8082: Kết thúc quy trình hiện có: lsof -ti:8082 | xargs kill -9
ModuleNotFoundError: Cài đặt các phần phụ thuộc: pip install -r requirements.txt
Không kết nối được với cơ sở dữ liệu: Kiểm tra tệp .env – điền ALLOYDB_REGION, ALLOYDB_CLUSTER và ALLOYDB_INSTANCE
Kết nối bị từ chối: Đảm bảo bạn đã bật IP công khai trên thực thể AlloyDB
Tập lệnh xác minh không thành công: Kiểm tra để đảm bảo rằng quá trình gieo hạt đã hoàn tất thành công ở Bước 4

6. Bước 2: Đôi mắt (Tác nhân thị giác)

Mặc dù có thể truy cập vào cơ sở dữ liệu, nhưng hãy đánh thức đôi mắt bằng Gemini 3 Flash. Tác nhân thị giác thực hiện "phép toán thị giác" thông qua tính năng Thực thi mã.

The Audit: The Hallucination

Nếu bạn hỏi một mô hình đa phương thức tiêu chuẩn "Có bao nhiêu hộp trong hình ảnh lộn xộn này?", mô hình đó sẽ xử lý hình ảnh dưới dạng một ảnh chụp nhanh tĩnh và đưa ra phỏng đoán.

Mô hình nói: "Tôi thấy khoảng 12 hộp."
Thực tế: Có 15 hộp.
Kết quả: Lỗi chuỗi cung ứng.

Cách khắc phục: Kích hoạt vòng lặp Suy nghĩ – Hành động – Quan sát

Chúng tôi bật tính năng Thực thi mã và ThinkingConfig để mô hình viết Python (OpenCV) nhằm đếm một cách xác định.

Mở agents/vision-agent/agent.py .
Tìm phần GenerateContentConfig (khoảng dòng 68-78).
Huỷ đánh dấu cả khối thinking_config=types.ThinkingConfig(...) và tools=[types.Tool(code_execution=...)].
Ứng dụng đã được định cấu hình để sử dụng GEMINI_API_KEY của bạn từ môi trường.

Tệp: agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="MINIMAL",  # Valid: "MINIMAL", "LOW", "MEDIUM", "HIGH"
        include_thoughts=False    # Set to True for debugging
    ),
    # CODELAB STEP 2: Uncomment to enable code execution
    tools=[types.Tool(code_execution=types.ToolCodeExecution)]
)

Tại sao thinking_level="MINIMAL"?

Đối với nhiệm vụ này (đếm các mục thông qua việc thực thi mã), "TỐI THIỂU" cung cấp đủ suy luận để lập kế hoạch cho tập lệnh và xác minh số lượng. Việc sử dụng "HIGH" sẽ làm tăng độ trễ từ 2 đến 3 lần mà không cải thiện độ chính xác cho các tác vụ xác định. Tối ưu hoá chi phí và hiệu suất – điều chỉnh độ sâu suy luận cho phù hợp với độ phức tạp của nhiệm vụ.

Tối ưu hóa chi phí và hiệu suất là một kỹ năng quan trọng đối với kỹ sư AI sản xuất: điều chỉnh độ sâu suy luận cho phù hợp với độ phức tạp của nhiệm vụ.

Khởi động Trợ lý thị giác

🔄 Kiểm tra đường dẫn: Nếu bạn vẫn ở trong agents/supplier-agent/, trước tiên hãy quay lại thư mục gốc của kho lưu trữ bằng lệnh cd ../..

Bước 1: Chuyển đến thư mục tác nhân thị giác

cd agents/vision-agent

Bước 2: Cài đặt các phần phụ thuộc

pip install -r requirements.txt

Bước 3: Khởi động máy chủ tác nhân thị giác

uvicorn main:app --host 0.0.0.0 --port 8081 > /dev/null 2>&1 &

> /dev/null 2>&1 & chạy máy chủ ở chế độ nền và ngăn chặn đầu ra để không làm gián đoạn thiết bị đầu cuối của bạn.

Xác minh

Thử nghiệm tính năng khám phá A2A:

curl http://localhost:8081/.well-known/agent-card.json

Dự kiến: JSON có tên và kỹ năng của nhân viên hỗ trợ. Bạn sẽ kiểm thử tính năng đếm bằng thị giác thực tế bằng giao diện người dùng của Tháp điều khiển ở Bước 8.

7. Bước 3: Bắt tay (Thẻ đại lý A2A)

Nhân viên hỗ trợ của chúng tôi nhìn thấy vấn đề (Thị giác) và biết nhà cung cấp (Bộ nhớ). Giao thức A2A cho phép khám phá động – giao diện người dùng học cách giao tiếp với từng tác nhân bằng cách đọc thẻ của tác nhân đó.

A2A so với API REST truyền thống

Aspect	REST truyền thống	Giao thức A2A
Khám phá thiết bị đầu cuối	URL được mã hoá cứng trong cấu hình	Động thông qua /.well-known/agent-card.json
Mô tả chức năng	Tài liệu API (dành cho người dùng)	Kỹ năng (máy có thể đọc được)
Tích hợp	Mã thủ công cho mỗi dịch vụ	Đối sánh ngữ nghĩa: "Tôi cần tìm khoảng không quảng cáo" → khám phá kỹ năng
Đã thêm tác nhân mới	Cập nhật cấu hình của tất cả các ứng dụng	Không cần cấu hình – tự động phát hiện

Lợi ích trong thực tế: Trong một vi dịch vụ truyền thống, nếu thêm "Đại lý hậu cần" thứ ba, bạn sẽ cần cập nhật mã của Tháp kiểm soát bằng URL và hợp đồng API của đại lý đó. Với A2A, Control Tower sẽ tự động phát hiện và hiểu được các chức năng của A2A thông qua nội dung mô tả kỹ năng bằng ngôn ngữ tự nhiên.

Đó là lý do A2A cho phép Thành phần tác nhân cắm và chạy – mẫu kiến trúc cho các hệ thống tự trị.

Tạo Thẻ tác nhân

🔄 Kiểm tra đường dẫn: Nếu bạn vẫn ở trong agents/vision-agent/, trước tiên, hãy quay lại thư mục gốc của kho lưu trữ bằng lệnh cd ../..

Thẻ đại lý đã được thêm vào agents/supplier-agent/agent_card.json. Mở và xem xét:

{
  "name": "Acme Supplier Agent",
  "description": "Autonomous fulfillment for industrial parts via AlloyDB ScaNN.",
  "version": "1.0.0",
  "skills": [{
    "id": "search_inventory",
    "name": "Search Inventory",
    "description": "Searches the warehouse database for semantic matches using AlloyDB ScaNN vector search.",
    "tags": ["inventory", "search", "alloydb"],
    "examples": ["Find stock for Industrial Widget X-9", "Who supplies ball bearings?"]
  }]
}

Bạn có thể tuỳ chỉnh tên, nội dung mô tả hoặc ví dụ cho phù hợp với trường hợp sử dụng của mình.

Khởi động lại Supplier Agent để tải thẻ:

Bước 1: Dừng tác nhân đang chạy

pkill -f "uvicorn main:app.*8082"

Bước 2: Chuyển đến thư mục tác nhân

cd agents/supplier-agent

Bước 3: Khởi động lại tác nhân

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

> /dev/null 2>&1 & chạy máy chủ ở chế độ nền và ngăn chặn đầu ra để không làm gián đoạn thiết bị đầu cuối của bạn.

Bước 4: Xác minh thẻ nhân viên hỗ trợ mới (chờ 2-3 giây sau khi bắt đầu)

curl http://localhost:8082/.well-known/agent-card.json

Đầu ra dự kiến: JSON có tên, nội dung mô tả và kỹ năng mà bạn đã điền.

8. Bước 4: Tháp điều khiển

Chạy giao diện người dùng Control Tower bằng FastAPI + WebSockets. Nền tảng này khám phá các tác nhân thông qua A2A và điều phối toàn bộ vòng lặp bằng thông tin cập nhật theo thời gian thực.

Bắt đầu tất cả dịch vụ

Cách dễ nhất để bắt đầu tất cả các dịch vụ:

Xác minh rằng bạn đang ở thư mục gốc của kho lưu trữ

pwd  # Should end with: visual-commerce-gemini-3-alloydb

Sau đó:

sh run.sh

Lệnh duy nhất này sẽ bắt đầu:

Vision Agent trên cổng 8081
Tác nhân nhà cung cấp trên cổng 8082
Control Tower trên cổng 8080

Chờ khoảng 10 giây để tất cả các dịch vụ khởi động.

Kiểm thử hệ thống

Truy cập Control Tower:

Nhấp vào nút Xem trước trên web (biểu tượng con mắt 👁️) trên thanh công cụ Cloud Shell
Chọn "Xem trước trên cổng 8080"
Trang tổng quan Control Tower sẽ mở ra trong một thẻ mới

Chạy bản minh hoạ:

Trên cùng bên phải: Trạng thái kết nối (dấu chấm "Đang hoạt động" màu xanh lục), nút bật/tắt chế độ DEMO/AUTO và các chế độ điều khiển âm thanh
Trung tâm: Canvas chính của quy trình làm việc với tính năng tải hình ảnh lên và trực quan hoá dữ liệu phân tích
Bảng điều khiển bên (xuất hiện trong quá trình phân tích): Dòng thời gian của quy trình làm việc (bên trái), tính năng theo dõi tiến trình và trình xem mã (bên phải)

Cách 1: Bắt đầu nhanh (Nên dùng)

Trên trang chủ, bạn sẽ thấy phần "Bắt đầu nhanh" có các hình ảnh mẫu
Nhấp vào một hình ảnh mẫu bất kỳ để tự động bắt đầu phân tích
Xem quy trình làm việc tự động (khoảng 30 – 45 giây)

Cách 2: Tải lên nội dung của riêng bạn

Kéo và thả hình ảnh kho hàng/kệ hàng (PNG, JPG, tối đa 10 MB) hoặc nhấp để duyệt qua
Nhấp vào "Bắt đầu quy trình làm việc tự động"
Quan sát quy trình gồm 4 giai đoạn

Điều gì sẽ xảy ra:

Khám phá tác nhân: Các giao thức A2A cho thấy thẻ Tác nhân thị giác và Tác nhân nhà cung cấp cùng với các kỹ năng và điểm cuối của chúng
Phân tích hình ảnh: Gemini 3 Flash tạo và thực thi mã Python (OpenCV) để đếm các mục. Thanh tiến trình cho biết các bước phụ. Các hộp giới hạn phủ lên các mục được phát hiện. Huy hiệu kết quả cho biết "✓ Đã xác minh bằng mã" hoặc "~ Ước tính"
So khớp nhà cung cấp: Ảnh động tìm kiếm vectơ ScaNN của AlloyDB. Cụm từ tìm kiếm xuất hiện (ví dụ: "hộp kim loại công nghiệp"). Thẻ kết quả cho thấy linh kiện, nhà cung cấp và điểm tin cậy trùng khớp
Đơn đặt hàng: Thẻ biên nhận có mã đơn đặt hàng, số lượng và thông tin chi tiết

Lưu ý: Bật chế độ DEMO (trên cùng bên phải) để tạm dừng ở mỗi giai đoạn của bản trình bày. Ở chế độ TỰ ĐỘNG, quy trình làm việc sẽ chạy liên tục.

Điều gì vừa xảy ra

Control Tower đã sử dụng Giao thức A2A để khám phá cả hai tác nhân thông qua /.well-known/agent-card.json, điều phối hoạt động phân tích hình ảnh (Gemini 3 Flash có khả năng thực thi mã), thực hiện tìm kiếm vectơ (AlloyDB ScaNN) và đặt một đơn đặt hàng tự động – tất cả đều có thông tin cập nhật WebSocket theo thời gian thực. Mỗi tác nhân đều thể hiện các chức năng của mình thông qua tiêu chuẩn A2A, cho phép kết hợp plug-and-play mà không cần SDK tuỳ chỉnh. Tìm hiểu thêm: Giao thức A2A

Khắc phục sự cố

Lỗi liên quan đến đường dẫn:

"No such file or directory" (Không có tệp hoặc thư mục nào như vậy) khi chạy các lệnh: Bạn không ở thư mục gốc của kho lưu trữ.

# Check where you are
pwd

# If you're lost, navigate to home and back to repo
cd
cd visual-commerce-gemini-3-alloydb

Lỗi dịch vụ:

"Địa chỉ đã được sử dụng": Các quy trình từ những lần chạy trước vẫn đang hoạt động.

# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents

Dịch vụ không khởi động: Kiểm tra xem các cổng có đang được sử dụng hay không:

# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent

"Connection refused" (Kết nối bị từ chối) đến AlloyDB: Xác minh rằng bạn đã bật IP công khai trên thực thể AlloyDB

9. 🎁 Phần thưởng: Triển khai lên Cloud Run

Không bắt buộc – Mọi thứ đều hoạt động cục bộ! Nhưng nếu bạn muốn chia sẻ tác phẩm của mình bằng một URL công khai, hãy làm như sau:

# From repo root
sh deploy/deploy.sh

Điều gì sẽ xảy ra:

Đọc cấu hình .env
Yêu cầu bạn nhập tên (xuất hiện trong ứng dụng đã triển khai)
Triển khai cả 3 dịch vụ dưới dạng một vùng chứa Cloud Run duy nhất
Cấp vai trò IAM để truy cập vào AlloyDB
Xuất một URL có thể chia sẻ

Những người truy cập vào URL của bạn sẽ thấy một cửa sổ bật lên:

10. Dọn dẹp

Để tránh bị tính phí, hãy huỷ tất cả tài nguyên bằng tập lệnh dọn dẹp tự động:

# From repo root
sh deploy/cleanup.sh

Thao tác này sẽ xoá an toàn:

Cụm AlloyDB (yếu tố chính thúc đẩy chi phí)
Dịch vụ Cloud Run (nếu được triển khai)
Tài khoản dịch vụ được liên kết

Tập lệnh sẽ nhắc bạn xác nhận trước khi xoá bất kỳ nội dung nào.

11. Tài liệu tham khảo và tài liệu đọc thêm

Tất cả tuyên bố về kỹ thuật trong lớp học lập trình này đều được xác minh từ tài liệu chính thức của Google Cloud và AI của Google.

Tài liệu chính thức

Gemini 3 Flash:

API thực thi mã: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
Hướng dẫn cho nhà phát triển: https://ai.google.dev/gemini-api/docs/gemini-3
Tài liệu về mô hình: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
Thẻ mô hình: https://deepmind.google/models/gemini/flash/

AI và ScaNN của AlloyDB:

Điểm chuẩn hiệu suất của ScaNN: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
Tìm hiểu về chỉ mục ScaNN: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
Tìm hiểu sâu về AI trên AlloyDB: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
Các phương pháp hay nhất để điều chỉnh: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
Tài liệu về AlloyDB: https://cloud.google.com/alloydb/docs

Bộ công cụ MCP dành cho cơ sở dữ liệu (phương pháp thay thế):

MCP Toolbox: https://googleapis.github.io/genai-toolbox/getting-started/introduction/

Thông tin về giá:

Giá của Gemini API: https://ai.google.dev/gemini-api/docs/pricing
Giá của AlloyDB: https://cloud.google.com/alloydb/pricing
Giá của Vertex AI: https://cloud.google.com/vertex-ai/pricing

Tuyên bố đã xác minh về hiệu suất

Tính năng	Tuyên bố	Nguồn
ScaNN so với HNSW (đã lọc)	Nhanh hơn 10 lần	Blog của Google Cloud (đã xác minh)
ScaNN so với HNSW (chuẩn)	Nhanh hơn 4 lần	Blog của Google Cloud (đã xác minh)
Mức sử dụng bộ nhớ của ScaNN	Nhỏ hơn từ 3 đến 4 lần	Blog của Google Cloud (đã xác minh)
Thời gian xây dựng chỉ mục ScaNN	Nhanh hơn 8 lần	Blog của Google Cloud (đã xác minh)
Hết thời gian thực thi mã	Tối đa 30 giây	Tài liệu Google Cloud (đã xác minh)
Thực thi mã I/O tệp	Không được hỗ trợ	Tài liệu Google Cloud (đã xác minh)
Hành vi Nhiệt độ=0	Đầu ra xác định	Cộng đồng đã xác minh

Tài nguyên khác

Giao thức Agent-to-Agent (A2A):

A2A chuẩn hoá quy trình khám phá và giao tiếp của tác nhân
Thẻ nhân viên hỗ trợ được cung cấp tại /.well-known/agent-card.json
Tiêu chuẩn mới nổi cho hoạt động cộng tác của các tác nhân tự trị

Nghiên cứu ScaNN:

Dựa trên 12 năm nghiên cứu của Google Research
Hỗ trợ Google Tìm kiếm và YouTube ở quy mô hàng tỷ người dùng
Phát hành rộng rãi: tháng 10 năm 2024
Chỉ mục vectơ PostgreSQL đầu tiên phù hợp với hàng triệu đến hàng tỷ vectơ

12. Chế độ thử thách: Level Up kỹ năng tác nhân của bạn

Bạn đã xây dựng một chuỗi cung ứng tự động hoạt động hiệu quả. Bạn đã sẵn sàng thúc đẩy kênh tăng trưởng hơn nữa chưa? Những thử thách này áp dụng các mẫu mà bạn đã học vào những vấn đề mới.

Thử thách 1: Tìm kiếm dựa trên hình ảnh (Nhúng đa phương thức)

Quy trình hiện tại: Vision Agent đếm các mặt hàng → tạo cụm từ tìm kiếm dạng văn bản → Supplier Agent nhúng văn bản → tìm kiếm AlloyDB

Thử thách: Bỏ qua hoàn toàn văn bản – gửi hình ảnh đã cắt trực tiếp cho Tác nhân nhà cung cấp.

Gợi ý:

Việc thực thi mã của Vision Agent có thể cắt từng mục trong hình ảnh kệ hàng
Mô hình multimodalembedding@001 của Vertex AI có thể nhúng trực tiếp hình ảnh
Sửa đổi inventory.py để chấp nhận byte hình ảnh thay vì văn bản
Cập nhật nội dung mô tả kỹ năng A2A để cho biết "Chấp nhận: image/jpeg hoặc text"

Tại sao điều này lại quan trọng: Tính năng tìm kiếm bằng hình ảnh chính xác hơn đối với những bộ phận có hình thức phức tạp (biến thể màu sắc, hư hỏng, khác biệt về bao bì).

Thử thách 2: Khả năng quan sát – Xây dựng niềm tin bằng sự minh bạch

Trạng thái hiện tại: Hệ thống hoạt động, nhưng bạn không thể thấy "bên dưới"

Thử thách: Kiểm tra nhật ký truy vấn của AlloyDB để chứng minh rằng tính năng tìm kiếm vectơ đang thực thi.

Các bước:

Theo mặc định, thông tin chi tiết về truy vấn sẽ được bật trên AlloyDB. Để xác minh, hãy chạy:

gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"

Chạy tìm kiếm nhà cung cấp thông qua giao diện người dùng
Xem SQL thực tế đã thực thi:

gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

Đầu ra dự kiến: Bạn sẽ thấy chính xác truy vấn ORDER BY part_embedding <=> $1::vector LIMIT 1 cùng với thời gian thực thi.

Lý do điều này quan trọng: Khả năng quan sát giúp tạo dựng niềm tin. Khi các bên liên quan hỏi "Tác nhân này đưa ra quyết định như thế nào?", bạn có thể cho họ xem kế hoạch truy vấn, chứ không chỉ kết quả.

Thử thách 3: Thành phần nhiều tác nhân

Thử thách: Thêm một tác nhân thứ ba (Tác nhân hậu cần) để tính phí vận chuyển dựa trên vị trí kho hàng và trọng lượng của mặt hàng.

Cấu trúc:

Đầu ra của Vision Agent: số lượng mặt hàng
Đầu ra của Trợ lý nhà cung cấp: vị trí của nhà cung cấp
Thông tin đầu vào của Logistics Agent (MỚI): điểm đến, trọng lượng → thông tin đầu ra: phí vận chuyển + Giờ đến dự kiến

Lưu ý: Giao thức A2A giúp việc này trở nên đơn giản – hãy tạo một thẻ tác nhân mới có kỹ năng calculate_shipping. Control Tower sẽ tự động phát hiện ra tài khoản đó.

Mẫu bạn đang học: Đây là cốt lõi của Cấu trúc hướng tác nhân – các hệ thống phức tạp được xây dựng từ những chuyên gia nhỏ, có thể kết hợp.

13. Kết luận

Bạn đã chuyển đổi thành công từ AI tạo sinh sang AI tác nhân.

Những gì chúng tôi đã xây dựng:

Thị giác: Chúng tôi đã thay thế "đoán" bằng Thực thi mã (Gemini 3 Flash thông qua khoá API).
Bộ nhớ: Chúng tôi đã thay thế "tìm kiếm chậm" bằng AlloyDB ScaNN (thông qua GCP).
Hành động: Chúng tôi đã thay thế "tích hợp API" bằng Giao thức A2A.

Lợi ích của kiến trúc kết hợp:

Lớp học lập trình này minh hoạ một phương pháp kết hợp:

Vision Agent: Sử dụng Gemini API (khoá API) – đơn giản, có bậc miễn phí, không cần tính phí trên GCP
Tác nhân nhà cung cấp: Sử dụng GCP (Vertex AI + AlloyDB) – cấp doanh nghiệp, tuân thủ quy định

Đây là cấu trúc của nền kinh tế tự chủ. Bạn có thể giữ lại mã này.

Các bước tiếp theo

Lấy khoá Gemini API (có bậc miễn phí)
Khám phá tài liệu về Gemini API
Xem Tài liệu về AI AlloyDB
Khám phá tính năng Thực thi mã của Gemini

Xây dựng chuỗi cung ứng tự động bằng Gemini 3 Flash và AlloyDB AI Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

1. Tổng quan

Kiến trúc tất định

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

Kiến thức bạn sẽ học được

Yêu cầu

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

Tạo dự án

Thiết lập cơ sở dữ liệu [AlloyDB]

Nhận mã

Thiết lập dự án

Bật IP công khai trên AlloyDB

Cấp quyền cho Vertex AI

Chạy tập lệnh thiết lập

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

Kết nối với AlloyDB Studio

Bật tiện ích

Tạo Bảng khoảng không quảng cáo

Cột part_embedding lưu trữ các vectơ 768 chiều từ text-embedding-005. Đây là yếu tố giúp tìm kiếm ngữ nghĩa hoạt động.

Chèn dữ liệu mẫu

Cấp quyền nhúng

Tạo vectơ nhúng

Tạo chỉ mục ScaNN

Xác minh mọi thứ đã hoạt động

4. Tìm hiểu về cấu trúc

Ngăn xếp tác nhân

Tác nhân thị giác (agents/vision-agent/)

Nhân viên hỗ trợ của nhà cung cấp (agents/supplier-agent/)

Control Tower (frontend/)

Quy trình A2A

Kết nối AlloyDB

5. Bước 1: Bộ nhớ (Tác nhân nhà cung cấp)

The Audit: The Amnesiac

Khởi động Supplier Agent

Cách khắc phục: Triển khai toán tử <=>

Xác minh

6. Bước 2: Đôi mắt (Tác nhân thị giác)

The Audit: The Hallucination

Cách khắc phục: Kích hoạt vòng lặp Suy nghĩ – Hành động – Quan sát

Khởi động Trợ lý thị giác

Xác minh

7. Bước 3: Bắt tay (Thẻ đại lý A2A)

A2A so với API REST truyền thống

Tạo Thẻ tác nhân

8. Bước 4: Tháp điều khiển

Bắt đầu tất cả dịch vụ

Kiểm thử hệ thống

Điều gì vừa xảy ra

Khắc phục sự cố

9. 🎁 Phần thưởng: Triển khai lên Cloud Run

10. Dọn dẹp

11. Tài liệu tham khảo và tài liệu đọc thêm

Tài liệu chính thức

Tài nguyên khác

12. Chế độ thử thách: Level Up kỹ năng tác nhân của bạn

Thử thách 1: Tìm kiếm dựa trên hình ảnh (Nhúng đa phương thức)

Thử thách 2: Khả năng quan sát – Xây dựng niềm tin bằng sự minh bạch

Thử thách 3: Thành phần nhiều tác nhân

13. Kết luận

Xây dựng chuỗi cung ứng tự động bằng Gemini 3 Flash và AlloyDB AI