Panduan memulai: Membangun dan men-deploy aplikasi web Python (smolagents) ke Cloud Run

Panduan memulai: Membangun dan men-deploy aplikasi web Python (smolagents) ke Cloud Run

Dokumen ini menunjukkan cara membangun dan men-deploy aplikasi smolagents ke Cloud Run.

Dengan mengikuti langkah-langkah dalam panduan memulai ini, Cloud Run akan otomatis membuat Dockerfile untuk Anda saat Anda men-deploy dari kode sumber.

Sebelum memulai

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

Instal Google Cloud CLI.

Catatan: Jika Anda telah menginstal gcloud CLI sebelumnya, pastikan Anda memiliki versi terbaru dengan menjalankan gcloud components update.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Jika Anda menggunakan project yang sudah ada untuk panduan ini, pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini. Jika berhasil membuat project baru, berarti Anda sudah memiliki izin yang diperlukan.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Instal Google Cloud CLI.

Catatan: Jika Anda telah menginstal gcloud CLI sebelumnya, pastikan Anda memiliki versi terbaru dengan menjalankan gcloud components update.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Jika Anda menggunakan project yang sudah ada untuk panduan ini, pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini. Jika berhasil membuat project baru, berarti Anda sudah memiliki izin yang diperlukan.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

1. Jika Anda dikenai kebijakan organisasi pembatasan domain yang membatasi pemanggilan yang tidak diautentikasi untuk project, Anda perlu mengakses layanan yang di-deploy seperti yang dijelaskan di bagian Menguji layanan pribadi.

2. Aktifkan Cloud Run Admin API dan Cloud Build API:

   Peran yang diperlukan untuk mengaktifkan API

   Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

   gcloud services enable run.googleapis.com cloudbuild.googleapis.com

   Setelah Cloud Run Admin API diaktifkan, akun layanan default Compute Engine akan dibuat secara otomatis.

3. Tinjau harga Cloud Run atau perkirakan biaya dengan kalkulator harga.
4. Anda memerlukan kunci API dari Google AI Studio untuk men-deploy aplikasi smolagents dengan model Gemini. Untuk membuat kunci API menggunakan Google AI Studio, lihat Menggunakan kunci API Gemini dalam dokumentasi Gemini API.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menyelesaikan panduan memulai ini, minta administrator untuk memberi Anda peran IAM berikut:

• Cloud Run Admin (roles/run.admin) di project
• Cloud Run Source Developer (roles/run.sourceDeveloper) di project
• Pengguna Akun Layanan (roles/iam.serviceAccountUser) di identitas layanan
• Logs Viewer (roles/logging.viewer) di project

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Memberi akun layanan Cloud Build akses ke project Anda

Cloud Build otomatis menggunakan akun layanan default Compute Engine sebagai akun layanan Cloud Build default untuk membangun kode sumber dan resource Cloud Run Anda, kecuali jika Anda mengganti perilaku ini.

Agar Cloud Build dapat membangun sumber Anda, berikan peran Cloud Run Builder (roles/run.builder) di project Anda kepada akun layanan Cloud Build:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder

Ganti PROJECT_ID dengan project ID Google Cloud Anda dan SERVICE_ACCOUNT_EMAIL_ADDRESS dengan alamat email akun layanan Cloud Build. Jika Anda menggunakan akun layanan default Compute Engine sebagai akun layanan Cloud Build, gunakan format berikut untuk alamat email akun layanan:

[e-mail]

Ganti PROJECT_NUMBER dengan nomor project Google Cloud Anda.

Untuk mengetahui petunjuk mendetail tentang cara menemukan project ID dan nomor project Anda, lihat Membuat dan mengelola project.

Pemberian peran builder Cloud Run memerlukan waktu beberapa menit untuk diterapkan.

Menulis aplikasi contoh

Untuk menulis aplikasi di Python:

1. Buat direktori baru bernama my-agent-app dan ubah ke direktori tersebut:

   mkdir my-agent-app
   cd my-agent-app
   

2. Buat file bernama main.py lalu tempelkan kode berikut ke dalamnya:

   import os
   from fastapi import FastAPI, HTTPException
   from pydantic import BaseModel
   from smolagents import CodeAgent, LiteLLMModel, tool
   
   # 1. Define a simple tool for the agent
   @tool
   def get_greeting(name: str) -> str:
     """
     Returns a special greeting for the user.
     Args:
         name: The name of the person to greet.
     """
     return f"Hello {name}, welcome to the agentic world running on Cloud Run!"
   
   # 2. Initialize the Gemini Model via LiteLLM
   # Make sure GEMINI_API_KEY is set in your environment variables
   model = LiteLLMModel(
   model_id="gemini/gemini-2.5-flash", # This is the model name. If a newer model is available, you can use that.
   api_key=os.environ.get("GEMINI_API_KEY")
   )
   
   # 3. Create the CodeAgent
   agent = CodeAgent(
     tools=[get_greeting],
     model=model,
     add_base_tools=True # Adds basic python tools like print
   )
   
   # 4. Setup FastAPI
   app = FastAPI()
   
   class AgentRequest(BaseModel):
     task: str
   
   @app.get("/")
   def health_check():
     return {"status": "running", "service": "smolagents-fastapi"}
   
   @app.post("/run")
   def run_agent(request: AgentRequest):
     try:
       # Run the agent with the user's task
       response = agent.run(request.task)
       return {"response": str(response)}
     except Exception as e:
       raise HTTPException(status_code=500, detail=str(e))
   

