التعرُّف على كيفية إنشاء تطبيق LangChain ونشره على Cloud Run

1. نظرة عامة

في هذا الدرس العملي، ستتعرّف على كيفية نشر تطبيق 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
    • poetry لإدارة التبعيات
    • pipx لتثبيت وتشغيل واجهة سطر الأوامر (CLI) الخاصة بـ LangChain وpoetry في بيئات افتراضية معزولة

إليك مدونة تساعدك في تثبيت الأدوات المطلوبة لهذا الشرح.

محطات العمل في السحابة الإلكترونية

بدلاً من جهازك المحلّي، يمكنك أيضًا استخدام Cloud Workstations على Google Cloud. يُرجى العِلم أنّه اعتبارًا من أبريل 2024، يتم تشغيل إصدار Python الأقل من 3.11، لذا قد تحتاج إلى ترقية Python قبل البدء.

تفعيل واجهات برمجة التطبيقات على السحابة الإلكترونية

أولاً، شغِّل الأمر التالي للتأكّد من ضبط مشروع على السحابة الإلكترونية الصحيح لاستخدامه:

gcloud config list project

إذا لم يظهر المشروع الصحيح، يمكنك ضبطه باستخدام الأمر التالي:

gcloud config set project <PROJECT_ID>

فعِّل الآن واجهات برمجة التطبيقات التالية:

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 في العديد من المواقع الجغرافية حول العالم، وعليك اختيار أحدها لنشر الموارد التي ستستخدمها في هذا المختبر. اضبط المنطقة كمتغيّر بيئة في shell (تستخدم الأوامر اللاحقة هذا المتغيّر):

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 وتخطَّ تثبيت الحِزم بالضغط على مفتاح الإدخال:

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
  • شغِّل الأمر docker build.
  • ادفع صورة الحاوية الناتجة إلى Artifact Registry.
  • أنشئ خدمة Cloud Run باستخدام صورة الحاوية.

عند اكتمال الأمر، سيتم عرض عنوان URL يستخدم HTTPS على النطاق run.app. هذا هو عنوان URL العلني لخدمة Cloud Run الجديدة

8. استكشاف ساحة الألعاب

افتح عنوان URL الخاص بخدمة Cloud Run وانتقِل إلى /playground. سيظهر حقل نص. يمكنك استخدامه لطرح أسئلة حول ملاحظات إصدار Cloud Run، كما هو موضّح هنا:

9- تهانينا

لقد أنشأت تطبيق LangChain ونشرته بنجاح على Cloud Run. أحسنت!

في ما يلي المفاهيم الأساسية:

  • استخدام إطار عمل LangChain لإنشاء تطبيق "التوليد المعزّز بالاسترجاع" (RAG)
  • استخدام PostgreSQL على Cloud SQL كقاعدة بيانات متجهة مع pgvector، والتي يتم تثبيتها تلقائيًا على Cloud SQL
  • تشغيل مهمة فهرسة أطول مدة كإحدى مهام Cloud Run وتشغيل تطبيق ويب كإحدى خدمات Cloud Run
  • يمكنك تضمين سلسلة LangChain في تطبيق FastAPI باستخدام LangServe، ما يوفّر واجهة ملائمة للتفاعل مع تطبيق RAG.

تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud Platform مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، اتّبِع الخطوات التالية:

  • في Cloud Console، انتقِل إلى صفحة "إدارة الموارد".
  • في قائمة المشاريع، اختَر مشروعك ثم انقر على "حذف".
  • في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على "إيقاف" لحذف المشروع.

إذا كنت تريد الاحتفاظ بالمشروع، احرص على حذف الموارد التالية:

  • مثيل Cloud SQL
  • خدمة Cloud Run
  • مهمة Cloud Run