Batch Processing là gì?

Batch Processing cho phép bạn:

• Gửi nhiều request cùng lúc thay vì request một cái một
• Chấp nhận xử lý không đồng bộ (asynchronous) — không cần chờ kết quả ngay lập tức
• Tiết kiệm 50% chi phí so với streaming API thông thường
• Xử lý quy mô lớn: lên đến 100,000 requests hoặc 256MB dữ liệu trong một batch

Khi nào dùng Batch Processing?

• Phân tích hàng loạt tài liệu (ví dụ: phân loại 1000 email khách hàng)
• Xử lý dữ liệu hàng ngày (Daily batch jobs)
• Tóm tắt nội dung lớn (Summary generation)
• Chế độ night-time processing khi chi phí không quyết định vấn đề thời gian
• Tạo embeddings cho hàng ngàn tài liệu

Message Batches API hoạt động như thế nào

Message Batches API tuân theo quy trình 4 bước:

1. Chuẩn bị và gửi Batch

Bạn tạo một tệp JSON chứa danh sách các request. Mỗi request là một tin nhắn API thông thường, nhưng được đóng gói thành một batch duy nhất.

2. Xử lý không đồng bộ

Anthropic xử lý các request của bạn trong hàng đợi. Điều này có thể mất vài phút hoặc vài giờ tùy theo kích thước batch và tải hệ thống.

3. Theo dõi trạng thái (Polling)

Bạn có thể kiểm tra trạng thái batch bất cứ lúc nào. Hệ thống sẽ cho bạn biết tiến độ: đã hoàn thành bao nhiêu request, còn lại bao nhiêu.

4. Lấy kết quả

Khi batch hoàn thành, bạn lấy kết quả và xử lý chúng. Các kết quả có sẵn trong 29 ngày.

💡 Tip: Bạn có thể đăng ký webhook để nhận thông báo khi batch hoàn thành, thay vì phải kiểm tra liên tục.

Hạn chế của Batch Processing

⚠️ Lưu ý: Batch Processing không hỗ trợ streaming. Bạn sẽ nhận được phản hồi hoàn chỉnh cho mỗi request, không phải token-by-token như API thông thường.

Bảng giá Batch API

Batch Processing giảm giá 50% so với API thông thường cho tất cả mô hình Claude. Dưới đây là bảng giá cập nhật:

Ví dụ tính toán: Nếu bạn xử lý 1 triệu token input với Claude Sonnet qua API thường sẽ mất $3, nhưng qua Batch API chỉ mất $1.50. Khi xử lý hàng loạt dữ liệu lớn, tiết kiệm này rất đáng kể!

Cách sử dụng Message Batches API

Bước 1: Chuẩn bị dữ liệu Batch

Tạo một tệp JSON với danh sách các request. Mỗi request phải có định dạng:

{
  "custom_id": "request-1",
  "params": {
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Summarize this article in one sentence..."
      }
    ]
  }
}

Lưu ý: custom_id phải là duy nhất trong batch, dùng để định danh request khi nhận kết quả.

Bước 2: Gửi Batch với Python

import anthropic
import json

client = anthropic.Anthropic()

# Chuẩn bị batch requests
batch_requests = [
    {
        "custom_id": "request-1",
        "params": {
            "model": "claude-3-5-sonnet-20241022",
            "max_tokens": 1024,
            "messages": [
                {
                    "role": "user",
                    "content": "Classify this email: 'Great product, highly recommend!'"
                }
            ]
        }
    },
    {
        "custom_id": "request-2",
        "params": {
            "model": "claude-3-5-sonnet-20241022",
            "max_tokens": 1024,
            "messages": [
                {
                    "role": "user",
                    "content": "Classify this email: 'This is not working, fix it immediately!'"
                }
            ]
        }
    }
]

# Gửi batch
batch = client.beta.messages.batches.create(requests=batch_requests)

print(f"Batch ID: {batch.id}")
print(f"Status: {batch.processing_status}")

Bước 3: Theo dõi trạng thái Batch

