Codelab - Firestore, 벡터 검색, Langchain, Gemini를 사용하여 문맥 요가 자세 추천 앱 빌드하기 (Python 버전)

1. 소개

이 Codelab에서는 벡터 검색을 사용하여 요가 자세를 추천하는 애플리케이션을 빌드합니다.

이 Codelab에서는 다음과 같이 단계별로 접근합니다.

  1. 요가 자세의 기존 Hugging Face 데이터 세트 (JSON 형식)를 활용합니다.
  2. Gemini를 사용하여 각 포즈에 대한 설명을 생성하는 추가 필드 설명으로 데이터 세트를 개선합니다.
  3. Langchain을 사용하여 문서를 만들고 Firestore Langchain 통합을 사용하여 Firestore에 컬렉션과 임베딩을 만듭니다.
  4. 벡터 검색을 허용하도록 Firestore에 복합 색인을 만듭니다.
  5. 아래와 같이 모든 것을 통합하는 Flask 애플리케이션에서 벡터 검색을 활용합니다.

84e1cbf29cbaeedc.png

실행할 작업

  • 벡터 검색을 사용하여 요가 자세를 추천하는 웹 애플리케이션을 설계, 빌드, 배포합니다.

학습할 내용

  • Gemini를 사용하여 텍스트 콘텐츠를 생성하고 이 Codelab의 맥락에서 요가 자세에 대한 설명을 생성하는 방법
  • Firestore용 Langchain 문서 로더를 사용하여 Hugging Face의 향상된 데이터 세트에서 레코드를 벡터 임베딩과 함께 Firestore로 로드하는 방법
  • Firestore용 Langchain 벡터 저장소를 사용하여 자연어 쿼리를 기반으로 데이터를 검색하는 방법
  • Google Cloud Text to Speech API를 사용하여 오디오 콘텐츠를 생성하는 방법

필요한 항목

  • Chrome 웹브라우저
  • Gmail 계정
  • 결제가 사용 설정된 Cloud 프로젝트

이 Codelab은 초보자를 포함한 모든 수준의 개발자를 위해 설계되었으며 샘플 애플리케이션에서 Python을 사용합니다. 하지만 Python 지식이 없어도 제시된 개념을 이해하는 데는 문제가 없습니다.

2. 시작하기 전에

프로젝트 만들기

  1. Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
  2. Cloud 프로젝트에 결제가 사용 설정되어 있어야 하므로 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요 .
  3. bq가 미리 로드되어 제공되는 Google Cloud에서 실행되는 명령줄 환경인 Cloud Shell을 사용합니다. Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.

Cloud Shell 활성화 버튼 이미지

  1. Cloud Shell에 연결되면 다음 명령어를 사용하여 이미 인증되었는지, 프로젝트가 프로젝트 ID로 설정되어 있는지 확인합니다.
gcloud auth list
  1. Cloud Shell에서 다음 명령어를 실행하여 gcloud 명령어가 프로젝트를 알고 있는지 확인합니다.
gcloud config list project
  1. 프로젝트가 설정되지 않은 경우 다음 명령어를 사용하여 설정합니다.
gcloud config set project <YOUR_PROJECT_ID>
  1. 아래 명령어를 통해 필수 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 명령어 및 사용법은 문서를 참조하세요.

저장소 클론 및 환경 설정 설정

다음 단계는 나머지 Codelab에서 참조할 샘플 저장소를 클론하는 것입니다. Cloud Shell에 있다고 가정하고 홈 디렉터리에서 다음 명령어를 실행합니다.

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

편집기를 실행하려면 Cloud Shell 창의 툴바에서 편집기 열기를 클릭합니다. 왼쪽 상단의 메뉴 바를 클릭하고 아래와 같이 File(파일) → Open Folder(폴더 열기)를 선택합니다.

66221fd0d0e5202f.png

yoga-poses-recommender-python 폴더를 선택하면 아래와 같이 폴더가 열리고 다음 파일이 표시됩니다.

