Sunucusuz yapay zeka: Cloud Run ile EmbeddingGemma

1. Giriş

Bu codelab'de, GPU'ları kullanarak EmbeddingGemma adlı güçlü çok dilli metin yerleştirme modelini Cloud Run'da nasıl dağıtacağınızı öğreneceksiniz. Ardından, semantik arama uygulaması için yerleştirmeler oluşturmak üzere bu dağıtılan hizmeti kullanırsınız.

Metin üreten geleneksel büyük dil modellerinin (LLM'ler) aksine, yerleştirme modelleri metni sayısal vektörlere dönüştürür. Bu vektörler, kullanıcının sorgusuyla en alakalı dokümanları bulmanızı sağlayan Almayla Artırılmış Üretim (RAG) sistemleri oluşturmak için çok önemlidir.

Yapacaklarınız

• Ollama kullanarak EmbeddingGemma modelini kapsayıcıya alın.
• Container'ı GPU hızlandırmasıyla Cloud Run'a dağıtın.
• Örnek metin için yerleştirmeler oluşturarak dağıtılan modeli test edin.
• Dağıtılan hizmetinizi kullanarak basit bir semantik arama sistemi oluşturun.

İhtiyacınız olanlar

• Faturalandırmanın etkin olduğu bir Google Cloud projesi.
• Docker ve komut satırı hakkında temel düzeyde bilgi sahibi olmanız gerekir.

2. Başlamadan önce

Proje Ayarları

1. Google Hesabınız yoksa Google Hesabı oluşturmanız gerekir.
   • İş veya okul hesabı yerine kişisel hesap kullanıyorsanız. İş ve okul hesaplarında, bu laboratuvar için gereken API'leri etkinleştirmenizi engelleyen kısıtlamalar olabilir.
2. Google Cloud Console'da oturum açın.
3. Cloud Console'da faturalandırmayı etkinleştirin.
   • Bu laboratuvarı tamamlamak için 1 ABD dolarından daha az tutarda bulut kaynağı kullanmanız gerekir.
   • Daha fazla ücret ödememek için bu laboratuvarın sonundaki adımları uygulayarak kaynakları silebilirsiniz.
   • Yeni kullanıcılar 300 ABD doları değerinde ücretsiz deneme sürümünden yararlanabilir.
4. Yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanmayı seçin.
   • Proje kotasıyla ilgili bir hata görürseniz yeni bir proje oluşturmak için mevcut bir projeyi yeniden kullanın veya mevcut bir projeyi silin.

Cloud Shell'i Başlatma

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.

1. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
2. Cloud Shell'e bağlandıktan sonra kimlik doğrulamanızı onaylayın:

   gcloud auth list
   

3. Projenizin seçildiğini onaylayın:

   gcloud config get project
   

4. Gerekirse ayarlayın:

   gcloud config set project <YOUR_PROJECT_ID>
   

API'leri etkinleştir

Gerekli tüm API'leri etkinleştirmek için bu komutu çalıştırın:

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

3. Modeli Containerize Etme

EmbeddingGemma'yı sunucusuz olarak çalıştırmak için bunu bir kapsayıcıya paketlememiz gerekir. LLM'leri çalıştırmak için basit bir çerçeve olan Ollama ve Docker'ı kullanacağız.

Dockerfile'ı oluşturma

Cloud Shell'de projeniz için yeni bir dizin oluşturun ve bu dizine gidin:

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

Aşağıdaki içeriğe sahip Dockerfile adlı bir dosya oluşturun:

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"]

Bu Dockerfile şunları yapar:

1. Resmi Ollama temel görüntüsünden başlar.
2. Ollama'yı 8080 bağlantı noktasında (Cloud Run'ın varsayılanı) dinleyecek şekilde yapılandırır.
3. RUN komutu, ollama sunucusunu başlatır ve derleme işlemi sırasında embeddinggemma modelini indirir. Böylece model, görüntüye yerleştirilir.
4. OLLAMA_KEEP_ALIVE=-1, sonraki isteklerin daha hızlı işlenmesi için modelin GPU belleğinde yüklü kalmasını sağlar.

4. Derleme ve Dağıtım

Container'ımızı tek bir adımda oluşturup dağıtmak için Cloud Run kaynak dağıtımını kullanacağız. Bu komut, görüntüyü Cloud Build kullanarak oluşturur, Artifact Registry'de depolar ve Cloud Run'a dağıtır.

Dağıtmak için aşağıdaki komutu çalıştırın:

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

Not: Bu dağıtım, model ağırlıklarını çektiği ve kapsayıcıyı oluşturduğu için birkaç dakika sürebilir. Cloud Run kaynak dağıtımını ilk kez kullanıyorsanız yeni bir Artifact Registry deposu oluşturmanız istenebilir. Devam etmek için y yanıtını verin.

Yapılandırmayı Anlama

• --source ., geçerli dizini derleme kaynağı olarak belirtir.
• --region europe-west1 Cloud Run'da GPU'ları destekleyen bir bölge kullanıyoruz.
• --concurrency 4, OLLAMA_NUM_PARALLEL ortam değişkeninin değeriyle eşleşecek şekilde ayarlanır.
• --gpu 1 ile --gpu-type nvidia-l4, hizmetteki her Cloud Run örneğine 1 NVIDIA L4 GPU atar.
• --max-instances 1, ölçeklenecek maksimum örnek sayısını belirtir. Projenizin NVIDIA L4 GPU kotasına eşit veya bu kotadan daha düşük olmalıdır.
• --no-allow-unauthenticated, hizmete kimliği doğrulanmamış erişimi kısıtlar. Hizmeti özel tutarak hizmetler arası iletişim için Cloud Run'ın yerleşik Identity and Access Management (IAM) kimlik doğrulamasını kullanabilirsiniz.
• GPU'nun etkinleştirilmesi için --no-cpu-throttling gereklidir.
• --no-gpu-zonal-redundancy Bölgesel yük devretme gereksinimlerinize ve kullanılabilir kotaya bağlı olarak bölgesel yedeklilik seçeneklerini ayarlayın.

