۱. مرور کلی
یک عامل ، یک برنامهی خودکار است که با یک مدل هوش مصنوعی صحبت میکند تا با استفاده از ابزارها و زمینهای که در اختیار دارد، عملیاتی مبتنی بر هدف را انجام دهد و قادر به تصمیمگیری خودکار مبتنی بر حقیقت است!
چارچوبهای عامل مانند کیت توسعه عامل (ADK)، LangChain و smolagents برای ایجاد عاملها استفاده میشوند. برنامههای عامل ایجاد شده از طریق چنین چارچوبهایی میتوانند روی Cloud Run مستقر شوند و به عنوان برنامههای بدون سرور در دسترس کاربران قرار گیرند.
در این آزمایشگاه کد، ما با استفاده از LangChain یک عامل (agent) خواهیم ساخت و آن را در Cloud Run مستقر خواهیم کرد.
آنچه خواهید ساخت
آمادهاید تا از نمونه اولیه PROMPT به ساخت یک عامل (agent) بروید؟؟؟ ما با استفاده از LangChain یک عامل ایجاد خواهیم کرد تا اطلاعات مربوط به چهرههای تاریخی را در قالبی ساختاریافته دریافت کند. به عنوان بخشی از این آزمایش، شما:
- ساخت یک عامل ساده برای تولید اطلاعات در مورد چهره تاریخی در قالبی ساختارمند با استفاده از LangChain
- عامل را به صورت محلی اجرا کنید و مطمئن شوید که طبق انتظار کار میکند
- عامل را در Cloud Run مستقر کنید و با استفاده از Cloud Run URL آن را فراخوانی کنید.
الزامات
۲. قبل از شروع
ایجاد یک پروژه
- در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
- مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .
- با کلیک روی این لینک، Cloud Shell را فعال کنید. میتوانید با کلیک روی دکمه مربوطه از Cloud Shell، بین Cloud Shell Terminal (برای اجرای دستورات ابری) و Editor (برای ساخت پروژهها) جابجا شوید.
- پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی میکنید که آیا از قبل احراز هویت شدهاید و پروژه روی شناسه پروژه شما تنظیم شده است یا خیر:
gcloud auth list
- دستور زیر را در Cloud Shell اجرا کنید تا تأیید شود که دستور gcloud از پروژه شما اطلاع دارد.
gcloud config list project
- اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:
gcloud config set project <YOUR_PROJECT_ID>
- حتماً پایتون ۳.۱۳+ داشته باشید
برای سایر دستورات و کاربردهای gcloud به مستندات مراجعه کنید.
۳. ایجاد عامل 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"}
۴. عامل را آزمایش کنید
قبل از استقرار، میتوانید آن را به صورت محلی آزمایش کنید.
- یک کلید API برای Gemini در AI Studio ایجاد کنید.
- کلید API جمینی را به صورت زیر صادر کنید:
export GOOGLE_API_KEY="AIzaSy..."
- سرور را اجرا کنید.
uvicorn main:app --port 8080 --host 0.0.0.0
- با استفاده از دستور
curlزیر، عامل را آزمایش کنید:
curl -X POST http://localhost:8080/chat \
-H "Content-Type: application/json" \
-d '{"name": "Abraham Lincoln"}'
بررسی کنید که آیا خروجی با ساختار JSON شامل نام، تاریخ تولد و کشور تولد دریافت میکنید یا خیر.
۵. استقرار در Cloud Run
ما از دستور gcloud run deploy برای استقرار برنامه عامل در Cloud Run استفاده خواهیم کرد. دستور زیر کانتینر را با استفاده از Cloud Build میسازد و آن را در یک مرحله در Cloud Run مستقر میکند.
YOUR_API_KEY را با کلید API واقعی Gemini خود جایگزین کنید.
gcloud run deploy gemini-fastapi-service \
--source . \
--platform managed \
--region us-central1 \
--allow-unauthenticated \
--set-env-vars GOOGLE_API_KEY=<YOUR_API_KEY>
پس از استقرار، باید نقطه پایانی خود را در ترمینال ببینید که برای استفاده شما آماده است.
۶. تست استقرار
از نقطه پایانی Cloud Run استفاده کنید و curl را انجام دهید تا مطمئن شوید که به نتایج مورد انتظار میرسید.
curl -X POST <CLOUD_RUN_ENDPOINT> \
-H "Content-Type: application/json" \
-d '{"name": "Abraham Lincoln"}'
شما باید همان نتیجهای را که در برنامهی محلیِ در حال اجرا گرفته بودید، دریافت کنید.
۷. تمیز کردن
برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع استفاده شده در این آزمایشگاه کد، این مراحل را دنبال کنید:
- در کنسول گوگل کلود، به صفحه مدیریت منابع بروید.
- در لیست پروژهها، پروژهای را که میخواهید حذف کنید انتخاب کنید و سپس روی «حذف» کلیک کنید.
- در کادر محاورهای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن کلیک کنید.
۸. تبریک
تبریک! شما با موفقیت عامل LangChain خود را که در Cloud Run مستقر شده بود، ایجاد و با آن تعامل کردید!