44699efc7fb1b911.png

이제 사용할 환경 변수를 설정해야 합니다. 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"

Google Cloud 프로젝트 및 Firestore 데이터베이스 리전을 만들 때 선택한 대로 project_idlocation의 값을 업데이트합니다. location의 값이 Google Cloud 프로젝트와 Firestore 데이터베이스에서 동일한 것이 좋습니다(예: us-central1).

이 Codelab에서는 사전 구성된 값을 사용합니다. 단, 구성에 따라 설정해야 하는 project_idlocation은 예외입니다.

이 파일을 config.template.yaml 파일과 동일한 폴더에 config.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에서 버전 잠겨 있습니다. . 요약하면 가상 환경에 설치할 requirements.txt의 Python 패키지 종속 항목이 포함된 가상 Python 환경을 만들어야 합니다. 이렇게 하려면 Cloud Shell IDE의 Command Palette (Ctrl+Shift+P)로 이동하여 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는 애플리케이션 데이터의 백엔드로 사용할 완전 관리형 서버리스 문서 데이터베이스입니다. Cloud Firestore의 데이터는 문서컬렉션으로 구성됩니다.

Firestore 데이터베이스 초기화

Cloud 콘솔에서 Firestore 페이지로 이동합니다.

이전에 프로젝트에서 Firestore 데이터베이스를 초기화하지 않은 경우 Create Database 아이콘을 클릭하여 default 데이터베이스를 만듭니다. 데이터베이스를 만들 때 다음 값을 사용합니다.

  • Firestore 모드: Native.
  • 위치: 기본 위치 설정을 사용합니다.
  • 보안 규칙의 경우 Test rules을 선택합니다.
  • 데이터베이스를 만듭니다.

504cabdb99a222a5.png

다음 섹션에서는 기본 Firestore 데이터베이스에 poses라는 이름의 컬렉션을 만들기 위한 기반을 설정합니다. 이 컬렉션에는 샘플 데이터 (문서) 또는 요가 자세 정보가 저장되며, 이 정보는 애플리케이션에서 사용됩니다.

이제 Firestore 데이터베이스 설정 섹션이 완료되었습니다.

4. 요가 자세 데이터 세트 준비

첫 번째 작업은 애플리케이션에 사용할 요가 자세 데이터 세트를 준비하는 것입니다. 기존 Hugging Face 데이터 세트로 시작하여 추가 정보로 개선해 보겠습니다.

요가 자세용 Hugging Face 데이터 세트를 확인하세요. 이 Codelab에서는 데이터 세트 중 하나를 사용하지만, 실제로는 다른 데이터 세트를 사용하고 설명된 것과 동일한 기법을 따라 데이터 세트를 개선할 수 있습니다.

298cfae7f23e4bef.png

Files and versions 섹션으로 이동하면 모든 포즈의 JSON 데이터 파일을 가져올 수 있습니다.

3fe6e55abdc032ec.png

yoga_poses.json 파일을 다운로드하여 제공해 드렸습니다. 이 파일의 이름은 yoga_poses_alldata.json이며 /data 폴더에 있습니다.

Cloud Shell 편집기에서 data/yoga_poses.json 파일로 이동하여 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 편집기에서 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()

이 애플리케이션은 각 요가 자세 JSON 레코드에 새 description 필드를 추가합니다. 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

승인을 요청하는 메시지가 표시되면 승인해 주세요.

애플리케이션이 실행되기 시작합니다. 새 Google Cloud 계정에 있을 수 있는 비율 한도 할당량을 방지하기 위해 레코드 간에 30초의 지연을 추가했으니 기다려 주시기 바랍니다.

진행 중인 샘플 실행은 아래와 같습니다.

8e830d9ea9b6c60.png

Gemini 호출로 세 레코드가 모두 개선되면 data/yoga_poses_with_description.json 파일이 생성됩니다. 확인해 보세요.

