מידע על פיתוח ופריסה של אפליקציית LangChain ב-Cloud Run

1. סקירה כללית

בשיעור ה-Lab הזה תלמדו איך לפרוס אפליקציית LangChain שמשתמשת ב-Gemini כדי לאפשר לכם לשאול שאלות על הערות המוצר של Cloud Run.

דוגמה לאופן שבו האפליקציה פועלת: אם שואלים את השאלה "האם אפשר לטעון קטגוריה של Cloud Storage כנפח אחסון ב-Cloud Run?", האפליקציה תגיב "כן, החל מ-19 בינואר 2024" או משהו דומה.

כדי להחזיר תשובות מבוססות, האפליקציה קודם אוספת את הערות המוצר של Cloud Run שדומות לשאלה, ואז מעבירה את השאלה ואת הערות המוצר ל-Gemini. (זהו דפוס שנקרא בדרך כלל RAG). זהו תרשים שמראה את הארכיטקטורה של האפליקציה:

2. הגדרה ודרישות

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

  • כדי לפרוס את המשאבים הדרושים לאפליקציה צריך פרויקט ב-Google Cloud.
  • כדי לפרוס את האפליקציה, צריך להתקין את gcloud במחשב המקומי, לבצע אימות ולהגדיר אותו לשימוש בפרויקט.
    • gcloud auth login
    • gcloud config set project
  • אם אתם רוצים להריץ את האפליקציה במחשב המקומי שלכם, מומלץ לוודא שפרטי הכניסה שמוגדרים כברירת מחדל לאפליקציה מוגדרים נכון, כולל הגדרת המכסה בפרויקט.
    • gcloud auth application-default login
    • gcloud auth application-default set-quota-project
  • בנוסף, צריך להתקין את התוכנה הבאה:
    • Python (נדרשת גרסה 3.11 ואילך)
    • LangChain CLI
    • poetry לניהול יחסי תלות
    • pipx כדי להתקין ולהריץ את ה-CLI של LangChain ו-poetry בסביבות וירטואליות מבודדות

הנה פוסט בבלוג שיעזור לכם להתחיל להתקין את הכלים הנדרשים להדרכה הזו.

תחנות עבודה בענן

במקום המחשב המקומי, אפשר גם להשתמש ב-Cloud Workstations ב-Google Cloud. שימו לב: החל מאפריל 2024, גרסת Python ישנה יותר מ-3.11, כך שייתכן שתצטרכו לשדרג את גרסת Python לפני שתתחילו.

הפעלת ממשקי Cloud API

קודם כול, מריצים את הפקודה הבאה כדי לוודא שהגדרתם את הפרויקט הנכון ב-Google Cloud לשימוש:

gcloud config list project

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

gcloud config set project <PROJECT_ID>

עכשיו מפעילים את ממשקי ה-API הבאים:

gcloud services enable \
  bigquery.googleapis.com \
  sqladmin.googleapis.com \
  aiplatform.googleapis.com \
  cloudresourcemanager.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com

בחר אזור

Google Cloud זמין במיקומים רבים ברחבי העולם, ותצטרכו לבחור אחד מהם כדי לפרוס את המשאבים שבהם תשתמשו בסדנת העבודה הזו. מגדירים את האזור כמשתנה סביבה במסוף (הפקודה הבאה תשתמש במשתנה הזה):

export REGION=us-central1

3. יצירת המכונה של מסד נתונים וקטורי

חלק חשוב באפליקציה הזו הוא אחזור של הערות המוצר שרלוונטיות לשאלה של המשתמש. כדי להמחיש את זה בצורה מדויקת יותר, אם שואלים שאלה על Cloud Storage, רוצים שיתווסף להנחיה את נתוני הגרסה הבאים:

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

אראה לכם איך להשתמש ב-PostgreSQL ב-Cloud SQL כמסד נתונים של וקטורים. יצירת מכונה חדשה של Cloud SQL אורכת זמן מה, אז נעשה זאת עכשיו.

gcloud sql instances create sql-instance \
  --database-version POSTGRES_14 \
  --tier db-f1-micro \
  --region $REGION

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

PostgreSQL הוא שרת של מסד נתונים רלציוני, ובכל מכונה חדשה של Cloud SQL מותקנת כברירת מחדל התוסף pgvector. המשמעות היא שאפשר להשתמש בו גם כמסד נתונים וקטורי.

4. יצירה של תבנית לאפליקציית LangChain

כדי להמשיך, צריך להתקין את LangChain CLI ואת poetry לניהול יחסי התלות. כך מתקינים אותם באמצעות pipx:

pipx install langchain-cli poetry

מציבים את האפליקציה LangChain באמצעות הפקודה הבאה. כשמתבקשים, נותנים לתיקייה את השם run-rag ומדלגים על התקנת החבילות על ידי הקשה על Enter:

langchain app new

עוברים לספרייה run-rag ומתקינים את יחסי התלות

poetry install

