Codelab – פיתוח אפליקציה להמלצות על תנוחות יוגה לפי הקשר באמצעות Firestore, ‏ Vector Search, ‏ Langchain ו-Gemini (גרסת Python)

1. מבוא

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

במהלך הקודלאב, נשתמש בגישה הדרגתית לפי השלבים הבאים:

1. שימוש במערך נתונים קיים של Hugging Face עם תנוחות יוגה (בפורמט JSON).
2. משפרים את מערך הנתונים באמצעות תיאור שדה נוסף שמשתמש ב-Gemini כדי ליצור תיאורים לכל אחת מהתנוחות.
3. משתמשים ב-Langchain כדי ליצור מסמך, משתמשים בשילוב של Firestore Langchain כדי ליצור את האוסף וההטמעות ב-Firestore.
4. יצירת אינדקס מורכב ב-Firestore כדי לאפשר חיפוש וקטור.
5. אפשר להשתמש בחיפוש לפי וקטור באפליקציית Flask שמרכזת את כל הרכיבים, כפי שמתואר בהמשך:

מה עליכם לעשות

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

מה תלמדו

• איך משתמשים ב-Gemini כדי ליצור תוכן טקסטואלי, ובהקשר של סדנת הקוד הזו, ליצור תיאורים של תנוחות יוגה
• איך משתמשים ב-Langchain Document Loader for Firestore כדי לטעון ל-Firestore רשומות מקבוצת נתונים משופרת מ-Hugging Face, יחד עם Vector Embeddings
• איך משתמשים ב-Langchain Vector Store for Firestore כדי לחפש נתונים על סמך שאילתה בשפה טבעית
• איך משתמשים ב-Google Cloud Text to Speech API כדי ליצור תוכן אודיו

מה צריך להכין

• דפדפן האינטרנט Chrome
• חשבון Gmail
• פרויקט ב-Cloud שבו החיוב מופעל

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

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

יצירת פרויקט

1. בדף לבחירת הפרויקט במסוף Google Cloud, בוחרים או יוצרים פרויקט ב-Google Cloud.
2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט
3. נשתמש ב-Cloud Shell, סביבת שורת פקודה שפועלת ב-Google Cloud ומגיעה עם bq טעון מראש. לוחצים על Activate Cloud Shell בחלק העליון של מסוף Google Cloud.

4. אחרי שמתחברים ל-Cloud Shell, בודקים שכבר בוצע אימות ושהמזהה של הפרויקט מוגדר כפרויקט באמצעות הפקודה הבאה:

gcloud auth list

5. מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שהפקודה gcloud מכירה את הפרויקט.

gcloud config list project

6. אם הפרויקט לא מוגדר, משתמשים בפקודה הבאה כדי להגדיר אותו:

gcloud config set project <YOUR_PROJECT_ID>

7. מפעילים את ממשקי ה-API הנדרשים באמצעות הפקודה שמופיעה בהמשך. הפעולה עשויה להימשך כמה דקות, אז חשוב להמתין.

gcloud services enable firestore.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudfunctions.googleapis.com \
                       aiplatform.googleapis.com \
                       texttospeech.googleapis.com

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

Operation "operations/..." finished successfully.

האפשרות החלופית לפקודה gcloud היא דרך מסוף, על ידי חיפוש של כל מוצר או באמצעות הקישור הזה.

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

במסמכי העזרה מפורטות הפקודות של gcloud והשימוש בהן.

שכפול המאגר והגדרת הגדרות הסביבה

בשלב הבא נשתמש בקוד לדוגמה שנעזרים בו בשאר הקודלמעבדה. נניח שאתם נמצאים ב-Cloud Shell, נותנים את הפקודה הבאה מתוך ספריית הבית:

git clone https://github.com/rominirani/yoga-poses-recommender-python

