Men-deploy aplikasi AI agentic di GKE dengan Agent Development Kit (ADK) dan LLM yang dihosting sendiri

Tutorial ini menunjukkan cara men-deploy dan mengelola aplikasi AI/ML agentik dalam container menggunakan Google Kubernetes Engine (GKE). Dengan menggabungkan Google Agent Development Kit (ADK) dengan model bahasa besar (LLM) yang dihosting sendiri seperti Llama 3.1 yang ditayangkan oleh vLLM, Anda dapat mengoperasionalkan agen AI secara efisien dan dalam skala besar sambil mempertahankan kontrol penuh atas stack model. Tutorial ini memandu Anda melalui proses end-to-end untuk membawa agen berbasis Python dari pengembangan ke deployment produksi di cluster GKE Autopilot dengan akselerasi GPU.

Tutorial ini ditujukan untuk Engineer machine learning (ML), Developer, dan Arsitek cloud yang tertarik untuk menggunakan kemampuan orkestrasi container Kubernetes untuk menyajikan aplikasi AI/ML agentik. Untuk mempelajari lebih lanjut peran umum dan contoh tugas yang kami referensikan dalam Google Cloud konten, lihat Peran dan tugas pengguna GKE Enterprise umum.

Sebelum memulai, pastikan Anda memahami hal-hal berikut:

Latar belakang

Bagian ini menjelaskan teknologi utama yang digunakan dalam tutorial ini.

Agent Development Kit (ADK)

Agent Development Kit (ADK) adalah framework fleksibel dan modular untuk mengembangkan dan men-deploy agen AI. Meskipun dioptimalkan untuk Gemini dan ekosistem Google, ADK tidak mengharuskan Anda menggunakan model atau deployment tertentu, dan dibuat agar kompatibel dengan framework lain. ADK dirancang agar pengembangan agen terasa lebih seperti pengembangan software, sehingga memudahkan developer membuat, men-deploy, dan mengorkestrasi arsitektur agentic yang berkisar dari tugas dasar hingga alur kerja yang kompleks.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi ADK.

Layanan Kubernetes terkelola GKE

Google Cloud menawarkan berbagai layanan, termasuk GKE, yang sangat cocok untuk men-deploy dan mengelola workload AI/ML. GKE adalah layanan Kubernetes terkelola yang menyederhanakan deployment, penskalaan, dan pengelolaan aplikasi dalam container. GKE menyediakan infrastruktur yang diperlukan, termasuk resource yang skalabel, komputasi terdistribusi, dan jaringan yang efisien, untuk menangani permintaan komputasi LLM.

Untuk mengetahui informasi selengkapnya tentang konsep utama Kubernetes, lihat Mulai mempelajari Kubernetes. Untuk mengetahui informasi selengkapnya tentang GKE dan cara GKE membantu Anda melakukan penskalaan, mengotomatiskan, dan mengelola Kubernetes, lihat Ringkasan GKE.

vLLM

vLLM adalah framework penayangan LLM open source yang sangat dioptimalkan yang dapat meningkatkan throughput penayangan di GPU, dengan fitur seperti berikut:

  • Implementasi transformer yang dioptimalkan dengan PagedAttention.
  • Batch berkelanjutan untuk meningkatkan throughput penayangan secara keseluruhan.
  • Paralelisme tensor dan inferensi terdistribusi pada beberapa GPU.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi vLLM.

Menyiapkan lingkungan

Tutorial ini menggunakan Cloud Shell untuk mengelola resource yang dihosting di Google Cloud. Cloud Shell telah diinstal dengan software yang Anda perlukan untuk tutorial ini, termasuk kubectl, terraform, dan Google Cloud CLI.

Untuk menyiapkan lingkungan Anda dengan Cloud Shell, ikuti langkah-langkah berikut:

  1. Di Google Cloud konsol, luncurkan sesi Cloud Shell dan klik Ikon aktivasi Cloud Shell Activate Cloud Shell. Tindakan ini meluncurkan sesi di panel konsol Google Cloud .

  2. Tetapkan variabel lingkungan default:

    gcloud config set project PROJECT_ID
