Bài viết này hướng dẫn cách sử dụng LangServe để đóng gói ứng dụng LangChain thành một dịch vụ REST API, bao gồm thiết lập môi trường, viết mã, kiểm thử và triển khai sản xuất.

Giới thiệu về LangServe

LangServe là một thành phần trong hệ sinh thái LangChain, cho phép chuyển đổi các đối tượng Runnable (như chain, agent...) thành API REST nhanh chóng. Nó được xây dựng trên nền tảng FastAPI, hỗ trợ xử lý bất đồng bộ, hiệu năng cao và cung cấp giao diện Playground để thử nghiệm trực tiếp. Các tính năng chính gồm:

• Xuất logic LangChain thành endpoint API.
• Hỗ trợ các phương thức gọi: invoke, batch, stream.
• Tự động tạo giao diện web tương tác.
• Tích hợp liền mạch với hệ sinh thái LangChain.

Chuẩn bị môi trường

Cài đặt thư viện

Yêu cầu Python 3.8 trở lên. Cài đặt các gói cần thiết:

pip install langserve fastapi uvicorn langchain langchain-openai

• langserve: thư viện cốt lõi.
• fastapi: framework web hiệu suất cao.
• uvicorn: máy chủ ASGI chạy FastAPI.
• langchain: thư viện chính của LangChain.
• langchain-openai: tích hợp OpenAI LLM (có thể thay bằng nhà cung cấp khác).

Thiết lập khóa API

Với OpenAI, bạn có thể cấu hình qua biến môi trường:

export OPENAI_API_KEY="your-api-key"

Hoặc trong mã nguồn:

import os
os.environ["OPENAI_API_KEY"] = "your-api-key"

Kiểm tra cài đặt

python -c "import langserve, fastapi, uvicorn, langchain; print('OK')"

Quy trình triển khai cơ bản

1. Tạo đối tượng Runnable từ LangChain (chain, agent...).
2. Khởi tạo ứng dụng FastAPI.
3. Đăng ký Runnable làm route API bằng hàm add_routes.
4. Chạy server FastAPI.
5. Kiểm thử qua HTTP hoặc giao diện Playground.

Ví dụ: Triển khai API dịch thuật

Tạo file main.py:

from fastapi import FastAPI
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langserve import add_routes

# Tạo chain dịch thuật
translator_prompt = ChatPromptTemplate.from_template("Dịch sang tiếng Anh: {text}")
llm = ChatOpenAI(model="gpt-3.5-turbo")
translation_chain = translator_prompt | llm

# Khởi tạo ứng dụng FastAPI
service = FastAPI(
    title="Dịch thuật API",
    version="1.0",
    description="Dịch văn bản tiếng Trung sang tiếng Anh"
)

# Đăng ký route
add_routes(service, translation_chain, path="/translate")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(service, host="0.0.0.0", port=8000)

Chạy và kiểm thử

Khởi động server:

python main.py

Truy cập Playground tại: http://localhost:8000/translate/playground/

Gọi API bằng curl:

curl -X POST http://localhost:8000/translate/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": {"text": "Hôm nay là thứ Sáu"}}'

Hoặc dùng Python:

import requests
res = requests.post(
    "http://localhost:8000/translate/invoke",
    json={"input": {"text": "Hôm nay là thứ Sáu"}}
)
print(res.json())

Tính năng nâng cao

Phản hồi theo luồng (streaming)

from fastapi import FastAPI
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langserve import add_routes

prompt = ChatPromptTemplate.from_template("Trả lời: {query}")
streaming_llm = ChatOpenAI(model="gpt-3.5-turbo", streaming=True)
chat_chain = prompt | streaming_llm

app = FastAPI(title="Chat Streaming")
add_routes(app, chat_chain, path="/stream-chat")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Kiểm thử:

curl -X POST http://localhost:8000/stream-chat/stream \
  -H "Content-Type: application/json" \
  -d '{"input": {"query": "Thủ đô Việt Nam là gì?"}}'

Triển khai Agent

from fastapi import FastAPI
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_react_agent
from langchain_core.prompts import PromptTemplate
from langserve import add_routes

@tool
def web_search(keyword: str) -> str:
    return f"Kết quả tìm kiếm cho: {keyword}"

llm = ChatOpenAI(model="gpt-3.5-turbo")
tools = [web_search]
agent_prompt = PromptTemplate.from_template("Xử lý yêu cầu: {input}")
react_agent = create_react_agent(llm, tools, agent_prompt)
agent_runner = AgentExecutor(agent=react_agent, tools=tools)

api_app = FastAPI(title="Agent Service")
add_routes(api_app, agent_runner, path="/assistant")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(api_app, host="0.0.0.0", port=8000)

Định nghĩa schema đầu vào/ra

from pydantic import BaseModel

class TranslationInput(BaseModel):
    text: str

class TranslationOutput(BaseModel):
    result: str

add_routes(
    app,
    translation_chain,
    path="/translate",
    input_type=TranslationInput,
    output_type=TranslationOutput
)

Tích hợp LangSmith

Thiết lập biến môi trường:

export LANGCHAIN_TRACING_V2="true"
export LANGCHAIN_API_KEY="your-langsmith-key"

Sau đó chạy ứng dụng như bình thường – mọi request sẽ được ghi nhận trên bảng điều khiển LangSmith.

Lưu ý khi triển khai sản xuất

• Container hóa: Sử dụng Docker để đảm bảo tính nhất quán môi trường.
• Mở rộng quy mô: Dùng Gunicorn + Uvicorn worker để tăng khả năng xử lý đồng thời.
• Bảo mật: Thêm xác thực (API key, OAuth2) và bật HTTPS.
• Giám sát: Tích hợp LangSmith, Prometheus hoặc hệ thống logging.
• Tối ưu hiệu năng: Áp dụng cache (Redis), xử lý batch, giảm số lần gọi LLM.

Xử lý sự cố thường gặp

• Lỗi 500: Kiểm tra API key, định dạng đầu vào, hoặc trạng thái LLM.
• Playground không tải: Đảm bảo server bind tới 0.0.0.0, không phải 127.0.0.1.
• Stream bị ngắt: Xác minh LLM hỗ trợ streaming và kết nối mạng ổn định.
• Hiệu năng kém: Tối giản chain, dùng async, hoặc nâng cấp tài nguyên server.