با نحوه ساخت و استقرار یک برنامه LangChain در Cloud Run آشنا شوید

1. بررسی اجمالی

در این آزمایشگاه کد، نحوه استقرار یک برنامه LangChain را یاد می گیرید که از Gemini استفاده می کند تا به شما اجازه دهد از طریق یادداشت های انتشار Cloud Run سؤال بپرسید.

در اینجا مثالی از نحوه کار این برنامه آورده شده است: اگر این سوال را بپرسید "آیا می توانم یک سطل فضای ذخیره سازی ابری را به عنوان حجم در 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
• همچنین باید نرم افزار زیر را نصب کرده باشید:
  • پایتون (نسخه 3.11 یا بالاتر مورد نیاز است)
  • LangChain CLI
  • شعر برای مدیریت وابستگی
  • pipx برای نصب و اجرای LangChain CLI و شعر در محیط های مجازی ایزوله

در اینجا وبلاگی وجود دارد که به شما کمک می کند تا با نصب ابزارهای مورد نیاز برای این راهنما شروع کنید.

ایستگاه های کاری ابری

به جای دستگاه محلی خود، می توانید از ایستگاه های کاری ابری در Google Cloud نیز استفاده کنید. توجه داشته باشید که از آوریل 2024 نسخه پایتون پایین‌تر از 3.11 را اجرا می‌کند، بنابراین ممکن است قبل از شروع نیاز به ارتقای پایتون داشته باشید.

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. نمونه پایگاه داده برداری را ایجاد کنید

بخش کلیدی این برنامه بازیابی یادداشت‌های انتشار مربوط به سؤال کاربر است. برای واضح‌تر کردن این موضوع، اگر سؤالی در مورد فضای ذخیره‌سازی ابری می‌پرسید، می‌خواهید یادداشت انتشار زیر به درخواست اضافه شود:

19 ژانویه 2024: اکنون می توانید یک سطل Cloud Storage را به عنوان حجم ذخیره سازی برای خدمات و همچنین برای کارهای Cloud Run نصب کنید.

می‌توانید از جاسازی‌های متنی و یک پایگاه داده برداری برای یافتن یادداشت‌های انتشار مشابه معنایی استفاده کنید.

من به شما نشان خواهم داد که چگونه از 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 را نصب کرده باشید و برای مدیریت وابستگی ها شعر داشته باشید. در اینجا نحوه نصب آنها با استفاده از pipx آورده شده است:

pipx install langchain-cli poetry

برنامه LangChain را با دستور زیر داربست بزنید. وقتی از شما پرسیده شد، پوشه run-rag را نام ببرید و با فشردن اینتر از نصب بسته ها صرفنظر کنید:

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"

توجه: من در اینجا از یک رمز عبور آسان برای حدس زدن استفاده می‌کنم تا بتوان دستورالعمل‌ها را راحت‌تر دنبال کرد. در خارج از آزمایشگاه، اکیداً توصیه می شود که یک رمز عبور تصادفی ایجاد کنید، رمز عبور را در Secret Manager ذخیره کنید، و رمز را به عنوان یک متغیر محیطی (یا نصب شده به عنوان یک فایل) در برنامه خود قرار دهید.

کار نمایه سازی را مستقر کرده و اجرا کنید

اکنون کار را مستقر کرده و اجرا کنید:

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 : دستوری را برای اجرا در داخل کانتینر تنظیم می کند. در این مورد، اجرای پایتون است.
• --args app/indexer.py : آرگومان های دستور پایتون را ارائه می دهد. این به آن می گوید که اسکریپت indexer.py را در فهرست برنامه اجرا کند.
• --set-env-vars : متغیرهای محیطی را تنظیم می کند که اسکریپت پایتون می تواند در حین اجرا به آنها دسترسی داشته باشد.
• --region=$REGION : منطقه ای را که کار باید در آن مستقر شود را مشخص می کند.
• --execute-now : به Cloud Run می گوید که کار را بلافاصله پس از استقرار شروع کند.

برای تأیید اینکه کار با موفقیت انجام شده است، می توانید موارد زیر را انجام دهید:

• گزارش های مربوط به اجرای کار را از طریق کنسول وب بخوانید. باید «Done Saving: xxx release notes» را گزارش کند (که در آن 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 آپلود کنید
• Docker build را اجرا کنید.
• تصویر کانتینر حاصل را به Artifact Registry فشار دهید.
• با استفاده از تصویر ظرف، یک سرویس Cloud Run ایجاد کنید.

وقتی فرمان کامل شد، یک URL HTTPS در دامنه run.app فهرست می‌کند. این نشانی اینترنتی عمومی سرویس جدید Cloud Run شما است

8. زمین بازی را کاوش کنید

URL سرویس Cloud Run را باز کنید و به /playground بروید. یک فیلد متنی ظاهر می شود. از آن برای پرسیدن سؤالات روی یادداشت‌های انتشار Cloud Run استفاده کنید، مانند اینجا:

9. تبریک می گویم

شما با موفقیت یک برنامه LangChain را در Cloud Run ساخته و اجرا کرده اید. آفرین!

در اینجا مفاهیم کلیدی وجود دارد:

• استفاده از چارچوب LangChain برای ساختن یک برنامه Retrieval Augmented Generation (RAG).
• استفاده از PostgreSQL در Cloud SQL به عنوان یک پایگاه داده برداری با pgvector که به طور پیش فرض روی Cloud SQL نصب می شود.
• یک کار نمایه سازی طولانی تر را به عنوان کارهای Cloud Run و یک برنامه وب را به عنوان سرویس Cloud Run اجرا کنید.
• یک زنجیره LangChain را در یک برنامه FastAPI با LangServe بپیچید، و یک رابط کاربری راحت برای تعامل با برنامه RAG شما فراهم می کند.

پاک کن

برای جلوگیری از تحمیل هزینه به حساب Google Cloud Platform برای منابع استفاده شده در این آموزش:

• در Cloud Console، به صفحه مدیریت منابع بروید.
• در لیست پروژه، پروژه خود را انتخاب کنید و سپس روی Delete کلیک کنید.
• در گفتگو، ID پروژه را تایپ کنید و سپس بر روی Shut down کلیک کنید تا پروژه حذف شود.

اگر می خواهید پروژه را حفظ کنید، حتما منابع زیر را حذف کنید:

• نمونه ابر SQL
• سرویس Cloud Run
• کار Cloud Run