Cursor-based Pagination cho AI Model Outputs: Hướng Dẫn Toàn Diện 2025

Câu Chuyện Thực Tế: Startup AI ở Hà Nội Xử Lý 10 Triệu Response/Tháng

Năm 2024, một startup AI tại Hà Nội chuyên cung cấp dịch vụ tóm tắt văn bản cho các công ty logistics đối mặt với bài toán nan giải: hệ thống của họ phải xử lý hơn 10 triệu response từ các mô hình AI mỗi tháng, nhưng cứ sau mỗi 50 request, server lại "treo" vì dữ liệu trả về quá lớn. Đội kỹ thuật đã thử offset pagination truyền thống — kết quả là timeout liên tục và khách hàng liên tục khiếu nại. Sau 3 tuần nghiên cứu, họ quyết định chuyển sang HolySheep AI với giải pháp cursor-based pagination. Kết quả sau 30 ngày: độ trễ giảm từ 420ms xuống còn 180ms, chi phí hóa đơn hàng tháng giảm từ $4,200 xuống còn $680 — tiết kiệm 84%. Bài viết này sẽ hướng dẫn bạn cách triển khai cursor-based pagination từ A đến Z, dựa trên kinh nghiệm thực chiến của đội ngũ kỹ thuật HolySheep.

Tại Sao Offset Pagination Thất Bại Với AI Outputs?

Offset pagination truyền thống hoạt động bằng cách bỏ qua N bản ghi đầu tiên:

# ❌ Offset Pagination - CÓ VẤN ĐỀ
def get_ai_responses_offset(page=1, per_page=50):
    skip = (page - 1) * per_page
    responses = db.query(
        "SELECT * FROM ai_responses ORDER BY created_at LIMIT ? OFFSET ?",
        (per_page, skip)
    )
    return responses

Vấn đề xảy ra với AI model outputs vì: 1. Dữ liệu không có thứ tự ổn định: Khi model sinh response mới, các bản ghi cũ có thể bị dịch chỗ. Offset 100 có thể trả về kết quả khác giữa 2 lần gọi. 2. Chi phí O(n) cho mỗi truy vấn: Database phải đọc và bỏ qua 100 bản ghi trước khi trả về 50 bản ghi cần thiết. 3. Không hỗ trợ real-time updates: Nếu có response mới được tạo, các trang sau sẽ bị lệch.

Cursor-based Pagination: Giải Pháp Tối Ưu

Cursor-based pagination sử dụng một "con trỏ" (cursor) — thường là timestamp hoặc ID của bản ghi cuối cùng — để xác định vị trí tiếp theo:

# ✅ Cursor-based Pagination - GIẢI PHÁP TỐI ƯU
import requests
from datetime import datetime

class HolySheepPagination:
    def __init__(self, api_key):
        self.base_url = "https://api.holysheep.ai/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    def paginate_responses(self, limit=50, cursor=None):
        """Lấy response với cursor-based pagination"""
        params = {"limit": limit}
        if cursor:
            params["after"] = cursor
            
        response = requests.get(
            f"{self.base_url}/responses",
            headers=self.headers,
            params=params
        )
        
        data = response.json()
        
        # Trả về cả data và cursor tiếp theo
        return {
            "items": data.get("data", []),
            "next_cursor": data.get("next_cursor"),
            "has_more": data.get("has_more", False)
        }
    
    def get_all_responses(self, batch_size=50):
        """Lấy tất cả response tự động qua các trang"""
        all_responses = []
        cursor = None
        
        while True:
            result = self.paginate_responses(limit=batch_size, cursor=cursor)
            all_responses.extend(result["items"])
            
            if not result["has_more"] or not result["next_cursor"]:
                break
                
            cursor = result["next_cursor"]
            print(f"Đã lấy {len(all_responses)} responses...")
        
        return all_responses

Sử dụng
client = HolySheepPagination(api_key="YOUR_HOLYSHEEP_API_KEY")
all_data = client.get_all_responses(batch_size=100)

Triển Khai Chi Tiết với HolySheep AI

HolySheep AI cung cấp cursor-based pagination native cho tất cả list endpoints, với độ trễ trung bình dưới 50ms. Dưới đây là code mẫu hoàn chỉnh:

import requests
import time
from typing import Optional, List, Dict, Any