export GOOGLE_CLOUD_REGION=REGION
export PROJECT_ID=PROJECT_ID

    Ganti nilai berikut:

    • PROJECT_ID: Google Cloud project ID Anda.
    • REGION: Google Cloud region (misalnya, us-east4) untuk menyediakan cluster GKE, Artifact Registry, dan resource regional lainnya. Pastikan untuk menentukan region yang mendukung GPU L4 dan instance jenis mesin G2. Untuk memeriksa ketersediaan region, lihat Region dan zona GPU dalam dokumentasi Compute Engine.

Meng-clone project contoh

  1. Dari terminal Cloud Shell, clone repositori kode contoh tutorial:

    git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git

  2. Buka direktori tutorial:

    cd kubernetes-engine-samples/ai-ml/adk-vllm

Membuat dan mengonfigurasi resource Google Cloud

Untuk men-deploy agen, Anda harus melakukan provisioning resource Google Cloud yang diperlukan terlebih dahulu. Anda dapat membuat cluster GKE dan repositori Artifact Registry menggunakan gcloud CLI atau Terraform.

gcloud

Bagian ini menyediakan perintah gcloud CLI untuk menyiapkan cluster GKE dan Artifact Registry.

  1. Buat cluster GKE: Anda dapat men-deploy aplikasi agentik yang di-containerisasi di cluster GKE Autopilot atau Standard. Gunakan cluster Autopilot untuk pengalaman Kubernetes yang terkelola sepenuhnya. Untuk memilih mode operasi GKE yang paling sesuai dengan workload Anda, lihat Tentang mode operasi GKE.

    Autopilot

    Jalankan perintah berikut di Cloud Shell:

    gcloud container clusters create-auto CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION

    Ganti CLUSTER_NAME dengan nama cluster GKE Anda.

    Dengan Autopilot, GKE secara otomatis menyediakan node berdasarkan permintaan resource workload Anda. GPU yang diperlukan untuk LLM diminta dalam manifes deploy-llm.yaml dengan menggunakan nodeSelector.

    Untuk menambahkan permintaan nodeSelector ke GPU nvidia-l4, ikuti langkah-langkah berikut:

    1. Buka kubernetes-engine-samples/ai-ml/adk-vllm/deploy-llm/deploy-llm.yaml di editor.

    2. Tambahkan nodeSelector berikut di bagian spec.template.spec:

      nodeSelector:
cloud.google.com/gke-accelerator: nvidia-l4

    Standar

    1. Di Cloud Shell, buat cluster Standard dengan menjalankan perintah berikut:

      gcloud container clusters create CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION

      Ganti CLUSTER_NAME dengan nama cluster GKE Anda.

    2. Buat node pool yang mendukung GPU untuk cluster Anda dengan menjalankan perintah berikut:

      gcloud container node-pools create gpu-node-pool \
    --cluster=CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION \
    --machine-type=g2-standard-8 \
    --accelerator=type=nvidia-l4,count=1 \
    --enable-gvnic

      File deploy-llm.yaml menentukan GPU nvidia-l4, yang tersedia di seri mesin G2. Untuk mengetahui informasi selengkapnya tentang jenis mesin ini, lihat Jenis mesin GPU dalam dokumentasi Compute Engine.

  2. Buat repositori Artifact Registry: Buat repositori Artifact Registry untuk menyimpan dan mengelola image container Docker agen Anda secara aman.

    gcloud artifacts repositories create REPO_NAME \
    --repository-format=docker \
    --location=$GOOGLE_CLOUD_REGION

    Ganti REPO_NAME dengan nama repositori Artifact Registry yang ingin Anda gunakan (misalnya, adk-repo).

  3. Dapatkan URL repositori: Untuk memverifikasi jalur lengkap ke repositori Anda, jalankan perintah ini. Anda akan menggunakan format ini untuk memberi tag pada image Docker saat membangun image agen.

    gcloud artifacts repositories describe REPO_NAME \
    --location $GOOGLE_CLOUD_REGION

