Triển khai LangChain Agent trên Cloud Run

1. Tổng quan

Tác nhân là một chương trình tự động trò chuyện với một mô hình AI để thực hiện một thao tác dựa trên mục tiêu bằng cách sử dụng các công cụ và bối cảnh mà tác nhân có, đồng thời có khả năng đưa ra quyết định tự động dựa trên sự thật!

Các khung tác nhân như Bộ phát triển tác nhân(ADK), LangChain, smolagents được dùng để tạo tác nhân. Các ứng dụng đại lý được tạo thông qua những khung này có thể được triển khai trên Cloud Run và có thể được cung cấp cho người dùng dưới dạng các ứng dụng không máy chủ.

Trong lớp học lập trình này, chúng ta sẽ tạo một tác nhân bằng LangChain và triển khai tác nhân đó vào Cloud Run.

Sản phẩm bạn sẽ tạo ra

Bạn đã sẵn sàng chuyển từ nguyên mẫu PROMPT sang Xây dựng một tác nhân chưa? Chúng ta sẽ tạo một tác nhân bằng LangChain để lấy thông tin về nhân vật lịch sử ở định dạng có cấu trúc. Trong phòng thí nghiệm này, bạn sẽ:

1. Xây dựng một tác nhân đơn giản để tạo thông tin về nhân vật lịch sử theo định dạng có cấu trúc bằng LangChain
2. Chạy tác nhân trên thiết bị và đảm bảo tác nhân hoạt động như mong đợi
3. Triển khai tác nhân hỗ trợ cho Cloud Run và gọi tác nhân đó bằng URL Cloud Run

Yêu cầu

• Một trình duyệt, chẳng hạn như Chrome hoặc Firefox
• Một dự án trên Google Cloud đã bật tính năng thanh toán.

2. Trước khi bắt đầu

Tạo dự án

1. Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
2. Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên đám mây. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trong một dự án hay không.
3. Kích hoạt Cloud Shell bằng cách nhấp vào đường liên kết này. Bạn có thể chuyển đổi giữa Cloud Shell Terminal (để chạy các lệnh trên đám mây) và Trình chỉnh sửa (để tạo dự án) bằng cách nhấp vào nút tương ứng trong Cloud Shell.
4. Sau khi kết nối với Cloud Shell, bạn có thể kiểm tra để đảm bảo rằng bạn đã được xác thực và dự án được đặt thành mã dự án của bạn bằng lệnh sau:

gcloud auth list

5. Chạy lệnh sau trong Cloud Shell để xác nhận rằng lệnh gcloud biết về dự án của bạn.

gcloud config list project

6. Nếu bạn chưa đặt dự án, hãy dùng lệnh sau để đặt:

gcloud config set project <YOUR_PROJECT_ID>

7. Đảm bảo bạn có Python 3.13 trở lên

Tham khảo tài liệu để biết các lệnh và cách sử dụng gcloud khác.

3. Tạo tác nhân LangChain

Cấu trúc dự án

Trong Cloud Shell, hãy tạo một thư mục có tên là langchain-app rồi thêm các tệp sau vào thư mục đó:

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

Mã ứng dụng

Sau đây là các phần phụ thuộc mà bạn nên thêm vào requirements.txt:

fastapi
uvicorn
langchain
langchain-google-genai
python-dotenv

Trong main.py, chúng ta sẽ viết mã tác nhân sử dụng mô hình Gemini và truy xuất thông tin về nhân vật lịch sử. Sau khi truy xuất, hãy định dạng dữ liệu đó thành một định dạng có cấu trúc theo chỉ dẫn.

Cách triển khai này sử dụng cú pháp LCEL (Ngôn ngữ biểu thức LangChain) hiện đại.

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. Kiểm thử Nhân viên hỗ trợ

Bạn có thể kiểm thử cục bộ trước khi triển khai.

1. Tạo khoá Gemini API trong AI Studio.
2. Xuất khoá Gemini API dưới dạng:

export GOOGLE_API_KEY="AIzaSy..."

3. Chạy máy chủ.

uvicorn main:app --port 8080 --host 0.0.0.0

4. Kiểm thử tác nhân bằng lệnh curl sau:

curl -X POST http://localhost:8080/chat \
     -H "Content-Type: application/json" \
     -d '{"name": "Abraham Lincoln"}'

Kiểm tra để đảm bảo bạn nhận được đầu ra có cấu trúc JSON chứa tên, ngày sinh và quốc gia sinh.

5. Triển khai lên Cloud Run

Chúng ta sẽ dùng lệnh gcloud run deploy để triển khai ứng dụng tác nhân lên Cloud Run. Lệnh sau đây sẽ tạo vùng chứa bằng Cloud Build và triển khai vùng chứa đó vào Cloud Run trong một bước.

Thay thế YOUR_API_KEY bằng khoá Gemini API thực tế của bạn.

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

Lưu ý: Đối với bản phát hành công khai, bạn nên sử dụng Google Secret Manager để xử lý khoá API thay vì các biến môi trường thuần tuý.

Sau khi triển khai, bạn sẽ thấy điểm cuối trong thiết bị đầu cuối và có thể sử dụng điểm cuối đó.

6. Kiểm thử quá trình triển khai

Sử dụng điểm cuối Cloud Run và thực hiện curl để đảm bảo bạn nhận được kết quả như mong đợi.

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

Bạn sẽ nhận được kết quả tương tự như khi chạy ứng dụng cục bộ.

7. Dọn dẹp

Để tránh phát sinh phí cho tài khoản Google Cloud của bạn đối với các tài nguyên được dùng trong lớp học lập trình này, hãy làm theo các bước sau:

1. Trong bảng điều khiển Google Cloud, hãy chuyển đến trang Quản lý tài nguyên.
2. Trong danh sách dự án, hãy chọn dự án mà bạn muốn xoá, rồi nhấp vào Xoá.
3. Trong hộp thoại, hãy nhập mã dự án rồi nhấp vào Tắt để xoá dự án.

8. Xin chúc mừng

Xin chúc mừng! Bạn đã tạo và tương tác thành công với tác nhân LangChain được triển khai trên Cloud Run!