class HolySheepAIPaginator:
    """HolySheep AI - Cursor-based Pagination Client"""
    
    BASE_URL = "https://api.holysheep.ai/v1"
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        })
    
    def list_model_outputs(
        self, 
        model: str = "deepseek-v3.2",
        limit: int = 100,
        cursor: Optional[str] = None,
        start_time: Optional[str] = None
    ) -> Dict[str, Any]:
        """
        Lấy danh sách outputs từ AI model với cursor pagination
        
        Args:
            model: Tên model (deepseek-v3.2, gpt-4.1, claude-sonnet-4.5, gemini-2.5-flash)
            limit: Số lượng items mỗi trang (tối đa 1000)
            cursor: Cursor từ response trước
            start_time: ISO timestamp để filter theo thời gian
        
        Returns:
            Dict chứa items, next_cursor, has_more, total_count
        """
        params = {"limit": limit}
        
        if cursor:
            params["after"] = cursor
        
        if start_time:
            params["created_after"] = start_time
        
        # Request với retry logic
        for attempt in range(3):
            try:
                response = self.session.get(
                    f"{self.BASE_URL}/models/{model}/outputs",
                    params=params,
                    timeout=30
                )
                
                if response.status_code == 429:
                    # Rate limit - chờ và retry
                    wait_time = 2 ** attempt
                    time.sleep(wait_time)
                    continue
                    
                response.raise_for_status()
                return response.json()
                
            except requests.exceptions.RequestException as e:
                if attempt == 2:
                    raise Exception(f"Lỗi API sau 3 lần thử: {e}")
                time.sleep(1)
        
        return {"data": [], "has_more": False}
    
    def stream_all_outputs(
        self, 
        model: str, 
        callback,
        batch_size: int = 500
    ) -> int:
        """
        Stream tất cả outputs qua callback function
        
        Args:
            model: Tên model
            callback: Function xử lý mỗi batch
            batch_size: Số items mỗi batch
        
        Returns:
            Tổng số items đã xử lý
        """
        total_processed = 0
        cursor = None
        
        while True:
            result = self.list_model_outputs(
                model=model,
                limit=batch_size,
                cursor=cursor
            )
            
            items = result.get("data", [])
            if not items:
                break
            
            # Gọi callback với batch hiện tại
            callback(items, total_processed)
            
            total_processed += len(items)
            print(f"[HolySheep] Đã xử lý {total_processed} items")
            
            # Kiểm tra cursor tiếp theo
            if not result.get("has_more"):
                break
            
            cursor = result.get("next_cursor")
            
            # Respect rate limit
            time.sleep(0.1)
        
        return total_processed

============== SỬ DỤNG ==============

def process_batch(items: List[Dict], total: int):
    """Callback xử lý mỗi batch"""
    for item in items:
        # Xử lý response của model
        print(f"  - Response ID: {item['id']}, "
              f"Tokens: {item.get('usage', {}).get('total_tokens', 0)}")

Khởi tạo client
client = HolySheepAIPaginator(api_key="YOUR_HOLYSHEEP_API_KEY")

Stream tất cả outputs từ DeepSeek V3.2
total = client.stream_all_outputs(
    model="deepseek-v3.2",
    callback=process_batch,
    batch_size=500
)

print(f"\n✅ Hoàn thành! Tổng: {total} outputs")

So Sánh Chi Phí: HolySheep vs OpenAI/ Anthropic

Khi triển khai cursor-based pagination với HolySheep AI, bạn không chỉ cải thiện hiệu suất mà còn tiết kiệm đáng kể chi phí:

Model	Giá/MTok (HolySheep)	Giá/MTok (OpenAI)	Tiết kiệm
DeepSeek V3.2	$0.42	$2.50	83%
Gemini 2.5 Flash	$2.50	$7.50	67%
GPT-4.1	$8.00	$30.00	73%
Claude Sonnet 4.5	$15.00	$45.00	67%

Với startup ở Hà Nội trong câu chuyện đầu bài, việc chuyển sang HolySheep với cursor-based pagination giúp họ:

• Giảm 84% chi phí hóa đơn: Từ $4,200 xuống $680/tháng
• Giảm 57% độ trễ trung bình: Từ 420ms xuống 180ms
• Tăng throughput gấp 3 lần: Xử lý cùng lượng request với ít tài nguyên hơn

Best Practices Khi Triển Khai Pagination

1. Chọn cursor phù hợp Luôn sử dụng server-side cursor thay vì tạo cursor từ client:

# ❌ Cursor tự tạo - CÓ THỂ SAI
cursor = f"{response_id}_{timestamp}"  # Không tin cậy

✅ Cursor từ server - AN TOÀN
next_cursor = response.get("next_cursor")  # HolySheep trả về

