מדריך למתחילים: פיתוח ופריסה של אפליקציית אינטרנט ב-Python‏ (LangChain) ב-Cloud Run

ב-Cloud Run אתם יכולים לפתח ולפרוס אפליקציות LangChain שמשתמשות ב-Gemini כדי לענות על שאילתות. במדריך למתחילים הזה תפרסו אפליקציית אינטרנט ב-Python שעונה על שאלות לגבי ערי בירה, כש-Cloud Run יוצר את הקונטיינר באופן אוטומטי כשאתם פורסים מקוד המקור.

לפני שמתחילים

  1. התקינו את ה-CLI של Google Cloud.

  2. הגדירו שה-CLI של gcloud ישתמש בזהות המאוחדת שלכם.

    איך נכנסים ל-CLI של gcloud באמצעות הזהות המאוחדת?

  3. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  4. יוצרים או בוחרים פרויקט ב- Cloud de Confiance .

    התפקידים שנדרשים כדי לבחור או ליצור פרויקט

    • בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים?

    • יוצרים פרויקט ב- Cloud de Confiance :

      gcloud projects create PROJECT_ID

      מחליפים את PROJECT_ID בשם של הפרויקט ב- Cloud de Confiance שאתם יוצרים.

    • בוחרים את הפרויקט שיצרתם ב- Cloud de Confiance :

      gcloud config set project PROJECT_ID

      מחליפים את PROJECT_ID בשם הפרויקט ב- Cloud de Confiance .

  5. אם משתמשים בפרויקט קיים, מוודאים שיש את ההרשאות הנדרשות כדי להשלים את ההדרכה. אם משתמשים בפרויקט חדש, לא צריך לוודא כי כבר יש את ההרשאות הנדרשות.

  6. מוודאים שהחיוב מופעל בפרויקט ב- Cloud de Confiance .

  7. אם אתם כפופים לכלל מדיניות של הארגון של הגבלה לפי דומיין שמגבילה הפעלות לא מאומתות לפרויקט, תצטרכו לגשת לשירות שנפרס כמו שמתואר בקטע בדיקת שירותים פרטיים.

  8. מפעילים את Cloud Run Admin API ואת Cloud Build API, אם הם עדיין לא מופעלים:

    התפקידים שנדרשים כדי להפעיל ממשקי API

    כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים 

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

    אחרי שמפעילים את Cloud Run Admin API, חשבון השירות שמוגדר כברירת מחדל ב-Compute Engine נוצר באופן אוטומטי.

  9. למחירון של Cloud Run או למחשבון עלויות.
  10. כדי לפרוס את אפליקציית LangChain עם מודל Gemini, צריך מפתח API מ-Google AI Studio. כדי ליצור מפתח API באמצעות Google AI Studio, ראו שימוש במפתחות Gemini API במאמרי העזרה של ה-API של Gemini. תצטרכו להפנות למפתח הזה כשאתם פורסים את השירות.

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות להשלמת המדריך למתחילים, אתם צריכים לבקש מהאדמין לתת לכם את התפקידים הבאים ב-IAM:

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

מתן גישה לפרויקט לחשבון השירות של Cloud Build

כברירת מחדל, Cloud Build משתמש בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine בתור חשבון השירות שמוגדר כברירת מחדל ב-Cloud Build כדי ליצור את קוד המקור ואת המשאב של Cloud Run, אלא אם משנים את ההתנהגות הזו.

כדי ש-Cloud Build יוכל ליצור את המקורות, צריך להקצות לחשבון השירות של Cloud Build את התפקיד Cloud Run Builder‏ (roles/run.builder) בפרויקט:

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

מחליפים את PROJECT_ID במזהה הפרויקט ב- Cloud de Confianceואת SERVICE_ACCOUNT_EMAIL_ADDRESS בכתובת האימייל של חשבון השירות של Cloud Build. אם אתם משתמשים בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine בתור חשבון השירות של Cloud Build, השתמשו בפורמט הבא לכתובת האימייל של חשבון השירות:

PROJECT_NUMBER-compute@developer.s3ns-system.iam.gserviceaccount.com

מחליפים את PROJECT_NUMBER במספר הפרויקט ב- Cloud de Confiance.

במאמר יצירה וניהול של פרויקטים מוסבר איך למצוא את מזהה הפרויקט ואת מספר הפרויקט.

הקצאת התפקיד "מפתח ב-Cloud Run" מתעדכנת תוך כמה דקות.

כתיבת האפליקציה לדוגמה

