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 tôi 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 xác đị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ó:

17191a91a9c54146.png

  1. The Eyes (Tác nhân thị giác): Chúng tôi trang bị cho Gemini 3 Flash 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.
  2. 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.
  3. 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 với 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 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 Cloud Shell với AlloyDB bằng Proxy xác thực.

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 (bậc miễn phí có tại Google AI Studio) cho Vision Agent.

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

Tạo dự án

  1. 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.
  2. Đả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.
  1. 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, 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

Vậy là xong!

Giờ đây, bạn đã sẵn sàng thiết lập bằng một lần nhấp. Phần tiếp theo sẽ:

  • Tự động mở Cloud Shell
  • Sao chép kho lưu trữ
  • Hướng dẫn bạn toàn bộ quy trình thiết lập trong một hướng dẫn tương tác

3. Thiết lập chỉ bằng một lần nhấp trong Cloud Shell

Chúng tôi đã đơn giản hoá quy trình thiết lập thành một hướng dẫn có hướng dẫn về Cloud Shell. Mọi thứ đều được tự động hoá: việc cung cấp cơ sở hạ tầng, thiết lập AlloyDB, định cấu hình Auth Proxy và gieo dữ liệu vào cơ sở dữ liệu.

Chạy hướng dẫn về Cloud Shell

⚠️ QUAN TRỌNG – Trước khi nhấp: Khi nhấp vào nút bên dưới, bạn sẽ thấy một hộp thoại bảo mật hỏi "Mở trong Cloud Shell". Thao tác này xuất hiện TRƯỚC khi kho lưu trữ được sao chép.

Bạn phải:

  1. ✅ Đánh dấu vào hộp "Trust repo" (Tin tưởng kho lưu trữ)
  2. ✅ Nhấp vào "Xác nhận"

Nếu không có bước này, kho lưu trữ sẽ không được sao chép.

Bạn đã sẵn sàng chưa? Nhấp để mở dự án bằng hướng dẫn từng bước:

Điều gì xảy ra tiếp theo:

  1. Cloud Shell sẽ mở ra với kho lưu trữ được sao chép trước
  2. Một bảng điều khiển hướng dẫn sẽ xuất hiện ở bên phải cùng với hướng dẫn từng bước
  3. Bạn sẽ được hướng dẫn cách:
  • Lấy khoá Gemini API (có gói miễn phí)
  • Thiết lập dự án GCP trong thiết bị đầu cuối
  • Chạy thiết lập (kiểm tra API, bật nếu cần, cung cấp AlloyDB: khoảng 15 phút)
  • Thực hiện 2 thay đổi chính về mã (bật tính năng thị giác và bộ nhớ)
  • Tạo thẻ đại lý (giao thức A2A)
  • Bắt đầu tất cả các dịch vụ

Hướng dẫn này có tính tương tác – mỗi bước đều được đánh số và theo dõi tiến trình của bạn.

Cách khác: Thiết lập thủ công

Nếu bạn muốn tự kiểm soát:

  1. Mở Cloud Shell và xác minh rằng dự án của bạn đã được thiết lập
gcloud config get-value project
  1. Nếu cần, hãy thiết lập dự án
gcloud config set project YOUR_PROJECT_ID
  1. Sao chép kho lưu trữ
git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git
cd visual-commerce-gemini-3-alloydb
  1. Chạy chương trình thiết lập
sh setup.sh

Làm theo hướng dẫn trên màn hình trong tập lệnh thiết lập.

Tiếp theo: Hướng dẫn này sẽ hướng dẫn bạn thực hiện các bước còn lại. Sau khi hoàn tất, hãy tiếp tục đến Mục 4 để tìm hiểu những gì đã xảy ra bên trong

4. Hậu trường: Auth Proxy và Database Seeding

Vấn đề: AlloyDB nằm trong một VPC riêng tư. Cloud Shell nằm ngoài phạm vi này. Không thể kết nối trực tiếp.

Giải pháp: Uỷ quyền proxy AlloyDB tạo một đường hầm an toàn, được xác thực bằng IAM từ 127.0.0.1:5432 trên Cloud Shell đến phiên bản AlloyDB của bạn. Nếu phiên bản của bạn đã bật IP công khai, thì proxy sẽ sử dụng IP đó; nếu không, proxy sẽ kết nối qua IP riêng tư của VPC.

Những việc mà setup.sh đã làm

  1. Tự động phát hiện phiên bản AlloyDB của bạn (cụm, khu vực, dự án)
  2. Tạo .env bằng tất cả thông tin đăng nhập (GEMINI_API_KEY, DB_PASS, thông tin chi tiết về AlloyDB)
  3. Đã tải xuống và khởi động Auth Proxy (với –public-ip nếu có)
  4. Gieo cơ sở dữ liệu với 8 bộ phận kho hàng mẫu + chỉ mục ScaNN