이제 데이터 파일이 준비되었으며 다음 단계에서는 임베딩 생성과 함께 Firestore 데이터베이스를 데이터 파일로 채우는 방법을 알아봅니다.

5. Firestore로 데이터 가져오기 및 벡터 임베딩 생성

data/yoga_poses_with_description.json 파일이 있으므로 이제 이 파일로 Firestore 데이터베이스를 채우고 중요한 것은 각 레코드의 벡터 임베딩을 생성해야 합니다. 벡터 임베딩은 나중에 자연어로 제공된 사용자 쿼리로 유사성 검색을 수행해야 할 때 유용합니다.

Langchain Firestore 구성요소를 사용하여 위 프로세스를 구현합니다.

단계는 다음과 같습니다.

  1. JSON 객체 목록을 Langchain 문서 객체 목록으로 변환합니다. 각 문서에는 page_contentmetadata라는 두 가지 속성이 있습니다. 메타데이터 객체에는 name, description, sanskrit_name 등의 속성이 있는 전체 JSON 객체가 포함됩니다. page_content는 몇 개의 필드를 연결한 문자열 텍스트입니다.
  2. Document 객체 목록이 있으면 FirestoreVectorStore Langchain 클래스와 특히 이 문서 목록, 컬렉션 이름 (test-poses을 가리키는 TEST_COLLECTION 변수를 사용함), Vertex AI 임베딩 클래스, Firestore 연결 세부정보 (PROJECT_IDDATABASE 이름)와 함께 from_documents 메서드를 사용합니다. 이렇게 하면 컬렉션이 생성되고 각 속성에 대한 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.

레코드가 성공적으로 삽입되고 임베딩이 생성되었는지 확인하려면 Cloud 콘솔의 Firestore 페이지로 이동하세요.

504cabdb99a222a5.png

(기본) 데이터베이스를 클릭하면 test-poses 컬렉션과 해당 컬렉션 아래의 여러 문서가 표시됩니다. 각 문서는 하나의 요가 자세입니다.

d0708499e403aebc.png

문서를 클릭하여 필드를 조사합니다. 가져온 필드 외에도 embedding 필드가 있습니다. 이 필드는 text-embedding-004 Vertex AI 임베딩 모델을 제공한 Langchain VertexAIEmbeddings 클래스를 통해 자동으로 생성된 벡터 필드입니다.

d67113e2dc63cd6b.png

이제 레코드가 임베딩과 함께 Firestore 데이터베이스에 업로드되었으므로 다음 단계로 이동하여 Firestore에서 벡터 유사성 검색을 실행하는 방법을 살펴보겠습니다.

6. 전체 요가 자세를 Firestore 데이터베이스 컬렉션으로 가져오기

이제 160개의 요가 자세의 전체 목록인 poses 컬렉션을 만들겠습니다. 이 컬렉션에는 직접 가져올 수 있는 데이터베이스 가져오기 파일이 생성되어 있습니다. 이는 실습에서 시간을 절약하기 위한 조치입니다. 설명과 임베딩이 포함된 데이터베이스를 생성하는 프로세스는 이전 섹션에서 본 것과 동일합니다.

아래 단계에 따라 데이터베이스를 가져옵니다.

  1. 아래에 나온 gsutil 명령어를 사용하여 프로젝트에 버킷을 만듭니다. 아래 명령어에서 <PROJECT_ID> 변수를 Google Cloud 프로젝트 ID로 바꿉니다.
gsutil mb -l us-central1 gs://<PROJECT_ID>-my-bucket
  1. 이제 버킷이 생성되었으므로 준비한 데이터베이스 내보내기를 이 버킷에 복사한 후 Firebase 데이터베이스로 가져와야 합니다. 아래에 나온 명령어를 사용하세요.
gsutil cp -r gs://yoga-database-firestore-export-bucket/2025-01-27T05:11:02_62615  gs://<PROJECT_ID>-my-bucket

