Cloud Run'da LangChain Agent'ı dağıtma

1. Genel Bakış

Ajan, sahip olduğu araçları ve bağlamı kullanarak hedefe dayalı bir işlem gerçekleştirmek için yapay zeka modeliyle konuşan ve gerçekliğe dayalı olarak kendi kendine karar verebilen bağımsız bir programdır.

Temsilci oluşturmak için Agent Development Kit(ADK), LangChain ve smolagents gibi temsilci çerçeveleri kullanılır. Bu tür çerçeveler aracılığıyla oluşturulan aracı uygulamaları Cloud Run'a dağıtılabilir ve kullanıcılara sunucusuz uygulamalar olarak sunulabilir.

Bu codelab'de LangChain kullanarak bir aracı oluşturup Cloud Run'a dağıtacağız.

Ne oluşturacaksınız?

PROMPT prototipinden temsilci oluşturmaya geçmeye hazır mısınız? Tarihi şahsiyetler hakkında yapılandırılmış biçimde bilgi almak için LangChain kullanarak bir aracı oluşturacağız. Bu laboratuvar kapsamında şunları yapacaksınız:

  1. LangChain'i kullanarak tarihi şahsiyetler hakkında yapılandırılmış biçimde bilgi üreten basit bir aracı oluşturma
  2. Aracı yerel olarak çalıştırın ve beklendiği gibi çalıştığından emin olun.
  3. Aracıyı Cloud Run'a dağıtma ve Cloud Run URL'sini kullanarak çağırma

Şartlar

  • Chrome veya Firefox gibi bir tarayıcı
  • Faturalandırmanın etkin olduğu bir Google Cloud projesi.

2. Başlamadan önce

Proje oluşturma

  1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.
  3. Bu bağlantıyı tıklayarak Cloud Shell'i etkinleştirin. Cloud Shell'deki ilgili düğmeyi tıklayarak Cloud Shell Terminali (bulut komutlarını çalıştırmak için) ile Düzenleyici (projeleri oluşturmak için) arasında geçiş yapabilirsiniz.
  4. Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulandığını ve projenin proje kimliğinize ayarlandığını kontrol edin:
gcloud auth list
  1. gcloud komutunun projeniz hakkında bilgi sahibi olduğunu onaylamak için Cloud Shell'de aşağıdaki komutu çalıştırın.
gcloud config list project
  1. Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:
gcloud config set project <YOUR_PROJECT_ID>
  1. Python 3.13 veya sonraki bir sürümün yüklü olduğundan emin olun.

Diğer gcloud komutları ve kullanımı için belgelere bakın.

3. LangChain aracısı oluşturma

Proje Yapısı

Cloud Shell'inizde langchain-app adlı bir klasör oluşturun ve içine aşağıdaki dosyaları ekleyin:

langchain-gemini-fastapi-app/
├── main.py
├── requirements.txt

Uygulama Kodu

requirements.txt öğesine eklemeniz gereken bağımlılıklar şunlardır:

fastapi
uvicorn
langchain
langchain-google-genai
python-dotenv

main.py bölümünde, Gemini modelini kullanan ve tarihi şahsiyetler hakkında bilgi alan aracı kodunu yazacağız. Alındıktan sonra, belirtildiği şekilde yapılandırılmış bir biçime dönüştürür.

Bu uygulamada modern LCEL (LangChain Expression Language) söz dizimi kullanılır.

import os
import uvicorn
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from langchain_google_genai import ChatGoogleGenerativeAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import JsonOutputParser

# Initialize FastAPI
app = FastAPI(title="LangChain App for Historical Figures")

# 1. Setup Gemini Model
# We expect GOOGLE_API_KEY to be set in the environment variables
llm = ChatGoogleGenerativeAI(
    model="gemini-2.5-flash",
    temperature=0.7
)

# 2. Define the Prompt
prompt = ChatPromptTemplate.from_template("You are an expert Historian. For the historical personality {name}, you are able to accurately tell their birth date and birth country. Return the output in the JSON format containing name, birthDate, birthCountry. In case you are unable to retrieve birthDate or birthCountry, just have the unknown values as null. ensure the response is a valid json object only.")
output_parser = JsonOutputParser()

# Chain: Prompt -> Model -> Json Output Parser
chain = prompt | llm | output_parser

# 3. Define Request Model
class QueryRequest(BaseModel):
    name: str

# 4. Define Endpoint
@app.post("/chat")
async def chat(request: QueryRequest):
    try:
        response = await chain.ainvoke({"name": request.name})
        return response
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.get("/")
def health_check():
    return {"status": "ok", "service": "LangChain-Gemini-FastAPI"}

4. Aracıyı test etme

Dağıtmadan önce yerel olarak test edebilirsiniz.

  1. AI Studio'da Gemini API anahtarı oluşturun.
  2. Gemini API anahtarını şu şekilde dışa aktarın:
export GOOGLE_API_KEY="AIzaSy..."
  1. Sunucuyu çalıştırın.
uvicorn main:app --port 8080 --host 0.0.0.0
  1. Aşağıdaki curl komutunu kullanarak aracı test edin:
curl -X POST http://localhost:8080/chat \
     -H "Content-Type: application/json" \
     -d '{"name": "Abraham Lincoln"}'

Ad, doğum tarihi ve doğum ülkesini içeren bir JSON yapılandırılmış çıkış aldığınızı doğrulayın.

5. Cloud Run'a dağıt

Aracı uygulamasını Cloud Run'a dağıtmak için gcloud run deploy komutunu kullanacağız. Aşağıdaki komut, container'ı Cloud Build kullanarak oluşturur ve tek adımda Cloud Run'a dağıtır.

YOUR_API_KEY kısmını gerçek Gemini API anahtarınızla değiştirin.

gcloud run deploy gemini-fastapi-service \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_API_KEY=<YOUR_API_KEY>

Dağıtım tamamlandıktan sonra uç noktanızı terminalde görürsünüz ve kullanmaya başlayabilirsiniz.

6. Dağıtımı test etme

Cloud Run uç noktasını kullanın ve beklenen sonuçları aldığınızdan emin olmak için curl işlemini gerçekleştirin.

curl -X POST <CLOUD_RUN_ENDPOINT> \
     -H "Content-Type: application/json" \
     -d '{"name": "Abraham Lincoln"}'

Yerel olarak çalışan uygulamada aldığınız sonuçla aynı sonucu alırsınız.

7. Temizleme

Bu codelab'de kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız şu adımları uygulayın:

  1. Google Cloud Console'da Kaynakları yönetin sayfasına gidin.
  2. Proje listesinde silmek istediğiniz projeyi seçin ve Sil'i tıklayın.
  3. İletişim kutusunda proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.

8. Tebrikler

Tebrikler! Cloud Run'da dağıtılan LangChain aracınızı başarıyla oluşturup bu aracıyla etkileşim kurdunuz.