AI Serverless: Menyematkan Gemma dengan Cloud Run

1. Pengantar

Dalam codelab ini, Anda akan mempelajari cara men-deploy EmbeddingGemma, model penyematan teks multilingu yang canggih, di Cloud Run menggunakan GPU. Kemudian, Anda akan menggunakan layanan yang di-deploy ini untuk membuat embedding bagi aplikasi penelusuran semantik.

Tidak seperti Model Bahasa Besar (LLM) tradisional yang menghasilkan teks, model embedding mengonversi teks menjadi vektor numerik. Vektor ini sangat penting untuk membangun sistem Retrieval-Augmented Generation (RAG), yang memungkinkan Anda menemukan dokumen yang paling relevan untuk kueri pengguna.

Yang akan Anda lakukan

• Buat model EmbeddingGemma dalam container menggunakan Ollama.
• Deploy container ke Cloud Run dengan akselerasi GPU.
• Uji model yang di-deploy dengan membuat embedding untuk sampel teks.
• Bangun sistem penelusuran semantik ringan menggunakan layanan yang di-deploy.

Yang Anda butuhkan

• Project Google Cloud yang mengaktifkan penagihan.
• Pemahaman dasar tentang Docker dan command line.

2. Sebelum memulai

Penyiapan Project

1. Jika belum memiliki Akun Google, Anda harus membuat Akun Google.
   • Gunakan akun pribadi, bukan akun kantor atau sekolah. Akun kantor dan sekolah mungkin memiliki batasan yang mencegah Anda mengaktifkan API yang diperlukan untuk lab ini.
2. Login ke Konsol Google Cloud.
3. Aktifkan penagihan di Konsol Cloud.
   • Menyelesaikan lab ini akan dikenai biaya kurang dari $1 USD untuk resource Cloud.
   • Anda dapat mengikuti langkah-langkah di akhir lab ini untuk menghapus resource agar tidak dikenai biaya lebih lanjut.
   • Pengguna baru memenuhi syarat untuk mengikuti Uji Coba Gratis senilai$300 USD.
4. Buat project baru atau pilih untuk menggunakan kembali project yang ada.
   • Jika Anda melihat error tentang kuota project, gunakan kembali project yang ada atau hapus project yang ada untuk membuat project baru.

Mulai Cloud Shell

Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan alat yang diperlukan.

1. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
2. Setelah terhubung ke Cloud Shell, verifikasi autentikasi Anda:

   gcloud auth list
   

3. Pastikan project Anda dipilih:

   gcloud config get project
   

4. Tetapkan jika perlu:

   gcloud config set project <YOUR_PROJECT_ID>
   

Mengaktifkan API

Jalankan perintah ini untuk mengaktifkan semua API yang diperlukan:

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

3. Memasukkan Model ke dalam Container

Untuk menjalankan EmbeddingGemma tanpa server, kita perlu mengemasnya ke dalam container. Kita akan menggunakan Ollama, framework ringan untuk menjalankan LLM, dan Docker.

Buat Dockerfile

Di Cloud Shell, buat direktori baru untuk project Anda, lalu buka direktori tersebut:

mkdir embedding-gemma-codelab
cd embedding-gemma-codelab

Buat file bernama Dockerfile dengan konten berikut:

FROM ollama/ollama:latest

# Listen on all interfaces, port 8080
ENV OLLAMA_HOST=0.0.0.0:8080

# Store model weight files in /models
ENV OLLAMA_MODELS=/models

# Reduce logging verbosity
ENV OLLAMA_DEBUG=false

# Never unload model weights from the GPU
ENV OLLAMA_KEEP_ALIVE=-1

# Store the model weights in the container image
ENV MODEL=embeddinggemma:latest
RUN ollama serve & sleep 5 && ollama pull $MODEL

# Start Ollama
ENTRYPOINT ["ollama", "serve"]

Dockerfile ini melakukan hal berikut:

1. Dimulai dari image dasar Ollama resmi.
2. Mengonfigurasi Ollama untuk memproses di port 8080 (default Cloud Run).
3. Perintah RUN memulai server ollama dan mendownload model embeddinggemma selama proses build sehingga model tersebut di-bake ke dalam image.
4. Menetapkan OLLAMA_KEEP_ALIVE=-1 untuk memastikan model tetap dimuat dalam memori GPU untuk permintaan berikutnya yang lebih cepat.

4. Build dan Deploy

Kita akan menggunakan deployment sumber Cloud Run untuk membangun dan men-deploy container dalam satu langkah. Perintah ini akan membangun image menggunakan Cloud Build, menyimpannya di Artifact Registry, dan men-deploy-nya ke Cloud Run.

Jalankan perintah berikut untuk men-deploy:

gcloud run deploy embedding-gemma \
  --source . \
  --region europe-west1 \
  --concurrency 4 \
  --cpu 8 \
  --set-env-vars OLLAMA_NUM_PARALLEL=4 \
  --gpu 1 \
  --gpu-type nvidia-l4 \
  --max-instances 1 \
  --memory 32Gi \
  --no-allow-unauthenticated \
  --no-cpu-throttling \
  --no-gpu-zonal-redundancy \
  --timeout=600 \
  --labels dev-tutorial=codelab-embedding-gemma

Catatan: Deployment ini mungkin memerlukan waktu beberapa menit karena menarik bobot model dan membangun container. Jika ini pertama kalinya Anda menggunakan deployment sumber Cloud Run, Anda mungkin diminta untuk membuat repositori Artifact Registry baru - jawab y untuk melanjutkan.

Memahami Konfigurasi

• --source . menentukan direktori saat ini sebagai sumber untuk build.
• --region europe-west1 kita menggunakan region yang mendukung GPU di Cloud Run.
• --concurrency 4 ditetapkan agar sesuai dengan nilai variabel lingkungan OLLAMA_NUM_PARALLEL.
• --gpu 1 dengan --gpu-type nvidia-l4 menetapkan 1 GPU NVIDIA L4 ke setiap instance Cloud Run dalam layanan.
• --max-instances 1 menentukan jumlah maksimum instance yang akan diskalakan. Nilai ini harus sama dengan atau lebih rendah dari kuota GPU NVIDIA L4 project Anda.
• --no-allow-unauthenticated membatasi akses yang tidak diautentikasi ke layanan. Dengan menjaga layanan tetap pribadi, Anda dapat mengandalkan autentikasi Identity and Access Management (IAM) bawaan Cloud Run untuk komunikasi layanan-ke-layanan.
• --no-cpu-throttling diperlukan untuk mengaktifkan GPU.
• --no-gpu-zonal-redundancy menetapkan opsi redundansi zona bergantung pada persyaratan failover zona dan kuota yang tersedia.

Pertimbangan Region

GPU di Cloud Run tersedia di region tertentu. Anda dapat memeriksa wilayah yang didukung dalam dokumentasi.

Output Deployment

Setelah beberapa menit, deployment akan selesai dan Anda akan melihat pesan seperti:

Service [embedding-gemma] revision [embedding-gemma-12345-abc] has been deployed and is serving 100 percent of traffic.
Service URL: https://embedding-gemma-123456789012.europe-west1.run.app

Catatan: Jika Anda mencoba membuka URL secara langsung, Anda akan melihat "Error 403: Terlarang" karena layanan Anda memerlukan autentikasi.

5. Menguji Deployment

Karena kita men-deploy layanan dengan --no-allow-unauthenticated, kita tidak dapat curl URL publik begitu saja. Pertama-tama, kita harus memberi diri kita izin untuk mengakses layanan dan menggunakan token autentikasi dalam permintaan.

1. Beri akun pengguna Anda izin untuk memanggil layanan:

   gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
       --member=user:$(gcloud config get-value account) \
       --role='roles/run.invoker'
   

2. Simpan kredensial Google Cloud dan nomor project Anda dalam variabel lingkungan untuk digunakan dalam permintaan:

   export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)")
   export ID_TOKEN=$(gcloud auth print-identity-token)
   

3. Jalankan perintah berikut untuk membuat penyematan untuk "Sample text":

   curl -X POST "https://embedding-gemma-$PROJECT_NUMBER.europe-west1.run.app/api/embed" \
       -H "Authorization: Bearer $ID_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
           "model": "embeddinggemma",
           "input": "Sample text"
       }'
   

Anda akan melihat respons JSON yang berisi vektor (daftar panjang angka) di kolom embedding. Hal ini mengonfirmasi bahwa model penyematan yang didukung GPU serverless Anda berfungsi.

Responsnya akan terlihat seperti ini:

Klien Python

Anda juga dapat menggunakan Python untuk berinteraksi dengan layanan. Buat file bernama test_client.py:

import urllib.request
import urllib.parse
import json
import os

# 1. Setup the URL and Payload
url = f"https://embedding-gemma-{os.environ['PROJECT_NUMBER']}.europe-west1.run.app/api/embed"
payload = {
    "model": "embeddinggemma",
    "input": "Sample text"
}

# 2. Create the Request object
# Note: Providing 'data' automatically makes this a POST request
req = urllib.request.Request(
    url,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['ID_TOKEN']}",
        "Content-Type": "application/json"
    }
)

# 3. Execute and print the response
response = urllib.request.urlopen(req)
result = json.loads(response.read().decode("utf-8"))
print(result)

Jalankan:

python test_client.py

6. Membangun Aplikasi Penelusuran Semantik

Setelah layanan penyematan berfungsi, mari kita buat aplikasi Penelusuran Semantik sederhana. Kita akan menggunakan embedding yang dihasilkan untuk menemukan dokumen yang paling relevan untuk kueri tertentu.