# Kiểm tra trạng thái batch
batch = client.beta.messages.batches.retrieve(batch.id)

print(f"Status: {batch.processing_status}")
print(f"Completed: {batch.request_counts.completed}")
print(f"Remaining: {batch.request_counts.remaining}")
print(f"Expired: {batch.request_counts.errored}")

Bước 4: Lấy kết quả

# Chờ batch hoàn thành (hoặc dùng webhook)
import time

while True:
    batch = client.beta.messages.batches.retrieve(batch.id)
    if batch.processing_status == "completed":
        break
    print(f"Still processing... {batch.request_counts.completed}/{batch.request_counts.total}")
    time.sleep(5)

# Lấy kết quả
results = client.beta.messages.batches.results(batch.id)

for result in results:
    print(f"ID: {result.custom_id}")
    print(f"Status: {result.status}")
    if result.status == "succeeded":
        print(f"Response: {result.result.message.content[0].text}")
    else:
        print(f"Error: {result.error.message}")

Bước 5: Liệt kê các Batch

# Xem danh sách các batch của bạn
batches = client.beta.messages.batches.list()

for batch in batches.data:
    print(f"ID: {batch.id}, Status: {batch.processing_status}")

Bước 6: Hủy Batch

# Hủy batch đang chờ xử lý
client.beta.messages.batches.cancel(batch.id)
print("Batch cancelled")

Sử dụng cURL

Nếu bạn thích dùng cURL:

# Gửi batch
curl -X POST "https://api.anthropic.com/v1/messages/batches" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: message-batches-2024-09-24" \
  -H "Content-Type: application/json" \
  -d @batch.json

# Kết quả sẽ trả về batch ID

# Kiểm tra trạng thái
curl "https://api.anthropic.com/v1/messages/batches/BATCH_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: message-batches-2024-09-24"

# Lấy kết quả
curl "https://api.anthropic.com/v1/messages/batches/BATCH_ID/results" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: message-batches-2024-09-24"

Prompt Caching với Batch

Batch Processing hoạt động tuyệt vời với Prompt Caching. Nếu bạn có một hệ thống prompt lớn (ví dụ: một tài liệu hướng dẫn dài 10,000 token) mà được sử dụng lại trong nhiều request, Cache sẽ tự động được áp dụng.

Kết quả hiệu suất:

• Cache hit rate: 30-98% (tùy vào dữ liệu của bạn)
• Chi phí input token trong cache: chỉ 10% (so với 100% bình thường)
• Khi kết hợp với Batch discount, bạn có thể tiết kiệm tới 95% chi phí input!

Để sử dụng Prompt Caching, thêm block cache_control:

batch_requests = [
    {
        "custom_id": "request-1",
        "params": {
            "model": "claude-3-5-sonnet-20241022",
            "max_tokens": 1024,
            "system": [
                {
                    "type": "text",
                    "text": "Bạn là một chuyên gia phân tích dữ liệu...",
                    "cache_control": {"type": "ephemeral"}
                }
            ],
            "messages": [
                {
                    "role": "user",
                    "content": "Phân tích dữ liệu này: ..."
                }
            ]
        }
    }
]

Claude tự động phát hiện và cache các prompt lớn. Bạn không cần cấu hình gì thêm ngoài block cache_control.

Best Practices

1. Sử dụng custom_id có ý nghĩa

Không chỉ dùng số tự động. Hãy dùng ID có ý nghĩa để dễ theo dõi:

"custom_id": "user_123_sentiment_check"
"custom_id": "email_456_spam_classification"
"custom_id": "doc_789_summary"

2. Chia nhỏ batch lớn

Nếu bạn có 1 triệu request, đừng gửi tất cả trong một batch. Chia thành 10 batch 100,000 requests. Điều này giúp:

• Dễ theo dõi tiến độ
• Tránh timeout nếu một request gặp lỗi
• Có thể xử lý song song (parallel processing)

3. Theo dõi trạng thái thường xuyên