Bölgeyle İlgili Dikkat Edilmesi Gerekenler

Cloud Run'daki GPU'lar belirli bölgelerde kullanılabilir. Desteklenen bölgeleri belgelerden kontrol edebilirsiniz.

Dağıtım Çıkışı

Dağıtım birkaç dakika içinde tamamlanır ve şu gibi bir mesaj görürsünüz:

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

Not: URL'yi doğrudan ziyaret etmeye çalışırsanız hizmetiniz kimlik doğrulama gerektirdiğinden "403 Error: Forbidden" (403 Hatası: Yasaklandı) mesajını görürsünüz.

5. Dağıtımı test etme

Hizmeti --no-allow-unauthenticated ile dağıttığımız için herkese açık URL'yi basitçe curl yapamayız. Öncelikle hizmete erişmek ve istekte yetkilendirme jetonunu kullanmak için kendimize izin vermemiz gerekir.

1. Kullanıcı hesabınıza hizmeti çağırma izni verin:

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

2. İsteklerde kullanılmak üzere Google Cloud kimlik bilgilerinizi ve proje numaranızı ortam değişkenlerine kaydedin:

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

3. "Örnek metin" için yerleştirme oluşturmak üzere aşağıdaki komutu çalıştırın:

   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"
       }'
   

embedding alanı altında bir vektör (uzun bir sayı listesi) içeren bir JSON yanıtı görmelisiniz. Bu, sunucusuz GPU destekli yerleştirme modelinizin çalıştığını doğrular.

Yanıt aşağıdaki gibi görünür:

Python İstemcisi

Hizmetle etkileşim kurmak için Python'ı da kullanabilirsiniz. test_client.py adlı bir dosya oluşturun:

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)

Uygulayın:

python test_client.py

6. Semantik Arama Uygulaması Oluşturma

Çalışan bir yerleştirme hizmetimiz olduğuna göre şimdi basit bir Semantik Arama uygulaması oluşturalım. Oluşturulan gömmeleri, belirli bir sorgu için en alakalı dokümanı bulmak amacıyla kullanırız.

Bağımlılıklar

Vektör veritabanımız olarak chromadb'yı ve ollama istemci kitaplığını kullanacağız.

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

Arama uygulamasını oluşturma

Aşağıdaki kodu kullanarak semantic_search.py adlı bir dosya oluşturun:

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}")

Uygulamayı çalıştırma

Komut dosyasını yürütün:

uv run semantic_search.py

Not: KeyError: 'ID_TOKEN' veya KeyError: 'PROJECT_NUMBER' gibi bir hata görürseniz ID_TOKEN veya PROJECT_NUMBER ortam değişkenini ayarlamayı unuttunuz demektir. Bunları ayarlamak için export ID_TOKEN=$(gcloud auth print-identity-token) ve export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)") komutlarını çalıştırın.

Şuna benzer bir çıkış alırsınız:

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.

Bu komut dosyası, bir RAG sisteminin temelini gösterir: Hem belgeleri hem de sorguları vektörlere dönüştürmek için sunucusuz EmbeddingGemma hizmetinizi kullanır. Böylece, kullanıcının sorusunu yanıtlamak için gereken bilgileri tam olarak bulabilirsiniz.

7. Temizleme

Google Cloud hesabınızın sürekli olarak ücretlendirilmesini önlemek için bu codelab sırasında oluşturulan kaynakları silin.

Cloud Run hizmetini silme

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

Container görüntüsünü silme

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

Uyarı: Yukarıdaki komut başarısız olursa Artifact Registry yolunuzu tekrar kontrol edin. Depo adı, tam dağıtım ayarlarınıza bağlı olarak biraz farklılık gösterebilir. İpucu: Yapı depolarınızdaki resimleri listelemek için gcloud artifacts docker images list $REPO_PATH komutunu kullanabilirsiniz.

8. Tebrikler

Tebrikler! EmbeddingGemma'yı GPU'larla birlikte Cloud Run'da başarıyla dağıttınız ve semantik arama uygulamasına güç vermek için kullandınız.

Artık metin anlamını anlamayı gerektiren yapay zeka uygulamaları oluşturmak için ölçeklenebilir ve sunucusuz bir temeliniz var.

Öğrendikleriniz

• Docker ile Ollama modelini kapsama alma
• GPU özellikli bir hizmeti Cloud Run'a dağıtma
• Dağıtılan modeli semantik arama (RAG) için kullanma

Sonraki adımlar

• Gemma ailesindeki diğer modelleri keşfedin.
• Cloud Run GPU'ları hakkında daha fazla bilgi edinin.
• Diğer Cloud Run Codelab'lerini keşfedin.
• Bu alma adımını bir üretken modele bağlayarak tam bir RAG işlem hattı oluşturun.

Referans belgeleri

• EmbeddingGemma Model Card
• Ollama Belgeleri