نشر LangChain Agent على Cloud Run

1. نظرة عامة

الوكيل هو برنامج مستقل يتواصل مع نموذج ذكاء اصطناعي لتنفيذ عملية مستندة إلى هدف باستخدام الأدوات والسياق المتاحين له، وهو قادر على اتّخاذ قرارات مستقلة مستندة إلى الحقائق.

تُستخدَم أُطر عمل الوكلاء، مثل Agent Development Kit(ADK) وLangChain وsmolagents، لإنشاء الوكلاء. يمكن تفعيل تطبيقات الوكيل التي يتم إنشاؤها من خلال أُطر العمل هذه على Cloud Run، ويمكن إتاحتها للمستخدمين كتطبيقات بدون خادم.

في هذا الدرس التطبيقي حول الترميز، سننشئ وكيلاً باستخدام LangChain وننشره على Cloud Run.

ما ستنشئه

هل أنت مستعد للانتقال من النموذج الأوّلي PROMPT إلى إنشاء وكيل؟ سننشئ وكيلاً باستخدام LangChain للحصول على معلومات حول شخصية تاريخية بتنسيق منظَّم. في هذا الدرس التطبيقي، ستنفّذ ما يلي:

  1. إنشاء وكيل بسيط لإنشاء معلومات حول الشخصية التاريخية بتنسيق منظَّم باستخدام LangChain
  2. تشغيل الوكيل محليًا والتأكّد من أنّه يعمل على النحو المتوقّع
  3. نشر الوكيل على Cloud Run واستدعاؤه باستخدام عنوان URL الخاص بـ Cloud Run

المتطلبات

  • متصفّح، مثل Chrome أو Firefox
  • مشروع Google Cloud تم تفعيل الفوترة فيه

2. قبل البدء

إنشاء مشروع

  1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر أو أنشِئ مشروعًا على Google Cloud.
  2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع
  3. فعِّل Cloud Shell من خلال النقر على هذا الرابط. يمكنك التبديل بين Cloud Shell Terminal (لتنفيذ أوامر السحابة الإلكترونية) و"المحرّر" (لإنشاء المشاريع) من خلال النقر على الزر المناسب من Cloud Shell.
  4. بعد الاتصال بـ Cloud Shell، يمكنك التأكّد من أنّك قد أثبتّ هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:
gcloud auth list
  1. نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك.
gcloud config list project
  1. إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:
gcloud config set project <YOUR_PROJECT_ID>
  1. تأكَّد من توفُّر الإصدار 3.13 أو الإصدارات الأحدث من Python

يُرجى الرجوع إلى المستندات للاطّلاع على أوامر gcloud الأخرى وطريقة استخدامها.

3- إنشاء وكيل LangChain

بنية المشروع

في Cloud Shell، أنشئ مجلدًا باسم langchain-app، وأضِف الملفات التالية إليه:

langchain-gemini-fastapi-app/
├── main.py
├── requirements.txt

رمز التطبيق

في ما يلي الاعتمادات التي يجب إضافتها في requirements.txt:

fastapi
uvicorn
langchain
langchain-google-genai
python-dotenv

في main.py، سنكتب رمز البرنامج الذي يستخدم نموذج Gemini ويسترد المعلومات حول الشخصية التاريخية. بعد استرداد البيانات، يتم تنسيقها في شكل مهيكل حسب التوجيهات.

تستخدم هذه الطريقة بنية LCEL (لغة التعبير في LangChain) الحديثة.

import os
import uvicorn
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from langchain_google_genai import ChatGoogleGenerativeAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import JsonOutputParser

# Initialize FastAPI
app = FastAPI(title="LangChain App for Historical Figures")

# 1. Setup Gemini Model
# We expect GOOGLE_API_KEY to be set in the environment variables
llm = ChatGoogleGenerativeAI(
    model="gemini-2.5-flash",
    temperature=0.7
)

# 2. Define the Prompt
prompt = ChatPromptTemplate.from_template("You are an expert Historian. For the historical personality {name}, you are able to accurately tell their birth date and birth country. Return the output in the JSON format containing name, birthDate, birthCountry. In case you are unable to retrieve birthDate or birthCountry, just have the unknown values as null. ensure the response is a valid json object only.")
output_parser = JsonOutputParser()

# Chain: Prompt -> Model -> Json Output Parser
chain = prompt | llm | output_parser

# 3. Define Request Model
class QueryRequest(BaseModel):
    name: str

# 4. Define Endpoint
@app.post("/chat")
async def chat(request: QueryRequest):
    try:
        response = await chain.ainvoke({"name": request.name})
        return response
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.get("/")
def health_check():
    return {"status": "ok", "service": "LangChain-Gemini-FastAPI"}

4. اختبار الوكيل

قبل نشر التطبيق، يمكنك اختباره محليًا.

  1. أنشئ مفتاح Gemini API في AI Studio.
  2. صدِّر مفتاح Gemini API على النحو التالي:
export GOOGLE_API_KEY="AIzaSy..."
  1. شغِّل الخادم.
uvicorn main:app --port 8080 --host 0.0.0.0
  1. اختبِر الوكيل باستخدام الأمر curl التالي:
curl -X POST http://localhost:8080/chat \
     -H "Content-Type: application/json" \
     -d '{"name": "Abraham Lincoln"}'

تأكَّد من الحصول على ناتج منظَّم بتنسيق JSON يتضمّن الاسم وتاريخ الميلاد وبلد الميلاد.

5- النشر على Cloud Run

سنستخدم الأمر gcloud run deploy لنشر تطبيق الوكيل على Cloud Run. ينشئ الأمر التالي الحاوية باستخدام Cloud Build وينشرها على Cloud Run في خطوة واحدة.

استبدِل YOUR_API_KEY بمفتاح Gemini API الفعلي.

gcloud run deploy gemini-fastapi-service \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_API_KEY=<YOUR_API_KEY>

بعد نشرها، من المفترض أن ترى نقطة النهاية في الوحدة الطرفية التي ستكون جاهزة للاستخدام.

6. اختبار عملية النشر

استخدِم نقطة نهاية Cloud Run، ونفِّذ curl للتأكّد من الحصول على النتائج المتوقّعة.

curl -X POST <CLOUD_RUN_ENDPOINT> \
     -H "Content-Type: application/json" \
     -d '{"name": "Abraham Lincoln"}'

يجب أن تحصل على النتيجة نفسها التي حصلت عليها في التطبيق الذي يتم تشغيله محليًا.

7. تَنظيم

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

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

8. تهانينا

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