AI API 响应解析：choices/message/usage 字段完整说明

Vấn đề thực tế khi xử lý phản hồi từ API

Trong quá trình phát triển hệ thống chatbot và ứng dụng AI tại công ty, đội ngũ kỹ sư của tôi đã gặp một vấn đề tưởng chừng đơn giản nhưng lại gây ra không ít rắc rối: **cách parse và xử lý response từ API một cách chính xác và hiệu quả**. Tháng 3/2025, khi khối lượng request tăng đột biến từ 50,000 lên 500,000 mỗi ngày, chi phí API chúng tôi phải trả cho nhà cung cấp Mỹ lên tới **$12,000/tháng** — một con số khiến ban lãnh đạo phải đặt câu hỏi về tính khả thi của dự án. Sau khi thử nghiệm nhiều giải pháp, chúng tôi quyết định **di chuyển sang HolySheep AI** — relay API với tỷ giá chỉ ¥1=$1, tiết kiệm được 85% chi phí mà vẫn đảm bảo độ trễ dưới 50ms. Bài viết này sẽ hướng dẫn chi tiết cách parse response từ API, tránh các lỗi thường gặp, và chia sẻ kinh nghiệm thực chiến từ quá trình migration của đội ngũ tôi.

Cấu trúc response tiêu chuẩn từ API

Khi gọi endpoint chat completion, response trả về có cấu trúc JSON với ba trường chính mà bạn cần nắm vững:

{
  "id": "chatcmpl-abc123def456",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Xin chào! Tôi có thể giúp gì cho bạn?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 25,
    "total_tokens": 35
  }
}

Với HolySheep AI, response hoàn toàn tương thích với định dạng OpenAI, giúp bạn dễ dàng migrate mà không cần thay đổi logic xử lý.

Parse trường choices — Lấy nội dung phản hồi

Trường choices là một mảng chứa danh sách các lựa chọn phản hồi. Trong hầu hết trường hợp, bạn chỉ cần lấy phần tử đầu tiên:

import requests
import json

def get_ai_response(messages):
    """
    Gọi API và parse response từ HolySheep AI
    """
    base_url = "https://api.holysheep.ai/v1"
    api_key = "YOUR_HOLYSHEEP_API_KEY"
    
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "model": "gpt-4o",
        "messages": messages,
        "temperature": 0.7,
        "max_tokens": 1000
    }
    
    response = requests.post(
        f"{base_url}/chat/completions",
        headers=headers,
        json=payload,
        timeout=30
    )
    
    if response.status_code != 200:
        raise Exception(f"API Error: {response.status_code} - {response.text}")
    
    data = response.json()
    
    # Parse trường choices - lấy message đầu tiên
    choices = data.get("choices", [])
    if not choices:
        return None
    
    first_choice = choices[0]
    message = first_choice.get("message", {})
    content = message.get("content", "")
    finish_reason = first_choice.get("finish_reason", "")
    
    # Parse trường usage - theo dõi chi phí
    usage = data.get("usage", {})
    prompt_tokens = usage.get("prompt_tokens", 0)
    completion_tokens = usage.get("completion_tokens", 0)
    total_tokens = usage.get("total_tokens", 0)
    
    return {
        "content": content,
        "finish_reason": finish_reason,
        "usage": {
            "prompt_tokens": prompt_tokens,
            "completion_tokens": completion_tokens,
            "total_tokens": total_tokens
        }
    }

Sử dụng
messages = [
    {"role": "system", "content": "Bạn là trợ lý AI hữu ích."},
    {"role": "user", "content": "Giải thích về API response parsing"}
]

result = get_ai_response(messages)
print(f"Nội dung: {result['content']}")
print(f"Tokens sử dụng: {result['usage']['total_tokens']}")

Parse trường usage — Tính toán chi phí thực tế

Trường usage là yếu tố quan trọng để tính toán chi phí và tối ưu hóa prompt. Dưới đây là hàm tính chi phí với bảng giá HolySheep AI 2026:

# Bảng giá HolySheep AI 2026 (USD/MTok) - ¥1 = $1
PRICING = {
    "gpt-4o": {"input": 8.0, "output": 8.0},
    "gpt-4-turbo": {"input": 15.0, "output": 15.0},
    "claude-sonnet-4": {"input": 15.0, "output": 15.0},
    "gemini-2.5-flash": {"input": 2.50, "output": 2.50},
    "deepseek-v3.2": {"input": 0.42, "output": 0.42}
}