Dependensi

Kita akan menggunakan chromadb sebagai database vektor dan library klien ollama.

uv init semantic-search --description "Semantic Search Application"
cd semantic-search
uv add chromadb ollama

Buat Aplikasi Penelusuran

Buat file bernama semantic_search.py dengan kode berikut:

import ollama
import chromadb
import os

# 1. Define our knowledge base
documents = [
    "Poland is a country located in Central Europe.",
    "The capital and largest city of Poland is Warsaw.",
    "Poland's official language is Polish, which is a West Slavic language.",
    "Marie Curie, the pioneering scientist who conducted groundbreaking research on radioactivity, was born in Warsaw, Poland.",
    "Poland is famous for its traditional dish called pierogi, which are filled dumplings.",
    "The Białowieża Forest in Poland is one of the last and largest remaining parts of the immense primeval forest that once stretched across the European Plain.",
]

print("Initializing Vector Database...")
client = chromadb.Client()
collection = client.create_collection(name="docs")

# Configure the client to point to our Cloud Run proxy
ollama_client = ollama.Client(
    host=f"https://embedding-gemma-{os.environ['PROJECT_NUMBER']}.europe-west1.run.app",
    headers={'Authorization': 'Bearer ' + os.environ['ID_TOKEN']}
)

print("Generating embeddings and indexing documents...")
# 2. Store each document in the vector database
for i, d in enumerate(documents):
    # This calls our Cloud Run service to get the embedding
    response = ollama_client.embed(model="embeddinggemma", input=d)
    embeddings = response["embeddings"]
    collection.add(ids=[str(i)], embeddings=embeddings, documents=[d])

print("Indexing complete.\n")

# 3. Perform a Semantic Search
question = "What is Poland's official language?"
print(f"Query: {question}")

# Generate an embedding for the question
response = ollama_client.embed(model="embeddinggemma", input=question)

# Query the database for the most similar document
results = collection.query(
    query_embeddings=[response["embeddings"][0]],
    n_results=1
)

best_match = results["documents"][0][0]
print(f"Best Match Document: {best_match}")

Menjalankan Aplikasi

Jalankan skrip:

uv run semantic_search.py

Catatan: Jika Anda melihat error seperti KeyError: 'ID_TOKEN' atau KeyError: 'PROJECT_NUMBER', berarti Anda lupa menyetel variabel lingkungan ID_TOKEN atau PROJECT_NUMBER. Jalankan export ID_TOKEN=$(gcloud auth print-identity-token) dan export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)") untuk menyetelnya.

Anda akan melihat output yang serupa dengan ini:

Initializing Vector Database...
Generating embeddings and indexing documents...
Indexing complete.

Query: What is Poland's official language?
Best Match Document: Poland's official language is Polish, which is a West Slavic language.

Skrip ini menunjukkan inti dari sistem RAG: menggunakan layanan EmbeddingGemma serverless untuk mengonversi dokumen dan kueri menjadi vektor, sehingga Anda dapat menemukan informasi persis yang diperlukan untuk menjawab pertanyaan pengguna.

7. Pembersihan

Untuk menghindari biaya berkelanjutan pada akun Google Cloud Anda, hapus resource yang dibuat selama codelab ini.

Menghapus Layanan Cloud Run

gcloud run services delete embedding-gemma --region europe-west1 --quiet

Hapus Image Container

gcloud artifacts docker images delete \
    europe-west1-docker.pkg.dev/${GOOGLE_CLOUD_PROJECT}/cloud-run-source-deploy/embedding-gemma \
    --quiet

Peringatan: Periksa kembali jalur Artifact Registry Anda jika perintah di atas gagal, karena nama repositori mungkin sedikit berbeda bergantung pada setelan deployment yang tepat. Petunjuk: Anda dapat menggunakan gcloud artifacts docker images list $REPO_PATH untuk mencantumkan gambar di repositori artefak Anda.

8. Selamat

Selamat! Anda telah berhasil men-deploy EmbeddingGemma di Cloud Run dengan GPU dan menggunakannya untuk mendukung aplikasi penelusuran semantik.

Sekarang Anda memiliki fondasi serverless yang skalabel untuk membangun aplikasi AI yang memerlukan pemahaman makna teks.

Yang telah Anda pelajari

• Cara membuat container model Ollama dengan Docker.
• Cara men-deploy layanan yang mendukung GPU ke Cloud Run.
• Cara menggunakan model yang di-deploy untuk penelusuran semantik (RAG).

Langkah berikutnya

• Jelajahi model lain dalam keluarga Gemma.
• Pelajari lebih lanjut GPU Cloud Run.
• Pelajari Codelab Cloud Run lainnya.
• Bangun pipeline RAG lengkap dengan menghubungkan langkah pengambilan ini ke model generatif.

Dokumen referensi

• Kartu Model EmbeddingGemma
• Dokumentasi Ollama