יצרת עכשיו אפליקציית LangServe. LangServe עוטף את FastAPI סביב שרשרת LangChain. הספרייה כוללת סביבה מובנית לניסוי שבה אפשר לשלוח בקלות הנחיות ולבדוק את התוצאות, כולל כל השלבים המקשרים. מומלץ לפתוח את התיקייה run-rag בעורך שלך ולגלות מה יש בה.

5. יצירת המשימה להוספה לאינדקס

לפני שנתחיל להרכיב את אפליקציית האינטרנט, חשוב לוודא שהערות המוצר של Cloud Run נוספו לאינדקס במסד הנתונים של Cloud SQL. בקטע הזה תיצורו משימה להוספה לאינדקס שתבצע את הפעולות הבאות:

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

בתיקייה run-rag/app, יוצרים קובץ indexer.py עם התוכן הבא:

import os
from google.cloud.sql.connector import Connector
import pg8000
from langchain_community.vectorstores.pgvector import PGVector
from langchain_google_vertexai import VertexAIEmbeddings
from google.cloud import bigquery


# Retrieve all Cloud Run release notes from BigQuery 
client = bigquery.Client()
query = """
SELECT
  CONCAT(FORMAT_DATE("%B %d, %Y", published_at), ": ", description) AS release_note
FROM `bigquery-public-data.google_cloud_release_notes.release_notes`
WHERE product_name= "Cloud Run"
ORDER BY published_at DESC
"""
rows = client.query(query)

print(f"Number of release notes retrieved: {rows.result().total_rows}")

# Set up a PGVector instance 
connector = Connector()

def getconn() -> pg8000.dbapi.Connection:
    conn: pg8000.dbapi.Connection = connector.connect(
        os.getenv("DB_INSTANCE_NAME", ""),
        "pg8000",
        user=os.getenv("DB_USER", ""),
        password=os.getenv("DB_PASS", ""),
        db=os.getenv("DB_NAME", ""),
    )
    return conn

store = PGVector(
    connection_string="postgresql+pg8000://",
    use_jsonb=True,
    engine_args=dict(
        creator=getconn,
    ),
    embedding_function=VertexAIEmbeddings(
        model_name="textembedding-gecko@003"
    ),
    pre_delete_collection=True  
)

# Save all release notes into the Cloud SQL database
texts = list(row["release_note"] for row in rows)
ids = store.add_texts(texts)

print(f"Done saving: {len(ids)} release notes")

מוסיפים את יחסי התלות הנדרשים:

poetry add \
  "cloud-sql-python-connector[pg8000]" \
  langchain-google-vertexai==1.0.5 \
  langchain-community==0.2.5 \
  pgvector

יצירת מסד הנתונים ומשתמש

יוצרים מסד נתונים release-notes במכונה של Cloud SQL‏ sql-instance:

gcloud sql databases create release-notes --instance sql-instance

יוצרים משתמש מסד נתונים בשם app:

gcloud sql users create app --instance sql-instance --password "myprecious"

פריסה והפעלה של המשימה להוספה לאינדקס

עכשיו פורסים ומריצים את המשימה:

DB_INSTANCE_NAME=$(gcloud sql instances describe sql-instance --format="value(connectionName)")

gcloud run jobs deploy indexer \
  --source . \
  --command python \
  --args app/indexer.py \
  --set-env-vars=DB_INSTANCE_NAME=$DB_INSTANCE_NAME \
  --set-env-vars=DB_USER=app \
  --set-env-vars=DB_NAME=release-notes \
  --set-env-vars=DB_PASS=myprecious \
  --region=$REGION \
  --execute-now

זו פקודה ארוכה, בואו נראה מה קורה:

הפקודה הראשונה מאחזרת את שם החיבור (מזהה ייחודי בפורמט project:region:instance) ומגדירה אותו כמשתנה הסביבה DB_INSTANCE_NAME.

הפקודה השנייה פורסת את המשימה ב-Cloud Run. כך פועלות הדגלים:

  • --source .: מציין שקוד המקור של המשימה נמצא בספריית העבודה הנוכחית (הספרייה שבה מריצים את הפקודה).
  • --command python: מגדיר את הפקודה להרצה בתוך הקונטיינר. במקרה כזה, מריצים Python.
  • --args app/indexer.py: מספק את הארגומנטים לפקודת python. הפקודה הזו מורה להפעיל את הסקריפט indexer.py בספריית האפליקציה.
  • --set-env-vars: הגדרת משתני סביבה שסקריפט Python יכול לגשת אליהם במהלך ההרצה.
  • --region=$REGION: ציון האזור שבו צריך לפרוס את המשימה.
  • --execute-now: האפשרות הזו מורה ל-Cloud Run להפעיל את המשימה מיד אחרי הפריסה שלה.

כדי לוודא שהמשימה הושלמה, אפשר:

  • קריאת היומנים של ביצוע המשימה דרך מסוף האינטרנט. אמורה להופיע ההודעה 'סיום השמירה: xxx נתוני גרסה' (כאשר xxx הוא מספר נתוני הגרסה שנשמרו).
  • אפשר גם לנווט למופע Cloud SQL במסוף האינטרנט, ולהשתמש ב-Cloud SQL Studio כדי לשלוח שאילתה לגבי מספר הרשומות בטבלה langchain_pg_embedding.