Terraform

Bagian ini menjelaskan cara menggunakan konfigurasi Terraform yang disertakan dalam repositori contoh untuk menyediakan resource Google Cloud Anda secara otomatis.

  1. Buka direktori Terraform: Direktori \terraform berisi semua file konfigurasi yang diperlukan untuk membuat cluster GKE dan resource lain yang diperlukan.

    cd terraform

  2. Buat file variabel Terraform: Salin contoh file variabel (example_vars.tfvars) yang disediakan untuk membuat file vars.tfvars Anda sendiri.

    cp example_vars.tfvars vars.tfvars

    Buka file vars.tfvars di editor dan ganti nilai placeholder dengan konfigurasi spesifik Anda. Minimal, Anda harus mengganti PROJECT_ID dengan ID project Google Cloud Anda dan CLUSTER_NAME dengan nama cluster GKE Anda.

  3. Lakukan inisialisasi Terraform: Untuk mendownload plugin penyedia yang diperlukan untuk Google Cloud, jalankan perintah ini.

    terraform init

  4. Tinjau rencana eksekusi: Perintah ini menunjukkan perubahan infrastruktur yang akan dilakukan Terraform.

    terraform plan -var-file=vars.tfvars

  5. Terapkan konfigurasi: Untuk membuat resource di project Google Cloud , jalankan rencana Terraform. Konfirmasi dengan yes saat diminta.

    terraform apply -var-file=vars.tfvars

Setelah Anda menjalankan perintah ini, Terraform akan menyediakan cluster GKE dan repositori Artifact Registry, serta mengonfigurasi peran dan akun layanan IAM yang diperlukan, termasuk Federasi Workload Identity untuk GKE.

Untuk mempelajari lebih lanjut cara menggunakan Terraform, lihat Menyediakan resource GKE dengan Terraform.

Konfigurasi kubectl untuk berkomunikasi dengan cluster Anda

Untuk mengonfigurasi kubectl agar dapat berkomunikasi dengan cluster Anda, jalankan perintah berikut:

gcloud container clusters get-credentials CLUSTER_NAME \
    --location=${GOOGLE_CLOUD_REGION}

Ganti CLUSTER_NAME dengan nama cluster GKE Anda.

Membangun image agen

Setelah Anda membuat infrastruktur menggunakan gcloud CLI atau Terraform, ikuti langkah-langkah berikut untuk membangun aplikasi agen Anda.

  1. Berikan peran IAM yang diperlukan untuk Cloud Build: Layanan Cloud Build memerlukan izin untuk mengirim image container agen ke Artifact Registry. Berikan peran roles/artifactregistry.writer ke akun layanan default Compute Engine, yang digunakan oleh Cloud Build.

    1. Buat email untuk akun layanan default Compute Engine:

      export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export COMPUTE_SA_EMAIL=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com

    2. Berikan peran roles/artifactregistry.writer ke akun layanan:

      gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member=serviceAccount:${COMPUTE_SA_EMAIL} \
    --role=roles/artifactregistry.writer

  2. Bangun dan kirim image container agen: Dari direktori root project (adk/llama/vllm), bangun image Docker Anda dan kirim ke Artifact Registry dengan menjalankan perintah berikut.

    export IMAGE_URL="${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME/adk-agent:latest"