כדי לכתוב אפליקציה ב-Python:

  1. יוצרים ספרייה חדשה בשם langchain-gemini-fastapi-app ועוברים אליה:

    mkdir langchain-gemini-fastapi-app
cd langchain-gemini-fastapi-app

  2. יוצרים קובץ בשם main.py ומדביקים בו את הקוד הבא:

    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 StrOutputParser

# Initialize FastAPI
app = FastAPI(title="LangChain Gemini Cloud Run App")

# 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 Chain
prompt = ChatPromptTemplate.from_template("You are a helpful assistant. Answer the following question concisely: {topic}")
output_parser = StrOutputParser()

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

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

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

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

  3. יוצרים קובץ בשם requirements.txt ומדביקים בו את הקוד הבא:

    fastapi
uvicorn
langchain
langchain-google-genai
python-dotenv

פריסה ב-Cloud Run מקוד המקור

פריסה מהמקור יוצרת באופן אוטומטי קובץ אימג' של קונטיינר מקוד המקור ופורסת אותו.

כדי לפרוס מהמקור, משתמשים בפקודה הבאה:

  gcloud run deploy gemini-fastapi-service \
    --source . \
    --region us-central1 \
    --no-allow-unauthenticated \
    --set-env-vars GEMINI_API_KEY=API_KEY

מחליפים את API_KEY במפתח ה-API של Google AI Studio. בסביבת הייצור, מומלץ להשתמש ב-Secret Manager כדי לטפל במפתח ה-API, במקום במשתני סביבה פשוטים.

אחרי שפורסים את האפליקציה, כתובת ה-URL של השירות מופיעה ב-Cloud Run, למשל https://gemini-fastapi-service-xyz-uc.a.run.app.

בדיקת השירות של Cloud Run

כדי לבדוק את השירות, שולחים שאילתה לסוכן באמצעות פקודת ה-curl הבאה:

  curl -X POST YOUR-SERVICE-URL/chat \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    -d '{"topic": "What is the capital of France?"}'

מחליפים את YOUR-SERVICE-URL בכתובת ה-URL של השירות.

הסוכן שולח את התשובה הבאה:

  {
  "response": "Paris"
  }

כדי לוודא שהשירות פועל כמו שצריך, בודקים את הכרטיסייה Logs של שירות Cloud Run.

הסרת המשאבים

כדי לא לצבור חיובים לחשבון Cloud de Confiance על המשאבים שבהם השתמשתם בדף הזה, אתם צריכים למחוק את הפרויקט ב- Cloud de Confiance יחד עם המשאבים.

כדי להימנע מחיובים נוספים בחשבון Cloud de Confiance by S3NS , צריך למחוק את כל המשאבים שפרסתם באמצעות המדריך למתחילים.

מחיקת המאגר

ב-Cloud Run לא תחויבו כשהשירות שפרסתם לא בשימוש. עם זאת, יכול להיות שעדיין תחויבו על אחסון קובץ האימג' של הקונטיינר ב-Artifact Registry. כדי למחוק מאגרים של Artifact Registry, פועלים לפי השלבים שמפורטים במאמר מחיקת מאגרים במסמכי התיעוד של Artifact Registry.

מחיקת השירות

שירותי Cloud Run לא צוברים עלויות עד שהם מקבלים בקשות. כדי למחוק את השירות ב-Cloud Run, מבצעים את אחת מהפעולות הבאות:

המסוף

כדי למחוק שירות:

  1. נכנסים לדף Services של Cloud Run במסוף Cloud de Confiance by S3NS :

    כניסה ל-Cloud Run

  2. ברשימת השירותים, מאתרים את השירות שרוצים למחוק ולוחצים על תיבת הסימון שלו כדי לבחור אותו.

  3. לוחצים על Delete. כל הגרסאות של השירות יימחקו.

gcloud

כדי למחוק שירות, מריצים את הפקודה הבאה:

gcloud run services delete SERVICE --region REGION

מחליפים את מה שכתוב בשדות הבאים:

  • ‫SERVICE: שם השירות.
  • ‫REGION: Cloud de Confiance האזור של השירות.

מחיקת פרויקט הבדיקה

מחיקת הפרויקט ב- Cloud de Confiance מפסיקה את החיוב על כל המשאבים באותו פרויקט. כדי לשחרר את כל המשאבים של Cloud de Confiance by S3NS בפרויקט:

    כדי למחוק פרויקט ב- Cloud de Confiance :

    gcloud projects delete PROJECT_ID

המאמרים הבאים

למידע נוסף על בניית קונטיינר מקוד מקור ודחיפה למאגר, ראו: