Bối cảnh & Vấn đề thực tế
Xử lý dữ liệu text tự do từ người dùng chưa bao giờ là việc dễ chịu. Email khiếu nại, tin nhắn CSKH, hóa đơn quét OCR hay ghi chú đơn hàng luôn lộn xộn. Bạn phải bẻ nhỏ đống chuỗi đó thành định dạng chuẩn để đẩy vào PostgreSQL. Cách làm cũ thường dựa vào Regex và hàng tá điều kiện if-else chằng chịt. Chỉ cần khách gõ sai chính tả hay đổi cách xưng hô, parser sẽ vỡ tan tành.
Khi LLM phổ biến, gọi OpenAI API ép trả về JSON trở thành lựa chọn hiển nhiên. Dù vậy, tự dựng prompt kèm JSON Schema thô thường đem lại chuỗi ngày debug mệt mỏi. Model hay tự ý thêm lời chào ngoài JSON, nuốt mất trường bắt buộc hoặc trả về chuỗi thay vì số nguyên. Trong khi đó, LangChain lại quá cồng kềnh với quá nhiều lớp trừu tượng thừa thãi cho một tác vụ bóc tách dữ liệu đơn giản.
Khi traffic hệ thống tăng lên hơn 3.000 ticket/ngày, team mình buộc phải tìm hướng đi khác gọn gàng hơn. Yêu cầu đặt ra rất rõ: phải type-safe, có validation chặt chẽ ở cấp ứng dụng và code phải giống Python thuần túy. Đó là lý do tụi mình chọn Marvin làm thư viện lõi cho service trích xuất suốt 6 tháng qua.
Marvin do đội ngũ Prefect phát triển. Thư viện này biến model ngôn ngữ lớn thành các hàm Python thông thường (AI Functions) và tích hợp sâu với Pydantic. Bạn không cần vật lộn viết prompt template dài dòng. Bạn chỉ việc khai báo hàm kèm type hint rõ ràng; toàn bộ việc suy luận ngữ nghĩa và validate schema sẽ do Marvin tự xử lý ngầm.
Cài đặt môi trường
Marvin hoạt động mượt nhất từ Python 3.10 trở lên. Bạn nên tạo virtual environment riêng để cô lập dependencies:
# Khởi tạo và kích hoạt môi trường ảo
python3 -m venv .venv
source .venv/bin/activate
# Cài đặt Marvin, Pydantic v2 và python-dotenv
pip install marvin pydantic python-dotenv
Mặc định Marvin kết nối thẳng tới OpenAI. Nếu hạ tầng nội bộ đòi hỏi bảo mật khắt khe, bạn hoàn toàn có thể trỏ thư viện sang Azure OpenAI, Claude hoặc cụm Ollama self-host.
Cấu hình kết nối
Tạo file .env tại thư mục gốc của project để lưu API key và model mặc định:
OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"
MARVIN_CHAT_COMPLETION_MODEL="gpt-4o-mini"
Với các tác vụ phân loại và trích xuất thực thể, gpt-4o-mini là lựa chọn cân bằng nhất. Phản hồi trung bình chỉ mất 250ms – 400ms, độ chính xác đạt trên 96% mà chi phí lại rẻ hơn 15 lần so với gpt-4o.
1. Phân loại nội dung tức thì với marvin.classify
Hãy xét bài toán phân luồng ticket hỗ trợ khách hàng theo độ khẩn cấp. Thay vì nhồi một prompt dài hai trang để hướng dẫn LLM, bạn chỉ cần một Enum chuẩn:
from enum import Enum
from dotenv import load_dotenv
import marvin
load_dotenv()
class Priority(Enum):
LOW = "Thắc mắc thông thường, góp ý tính năng, hỏi giờ làm việc"
MEDIUM = "Lỗi hiển thị nhỏ, không chặn luồng thanh toán"
HIGH = "Lỗi trừ tiền tài khoản, lộ bảo mật, sập dịch vụ"
customer_message = "Tài khoản vừa bị trừ 500k hai lần nhưng đơn vẫn báo huỷ, giải quyết ngay giúp tôi!"
# Phân loại trực tiếp sang Enum
result = marvin.classify(customer_message, Priority)
print(f"Mức độ: {result.name} | Định nghĩa: {result.value}")
# Output: Mức độ: HIGH | Định nghĩa: Lỗi trừ tiền tài khoản, lộ bảo mật, sập dịch vụ
Marvin tự đọc docstring và value trong Enum làm căn cứ phân loại. Không có prompt thủ công. Kết quả trả về là một Enum instance chuẩn, sẵn sàng để router rẽ nhánh logic ngay lập tức.
2. Bóc tách dữ liệu theo Pydantic Schema với marvin.extract
Bài toán tiếp theo: khách hàng gửi email đặt phòng khách sạn tự do bằng tiếng Việt. Cần trích xuất tên, số điện thoại, ngày nhận phòng và yêu cầu đi kèm vào database.
from typing import List, Optional
from datetime import date
from pydantic import BaseModel, Field
import marvin
class BookingRequest(BaseModel):
customer_name: str = Field(description="Tên khách hàng")
phone_number: Optional[str] = Field(None, description="Số điện thoại 10 số")
checkin_date: Optional[date] = Field(None, description="Ngày nhận phòng")
room_count: int = Field(default=1, description="Số phòng đặt")
special_notes: List[str] = Field(default_factory=list, description="Yêu cầu thêm")
raw_email = """
Chào bạn, mình là Minh Tuấn (0912345678).
Ngày 25/11/2026 tới bên mình cần đặt 3 phòng.
Nhớ bố trí tầng cao, view biển và chuẩn bị bàn làm việc nhé.
"""
# Trích xuất dữ liệu khớp đúng với Pydantic schema
bookings = marvin.extract(raw_email, target=BookingRequest)
for booking in bookings:
print(booking.model_dump_json(indent=2))
Dữ liệu đầu ra là instance Pydantic xịn. Trường checkin_date tự ép sang datetime.date, còn số lượng phòng ra kiểu int. Bạn có thể ném thẳng object này vào SQLAlchemy session mà không sợ lỗi type mismatch.
3. Biến hàm Python thành AI Function với @marvin.fn
Đây là tính năng đáng giá nhất của thư viện. Decorator @marvin.fn biến signature và docstring của hàm thành logic thực thi của model:
from pydantic import BaseModel
import marvin
class NormalizedAddress(BaseModel):
street: str
ward: str
district: str
province: str
@marvin.fn
def parse_vietnamese_address(raw_text: str) -> NormalizedAddress:
"""
Phân tích chuỗi địa chỉ giao hàng viết tắt hoặc không chuẩn tại Việt Nam
thành 4 cấp hành chính: số nhà/đường, phường/xã, quận/huyện, tỉnh/thành phố.
"""
address_input = "sn 45 ngõ 120 trần duy hưng, trung hoà, cầu giấy hn"
parsed = parse_vietnamese_address(address_input)
print(f"{parsed.street} | {parsed.ward} | {parsed.district} | {parsed.province}")
# Output: Số 45 ngõ 120 Trần Duy Hưng | Phường Trung Hoà | Quận Cầu Giấy | Hà Nội
Hàm này cư xử hệt như code native trong codebase. Service layer gọi nó mà không cần biết phía sau đang dùng model nào.
Kinh nghiệm vận hành Production
Đưa LLM vào core flow đòi hỏi hệ thống phòng thủ chắc chắn. Bạn không thể phó mặc tính ổn định cho mạng Internet bên ngoài.
1. Bọc Fallback và quản lý Timeout
OpenAI API đôi khi nghẽn mạng hoặc quá tải. Hãy chủ động đặt timeout và bắt ngoại lệ để trả về giá trị an toàn:
import logging
import marvin
marvin.settings.openai.chat.completions.timeout = 5.0
def safe_classify_ticket(ticket_content: str) -> Priority:
try:
return marvin.classify(ticket_content, Priority)
except Exception as exc:
logging.error(f"LLM classification failed: {exc}")
# Fallback về mức mặc định để luồng xử lý không bị đứt đoạn
return Priority.MEDIUM
2. Cắt giảm 45% chi phí bằng Cache
Trong thực tế, khoảng 30% đến 40% request có nội dung tương tự nhau. Gắn Redis cache hoặc functools.lru_cache theo hash của input sẽ giúp bạn tiết kiệm ngân sách đáng kể:
from functools import lru_cache
@lru_cache(maxsize=4096)
@marvin.fn
def standardize_brand_name(raw_name: str) -> str:
"""Chuẩn hóa tên thương hiệu thời trang về tên chính thức (ví dụ: nk -> Nike)."""
Ở team mình, việc cache 4.096 sản phẩm tìm kiếm phổ biến đã giảm hóa đơn OpenAI từ $420 xuống còn $230 mỗi tháng.
3. Viết Unit Test tự động cho AI Function
Đừng bao giờ deploy AI function mà thiếu test kiểm chứng. Hãy dùng pytest với assertion dạng tập hợp để kiểm tra độ tin cậy của output:
# tests/test_address_parser.py
def test_parse_vietnamese_address():
raw = "1 Đại Cồ Việt, Bách Khoa, Hai Bà Trưng, Hà Nội"
res = parse_vietnamese_address(raw)
assert res.province in ["Hà Nội", "Thành phố Hà Nội"]
assert res.district in ["Hai Bà Trưng", "Quận Hai Bà Trưng"]
assert "1 Đại Cồ Việt" in res.street
Marvin mang lại trải nghiệm lập trình rất tự nhiên. Thay vì chắp vá các chuỗi prompt mong manh, bạn làm việc trực tiếp với type hint và object an toàn. Đây là hướng tiếp cận thực dụng nhất để đưa AI vào hệ thống backend hiện đại.