6. כתיבת אפליקציית האינטרנט

פותחים את הקובץ app/server.py בכלי העריכה. תופיע השורה הבאה:

# Edit this to add the chain you want to add

מחליפים את התגובה הזו בקטע הקוד הבא:

# (1) Initialize VectorStore
connector = Connector()


def getconn() -> pg8000.dbapi.Connection:
    conn: pg8000.dbapi.Connection = connector.connect(
        os.getenv("DB_INSTANCE_NAME", ""),
        "pg8000",
        user=os.getenv("DB_USER", ""),
        password=os.getenv("DB_PASS", ""),
        db=os.getenv("DB_NAME", ""),
    )
    return conn


vectorstore = PGVector(
    connection_string="postgresql+pg8000://",
    use_jsonb=True,
    engine_args=dict(
        creator=getconn,
    ),
    embedding_function=VertexAIEmbeddings(
        model_name="textembedding-gecko@003"
    )
)

# (2) Build retriever


def concatenate_docs(docs):
    return "\n\n".join(doc.page_content for doc in docs)


notes_retriever = vectorstore.as_retriever() | concatenate_docs

# (3) Create prompt template
prompt_template = PromptTemplate.from_template(
    """You are a Cloud Run expert answering questions. 
Use the retrieved release notes to answer questions
Give a concise answer, and if you are unsure of the answer, just say so.

Release notes: {notes}

Here is your question: {query}
Your answer: """)

# (4) Initialize LLM
llm = VertexAI(
    model_name="gemini-1.0-pro-001",
    temperature=0.2,
    max_output_tokens=100,
    top_k=40,
    top_p=0.95
)

# (5) Chain everything together
chain = (
    RunnableParallel({
        "notes": notes_retriever,
        "query": RunnablePassthrough()
    })
    | prompt_template
    | llm
    | StrOutputParser()
)

צריך גם להוסיף את הייבוא הבא:

import pg8000
import os
from google.cloud.sql.connector import Connector
from langchain_google_vertexai import VertexAI
from langchain_google_vertexai import VertexAIEmbeddings
from langchain_core.runnables import RunnablePassthrough, RunnableParallel
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import PromptTemplate
from langchain_community.vectorstores.pgvector import PGVector

לבסוף, משנים את השורה 'NotImplemented' ל:

# add_routes(app, NotImplemented)
add_routes(app, chain)

7. פריסת אפליקציית האינטרנט ב-Cloud Run

מהספרייה run-rag, מריצים את הפקודה הבאה כדי לפרוס את האפליקציה ב-Cloud Run:

DB_INSTANCE_NAME=$(gcloud sql instances describe sql-instance --format="value(connectionName)")

gcloud run deploy run-rag \
  --source . \
  --set-env-vars=DB_INSTANCE_NAME=$DB_INSTANCE_NAME \
  --set-env-vars=DB_USER=app \
  --set-env-vars=DB_NAME=release-notes \
  --set-env-vars=DB_PASS=myprecious \
  --region=$REGION \
  --allow-unauthenticated

הפקודה הזו מבצעת את הפעולות הבאות:

  • העלאת קוד המקור ל-Cloud Build
  • הפעלת build של Docer.
  • מעבירים את קובץ האימג' שנוצר בקונטיינר ל-Artifact Registry.
  • יוצרים שירות Cloud Run באמצעות קובץ האימג' בקונטיינר.

בסיום הפקודה, תופיע כתובת URL מסוג HTTPS בדומיין run.app. זוהי כתובת ה-URL הציבורית של שירות Cloud Run החדש

8. סיור בגן המשחקים

פותחים את כתובת ה-URL של שירות Cloud Run ועוברים אל /playground. יופיע שדה טקסט. אפשר להשתמש בו כדי לשאול שאלות על נתוני הגרסה של Cloud Run, למשל:

9. מזל טוב

סיימתם לפתח ולפרוס אפליקציית LangChain ב-Cloud Run. כל הכבוד!

אלה המושגים המרכזיים:

  • שימוש ב-LangChain Framework כדי ליצור אפליקציה של יצירת טקסט משופר לאחזור (RAG).
  • שימוש ב-PostgreSQL ב-Cloud SQL כמסד נתונים וקטורי עם pgvector, שמתקין כברירת מחדל ב-Cloud SQL.
  • להריץ משימה ממושכת יותר של הוספה לאינדקס כמשימות של Cloud Run ואפליקציית אינטרנט כשירות של Cloud Run.
  • אורזים שרשרת LangChain באפליקציה FastAPI באמצעות LangServe, שמספק ממשק נוח לאינטראקציה עם אפליקציית RAG.

הסרת המשאבים

כדי להימנע מצבירת חיובים בחשבון Google Cloud Platform על המשאבים שבהם השתמשתם במדריך הזה:

  • נכנסים לדף Manage resources במסוף Cloud.
  • ברשימת הפרויקטים, בוחרים את הפרויקט הרלוונטי ולוחצים על 'מחיקה'.
  • כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

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

  • מופע של Cloud SQL
  • שירות Cloud Run
  • משימה ב-Cloud Run