Tệp .env của bạn đã sẵn sàng. Tất cả các lần chạy trong tương lai sẽ tự động tải thông tin đăng nhập.

Xác minh xem có hiệu quả không

Đảm bảo bạn vẫn ở thư mục gốc của kho lưu trữ

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

Kiểm tra xem Auth Proxy có đang chạy không

ps aux | grep alloydb-auth-proxy

Nội dung đã được tạo

  • bảng khoảng không quảng cáo có 8 phần và 768 mục nhúng
  • Chỉ mục ScaNN (idx_inventory_scann) để tìm kiếm vectơ nhanh

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

Nhân viên của nhà cung cấp ghi nhớ hàng triệu bộ phận bằng AlloyDB ScaNN. Chúng tôi bắt đầu bằng máy chủ A2A, sau đó sửa truy vấn vectơ.

The Audit: The Amnesiac

Nếu bạn truy vấn Supplier Agent ngay bây giờ (bằng SQL của phần giữ chỗ), thì nó sẽ trả về hàng đầu tiên mà nó tìm thấy chứ không phải kết quả khớp gần nhất. Không có khái niệm về sự tương đồng. Đó là một người bị mất trí nhớ.

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)

Mục nhúng ngữ nghĩa thực

Trong quá trình thiết lập, cơ sở dữ liệu được gieo hạt bằng các vectơ nhúng ngữ nghĩa thực được tạo thông qua mô hình text-embedding-005 của Google Gen AI SDK. Điều này đảm bảo việc so khớp mức độ tương tự chính xác chứ không phải là các vectơ ngẫu nhiên. Quá trình gieo hạt mất khoảng 10 giây cho 13 mục mẫu bằng cách sử dụng quá trình tạo vectơ nhúng song song để tạo các vectơ 768 chiều có ý nghĩa, nắm bắt ý nghĩa ngữ nghĩa của từng phần.

AlloyDB Detour: Tại sao nên dùng ScaNN?

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

Tác nhân này đi kèm với một truy vấn giữ chỗ. Chúng ta cần bật tính năng tìm kiếm vectơ ScaNN.

Bước 1: Mở tệp kho hàng

cd agents/supplier-agent

Bước 2: Tìm TODO trong inventory.py

Tìm hàm find_supplier() ở khoảng dòng 47-60. Bạn sẽ thấy:

# ============================================================
# CODELAB STEP 1: Implement ScaNN Vector Search
# ============================================================
# TODO: Replace this placeholder query with ScaNN vector search

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

Bước 3: Thay thế SQL giữ chỗ bằng tính năng tìm kiếm vectơ ScaNN

Xoá hai dòng sau:

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

Sau đó thay thế chúng bằng:

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

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

  • <=> là toán tử khoảng cách cosine 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 kiểu vectơ của PostgreSQL
  • LIMIT 1 chỉ trả về kết quả trùng khớp gần nhất
  • 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

44500cdeeca3cee8.png

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.

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. Vision Agent thực hiện "phép toán trực quan" thông qua tính năng Thực thi mã. Máy chủ A2A (main.py) uỷ quyền cho agent_executor.py, lệnh này gọi agent.py để phân tích Gemini.

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.

Giải pháp: Đánh thức 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.

  1. Mở agents/vision-agent/agent.py .
  2. Tìm phần GenerateContentConfig.
  3. Huỷ đánh dấu cả khối thinking_config=types.ThinkingConfig(...) và tools=[types.Tool(code_execution=...)] .
  4. Ứ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="LOW",  # 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="LOW"?

Đối với tác vụ cụ thể này (đếm các mục thông qua việc thực thi mã), "THẤP" cung cấp đủ ngân sách lý luận để:

  • Lên kế hoạch cho cấu trúc tập lệnh Python
  • Quyết định phương pháp xử lý hình ảnh cần sử dụng
  • Xác minh rằng số lượng khớp với số lượng khung hình chữ nhật

Việc sử dụng "HIGH" sẽ làm tăng độ trễ và chi phí gấp 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. Hãy dành "CAO" cho những suy luận phức tạp gồm nhiều bước (ví dụ: "Phân tích tình trạng gián đoạn chuỗi cung ứng này và đề xuất 3 nhà cung cấp thay thế kèm theo lý do").

Tối ưu hoá chi phí và hiệu suất là một kỹ năng quan trọng đối với kỹ thuật AI sản xuất: điều chỉnh độ sâu lý 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 tác nhân. 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.