כדי להפעיל את העורך, לוחצים על Open Editor בסרגל הכלים שבחלון של Cloud Shell. לוחצים על סרגל התפריטים בפינה הימנית העליונה ובוחרים באפשרות 'קובץ' → 'פתיחת תיקייה', כפי שמוצג בהמשך:

בוחרים בתיקייה yoga-poses-recommender-python והיא אמורה להיפתח עם הקבצים הבאים, כפי שמוצג בהמשך:

עכשיו צריך להגדיר את משתני הסביבה שבהם נשתמש. לוחצים על הקובץ config.template.yaml ותוכלו לראות את התוכן כמו שמוצג בהמשך:

project_id: your-project-id
location: us-central1
gemini_model_name: gemini-1.5-flash-002
embedding_model_name: text-embedding-004
image_generation_model_name: imagen-3.0-fast-generate-002
database: (default)
collection: poses
test_collection: test-poses
top_k: "3"

יש לעדכן את הערכים של project_id ושל location בהתאם לבחירה שלך בזמן יצירת הפרויקט ב-Google Cloud ואזור מסד הנתונים של Firestore. באופן אידיאלי, הערכים של location צריכים להיות זהים בפרויקט Google Cloud ובמסד הנתונים של Firestore, למשל us-central1.

לצורך הקודלאב הזה, נשתמש בערכים שהוגדרו מראש (חוץ מ-project_id ו-location, שצריך להגדיר בהתאם להגדרות שלכם.

עליך לשמור את הקובץ הזה בתור config.yaml באותה תיקייה שבה נמצא הקובץ config.template.yaml.

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

dependencies = [
    "datasets>=3.2.0",
    "flask>=3.1.0",
    "google-cloud-aiplatform>=1.78.0",
    "google-cloud-texttospeech>=2.24.0",
    "langchain-community>=0.3.15",
    "langchain-core>=0.3.31",
    "langchain-google-community>=2.0.4",
    "langchain-google-firestore>=0.5.0",
    "langchain-google-vertexai>=2.0.7",
    "pydantic-settings>=2.7.1",
    "pyyaml>=6.0.2",
    "tenacity>=9.0.0",
]

יחסי התלות האלה כבר נעול לגרסה ב-requirements.txt.. לסיכום, אנחנו צריכים ליצור סביבה וירטואלית של Python עם יחסי התלות של חבילות Python ב-requirements.txt כדי להתקין אותם בסביבה הווירטואלית. כדי לעשות זאת, עוברים אל Command Palette (Ctrl+Shift+P) ב-Cloud Shell IDE ומקלידים Python: Create Environment. פועלים לפי השלבים הבאים כדי לבחור קובץ Virtual Environment(venv), קובץ Python 3.x interpreter ואת הקובץ requirements.txt.

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

source .venv/bin/activate

אמורה להופיע ההודעה (‎.venv) במסוף. לדוגמה: -> (.venv) yourusername@cloudshell:

מצוין! עכשיו אנחנו מוכנים להמשיך למשימה של הגדרת מסד הנתונים של Firestore.

3. הגדרת Firestore

Cloud Firestore הוא מסד נתונים מנוהל למסמכים ללא שרת (serverless), שבו נשתמש כקצה עורפי לנתוני האפליקציה שלנו. הנתונים ב-Cloud Firestore מאורגנים בקולקציות של מסמכים.

הפעלה של מסד נתונים ב-Firestore

נכנסים לדף Firestore במסוף Cloud.

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

• מצב Firestore: Native.
• מיקום: משתמשים בהגדרות ברירת המחדל של המיקום.
• עבור כללי האבטחה, בוחרים באפשרות Test rules.
• יוצרים את מסד הנתונים.

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

חשוב לזכור שזהו אותו Firestore שאתם מכירים ואוהבים אם אתם משתמשים ב-Firebase. למעשה, אפשר להגיע לאותו מופע של מסד הנתונים באמצעות מסוף Firebase.

זהו סוף הקטע של הגדרת מסד הנתונים של Firestore.

4. הכנת מערך הנתונים של תנוחות יוגה

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

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

אם נעבור לקטע Files and versions, נוכל לקבל את קובץ הנתונים בפורמט JSON של כל תנוחות הישיבה.

הורדנו את yoga_poses.json ושלחנו לך את הקובץ הזה. שם הקובץ הוא yoga_poses_alldata.json והוא נמצא בתיקייה /data.

כדי להכיר את התהליך, נציג את התהליכים המלאים ליצירת תיאורים וליצירת הטמעות (embeddings) בקבוצת משנה קטנה יותר של כמה רשומות.

עוברים לקובץ data/yoga_poses.json בעורך של Cloud Shell ומעיינים ברשימת אובייקטי ה-JSON, שבהם כל אובייקט JSON מייצג תנוחת יוגה. יש לנו סך של 3 רשומות, ורשומת לדוגמה מוצגת בהמשך:

{
   "name": "Big Toe Pose",
   "sanskrit_name": "Padangusthasana",
   "photo_url": "https://pocketyoga.com/assets/images/full/ForwardBendBigToe.png",
   "expertise_level": "Beginner",
   "pose_type": ["Standing", "Forward Bend"]
 }

זו הזדמנות מצוינת להציג את Gemini ולהסביר איך אפשר להשתמש במודל ברירת המחדל עצמו כדי ליצור בשבילו שדה description.

ב-Cloud Shell Editor, עוברים לקובץ generate-descriptions.py. התוכן של הקובץ הזה מוצג בהמשך:

import json
import time
import logging
import vertexai
from langchain_google_vertexai import VertexAI
from tenacity import retry, stop_after_attempt, wait_exponential
from settings import get_settings

settings = get_settings()
logging.basicConfig(
    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
)
# Initialize Vertex AI SDK
vertexai.init(project=settings.project_id, location=settings.location)
logging.info("Done Initializing Vertex AI SDK")


@retry(
    stop=stop_after_attempt(5),
    wait=wait_exponential(multiplier=1, min=4, max=10),
)
def generate_description(pose_name, sanskrit_name, expertise_level, pose_types):
    """Generates a description for a yoga pose using the Gemini API."""

    prompt = f"""
    Generate a concise description (max 50 words) for the yoga pose: {pose_name}
    Also known as: {sanskrit_name}
    Expertise Level: {expertise_level}
    Pose Type: {", ".join(pose_types)}

    Include key benefits and any important alignment cues.
    """
    try:
        model = VertexAI(model_name=settings.gemini_model_name, verbose=True)
        response = model.invoke(prompt)
        return response
    except Exception as e:
        logging.info(f"Error generating description for {pose_name}: {e}")
        return ""


def add_descriptions_to_json(input_file, output_file):
    """Loads JSON data, adds descriptions, and saves the updated data."""

    with open(input_file, "r") as f:
        yoga_poses = json.load(f)

    total_poses = len(yoga_poses)
    processed_count = 0

    for pose in yoga_poses:
        if pose["name"] != " Pose":
            start_time = time.time()  # Record start time
            pose["description"] = generate_description(
                pose["name"],
                pose["sanskrit_name"],
                pose["expertise_level"],
                pose["pose_type"],
            )
            end_time = time.time()  # Record end time

            processed_count += 1
            end_time = time.time()  # Record end time
            time_taken = end_time - start_time
            logging.info(
                f"Processed: {processed_count}/{total_poses} - {pose['name']} ({time_taken:.2f} seconds)"
            )

        else:
            pose["description"] = ""
            processed_count += 1
            logging.info(
                f"Processed: {processed_count}/{total_poses} - {pose['name']} ({time_taken:.2f} seconds)"
            )
        # Adding a delay to avoid rate limit
        time.sleep(30)

    with open(output_file, "w") as f:
        json.dump(yoga_poses, f, indent=2)


def main():
    # File paths
    input_file = "./data/yoga_poses.json"
    output_file = "./data/yoga_poses_with_descriptions.json"

    # Add descriptions and save the updated JSON
    add_descriptions_to_json(input_file, output_file)


if __name__ == "__main__":
    main()

האפליקציה הזו תוסיף שדה description חדש לכל רשומת JSON של תנוחת יוגה. התיאור יתקבל באמצעות קריאה למודל Gemini, שבו נציג לו את ההנחיה הנדרשת. השדה מתווסף לקובץ ה-JSON והקובץ החדש נכתב לקובץ data/yoga_poses_with_descriptions.json.

הנה השלבים העיקריים:

1. בפונקציה main(), תוכלו לראות שהיא מפעילה את הפונקציה add_descriptions_to_json ומספקת את קובץ הקלט ואת קובץ הפלט הצפויים.
2. הפונקציה add_descriptions_to_json מבצעת את הפעולות הבאות לכל רשומת JSON, כלומר פרטי הפוסט בנושא יוגה:
3. הוא מחלץ את pose_name, sanskrit_name, expertise_level ו-pose_types.
4. הפונקציה מפעילה את הפונקציה generate_description, שמרכיבת הנחיה ואז מפעילה את סיווג המודל Langchain VertexAI כדי לקבל את טקסט התשובה.
5. לאחר מכן, טקסט התגובה הזה מתווסף לאובייקט ה-JSON.
6. לאחר מכן, רשימת האובייקטים המעודכנת בפורמט JSON נכתבת בקובץ היעד.

נבקש ממך להריץ את האפליקציה הזו. פותחים חלון מסוף חדש (Ctrl+Shift+C) ומריצים את הפקודה הבאה:

python generate-descriptions.py

אם תתבקשו להעניק הרשאה כלשהי, עליכם לספק אותה.

האפליקציה תתחיל לפעול. הוספנו עיכוב של 30 שניות בין הרשומות כדי למנוע מכסות של הגבלת קצב שליחת הבקשות שעשויות להיות בחשבונות Google Cloud חדשים. לכן, יש להמתין.

בהמשך מוצגת דוגמה להרצה מתמשכת:

אחרי שכל 3 הרשומות ישופרו באמצעות הקריאה ל-Gemini, ייווצר קובץ data/yoga_poses_with_description.json. אפשר לעיין בזה.

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

5. ייבוא נתונים ל-Firestore ויצירת הטמעות של וקטורים

יש לנו את הקובץ data/yoga_poses_with_description.json ועכשיו אנחנו צריכים לאכלס את מסד הנתונים של Firestore באמצעותו, וחשוב גם ליצור את הטמעות הווקטורים לכל אחד מהרשומות. הטמעות הווקטורים יהיו שימושיות בשלב מאוחר יותר, כשנצטרך לבצע חיפוש של דמיון ביניהם לבין שאילתת המשתמש שסופקה בשפה טבעית.

כדי להטמיע את התהליך שמתואר למעלה, נשתמש ברכיבי Langchain Firestore.

כדי לעשות זאת, צריך לפעול לפי השלבים הבאים:

1. נמיר את רשימת אובייקטי ה-JSON לרשימה של אובייקטים מסוג Langchain Document. לכל מסמך יהיו שני מאפיינים: page_content ו-metadata. אובייקט המטא-נתונים יכיל את אובייקט ה-JSON כולו, עם מאפיינים כמו name, description, sanskrit_name וכו'. השדה page_content יהיה מחרוזת טקסט שתהיה שרשור של כמה שדות.
2. אחרי שתהיה לנו רשימה של אובייקטים מסוג Document, נשתמש בכיתה Langchain‏ FirestoreVectorStore ובפרט בשיטה from_documents עם רשימת המסמכים הזו, שם האוסף (אנחנו משתמשים במשתנה TEST_COLLECTION שמצביע על test-poses), בכיתה Vertex AI Embedding ובפרטי החיבור ל-Firestore (שם PROJECT_ID ו-DATABASE). הפעולה הזו תיצור את האוסף ותייצר גם שדה embedding לכל אחד מהמאפיינים.

הקוד של import-data.py מופיע בהמשך (חלקים מהקוד קוצרו כדי לקצר את הטקסט):

... 

def create_langchain_documents(poses):
   """Creates a list of Langchain Documents from a list of poses."""
   documents = []
   for pose in poses:
       # Convert the pose to a string representation for page_content
       page_content = (
           f"name: {pose.get('name', '')}\n"
           f"description: {pose.get('description', '')}\n"
           f"sanskrit_name: {pose.get('sanskrit_name', '')}\n"
           f"expertise_level: {pose.get('expertise_level', 'N/A')}\n"
           f"pose_type: {pose.get('pose_type', 'N/A')}\n"
       ).strip()
       # The metadata will be the whole pose
       metadata = pose

       document = Document(page_content=page_content, metadata=metadata)
       documents.append(document)
   logging.info(f"Created {len(documents)} Langchain documents.")
   return documents

def main():
    all_poses = load_yoga_poses_data_from_local_file(
        "./data/yoga_poses_with_descriptions.json"
    )
    documents = create_langchain_documents(all_poses)
    logging.info(
        f"Successfully created langchain documents. Total documents: {len(documents)}"
    )

    embedding = VertexAIEmbeddings(
        model_name=settings.embedding_model_name,
        project=settings.project_id,
        location=settings.location,
    )

    client = firestore.Client(project=settings.project_id, database=settings.database)

    vector_store = FirestoreVectorStore.from_documents(
        client=client,
        collection=settings.test_collection,
        documents=documents,
        embedding=embedding,
    )
    logging.info("Added documents to the vector store.")


if __name__ == "__main__":
    main()

נבקש ממך להריץ את האפליקציה הזו. פותחים חלון מסוף חדש (Ctrl+Shift+C) ומריצים את הפקודה הבאה:

python import-data.py

אם הכל יתבצע כמו שצריך, אמורה להופיע הודעה דומה לזו שבהמשך:

2025-01-21 14:50:06,479 - INFO - Added documents to the vector store.

כדי לבדוק אם הרשומות הוכנסו בהצלחה והטמעות ה-embedding נוצרו, אפשר להיכנס לדף Firestore במסוף Cloud.

לוחצים על מסד הנתונים (ברירת המחדל), שבו אמורה להופיע האוסף test-poses ומספר מסמכים באוסף הזה. כל מסמך הוא תנוחת יוגה אחת.

לוחצים על אחד מהמסמכים כדי לבדוק את השדות. בנוסף לשדות שייבאנו, יופיע גם השדה embedding. זהו שדה וקטורים שנוצר באופן אוטומטי עבורכם באמצעות הכיתה Langchain‏ VertexAIEmbeddings שבה השתמשנו, שבה סיפקנו את מודל ההטמעה (Embedding) של Vertex AI‏ text-embedding-004.

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

6. ייבוא תנוחות יוגה מלאות לאוסף של מסדי נתונים ב-Firestore

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

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

1. יוצרים קטגוריה בפרויקט באמצעות הפקודה gsutil שמופיעה בהמשך. מחליפים את המשתנה <PROJECT_ID> בפקודה הבאה במזהה הפרויקט ב-Google Cloud.

gsutil mb -l us-central1 gs://<PROJECT_ID>-my-bucket

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

gsutil cp -r gs://yoga-database-firestore-export-bucket/2025-01-27T05:11:02_62615  gs://<PROJECT_ID>-my-bucket

עכשיו שיש לנו את הנתונים לייבוא, אנחנו יכולים לעבור לשלב האחרון של ייבוא הנתונים למסד הנתונים של Firebase (default) שיצרנו.

3. משתמשים בפקודה הבאה של gcloud:

gcloud firestore import gs://<PROJECT_ID>-my-bucket/2025-01-27T05:11:02_62615

הייבוא יימשך כמה שניות. בסיום, תוכלו לאמת את מסד הנתונים ואת הקולקציה ב-Firestore. לשם כך, עוברים אל https://console.cloud.google.com/firestore/databases, בוחרים את מסד הנתונים default ואת הקולקציה poses כפי שמתואר בהמשך:

זהו, סיימנו ליצור את האוסף ב-Firestore שבו נשתמש באפליקציה.

7. ביצוע חיפוש דמיון וקטורי ב-Firestore

כדי לבצע חיפוש דמיון וקטורי, נקבל את השאילתה מהמשתמש. דוגמה לשאילתה הזו יכולה להיות "Suggest me some exercises to relieve back pain".

כדאי לעיין בקובץ search-data.py. הפונקציה העיקרית שצריך לבדוק היא פונקציית החיפוש, שמוצגת בהמשך. באופן כללי, הקוד יוצר סוג הטמעה (embedding) שמשמש ליצירת הטמעה לשאילתת המשתמש. לאחר מכן, הוא משתמש במחלקה FirestoreVectorStore כדי להפעיל את הפונקציה similarity_search שלה.

def search(query: str):
    """Executes Firestore Vector Similarity Search"""
    embedding = VertexAIEmbeddings(
        model_name=settings.embedding_model_name,
        project=settings.project_id,
        location=settings.location,
    )

    client = firestore.Client(project=settings.project_id, database=settings.database)

    vector_store = FirestoreVectorStore(
        client=client, collection=settings.collection, embedding_service=embedding
    )

    logging.info(f"Now executing query: {query}")
    results: list[Document] = vector_store.similarity_search(
        query=query, k=int(settings.top_k), include_metadata=True
    )
    for result in results:
        print(result.page_content)

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

הפקודה gcloud ליצירת האינדקס המשולב מוצגת בהמשך:

gcloud firestore indexes composite create --project=<YOUR_PROJECT_ID> --collection-group=poses --query-scope=COLLECTION --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=embedding

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

gcloud firestore indexes composite list

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

נסו עכשיו את הפקודה הבאה:

python search-data.py --prompt "Recommend me some exercises for back pain relief"

אמורות להופיע כמה המלצות. הנה דוגמה להרצה:

2025-01-21 15:48:51,282 - INFO - Now executing query: Recommend me some exercises for back pain relief
name: Supine Spinal Twist Pose
description: A gentle supine twist (Supta Matsyendrasana), great for beginners.  Releases spinal tension, improves digestion, and calms the nervous system.  Keep shoulders flat on the floor and lengthen the spine.

sanskrit_name: Supta Matsyendrasana
expertise_level: Beginner
pose_type: ['Supine', 'Twist']
name: Cow Pose
description: Cow Pose (Bitilasana) is a gentle backbend, stretching the chest, shoulders, and abdomen.  Maintain a neutral spine, lengthen the tailbone, and avoid hyperextension.  Benefits include improved posture and stress relief.

sanskrit_name: Bitilasana
expertise_level: Beginner
pose_type: ['Arm Leg Support', 'Back Bend']
name: Locust I Pose
description: Locust Pose I (Shalabhasana A) strengthens the back, glutes, and shoulders.  Lie prone, lift chest and legs simultaneously, engaging back muscles.  Keep hips grounded and gaze slightly forward.

sanskrit_name: Shalabhasana A
expertise_level: Intermediate
pose_type: ['Prone', 'Back Bend']

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

8. אפליקציית האינטרנט

אפליקציית האינטרנט של Python Flask זמינה בקובץ main.py וקובץ ה-HTML של הקצה הקדמי נמצא בקובץ templates/index.html.

מומלץ לבדוק את שני הקבצים. מתחילים קודם עם הקובץ main.py שמכיל את הטיפול /search, שמקבל את ההנחיה שהועברה מקובץ ה-HTML index.html של הקצה הקדמי. לאחר מכן, המערכת מפעילה את שיטת החיפוש, שמבצעת את החיפוש לפי דמיון וקטורים שבדקנו בקטע הקודם.

לאחר מכן, התשובה נשלחת חזרה אל index.html עם רשימת ההמלצות. לאחר מכן, ההמלצות יוצגו בכרטיסים שונים בindex.html.

הרצת האפליקציה באופן מקומי

פותחים חלון מסוף חדש (Ctrl+Shift+C) או חלון מסוף קיים ומזינים את הפקודה הבאה:

python main.py

דוגמה להרצה:

 * Serving Flask app 'main'
 * Debug mode: on
2025-01-21 16:02:37,473 - INFO - WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:8080
 * Running on http://10.88.0.4:8080
2025-01-21 16:02:37,473 - INFO - Press CTRL+C to quit
2025-01-21 16:02:37,474 - INFO -  * Restarting with stat
2025-01-21 16:02:41,462 - WARNING -  * Debugger is active!
2025-01-21 16:02:41,484 - INFO -  * Debugger PIN: 440-653-555

אחרי שהאפליקציה מופעלת, אפשר להיכנס לכתובת ה-URL הראשית שלה בלחיצה על הלחצן 'תצוגה מקדימה באינטרנט' שמוצג בהמשך:

אמור להופיע קובץ index.html שמוצג, כפי שמוצג בהמשך:

מזינים שאילתה לדוגמה (לדוגמה : Provide me some exercises for back pain relief) ולוחצים על הלחצן Search. הפעולה הזו אמורה לאחזר כמה המלצות מהמסד הנתונים. יופיע גם הלחצן Play Audio, שיוצר שידור אודיו על סמך התיאור, שאפשר לשמוע ישירות.

9. (אופציונלי) פריסת האפליקציה ב-Google Cloud Run

השלב האחרון יהיה פריסת האפליקציה הזו ב-Google Cloud Run. פקודה לפריסה מופיעה בהמשך. לפני הפריסה, חשוב להחליף את הערכים של המשתנה (<<YOUR_PROJECT_ID>>) בערכים הספציפיים לפרויקט שלכם. אלה ערכים שתוכלו לאחזר מהקובץ config.yaml.

gcloud run deploy yogaposes --source . \
  --port=8080 \
  --allow-unauthenticated \
  --region=us-central1 \
  --platform=managed  \
  --project=<<YOUR_PROJECT_ID>> \
  --env-vars-file=config.yaml

מריצים את הפקודה שלמעלה מהתיקייה ברמה הבסיסית (root) של האפליקציה. יכול להיות שתתבקשו גם להפעיל את ממשקי Google Cloud API, לאשר הרשאות שונות ולספק אישור.

תהליך הפריסה יימשך כ-5 עד 7 דקות, לכן יש להמתין.

בסיום הפריסה, כתובת ה-URL של שירות Cloud Run תופיע בפלט של הפריסה. הפורמט שלו יהיה:

Service URL: https://yogaposes-<<UNIQUEID>.us-central1.run.app

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

אפשר גם להיכנס אל Cloud Run דרך מסוף Google Cloud, ותראו את רשימת השירותים ב-Cloud Run. השירות yogaposes צריך להיות אחד מהשירותים (אם לא היחיד) שמפורטים שם.

כדי להציג את פרטי השירות, כמו כתובת URL, הגדרות, יומנים ועוד, לוחצים על שם השירות הספציפי (במקרה שלנו, yogaposes).

זהו, סיימנו את הפיתוח והפריסה של אפליקציית האינטרנט שלנו להמלצות על תנוחות יוגה ב-Cloud Run.

10. מזל טוב

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

מסמכי עזר

• Firestore
• Firestore – חיפוש באמצעות הטמעת וקטורים
• ניהול אינדקסים ב-Firestore
• Cloud Run
• Langchain Document Loader ל-Firestore
• Langchain Vector Store for Firestore