gcloud builds submit --tag $IMAGE_URL

  3. Verifikasi bahwa image telah dikirim: Setelah proses build berhasil diselesaikan, verifikasi bahwa image container agen Anda telah dikirim ke Artifact Registry dengan mencantumkan image di repositori Anda.

    gcloud artifacts docker images list ${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME

    Anda akan melihat output yang mencantumkan gambar yang baru saja Anda kirim dan diberi tag sebagai latest.

Men-deploy model

Setelah menyiapkan cluster GKE dan membuat image agen, langkah berikutnya adalah men-deploy model Llama 3.1 yang dihosting sendiri ke cluster Anda. Untuk melakukannya, deploy server inferensi vLLM yang telah dikonfigurasi sebelumnya yang menarik model dari Hugging Face dan menyajikannya secara internal dalam cluster.

  1. Buat secret Kubernetes untuk kredensial Hugging Face: Untuk mengizinkan cluster GKE mendownload model Llama 3.1 yang dibatasi, Anda harus memberikan token Hugging Face sebagai secret Kubernetes. Manifes deploy-llm.yaml dikonfigurasi untuk menggunakan rahasia ini untuk autentikasi.

    kubectl create secret generic hf-secret \
    --from-literal=hf-token-secret=HUGGING_FACE_TOKEN

    Ganti HUGGING_FACE_TOKEN dengan token Anda.

  2. Lihat manifes: Dari direktori root project (adk/llama/vllm), buka direktori /deploy-llm yang berisi manifes Deployment model.

    cd deploy-llm

  3. Terapkan manifes: Jalankan perintah berikut untuk menerapkan manifes deploy-llm.yaml ke cluster Anda.

    kubectl apply -f deploy-llm.yaml

    Perintah ini akan membuat tiga resource Kubernetes:

    • Deployment yang menjalankan server vLLM, yang dikonfigurasi untuk menggunakan model meta-llama/Llama-3.1-8B-Instruct.
    • Layanan bernama vllm-llama3-service yang mengekspos server vLLM di alamat IP cluster internal, sehingga memungkinkan agen ADK berkomunikasi dengannya.
    • ConfigMap yang berisi template chat Jinja yang diperlukan oleh model Llama 3.1.

  4. Verifikasi Deployment model: Server vLLM menarik file model dari Hugging Face. Proses ini dapat memerlukan waktu beberapa menit. Anda dapat memantau status Pod untuk memastikan kesiapannya.

    1. Tunggu hingga Deployment tersedia.

      kubectl wait --for=condition=available --timeout=600s deployment/vllm-llama3-deployment

    2. Lihat log dari Pod yang sedang berjalan untuk mengonfirmasi bahwa server berhasil dimulai.

      export LLM_POD=$(kubectl get pods -l app=vllm-llama3 -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $LLM_POD

      Deployment siap saat Anda melihat output log yang mirip dengan berikut ini, yang menunjukkan bahwa server LLM telah dimulai dan rute API tersedia:

      INFO 07-16 14:15:16 api_server.py:129] Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

    3. Kirim permintaan langsung ke server model untuk mengonfirmasi bahwa LLM sudah siap. Untuk melakukannya, buka terminal Cloud Shell baru dan jalankan perintah berikut untuk meneruskan vllm-llama3-service ke komputer lokal Anda:

      kubectl port-forward service/vllm-llama3-service 8000:8000

    4. Di terminal lain, kirim permintaan sampel ke endpoint API model menggunakan curl. Contoh:

      curl -X POST http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "prompt": "Hello!",
    "max_tokens": 10
  }'

      Jika perintah menampilkan respons JSON yang berhasil, LLM Anda sudah siap. Anda kini dapat menghentikan proses penerusan port dengan kembali ke jendela terminalnya dan menekan Ctrl+C, lalu melanjutkan untuk men-deploy agen.

Men-deploy aplikasi agen