dc9bc53007336472.png

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à nắm đượ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ị.

Cách khắc phục: Tạo thẻ nhân viên hỗ trợ

Chúng ta cần xác định những việc mà Supplier Agent có thể làm.

  1. Sao chép agents/supplier-agent/agent_card_skeleton.json vào agents/supplier-agent/agent_card.json.
  2. Chỉnh sửa tệp để thay thế phần giữ chỗ:

Trước (khung):

{
  "name": "___FILL: agent-name ___",
  "description": "___FILL: what-this-agent-does ___"
}

Sau khi chỉnh sửa:

{
  "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?"]
  }]
}
  1. Khởi động lại Supplier Agent để tải thẻ mới:

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.

dd352ca2e7e6109a.png

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:

  • AlloyDB Auth Proxy (nếu chưa chạy)
  • 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:

  1. 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
  2. Chọn "Xem trước trên cổng 8080"
  3. Trang tổng quan Control Tower sẽ mở ra trong một thẻ mới

Chạy bản minh hoạ:

  1. 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 nút điều khiển âm thanh
  2. 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
  3. 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 (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)

  1. Trên trang chủ, bạn sẽ thấy phần "Bắt đầu nhanh" có các hình ảnh mẫu
  2. Nhấp vào một hình ảnh mẫu bất kỳ để tự động bắt đầu phân tích
  3. 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

  1. 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
  2. Nhấp vào "Bắt đầu quy trình làm việc tự động"
  3. Quan sát quy trình gồm 4 giai đoạn

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

  1. Khám phá tác nhân: Các phương thức A2A cho thấy thẻ Vision Agent và Supplier Agent cùng với các kỹ năng và điểm cuối của chúng
  2. 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"
  3. So khớp nhà cung cấp: Ảnh động tìm kiếm vectơ ScaNN của AlloyDB. Hiển thị cụm từ tìm kiếm (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
  4. Đơ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 công việc sẽ chạy liên tục.

1a031c4fd407a183.png

Đ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 theo thời gian thực qua WebSocket. 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:

  • "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 Auth Proxy đang chạy:
ps aux | grep alloydb-auth-proxy

Sự cố kết nối AlloyDB:

Nếu bạn thấy thông báo không kết nối được với máy chủ tại 127.0.0.1, cổng 5432:

Nếu bạn thấy không kết nối được với máy chủ tại 127.0.0.1, cổng 5432:

  1. Kiểm tra Proxy uỷ quyền: ps aux | grep alloydb-auth-proxy
  2. Xác minh đã bật IP công khai: gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
  3. Đối với quá trình phát triển cục bộ (không phải Cloud Shell):
  4. Vấn đề: Cloud Shell hoạt động tự động, nhưng các máy cục bộ cần có mạng được uỷ quyền
  5. Giải pháp: Chạy lại sh setup.sh và chọn lựa chọn 1 (uỷ quyền 0.0.0.0/0) khi được nhắc
  6. Lưu ý về bảo mật: Ngay cả khi có 0.0.0.0/0, kết nối vẫn yêu cầu:
  7. Thông tin đăng nhập GCP hợp lệ (Thông tin xác thực mặc định của ứng dụng)
  8. Mật khẩu cơ sở dữ liệu
  9. Mã hoá mTLS (Proxy xác thực xử lý việc này)

9. 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 cleanup.sh

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

  • Cụm AlloyDB (yếu tố chính quyết định 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.

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

Tất cả thông tin 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à Google AI.

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

Gemini 3 Flash:

AI và ScaNN của AlloyDB:

Thông tin về giá:

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

Tính năng

Nhận

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 tạo 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 Temperature=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á việc 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
  • 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ơ

11. Chế độ thử thách: Nâng cao kỹ năng sử dụng AI

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 hơn nữ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 đến Supplier Agent.

Gợi ý:

  1. Hoạt động thực thi mã của Vision Agent có thể cắt từng mục trong hình ảnh kệ hàng
  2. Mô hình multimodalembedding@001 của Vertex AI có thể nhúng trực tiếp hình ảnh
  3. Sửa đổi inventory.py để chấp nhận byte hình ảnh thay vì văn bản
  4. 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 lòng 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 đượ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 xây dựng lòng 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ả đầu ra.

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 Trợ lý thị giác: 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): vị trí xuất hiện, trọng lượng → thông tin đầu ra: phí vận chuyển + thời gian giao hàng 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ẻ đại lý 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.

12. Kết luận

Bạn đã chuyển đổi thành công từ AI tạo sinh sang AI có khả năng hành động.

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