Instructor: Thư Viện Python Đảm Bảo LLM Xuất JSON Hợp Lệ 100% — Hướng Dẫn 2026

pip install instructor

# Cài đặt khách hàng LLM yêu thích của bạn (OpenAI được hiển thị)
pip install openai

import instructor
from openai import OpenAI
from pydantic import BaseModel

# Đánh giá khách hàng OpenAI với Học viên
client = instructor.from_openai(OpenAI())

# Định nghĩa cấu trúc dữ liệu đầu ra như một mô hình Pydantic
class UserProfile(BaseModel):
    name: str
    age: int
    email: str
    interests: list[str]

# Trích xuất dữ liệu có cấu trúc từ ngôn ngữ tự nhiên
def extract_profile(user_description: str) -> UserProfile:
    return client.chat.completions.create(
        model="gpt-4o",
        response_model=UserProfile,
        messages=[
            {
                "role": "user",
                "content": f"Trích xuất một hồ sơ người dùng từ mô tả này: {user_description}"
            }
        ]
    )

# Sử dụng
profile = extract_profile(
    "Sarah là một kỹ sư phần mềm 28 tuổi ở Seattle. "
    "Cô yêu thích đi bộ, chụp ảnh và đọc tiểu thuyết khoa học viễn tưởng. "
    "Email của cô là sarah.chen@example.com"
)

print(profile)
# UserProfile(name='Sarah', age=28, email='sarah.chen@example.com', 
#             interests=['hiking', 'photography', 'reading sci-fi novels'])

# Truy cập các trường đã định kiểu trực tiếp
print(f"Tên: {profile.name}, Tuổi: {profile.age}")
print(f"Email hợp lệ: {'@' in profile.email}")

from pydantic import BaseModel, Field, field_validator

class ValidatedProduct(BaseModel):
    name: str = Field(description="Tên sản phẩm, tối đa 50 ký tự")
    price: float = Field(description="Giá USD, phải dương")
    category: str = Field(description="Một trong những loại sau: điện tử, quần áo, thực phẩm, sách")
    
    @field_validator('category')
    @classmethod
    def validate_category(cls, v):
        allowed = {'electronics', 'clothing', 'food', 'books'}
        if v.lower() not in allowed:
            raise ValueError(f"Loại sản phẩm phải là một trong: {allowed}")
        return v.lower()
    
    @field_validator('price')
    @classmethod
    def validate_price(cls, v):
        if v <= 0:
            raise ValueError("Giá phải dương")
        return round(v, 2)

# Instructor tự động thử lại khi có lỗi kiểm tra
def parse_product(description: str) -> ValidatedProduct:
    return client.chat.completions.create(
        model="gpt-4o",
        response_model=ValidatedProduct,
        max_retries=3,  # Thử lại tối đa 3 lần với phản hồi
        messages=[
            {"role": "user", "content": f"Phân tích sản phẩm này: {description}"}
        ]
    )

# Điều này sẽ hoạt động ngay cả khi lần thử đầu tiên có vấn đề
product = parse_product(
    "Tai nghe Bluetooth không dây với giảm tiếng ồn, giá $79.99. Loại điện tử."
)
print(product)
# ValidatedProduct(name='Tai nghe Bluetooth không dây', 
#                  price=79.99, category='electronics')

from typing import Optional, List
from pydantic import BaseModel, Field

class Address(BaseModel):
    street: str
    city: str
    state: str = Field(description="2-letter state code")
    zip_code: str
    country: str = "US"

class OrderItem(BaseModel):
    product_name: str
    quantity: int = Field(ge=1, description="Must be at least 1")
    unit_price: float = Field(gt=0)
    
    @property
    def total(self) -> float:
        return self.quantity * self.unit_price

class CustomerOrder(BaseModel):
    customer_name: str
    customer_email: str
    shipping_address: Address
    billing_address: Optional[Address] = None
    items: List[OrderItem]
    order_notes: Optional[str] = None
    
    @property
    def grand_total(self) -> float:
        return sum(item.total for item in self.items)

def extract_order(email_text: str) -> CustomerOrder:
    return client.chat.completions.create(
        model="gpt-4o",
        response_model=CustomerOrder,
        messages=[
            {"role": "user", "content": f"Extract order from email:\n\n{email_text}"}
        ]
    )

order = extract_order("""
Hi, I'd like to place an order.

Customer: John Smith (john.smith@email.com)
Ship to: 123 Oak Street, San Francisco, CA 94102

Items:
- MacBook Pro M3, qty 1, $1999
- USB-C Hub, qty 2, $49 each

Please gift wrap the laptop.
""")

