1. Giới thiệu
Tổng quan
Phòng thí nghiệm này minh hoạ cách triển khai một cách an toàn lệnh gọi dựa trên sự kiện của một tác nhân ADK được triển khai trên Cloud Run bằng cách sử dụng các dịch vụ Eventarc và Pub/Sub. Thông thường, người dùng hoặc một tác nhân khác sẽ gọi trực tiếp cho tác nhân. Tuy nhiên, khi một tác nhân được tích hợp vào các quy trình dựa trên sự kiện hiện có, việc thực hiện một lệnh gọi trực tiếp sẽ yêu cầu thay đổi phần mềm hiện có. Việc kích hoạt lệnh gọi tác nhân dựa trên một sự kiện cho phép kết hợp tác nhân vào các quy trình hiện có mà không cần thay đổi quy trình.
Bạn sẽ thực hiện
Trong lớp học lập trình này, bạn sẽ tạo một ứng dụng dựa trên tác nhân ZooKeeper có một tác nhân AI và sử dụng một số công cụ để cung cấp thông tin về động vật trong vườn thú tưởng tượng.
Bạn sẽ triển khai ứng dụng ZooKeeper dưới dạng một dịch vụ cho Cloud Run. Đây là một nền tảng điện toán không máy chủ, được quản lý toàn diện, chạy các vùng chứa không trạng thái trên cơ sở hạ tầng của Google. Sau đó, bạn sẽ thiết lập một trình kích hoạt Eventarc để gọi điểm cuối dịch vụ nhằm xử lý không đồng bộ các thông báo được đăng lên một chủ đề Pub/Sub. Bạn sẽ đảm bảo rằng quá trình triển khai tuân theo các phương pháp hay nhất, bao gồm cả việc sử dụng tài khoản dịch vụ IAM được chỉ định, cấp quyền truy cập có đặc quyền tối thiểu và giảm thiểu khả năng bị tấn công bằng cách chỉ cho phép Eventarc truy cập vào điểm cuối của ứng dụng ZooKeeper. Bạn sẽ thực hiện việc này với sự trợ giúp của Cloud Shell và bảng điều khiển Cloud. Bạn sẽ sử dụng các thư viện ADK và Cloud SDK cho Python. Để kiểm tra hành vi, bạn sẽ sử dụng gcloud CLI.
Kiến thức bạn sẽ học được
- Triển khai tác nhân ADK lên Google Cloud Run.
- Tích hợp trình kích hoạt Eventarc với tác nhân ADK đang chạy trên Google Cloud Run.
- Bảo mật việc triển khai và tích hợp với Eventarc bằng cách sử dụng nguyên tắc cấp quyền truy cập tối thiểu với sự trợ giúp của IAM trên Google Cloud.
- Xuất bản và kéo thông báo đến và đi từ Pub/Sub.
- Giảm thiểu khả năng ứng dụng của bạn bị lộ diện công khai khi triển khai trên Google Cloud Run.
Bạn cần có
- Trình duyệt web Chrome †
- Tài khoản Google cá nhân ‡
- Một Dự án trên Google Cloud được liên kết với một tài khoản thanh toán đang hoạt động
Xin lưu ý rằng tài khoản của bạn phải có quyền truy cập IAM vào dự án cho phép bạn cung cấp tài nguyên và định cấu hình quyền truy cập IAM vào các tài nguyên này.
† Trải nghiệm người dùng khi sử dụng các trình duyệt khác có thể khác với trải nghiệm được mô tả trong phòng thí nghiệm.
‡ Khi sử dụng tài khoản công ty hoặc trường học, bạn có thể bị hạn chế thực hiện một số thao tác được mô tả trong lớp học.
2. Thiết lập môi trường
Để đảm bảo môi trường phát triển hoạt động đầy đủ cho phòng thí nghiệm, bạn sẽ sử dụng Google Cloud Shell đã cài đặt sẵn tất cả các công cụ cần thiết. Làm theo hướng dẫn để thiết lập môi trường.
Tạo một Tài khoản Google nếu bạn chưa có.
Hướng dẫn thiết lập
- Sử dụng Tài khoản Google của bạn để đăng nhập vào Google Cloud Console.
- 👉 Mở trình chọn dự án trong thanh điều hướng trên cùng (trình chọn này có thể có nội dung "Chọn một dự án" hoặc cho thấy tên của một dự án hiện có) hoặc nhấp vào tổ hợp phím
Ctrl+Orồi chọn một dự án hiện có hoặc tạo một dự án mới.Quá trình tạo dự án mới sẽ mất vài giây. Chờ cho đến khi dự án sẵn sàng rồi chọn dự án đó bằng trình chọn dự án.
- 👉 Nhấp vào biểu tượng Cloud Shell ở đầu bảng điều khiển Google Cloud. (được đánh dấu bằng hình chữ nhật màu đỏ):
Nếu được yêu cầu, hãy nhấp vào **Uỷ quyền** trong hộp thoại bật lên để phê duyệt Cloud Shell sử dụng thông tin đăng nhập của tài khoản.
- 👉💻 Đảm bảo rằng bạn đã định cấu hình giao diện dòng lệnh gcloud để sử dụng dự án mà bạn đã chọn (hoặc tạo). Chạy lệnh sau để kiểm tra mã dự án đã định cấu hình:
gcloud config get-value projectYour active configuration is: [cloudshell-19597] [PROJECT_ID]
[PROJECT_ID]sẽ là mã nhận dạng của dự án mà bạn đã chọn hoặc tạo.👉💻 Nếu bạn thấy một giá trị khác, hãy chạy lệnh sau để định cấu hình mã dự án làm mã dự án mặc định cho các lệnh gcloud CLI:gcloud config set project [YOUR_PROJECT_ID]gcloud config set project lab-project-id-example-123
gcloud projects list \ --format='value(projectId)' \ --sort-by='~createTime'
- 👉💻 Thiết lập vị trí để cung cấp tài nguyên, mã nhận dạng và số dự án của bạn trong các biến môi trường:
export LOCATION="us-central1" export PROJECT_ID=$(gcloud config get-value project) export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") - 👉💻 Bật các API của Google cần thiết cho bài thực hành này.
gcloud services enable \ aiplatform.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ pubsub.googleapis.comOperation "operations/ab12345c-6e7f-8ghi-jkl9-m0e1d23456f7" finished successfully.
3. Triển khai ứng dụng minh hoạ ZooKeeper
Các bước sau đây sẽ cung cấp và định cấu hình tài nguyên, bao gồm cả việc triển khai ứng dụng AI dựa trên tác nhân.
Thiết lập tài nguyên Pub/Sub
Bạn sẽ tạo 2 chủ đề Pub/Sub. Một khoá sẽ được dịch vụ bên thứ ba dùng để gửi sự kiện đến ứng dụng AI dựa trên tác nhân của bạn. Một cho ứng dụng xuất bản kết quả của quá trình xử lý sự kiện.
- 👉💻 Tạo một chủ đề Pub/Sub dùng để kích hoạt ứng dụng AI có tác nhân:
gcloud pubsub topics create invoke_agent export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)") - 👉💻 Tạo một chủ đề Pub/Sub nơi ứng dụng có thể đăng các phản hồi của mình:
gcloud pubsub topics create agent_responses export RESPONSE_TOPIC_ID=$(gcloud pubsub topics describe agent_responses --format="value(name)") gcloud pubsub subscriptions create agent_responses \ --topic=agent_responses
Thiết lập tài khoản dịch vụ và chính sách IAM ở cấp dự án
Bạn sẽ tạo hai tài khoản dịch vụ để giới hạn phạm vi truy cập của dịch vụ Cloud Run và trình kích hoạt Eventarc ở mức tối thiểu theo nguyên tắc truy cập đặc quyền tối thiểu. Dịch vụ Cloud Run yêu cầu quyền ghi nhật ký và dấu vết, gọi LLM Gemini trên Google Vertex AI và đăng kết quả lên một chủ đề Pub/Sub. Quyền truy cập tối thiểu của trình kích hoạt Eventarc yêu cầu có quyền gọi dịch vụ Cloud Run ZooKeeper và truy cập vào Pub/Sub để đọc các sự kiện đã đăng. Hướng dẫn này giúp bạn cấp cho tài khoản dịch vụ của điều kiện kích hoạt các quyền cần thiết để mạo danh dịch vụ hệ thống Pub/Sub. Sau khi tạo tài nguyên trình kích hoạt Eventarc, bạn sẽ chạy lệnh cấp vai trò roles/run.invoker để cho phép tài khoản dịch vụ của trình kích hoạt gọi dịch vụ Cloud Run.
- 👉💻 Tạo tài khoản dịch vụ cho dịch vụ Cloud Run:
gcloud iam service-accounts create zookeeper-cloudrun-sa export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Cấp cho tài khoản dịch vụ quyền ghi nhật ký và dấu vết, đồng thời sử dụng các mô hình Gemini trên Vertex AI:
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/logging.logWriter" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/cloudtrace.agent" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/aiplatform.user" \ --condition=None - 👉💻 Cấp cho tài khoản dịch vụ quyền đăng thông báo vào chủ đề "agent_responses":
gcloud pubsub topics add-iam-policy-binding agent_responses \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/pubsub.publisher" - 👉💻 Tạo tài khoản dịch vụ cho điều kiện kích hoạt Eventarc:
gcloud iam service-accounts create zookeeper-trigger-sa export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Cấp quyền cho tài khoản dịch vụ hệ thống Pub/Sub để thực hiện các yêu cầu đẩy đã xác thực:
gcloud iam service-accounts add-iam-policy-binding "${TRIGGER_SA}" \ --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"
Triển khai ứng dụng ZooKeeper lên Cloud Run
Bạn sẽ tải mã của ứng dụng minh hoạ xuống từ GitHub. Sau đó, triển khai mã lên Cloud Run.
- 👉💻 Tải ứng dụng AI tác nhân xuống:
mkdir zoo-keeper-lab && cd zoo-keeper-lab git init git remote add origin https://github.com/GoogleCloudPlatform/devrel-demos git config set core.sparseCheckout true echo "ai-ml/agent-labs/adk_invoke_with_pubsub/" >> .git/info/sparse-checkout git pull origin main --depth 1 cd ai-ml/agent-labs/adk_invoke_with_pubsub/ - 👉💻 Triển khai ứng dụng AI có khả năng hành động trên Cloud Run:
gcloud run deploy zookeeper-agent \ --region="${LOCATION}" \ --source="." \ --no-allow-unauthenticated \ --quiet \ --service-account="${ZOOKEEPER_SA}" \ --set-env-vars="REPLY_TOPIC_ID=${RESPONSE_TOPIC_ID}"
Định cấu hình điều kiện kích hoạt Eventarc
Sau khi chuẩn bị tất cả tài nguyên (chủ đề Pub/Sub, tài khoản dịch vụ IAM và dịch vụ Cloud Run), bạn có thể thiết lập tài nguyên trình kích hoạt Eventarc. Bạn sẽ tạo tài nguyên trình kích hoạt Eventarc và cấp quyền gọi dịch vụ Cloud Run cho tài khoản dịch vụ của trình kích hoạt.
- 👉💻 Tạo điều kiện kích hoạt Eventarc:
gcloud eventarc triggers create invoke-agent \ --location="${LOCATION}" \ --destination-run-service="zookeeper-agent" \ --destination-run-path="/zookeeper" \ --destination-run-region="${LOCATION}" \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --transport-topic="${INVOKE_TOPIC_ID}" \ --service-account="${TRIGGER_SA}" - 👉💻 Cấp quyền cho tài khoản dịch vụ của điều kiện kích hoạt để gọi dịch vụ Cloud Run:
gcloud run services add-iam-policy-binding zookeeper-agent \ --region="${LOCATION}" \ --member="serviceAccount:${TRIGGER_SA}" \ --role="roles/run.invoker"
4. Xem cách hoạt động của giải pháp
Bây giờ, hãy xem lại những gì bạn vừa triển khai. Sơ đồ sau đây phản ánh tất cả các tài nguyên và cách chúng tương tác với nhau. Bạn sẽ sử dụng gcloud CLI để xuất bản một thông báo đến chủ đề "invoke_agent". Thao tác này sẽ mô phỏng một sự kiện mà dịch vụ bên thứ ba ghi vào dịch vụ nhắn tin để gọi ứng dụng AI tác nhân.
Việc triển khai được bảo mật theo quyền truy cập tối thiểu. Dịch vụ Cloud Run thực thi quy trình xác thực (xem đối số --no-allow-unauthenticated ở bước 9 trong phần trước). Chỉ những danh tính có vai trò/run.invoker hoặc các quyền tương tự mới có thể gọi dịch vụ này. Và vai trò này chỉ được cấp cho tài khoản dịch vụ của trình kích hoạt Eventarc. Tương tự, quyền truy cập vào chủ đề "invoke_agent" được giảm thiểu để ngăn chặn việc xuất bản trái phép các sự kiện. Bạn vẫn có thể gọi trực tiếp tác nhân ZooKeeper mà không cần đăng lên chủ đề Pub/Sub. Hãy xem phần 6 để tìm hiểu cách ẩn điểm cuối của ứng dụng khỏi quyền truy cập công khai.
Chạy quy trình công việc
Bạn sẽ mô phỏng một sự kiện bên ngoài bằng cách xuất bản một câu hỏi bằng ngôn ngữ tự nhiên lên ZooKeeper.
👉💻 Sử dụng lệnh sau để đăng một thông báo lên chủ đề Pub/Sub:
gcloud pubsub topics publish invoke_agent \
--message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'
Trên thực tế, thông tin sự kiện có thể sẽ ở dạng khó đọc hơn. Để xử lý sự kiện này, một ứng dụng AI có khả năng hành động sẽ cần có hướng dẫn chi tiết về định dạng của sự kiện, dữ liệu và những việc mà AI nên làm với thông tin sự kiện.
Bạn có thể kiểm tra để đảm bảo rằng tác nhân đã nhận được sự kiện, xử lý yêu cầu và đăng phản hồi vào chủ đề "agent_responses". Để đọc phản hồi, bạn sẽ sử dụng chế độ đăng ký "agent_responses" (lớp học lập trình này sử dụng cùng một mã nhận dạng cho cả chủ đề và chế độ đăng ký phản hồi).
👉💻 Sử dụng lệnh sau để đọc phản hồi của nhân viên hỗ trợ từ gói thuê bao Pub/Sub:
gcloud pubsub subscriptions pull agent_responses --auto-ack
Đầu ra sẽ in một bảng có siêu dữ liệu thông báo và tải trọng chứa câu trả lời rằng có 33 loài trong vườn thú. Cờ --auto-ack sẽ tự động xác nhận thư sau khi thư được kéo, nên thư sẽ không được gửi lại.
Cách hoạt động
Xem mã nguồn của ứng dụng AI dựa trên tác nhân bằng cách mở Cloud Shell Editor và xem các tệp trong thư mục ~/zoo-keeper-lab. Bạn cũng có thể xem mã nguồn trên GitHub.
- main.py triển khai một ứng dụng web FastAPI cơ bản với một trình xử lý duy nhất xử lý các sự kiện Eventarc.
- processor.py phân tích cú pháp thông báo của sự kiện để truy xuất mã nhận dạng người dùng và yêu cầu. Sau đó, nó sẽ tạo một phiên mới trong trình chạy ADK và gọi tác nhân Zookeeper để xử lý yêu cầu. Câu trả lời của nhân viên hỗ trợ được đăng lên chủ đề Pub/Sub "agent_responses".
- Thư mục con zookeeper_agent lưu trữ mã nguồn của tác nhân ADK. Bạn có thể chạy lệnh
adk run zookeeper_agenttừ thư mục gốc của ứng dụng để tương tác với tác nhân bằng adk CLI.
Cách khắc phục sự cố
Trong trường hợp có lệnh nào đó không thực hiện được, hãy đọc kỹ thông báo lỗi. Nếu quá trình triển khai đến Cloud Run không thành công, bước đầu tiên là xác định giai đoạn xảy ra lỗi trong quy trình.
- Nếu đầu ra của lệnh "gcloud run deploy..." báo cáo rằng bản dựng không thành công, hãy xem URL nhật ký bản dựng trong đầu ra và mở URL đó trong một cửa sổ riêng.
- Nếu đầu ra có nội dung như "service failed to start" (không khởi động được dịch vụ) hoặc tương tự, thì có nghĩa là dịch vụ triển khai nhưng sau đó quá trình thực thi không vượt qua được quy trình kiểm tra tình trạng. Trong trường hợp này, hãy mở Trình khám phá nhật ký hoặc xem đoạn văn sau để biết lệnh gcloud CLI. Đọc nhật ký để tìm nguyên nhân gốc rễ gây ra lỗi.
Điều gì sẽ xảy ra nếu bạn đăng một thông báo lên Pub/Sub nhưng tác nhân không phản hồi hoặc phản hồi có vẻ lạ?
👉💻 Sử dụng lệnh sau để đọc nhật ký ứng dụng được đăng từ lần thực thi gần đây:
gcloud logging read \
'resource.type = "cloud_run_revision" AND \
resource.labels.service_name = "zookeeper-agent" AND \
resource.labels.location = "us-central1"'
Các nhật ký này theo dõi quá trình thực thi và báo cáo các lỗi như tải trọng thông báo không chính xác hoặc không phân tích cú pháp được, phản hồi không hợp lệ từ mô hình Gemini, chế độ cài đặt môi trường không hợp lệ và các vấn đề có thể xảy ra khác.
5. Tăng cường bảo mật khi triển khai
Dịch vụ Cloud Run mà bạn đã triển khai sẽ hiển thị một điểm cuối công khai mà mọi người trên Internet đều có thể gọi. Mặc dù điểm cuối được bảo vệ để chống lại việc gọi trái phép và xác thực nghiêm ngặt cấu trúc của yêu cầu, nhưng điểm cuối này vẫn để lại vectơ tấn công cho phép các cuộc tấn công từ chối dịch vụ và từ chối ví. Vì đường dẫn gọi duy nhất cho dịch vụ trong thiết kế hiện tại là thông qua trình kích hoạt Eventarc, nên dịch vụ này không cần phải hiển thị điểm cuối của mình trên Internet.
👉💻 Đóng vectơ tấn công này bằng cách hạn chế các lệnh gọi đến dịch vụ chỉ từ một số ít nguồn, bao gồm cả các trình kích hoạt Eventarc:
gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal
Giờ đây, nếu cố gắng gọi URL của dịch vụ từ máy cục bộ, bạn sẽ gặp lỗi "404 Page not found" (Không tìm thấy trang 404).
👉💻 Sử dụng curl để gửi yêu cầu đến điểm cuối dịch vụ:
URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"
Bạn sẽ thấy kết quả tương tự như sau:
<html><head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>404 Page not found</title> </head> <body text=#000000 bgcolor=#ffffff> <h1>Error: Page not found</h1> <h2>The requested URL was not found on this server.</h2> <h2></h2> </body></html>
Sau thay đổi này, bạn sẽ không thể gọi ZooKeeper trực tiếp bằng cách gọi điểm cuối dịch vụ Cloud Run, trừ phi bạn thực hiện cuộc gọi từ VPC trong cùng một dự án, mạng VPC dùng chung mà bản sửa đổi của bạn được định cấu hình để gửi lưu lượng truy cập đến hoặc một máy chủ là một phần của phạm vi VPC Service Controls.
6. Tóm tắt
Xin chúc mừng! Bạn đã thiết lập thành công một môi trường để gọi không đồng bộ ứng dụng AI dựa trên tác nhân được kích hoạt bởi các sự kiện đến.
Dọn dẹp
Xin lưu ý rằng việc giữ lại các tài nguyên mà bạn đã cung cấp có thể phát sinh phí trong tài khoản thanh toán của bạn. Nếu không có ý định sử dụng môi trường này cho các thử nghiệm khác và để tránh các khoản phí sắp tới, bạn nên xoá những tài nguyên đã tạo trong lớp học lập trình này.
Có 2 cách để thực hiện việc này:
Cách 1: Tắt dự án
Việc tắt (xoá) dự án sẽ giải phóng tất cả tài nguyên và dữ liệu của dự án, đồng thời huỷ liên kết tài khoản thanh toán. Việc sử dụng phương thức này sẽ ngăn chặn việc tính thêm phí cho mọi tài nguyên hoặc dữ liệu được dùng cho lớp học lập trình này. Dùng lệnh sau để tắt dự án:
gcloud projects delete $(gcloud config get-value project) --quiet
Phương thức 2: Xoá tài nguyên trong dự án
Việc xoá dịch vụ Cloud Run giúp bạn không phải trả thêm phí khi sử dụng nền tảng không máy chủ. Xin lưu ý rằng phương thức này không xoá hoàn toàn tất cả dữ liệu được tạo trong lớp học lập trình, chẳng hạn như Cloud Build và nhật ký ứng dụng, hình ảnh vùng chứa, v.v. Hãy chạy lệnh sau để xoá dịch vụ:
gcloud run services delete zookeeper-agent --region=${LOCATION}
Định nghĩa về điều kiện kích hoạt Eventarc và chủ đề Pub/Sub không áp dụng chi phí quản lý (xem Giá Eventarc và Giá Pub/Sub để biết thêm thông tin).
Tìm hiểu thêm về việc ngừng dự án.
Bước tiếp theo
- Tìm hiểu thêm về mã bằng cách xem bản minh hoạ tại GitHub.
- Xem cấu trúc điều phối quyền truy cập vào các hệ thống doanh nghiệp riêng biệt
- Tìm hiểu cách kích hoạt Cloud Run bằng trình kích hoạt Eventarc
- Tìm hiểu thêm về ADK