3. Buat file bernama requirements.txt lalu tempelkan kode berikut ke dalamnya:

   fastapi
   uvicorn
   smolagents[toolkit]
   litellm
   

Men-deploy ke Cloud Run dari sumber

Men-deploy dari sumber secara otomatis akan mem-build image container dari kode sumber dan men-deploy-nya.

Untuk men-deploy dari sumber menggunakan perintah berikut:

  gcloud run deploy smolagents-demo \
    --source . \
    --region us-central1 \
    --no-allow-unauthenticated \
    --set-env-vars GEMINI_API_KEY=API_KEY

Ganti API_KEY dengan kunci API Google AI Studio Anda.

Cloud Run menampilkan URL layanan, seperti https://smolagents-demo-xyz-uc.a.run.app, setelah Anda berhasil men-deploy aplikasi.

Berhasil: Anda telah men-deploy aplikasi web smolagents ke Cloud Run.

Menguji layanan Cloud Run Anda

Uji layanan Anda dengan mengirimkan tugas ke agen menggunakan perintah curl berikut:

  curl -X POST YOUR-SERVICE-URL/run \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    -d '{"task": "Use the greeting tool to say hello to Gemini User"}'

Ganti YOUR-SERVICE-URL dengan URL layanan Anda.

Agen mengirimkan respons berikut:

{
 "response": "Hello Gemini User, welcome to the agentic world running on Cloud Run!"
}

Untuk memverifikasi bahwa layanan Anda berfungsi dengan benar, periksa tab Log layanan Cloud Run.

Pembersihan

Agar akun Google Cloud Anda tidak dikenai biaya untuk resource yang digunakan pada halaman ini, hapus project Google Cloud yang berisi resource tersebut.

Untuk menghindari biaya tambahan pada akun Google Cloud Anda, hapus semua resource yang Anda deploy dengan panduan memulai ini.

Menghapus repositori Anda

Cloud Run tidak mengenakan biaya saat layanan yang di-deploy tidak digunakan. Namun, Anda mungkin tetap dikenai biaya atas penyimpanan image container di Artifact Registry. Untuk menghapus repositori Artifact Registry, ikuti langkah-langkah di Menghapus repositori dalam dokumentasi Artifact Registry.

Menghapus layanan Anda

Layanan Cloud Run tidak menimbulkan biaya hingga menerima permintaan. Untuk menghapus layanan Cloud Run, ikuti salah satu langkah berikut:

Konsol

Untuk menghapus layanan:

1. Di konsol Google Cloud , buka halaman Services Cloud Run:

   Buka Cloud Run

2. Temukan layanan yang ingin Anda hapus dalam daftar layanan, lalu klik kotak centang layanan tersebut untuk memilihnya.

3. Klik Hapus. Tindakan ini akan menghapus semua revisi layanan.

gcloud

Untuk menghapus layanan, jalankan perintah berikut:

gcloud run services delete SERVICE --region REGION

Ganti kode berikut:

• SERVICE: nama layanan Anda.
• REGION: Google Cloud region layanan.

Menghapus project pengujian Anda

Menghapus project Google Cloud akan menghentikan penagihan untuk semua resource dalam project tersebut. Untuk melepaskan semua Google Cloud resource di project Anda, ikuti langkah-langkah berikut:

Perhatian: Penghapusan project memiliki efek berikut:
• Semua hal dalam project akan dihapus. Jika Anda menggunakan project yang ada untuk mengerjakan tugas di dokumen ini, saat Anda menghapusnya, pekerjaan lain dalam project tersebut juga akan dihapus.
• Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin juga membuat project ID kustom yang masih ingin digunakan pada masa mendatang. Agar tidak kehilangan URL yang menggunakan project ID tersebut, seperti URL appspot.com, hapus resource yang dipilih di dalam project, bukan menghapus seluruh project.

Menghapus Google Cloud project:

gcloud projects delete PROJECT_ID

Langkah berikutnya

Untuk informasi lebih lanjut dalam mem-build container dari kode sumber dan penerapan untuk repositori, lihat:

• Mengembangkan layanan Cloud Run
• Mem-build Container
• Menguji layanan Cloud Run secara lokal
• Men-deploy dari kode sumber