print(f"Customer: {order.customer_name}")
print(f"Shipping to: {order.shipping_address.city}")
print(f"Order total: ${order.grand_total:.2f}")

# Các trường tùy chọn có giá trị mặc định được xử lý một cách trơn tru
from pydantic import BaseModel
from typing import Optional
from datetime import datetime

class Event(BaseModel):
    name: str
    start_time: datetime
    end_time: Optional[datetime] = None
    location: Optional[str] = None
    description: Optional[str] = ""

event = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=Event,
    messages=[{
        "role": "user",
        "content": "Team standup meeting tomorrow at 10 AM in Conference Room B"
    }]
)
print(f"Event: {event.name}")
print(f"Starts: {event.start_time}")
print(f"Location: {event.location}")  # Conference Room B
print(f"Description: '{event.description}'")  # Sử dụng chuỗi trống rỗng mặc định

import asyncio
import instructor
from openai import AsyncOpenAI
from pydantic import BaseModel

# Sử dụng client async cho xử lý lô
async_client = instructor.from_openai(AsyncOpenAI())

class SentimentResult(BaseModel):
    text: str
    sentiment: str  # "positive", "negative", "neutral"
    confidence: float
    key_phrases: list[str]

async def analyze_single(text: str) -> SentimentResult:
    return await async_client.chat.completions.create(
        model="gpt-4o-mini",
        response_model=SentimentResult,
        messages=[
            {"role": "user", "content": f"Đánh giá tình cảm: {text}"}
        ]
    )

async def analyze_batch(texts: list[str]) -> list[SentimentResult]:
    """Xử lý nhiều văn bản đồng thời."""
    tasks = [analyze_single(text) for text in texts]
    results = await asyncio.gather(*tasks)
    return results

# Xử lý 100 đánh giá đồng thời
texts = [
    "Sản phẩm này vượt quá mong đợi của tôi!",
    "Chất lượng kém, hỏng sau một ngày.",
    "Được rồi, không gì đặc biệt nhưng làm việc được.",
    # ... 97 mục còn lại
]

results = asyncio.run(analyze_batch(texts))
positive = sum(1 for r in results if r.sentiment == "positive")
print(f"Positive: {positive}/{len(results)}")

from typing import Iterable
from pydantic import BaseModel

class PartialArticle(BaseModel):
    title: str
    sections: list[str]
    key_points: list[str]

# Truyền tải dữ liệu đa dạng hóa theo thời gian thực khi nó được tạo ra
def stream_article(topic: str) -> Iterable[PartialArticle]:
    return client.chat.completions.create_partial(
        model="gpt-4o",
        response_model=PartialArticle,
        stream=True,
        messages=[
            {"role": "user", "content": f"Write an article outline about: {topic}"}
        ]
    )

# Xử lý kết quả phần tử khi chúng đến
for partial in stream_article("trends về năng lượng tái tạo 2026"):
    print(f"Tiêu đề: {partial.title}")
    print(f"Số phần đã có: {len(partial.sections)}")
    print("---")

from pydantic import BaseModel, field_validator

class StrictDateRange(BaseModel):
    start_date: str = Field(description="Định dạng YYYY-MM-DD")
    end_date: str = Field(description="Định dạng YYYY-MM-DD, phải sau ngày bắt đầu")
    
    @field_validator('start_date', 'end_date')
    @classmethod
    def validate_date_format(cls, v):
        from datetime import datetime
        datetime.strptime(v, "%Y-%m-%d")
        return v
    
    @field_validator('end_date')
    @classmethod
    def validate_order(cls, end, info):
        start = info.data.get('start_date')
        if start and end <= start:
            raise ValueError("end_date phải sau start_date")
        return end

# Giáo viên sẽ retry với phản hồi lỗi kiểm tra cụ thể
def extract_date_range(text: str) -> StrictDateRange:
    return client.chat.completions.create(
        model="gpt-4o",
        response_model=StrictDateRange,
        max_retries=3,
        messages=[
            {"role": "user", "content": f"Extract date range: {text}"}
        ]
    )

# Ngay cả khi mô hình thay đổi ngày hoặc sử dụng định dạng sai ban đầu,
# Giáo viên sẽ nhắc lại với thông báo lỗi cụ thể
try:
    result = extract_date_range(
        "Dự án đã chạy từ 15 tháng 3 năm 2026 đến 10 tháng 1 năm 2026"
    )
    print(result)
except Exception as e:
    print(f"Thất bại sau số lần retry tối đa: {e}")

from typing import Literal

class SupportTicket(BaseModel):
    customer_query: str
    category: Literal[
        "billing", 
        "technical_support", 
        "account_access",
        "feature_request",
        "refund",
        "general_inquiry"
    ]
    priority: Literal["low", "medium", "high", "urgent"]
    suggested_response: str