def calculate_cost(response_usage, model):
    """
    Tính chi phí từ response usage (USD)
    Token count / 1,000,000 * Price per MTok
    """
    if model not in PRICING:
        return None
    
    pricing = PRICING[model]
    
    input_cost = (response_usage["prompt_tokens"] / 1_000_000) * pricing["input"]
    output_cost = (response_usage["completion_tokens"] / 1_000_000) * pricing["output"]
    total_cost = input_cost + output_cost
    
    return {
        "input_cost_usd": round(input_cost, 6),
        "output_cost_usd": round(output_cost, 6),
        "total_cost_usd": round(total_cost, 6),
        "savings_vs_openai": round((response_usage["total_tokens"] / 1_000_000) * 30.0 - total_cost, 2)
    }

def batch_process_with_cost_tracking(api_responses, model):
    """
    Xử lý hàng loạt và theo dõi chi phí
    """
    total_prompt_tokens = 0
    total_completion_tokens = 0
    total_cost = 0
    
    results = []
    for resp in api_responses:
        cost_info = calculate_cost(resp["usage"], model)
        results.append({
            "content": resp["content"],
            "cost": cost_info
        })
        
        total_prompt_tokens += resp["usage"]["prompt_tokens"]
        total_completion_tokens += resp["usage"]["completion_tokens"]
        total_cost += cost_info["total_cost_usd"]
    
    return {
        "results": results,
        "summary": {
            "total_requests": len(api_responses),
            "total_prompt_tokens": total_prompt_tokens,
            "total_completion_tokens": total_completion_tokens,
            "total_cost_usd": round(total_cost, 4),
            "avg_cost_per_request": round(total_cost / len(api_responses), 6)
        }
    }

Ví dụ sử dụng
sample_response = {
    "content": "Đây là câu trả lời mẫu",
    "usage": {
        "prompt_tokens": 1500,
        "completion_tokens": 800,
        "total_tokens": 2300
    }
}

cost = calculate_cost(sample_response["usage"], "deepseek-v3.2")
print(f"Chi phí input: ${cost['input_cost_usd']}")
print(f"Chi phí output: ${cost['output_cost_usd']}")
print(f"Tổng chi phí: ${cost['total_cost_usd']}")
print(f"So với OpenAI tiết kiệm: ${cost['savings_vs_openai']}")

Với model DeepSeek V3.2 giá chỉ **$0.42/MTok** so với $15-30/MTok tại nhà cung cấp Mỹ, đội ngũ của tôi đã giảm chi phí từ $12,000 xuống còn **$1,680/tháng** — tiết kiệm hơn 85%.

Xử lý streaming response

Với các ứng dụng cần phản hồi real-time, streaming là lựa chọn tối ưu. Dưới đây là cách xử lý:

import sseclient
import requests
from typing import Iterator

def stream_chat_completion(messages, model="gpt-4o"):
    """
    Xử lý streaming response từ HolySheep AI
    """
    base_url = "https://api.holysheep.ai/v1"
    api_key = "YOUR_HOLYSHEEP_API_KEY"
    
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "model": model,
        "messages": messages,
        "stream": True,
        "max_tokens": 2000
    }
    
    response = requests.post(
        f"{base_url}/chat/completions",
        headers=headers,
        json=payload,
        stream=True
    )
    
    accumulated_content = ""
    finish_reason = None
    total_tokens = 0
    
    # Parse SSE stream
    for line in response.iter_lines():
        if line:
            line_text = line.decode('utf-8')
            
            # Bỏ qua comments
            if line_text.startswith(':'):
                continue
            
            # Parse JSON data
            if line_text.startswith('data: '):
                data_str = line_text[6:]  # Remove 'data: ' prefix
                
                if data_str == '[DONE]':
                    break
                
                try:
                    chunk = json.loads(data_str)
                    
                    # Parse streaming chunk
                    delta = chunk.get("choices", [{}])[0].get("delta", {})
                    content = delta.get("content", "")
                    if content:
                        accumulated_content += content
                        yield {"type": "content", "data": content}
                    
                    # Lấy finish_reason khi hoàn thành
                    finish_reason = chunk.get("choices", [{}])[0].get("finish_reason")
                    
                    # Parse usage từ chunk cuối cùng
                    if chunk.get("usage"):
                        yield {"type": "usage", "data": chunk["usage"]}
                        
                except json.JSONDecodeError:
                    continue
    
    yield {
        "type": "done",
        "data": {
            "content": accumulated_content,
            "finish_reason": finish_reason
        }
    }