Đừng spam API. Kiểm tra trạng thái mỗi 30 giây hoặc 1 phút, không phải mỗi giây:

import time

interval = 30  # giây
max_wait = 3600  # 1 giờ
elapsed = 0

while elapsed < max_wait:
    batch = client.beta.messages.batches.retrieve(batch.id)
    if batch.processing_status == "completed":
        break
    elapsed += interval
    time.sleep(interval)

4. Dùng Webhook thay vì polling

Thay vì kiểm tra trạng thái liên tục, bạn có thể đăng ký webhook để nhận thông báo khi batch hoàn thành. Điều này tiết kiệm API calls và làm cho ứng dụng của bạn nhanh hơn.

5. Xử lý lỗi

Một số request có thể thất bại. Hãy lưu trữ những request thất bại và thử lại sau:

failed_requests = []
results = client.beta.messages.batches.results(batch.id)

for result in results:
    if result.status == "errored":
        failed_requests.append({
            "custom_id": result.custom_id,
            "error": result.error.message,
            "original_request": result.error.type
        })

print(f"Failed: {len(failed_requests)} requests")
if failed_requests:
    print("Saving failed requests for retry...")
    # Lưu vào DB hoặc file để thử lại sau

6. Tối ưu kích thước request

Cố gắng giữ mỗi request nhỏ gọn. Batch API tính phí dựa trên token, nên request càng nhỏ chi phí càng thấp. Ví dụ, thay vì gửi toàn bộ tài liệu, hãy gửi từng đoạn 500 token.

Câu hỏi thường gặp

Q: Batch Processing mất bao lâu?

A: Không có thời gian chính xác. Nó tùy thuộc vào:

• Kích thước batch (100 hay 100,000 requests?)
• Độ phức tạp của prompt (token input lớn không?)
• Tải hệ thống của Anthropic vào thời điểm đó

Thường từ vài phút đến vài giờ cho batch lớn.

Q: Tôi có thể xóa batch sau khi hoàn thành không?

A: Có, bạn có thể xóa batch bất cứ lúc nào sau khi hoàn thành. Nhưng kết quả sẽ mất. Nên lưu kết quả trước khi xóa.

Q: Batch có hỗ trợ vision (xử lý hình ảnh) không?

A: Có! Batch hoạt động với tất cả tính năng của Claude, bao gồm:

• Vision (xử lý hình ảnh)
• Tool use (gọi hàm bên ngoài)
• System messages
• Multi-turn conversations

Q: Tôi nên dùng Batch hay streaming API?

A: Dùng Batch nếu:

• Bạn có nhiều request cùng lúc
• Thời gian không phải vấn đề (có thể chờ vài giờ)
• Chi phí quan trọng hơn (muốn tiết kiệm 50%)

Dùng streaming API nếu:

• Bạn cần kết quả ngay lập tức (real-time)
• Người dùng đang chờ phản hồi
• Bạn muốn hiển thị token trả lời từng cái một

Q: Batch hỗ trợ những model nào?

A: Tất cả model Claude hiện tại đều hỗ trợ Batch:

• claude-opus-4.6
• claude-sonnet-4.6
• claude-haiku-4.5

Kiểm tra trang Claude Anthropic để cập nhật model mới nhất.

Q: Có custom_id phải là duy nhất không?

A: Có, mỗi custom_id phải duy nhất trong batch. Nếu trùng, API sẽ trả về lỗi. Nên dùng UUID hoặc ID kết hợp với timestamp.

Q: Dữ liệu batch được lưu bao lâu?

A: Kết quả batch có sẵn trong 29 ngày. Sau đó sẽ bị xóa tự động. Nên lưu kết quả quan trọng vào cơ sở dữ liệu của bạn.

Q: Batch có an toàn không?

A: Có! Anthropic bảo đảm:

• Dữ liệu workspace bị cách ly (không thể truy cập dữ liệu của workspace khác)
• Tất cả dữ liệu được mã hóa trong transit và at rest
• Tuân theo các tiêu chuẩn bảo mật cao nhất