가져올 데이터가 있으므로 이제 만든 Firebase 데이터베이스 (default)로 데이터를 가져오는 마지막 단계로 이동할 수 있습니다.

  1. 아래에 나온 gcloud 명령어를 사용합니다.
gcloud firestore import gs://<PROJECT_ID>-my-bucket/2025-01-27T05:11:02_62615

가져오기에 몇 초가 소요되며 준비가 완료되면 https://console.cloud.google.com/firestore/databases로 이동하여 아래와 같이 default 데이터베이스와 poses 컬렉션을 선택하여 Firestore 데이터베이스와 컬렉션을 확인할 수 있습니다.

a8f5a6ba69bec69b.png

이제 애플리케이션에서 사용할 Firestore 컬렉션 만들기가 완료되었습니다.

7. Firestore에서 벡터 유사성 검색 수행

벡터 유사성 검색을 실행하려면 사용자의 쿼리를 가져옵니다. 이 쿼리의 예는 "Suggest me some exercises to relieve back pain"일 수 있습니다.

search-data.py 파일을 살펴봅니다. 살펴볼 주요 함수는 아래에 표시된 검색 함수입니다. 대략적으로 사용자 쿼리의 임베딩을 생성하는 데 사용되는 임베딩 클래스를 만듭니다. 그런 다음 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.에 있습니다.

두 파일을 모두 살펴보는 것이 좋습니다. 먼저 프런트엔드 HTML index.html 파일에서 전달된 프롬프트를 사용하는 /search 핸들러가 포함된 main.py 파일로 시작합니다. 그러면 이전 섹션에서 살펴본 벡터 유사성 검색을 실행하는 검색 메서드가 호출됩니다.

그러면 응답이 맞춤 콘텐츠 목록과 함께 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을 방문합니다.

de297d4cee10e0bf.png

아래와 같이 제공된 index.html 파일이 표시됩니다.

20240a0e885ac17b.png

샘플 쿼리 (예 : Provide me some exercises for back pain relief)를 입력하고 Search 버튼을 클릭합니다. 그러면 데이터베이스에서 일부 추천이 검색됩니다. 설명을 기반으로 오디오 스트림을 생성하여 직접 들을 수 있는 Play Audio 버튼도 표시됩니다.

789b4277dc40e2be.png

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

애플리케이션의 루트 폴더에서 위 명령어를 실행합니다. Google Cloud API를 사용 설정하라는 메시지가 표시될 수도 있습니다. 다양한 권한에 대한 확인을 제공하세요.

배포 프로세스를 완료하는 데 약 5~7분이 소요되므로 기다려 주세요.

3a6d86fd32e4a5e.png

배포가 완료되면 배포 출력에 Cloud Run 서비스 URL이 표시됩니다. 형식은 다음과 같습니다.

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

이 공개 URL을 방문하면 동일한 웹 애플리케이션이 배포되고 실행되는 것을 볼 수 있습니다.

84e1cbf29cbaeedc.png

Google Cloud 콘솔에서 Cloud Run으로 이동하면 Cloud Run의 서비스 목록이 표시됩니다. yogaposes 서비스가 여기에 나열된 서비스 중 하나여야 합니다 (유일한 서비스가 아닐 수도 있음).

f2b34a8c9011be4c.png

특정 서비스 이름 (이 경우 yogaposes)을 클릭하면 URL, 구성, 로그 등 서비스의 세부정보를 볼 수 있습니다.

faaa5e0c02fe0423.png

이제 Cloud Run에서 요가 자세 추천 웹 애플리케이션을 개발하고 배포했습니다.

10. 축하합니다

축하합니다. 데이터 세트를 Firestore에 업로드하고, 임베딩을 생성하고, 사용자 쿼리를 기반으로 벡터 유사성 검색을 실행하는 애플리케이션을 빌드했습니다.

참조 문서