def classify_ticket(ticket_text: str) -> SupportTicket:
    return client.chat.completions.create(
        model="gpt-4o-mini",
        response_model=SupportTicket,
        messages=[
            {
                "role": "system",
                "content": "Bạn là một chuyên gia phân loại hỗ trợ khách hàng."
            },
            {"role": "user", "content": f"Phân loại ticket này:\n\n{ticket_text}"}
        ]
    )

# Phân loại đảm bảo sẽ là một trong các giá trị được cho phép
ticket = classify_ticket(
    "Tôi đã bị thu phí hai lần cho dịch vụ đăng ký của mình vào tháng này. "
    "Vui lòng hoàn tiền khoản phí trùng lặp ngay lập tức."
)
print(f"Loại: {ticket.category}")  # Luôn luôn là "billing"
print(f"Khẩn cấp: {ticket.priority}")  # Luôn một trong bốn giá trị

# Trích xuất thông tin cấu trúc từ các tài liệu dài
from pydantic import BaseModel

class ExtractedFact(BaseModel):
    subject: str
    predicate: str
    object_: str
    confidence: float

class DocumentExtraction(BaseModel):
    title: str
    facts: list[ExtractedFact]
    entities: list[str]
    summary: str

extraction = client.chat.completions.create(
    model="gpt-4o",
    response_model=DocumentExtraction,
    messages=[{
        "role": "user",
        "content": (
            "Trích xuất thông tin cấu trúc từ văn bản này:\n\n"
            "Apple Inc. được thành lập bởi Steve Jobs và Steve Wozniak "
            "ngày 1 tháng 4 năm 1976. Công ty có trụ sở tại Cupertino, California. "
            "Tim Cook trở thành CEO vào năm 2011."
        )
    }]
)
print(f"Tiêu đề: {extraction.title}")
print(f"Các đối tượng tìm thấy: {extraction.entities}")
print(f"Số lượng thông tin: {len(extraction.facts)}")

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import instructor
from openai import OpenAI

app = FastAPI(title="API Đầu ra LLM Cấu Trúc")
client = instructor.from_openai(OpenAI())

# Schema yêu cầu
class ExtractionRequest(BaseModel):
    text: str
    extract_fields: list[str]

# Schema trả lời
class ExtractedData(BaseModel):
    entities: list[dict]
    relationships: list[dict]
    summary: str

@app.post("/extract", response_model=ExtractedData)
async def extract_entities(request: ExtractionRequest):
    """Trích xuất các entitie cấu trúc từ văn bản không cấu trúc."""
    try:
        result = client.chat.completions.create(
            model="gpt-4o",
            response_model=ExtractedData,
            messages=[
                {
                    "role": "user",
                    "content": (
                        f"Trích xuất entitie từ văn bản này. "
                        f"Tập trung vào: {', '.join(request.extract_fields)}\n\n"
                        f"Văn bản: {request.text}"
                    )
                }
            ]
        )
        return result
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

# Chạy với: uvicorn main:app --reload

from typing import Type

class SearchQuery(BaseModel):
    """Tạo câu hỏi tìm kiếm với các tham số"""
    keywords: list[str]
    filters: dict[str, str]
    sort_by: Literal["relevance", "date", "price_asc", "price_desc"]
    
def generate_search(user_request: str) -> SearchQuery:
    return client.chat.completions.create(
        model="gpt-4o",
        response_model=SearchQuery,
        messages=[
            {
                "role": "user",
                "content": f"Generate an optimized search query for: {user_request}"
            }
        ]
    )

query = generate_search(
    "Find wireless earbuds under $100 with good battery life, newest first"
)
print(query.keywords)  # ['wireless earbuds', 'bluetooth']
print(query.filters)   # {'max_price': '100'}
print(query.sort_by)   # 'date'

import logging
import instructor

# Kích hoạt ghi chi tiết
instructor.enable_logging()
logging.basicConfig(level=logging.DEBUG)

# Hoặc cấu hình logger cụ thể
logger = logging.getLogger("instructor")
logger.setLevel(logging.INFO)

# Thêm handler file cho sản xuất
handler = logging.FileHandler("instructor.log")
handler.setFormatter(logging.Formatter(
    '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
))
logger.addHandler(handler)

# Tất cả các lần thử lại và lỗi kiểm tra đều được ghi nhật ký
result = client.chat.completions.create(
    model="gpt-4o",
    response_model=UserProfile,
    max_retries=3,
    messages=[{"role": "user", "content": "Extract: Jane, age 25, likes art"}]
)