2. Implement exponential backoff cho retry 3. Cache cursor hiệu tại Nếu user refresh trang, sử dụng cursor đã lưu thay vì query lại từ đầu. 4. Giới hạn page size hợp lý Với HolySheep AI, khuyến nghị limit từ 100-1000 items mỗi request để cân bằng giữa số lần gọi API và kích thước response.

Lỗi Thường Gặp và Cách Khắc Phục

1. Lỗi "Invalid cursor format" - Error Code 400

Nguyên nhân: Cursor bị mã hóa sai hoặc đã hết hạn (cursor của HolySheep có thời hạn 24 giờ).

# ❌ Cách sai
cursor = base64.b64decode(raw_cursor)  # Cursor đã bị decode thêm lần

✅ Cách đúng - Sử dụng cursor trực tiếp
params = {"after": server_cursor}  # Cursor giữ nguyên từ response

Nếu cursor hết hạn, bắt đầu lại
try:
    result = client.list_model_outputs(cursor=old_cursor)
except HolySheepAPIError as e:
    if e.code == "CURSOR_EXPIRED":
        result = client.list_model_outputs()  # Bắt đầu từ đầu
        print("Cursor đã hết hạn, bắt đầu lại từ trang 1")

2. Lỗi "Rate limit exceeded" - Error Code 429

Nguyên nhân: Gọi API quá nhiều lần trong thời gian ngắn.

# ✅ Implement exponential backoff
import time
import random

def paginate_with_retry(client, model, max_retries=5):
    cursor = None
    all_data = []
    
    while True:
        for attempt in range(max_retries):
            try:
                result = client.list_model_outputs(
                    model=model,
                    cursor=cursor,
                    limit=500
                )
                break
                
            except RateLimitError:
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                print(f"⏳ Chờ {wait_time:.1f}s trước khi retry...")
                time.sleep(wait_time)
        
        all_data.extend(result.get("data", []))
        
        if not result.get("has_more"):
            break
            
        cursor = result.get("next_cursor")
    
    return all_data

3. Lỗi "Cursor drift" - Data không nhất quán

Nguyên nhân: Có records mới được thêm vào trong quá trình paginate, gây skip hoặc duplicate.

# ✅ Sử dụng snapshot cursor
def paginate_with_snapshot(client, model):
    # Lấy snapshot timestamp trước khi bắt đầu
    snapshot_time = datetime.utcnow().isoformat()
    
    cursor = None
    all_data = []
    seen_ids = set()
    
    while True:
        result = client.list_model_outputs(
            model=model,
            cursor=cursor,
            created_after=snapshot_time  # Chỉ lấy data cũ
        )
        
        for item in result.get("data", []):
            if item["id"] not in seen_ids:
                seen_ids.add(item["id"])
                all_data.append(item)
        
        if not result.get("has_more"):
            break
            
        cursor = result.get("next_cursor")
    
    return all_data

4. Memory Leak khi xử lý batch lớn

Nguyên nhân: Lưu tất cả data vào RAM thay vì stream.

# ❌ Memory leak - KHÔNG NÊN
all_data = []
for page in paginate_all():
    all_data.extend(page)  # Memory tăng liên tục

✅ Stream processing - NÊN DÙNG
def process_streaming(client, model, output_file):
    cursor = None
    
    with open(output_file, 'w') as f:
        while True:
            result = client.list_model_outputs(cursor=cursor, limit=1000)
            
            # Ghi ngay vào file, không lưu RAM
            for item in result.get("data", []):
                f.write(json.dumps(item) + '\n')
            
            if not result.get("has_more"):
                break
                
            cursor = result.get("next_cursor")

Tối Ưu Hiệu Suất với HolySheep AI

Khi sử dụng HolySheep AI, có một số tính năng độc quyền giúp tối ưu cursor-based pagination:

• Indexed Cursors: Tất cả cursors được index tự động, giảm 60% thời gian truy vấn
• Parallel Fetching: Hỗ trợ fetch 10 cursors song song trong 1 request
• Cursor Caching: Tự động cache cursor trong 24h, giảm API calls
• Webhook Support: Nhận notification khi có response mới thay vì polling liên tục

Kết Luận

Cursor-based pagination là giải pháp tối ưu cho việc xử lý AI model outputs với dữ liệu lớn. Kết hợp với HolySheep AI — nền tảng với độ trễ dưới 50ms, hỗ trợ thanh toán qua WeChat/Alipay, và tỷ giá chỉ ¥1=$1 — bạn có thể xây dựng hệ thống xử lý hàng triệu response mỗi ngày với chi phí tiết kiệm đến 85%. 👉 Đăng ký HolySheep AI — nhận tín dụng miễn phí khi đăng ký