Sử dụng streaming
messages = [
    {"role": "user", "content": "Viết code Python để parse JSON"}
]

for event in stream_chat_completion(messages):
    if event["type"] == "content":
        print(event["data"], end="", flush=True)
    elif event["type"] == "done":
        print(f"\n\nHoàn thành với finish_reason: {event['data']['finish_reason']}")

Các trường finish_reason đặc biệt cần xử lý

Trường finish_reason cho biết lý do phản hồi kết thúc:

• stop: Model kết thúc tự nhiên do hoàn thành câu trả lời
• length: Đạt giới hạn max_tokens — cần tăng limit hoặc tối ưu prompt
• content_filter: Content bị filter do vi phạm policy
• function_call: Model yêu cầu gọi function (với function calling)

def handle_finish_reason(finish_reason, content, max_retries=3):
    """
    Xử lý các trường hợp finish_reason đặc biệt
    """
    if finish_reason == "stop":
        return {"status": "success", "content": content}
    
    elif finish_reason == "length":
        return {
            "status": "truncated",
            "content": content,
            "warning": "Response bị cắt do đạt giới hạn max_tokens"
        }
    
    elif finish_reason == "content_filter":
        return {
            "status": "filtered",
            "content": None,
            "error": "Content bị filter. Vui lòng thay đổi prompt."
        }
    
    else:
        return {
            "status": "unknown",
            "content": content,
            "finish_reason": finish_reason
        }

Lỗi thường gặp và cách khắc phục

1. Lỗi 401 Unauthorized — API Key không hợp lệ

**Nguyên nhân**: API key chưa được set đúng hoặc hết hạn.

# ❌ Sai - Key bị ghi đè hoặc sai format
headers = {
    "Authorization": "Bearer YOUR_HOLYSHEEP_API_KEY"  # Key chưa được thay thế
}

✅ Đúng - Sử dụng biến môi trường
import os

api_key = os.environ.get("HOLYSHEEP_API_KEY")
if not api_key:
    raise ValueError("HOLYSHEEP_API_KEY chưa được set")

headers = {
    "Authorization": f"Bearer {api_key}"
}

Kiểm tra key trước khi gọi
def verify_api_key(api_key):
    """Xác minh API key có hợp lệ không"""
    test_response = requests.get(
        "https://api.holysheep.ai/v1/models",
        headers={"Authorization": f"Bearer {api_key}"}
    )
    if test_response.status_code == 401:
        raise Exception("API Key không hợp lệ hoặc đã hết hạn. Vui lòng kiểm tra tại https://www.holysheep.ai/register")
    return True

2. Lỗi 429 Rate Limit — Quá nhiều request

**Nguyên nhân**: Vượt quota hoặc rate limit của tài khoản.

import time
from functools import wraps

def handle_rate_limit(max_retries=5, base_delay=1):
    """
    Decorator xử lý rate limit với exponential backoff
    """
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    if "429" in str(e) or "rate limit" in str(e).lower():
                        delay = base_delay * (2 ** attempt)
                        print(f"Rate limit hit. Đợi {delay}s trước retry {attempt + 1}/{max_retries}")
                        time.sleep(delay)
                    else:
                        raise
            raise Exception(f"Failed after {max_retries} retries")
        return wrapper
    return decorator

@handle_rate_limit(max_retries=5, base_delay=2)
def call_api_with_retry(messages, model="gpt-4o"):
    """Gọi API với retry logic"""
    response = requests.post(
        "https://api.holysheep.ai/v1/chat/completions",
        headers={
            "Authorization": f"Bearer {os.environ.get('HOLYSHEEP_API_KEY')}",
            "Content-Type": "application/json"
        },
        json={
            "model": model,
            "messages": messages
        },
        timeout=30
    )
    
    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        raise Exception(f"429: Rate limit. Retry after {retry_after}s")
    
    if response.status_code != 200:
        raise Exception(f"API Error {response.status_code}: {response.text}")
    
    return response.json()