Langkah berikutnya adalah men-deploy aplikasi agen berbasis ADK.

  1. Buka direktori /deploy-agent: Dari direktori root project Anda (adk/llama/vllm), buka direktori /deploy-agent yang berisi kode sumber dan manifes deployment agen.

    cd ../deploy-agent

  2. Perbarui manifes deployment agen:

    1. File manifes deploy-agent.yaml sampel berisi placeholder untuk project ID Anda di URL image container. Anda harus mengganti placeholder dengan project ID Google Cloud Anda.

      image: us-central1-docker.pkg.dev/PROJECT_ID/adk-repo/adk-agent:latest

      Untuk melakukan penggantian ini di tempat, Anda dapat menjalankan perintah berikut:

      sed -i "s/<PROJECT_ID>/$PROJECT_ID/g" deploy-agent.yaml

    2. Pastikan jalur readinessProbe disetel ke /, bukan /dev-ui. Untuk melakukan penggantian ini di tempat, Anda dapat menjalankan perintah berikut:

      sed -i "s|path: /dev-ui/|path: /|g" deploy-agent.yaml

  3. Terapkan manifes: Jalankan perintah berikut untuk menerapkan manifes deploy-agent.yaml ke cluster Anda.

    kubectl apply -f deploy-agent.yaml

    Perintah ini akan membuat dua resource Kubernetes:

    • Deployment bernama adk-agent yang menjalankan image container agen buatan kustom Anda.
    • Layanan bernama adk-agent jenis NodePort yang mengekspos aplikasi agen sehingga dapat diakses untuk pengujian.

  4. Verifikasi deployment agen: Periksa status Pod untuk memastikan Pod berjalan dengan benar.

    1. Tunggu hingga Deployment tersedia:

      kubectl wait --for=condition=available --timeout=300s deployment/adk-agent

    2. Lihat log dari Pod agen yang sedang berjalan:

      export AGENT_POD=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $AGENT_POD

Deployment berhasil jika Anda melihat output log yang mirip dengan berikut, yang menunjukkan bahwa server Uvicorn sedang berjalan dan siap menerima permintaan:

INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

Menguji agen yang di-deploy

Setelah berhasil men-deploy server vLLM dan aplikasi agen, Anda dapat menguji fungsi end-to-end dengan berinteraksi dengan UI web agen.

  1. Teruskan layanan agen ke komputer lokal Anda: Layanan adk-agent berjenis NodePort, tetapi cara paling langsung untuk mengaksesnya dari lingkungan Cloud Shell Anda adalah dengan menggunakan perintah kubectl port-forward. Buat tunnel yang aman ke Pod agen dengan menjalankan perintah ini.

    kubectl port-forward $AGENT_POD 8001:8001

  2. Akses UI web agen: Di Cloud Shell, klik tombol Web Preview, lalu pilih Preview on port 8001. Tab browser baru akan terbuka dan menampilkan antarmuka chat agen.

  3. Berinteraksi dengan agen: Ajukan pertanyaan kepada agen yang akan memanggil alat get_weather-nya. Contoh:

    What's the weather like in Tokyo?

    Agen akan terlebih dahulu memanggil LLM untuk memahami maksud dan mengidentifikasi kebutuhan untuk menggunakan alat get_weather. Kemudian, alat ini akan menjalankan "Tokyo" sebagai parameter. Terakhir, output alat akan digunakan untuk membuat respons. Anda akan melihat respons seperti berikut:

      The weather in Tokyo is 25°C and sunny.

  4. (Opsional) Verifikasi panggilan alat dalam log: Anda dapat mengamati interaksi agen dengan LLM dan eksekusi alat dengan melihat log Pod yang relevan.

    1. Log Pod agen: Di terminal baru, lihat log Pod adk-agent. Anda akan melihat panggilan alat dan hasilnya.

      kubectl logs -f $AGENT_POD

      Output menunjukkan alat yang dipanggil dan hasil yang diproses.

    2. Log Pod LLM: Lihat log Pod vllm-llama3-deployment untuk melihat permintaan masuk dari agen.

      kubectl logs -f $LLM_POD

      Log menampilkan perintah lengkap yang dikirim oleh agen ke LLM, termasuk pesan sistem, kueri Anda, dan definisi alat get_weather.

Setelah selesai menguji, Anda dapat menghentikan proses port-forward dengan kembali ke jendela terminalnya dan menekan Ctrl+C.