3. Lỗi Empty Response — choices array rỗng

**Nguyên nhân**: Prompt bị filter, model không hiểu request, hoặc lỗi server.

def safe_parse_response(response_data):
    """
    Parse response an toàn, xử lý trường hợp choices rỗng
    """
    if not response_data:
        return {
            "success": False,
            "error": "Response trống - có thể do timeout hoặc lỗi mạng"
        }
    
    choices = response_data.get("choices", [])
    
    if not choices:
        # Kiểm tra error trong response
        error = response_data.get("error", {})
        if error:
            return {
                "success": False,
                "error": error.get("message", "Unknown error")
            }
        
        # Kiểm tra xem có phải do nội dung bị filter không
        return {
            "success": False,
            "error": "Choices array rỗng. Có thể do content_filter hoặc lỗi server."
        }
    
    first_choice = choices[0]
    message = first_choice.get("message", {})
    
    return {
        "success": True,
        "content": message.get("content", ""),
        "finish_reason": first_choice.get("finish_reason"),
        "usage": response_data.get("usage", {})
    }

Sử dụng với error handling đầy đủ
response = call_api_with_retry(messages)
result = safe_parse_response(response)

if result["success"]:
    print(f"Câu trả lời: {result['content']}")
else:
    print(f"Lỗi: {result['error']}")
    # Retry với prompt khác hoặc báo cáo cho team

Kinh nghiệm thực chiến từ quá trình migration

Sau 3 tháng vận hành production với HolySheep AI, đội ngũ tôi rút ra một số bài học quý giá: **Về chi phí**: Với 500,000 request/tháng và trung bình 2,000 tokens/request, chi phí trước đây là **$12,000/tháng**. Sau khi chuyển sang HolySheep với bảng giá 2026 (GPT-4o: $8/MTok, DeepSeek V3.2: $0.42/MTok), chi phí chỉ còn **$1,680/tháng** — tiết kiệm 86%. **Về độ trễ**: Độ trễ trung bình đo được từ server Việt Nam đến HolySheep API là **35-45ms**, thấp hơn đáng kể so với 180-250ms khi gọi trực tiếp API Mỹ. **Về thanh toán**: HolySheep hỗ trợ WeChat và Alipay, rất thuận tiện cho các công ty Việt Nam không có thẻ quốc tế. Tỷ giá ¥1=$1 giúp tính chi phí dễ dàng. **Về rollback**: Chúng tôi giữ logic detection tự động chuyển về API chính thức nếu HolySheep không khả dụng:

class AIMultiProvider:
    def __init__(self):
        self.providers = {
            "holysheep": {
                "base_url": "https://api.holysheep.ai/v1",
                "api_key": os.environ.get("HOLYSHEEP_API_KEY"),
                "priority": 1
            },
            "openai": {
                "base_url": "https://api.openai.com/v1",
                "api_key": os.environ.get("OPENAI_API_KEY"),
                "priority": 2
            }
        }
    
    async def call_with_fallback(self, messages, model="gpt-4o"):
        """Gọi API với fallback tự động"""
        sorted_providers = sorted(
            self.providers.items(),
            key=lambda x: x[1]["priority"]
        )
        
        errors = []
        for name, config in sorted_providers:
            try:
                result = await self._call_api(config, messages, model)
                # Log thành công để theo dõi
                logger.info(f"Success with {name}")
                return {"provider": name, "data": result}
            except Exception as e:
                errors.append(f"{name}: {str(e)}")
                logger.warning(f"Failed with {name}: {e}")
                continue
        
        raise Exception(f"All providers failed: {errors}")

Bảng so sánh chi phí và hiệu suất

| Provider | Giá GPT-4o ($/MTok) | Độ trễ TB | Thanh toán | Quota | |----------|---------------------|-----------|------------|-------| | OpenAI | $15 input, $60 output | 180-250ms | Credit Card | 500 RPM | | **HolySheep AI** | **$8/$8** | **35-45ms** | **WeChat/Alipay** | **Tùy gói** | Với cùng volume 500,000 request/tháng, **HolySheep tiết kiệm 85%+ chi phí** và độ trễ thấp hơn 4-5 lần. 👉 **Đăng ký HolySheep AI — nhận tín dụng miễn phí khi đăng ký** tại https://www.holysheep.ai/register