Phản hồi JSON và độ tin cậy trong API V2

Hiểu phản hồi JSON

Phản hồi đơn lẻ thành công chứa data và meta. Ví dụ tập dữ liệu sau đây là phản hồi thực được ghi lại ngày 1 tháng 10 năm 2026 bằng khóa API; chỉ số dư tài khoản đã được thay thế. Ví dụ không thể hiện độ chính xác đã đo của sản phẩm, và một yêu cầu trực tiếp có thể trả về kết quả khác. Yêu cầu dùng khóa API trả về access.mode: api_key và null ở các trường hạn mức chỉ dành cho dùng thử; yêu cầu dùng thử theo IP trả về ip_trial cùng giới hạn dùng thử và thời điểm đặt lại.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Tuấn",
      "country": "VN"
    },
    "name": "tuấn",
    "gender": "male",
    "country": "VN",
    "confidence": 0.9915730337078652,
    "confidence_kind": "observed_frequency",
    "sample_count": 356,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "tuấn",
      "method": "normalized",
      "scope": "country",
      "country": "VN"
    }
  },
  "meta": {
    "request_id": "6630814b-b7c8-4e85-860d-dacee06d0d8c",
    "duration_ms": 11,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

• Lược đồ phản hồi đầy đủ và ví dụ lô

Trường phản hồi dự đoán

Các trường đầu vào được trả về

Các trường so khớp tập dữ liệu

Siêu dữ liệu về truy cập, tính phí và yêu cầu

Kết quả không xác định thành công

HTTP 200 nghĩa là thao tác đã hoàn tất; mã này không bảo đảm có giới tính. Giữ nguyên JSON null thay vì chuyển thành male, female, chuỗi rỗng hoặc độ tin cậy bằng 0. Kiểm tra data.result_status và data.reason tách biệt với lỗi HTTP.

Ví dụ thực chỉ dùng tập dữ liệu này, được ghi lại ngày 1 tháng 10 năm 2026, trả về source: none và reason: not_found và vẫn tốn 1 tín dụng. Một dòng tập dữ liệu có số lượng bằng nhau có thể trả về reason: ambiguous mà vẫn giữ sample_count. Kết quả AI không xác định dùng source: ai và reason: insufficient_evidence.

{
  "data": {
    "input": {
      "type": "name",
      "value": "zzzxxyy",
      "country": null
    },
    "name": null,
    "gender": null,
    "country": null,
    "confidence": null,
    "confidence_kind": null,
    "sample_count": null,
    "source": "none",
    "result_status": "unknown",
    "reason": "not_found",
    "country_source": null,
    "match": {
      "name": null,
      "method": null,
      "scope": null,
      "country": null
    }
  },
  "meta": {
    "request_id": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
    "duration_ms": 10,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Diễn giải độ tin cậy và bằng chứng so khớp

Độ tin cậy 0.9 nằm trên thang từ 0 đến 1. Với observed_frequency, giá trị này là số lượng của nhóm chiếm ưu thế chia cho tổng số của dòng tập dữ liệu được chọn; đây không phải độ chính xác toàn trình đã đo của sản phẩm. Điểm model_reported do AI cung cấp và không được hiệu chỉnh theo tần suất của tập dữ liệu.

Hãy chọn mọi ngưỡng của ứng dụng dựa trên dữ liệu đánh giá của riêng bạn và confidence_kind. Không xếp hạng trực tiếp điểm của tập dữ liệu và của AI như thể chúng đo cùng một thứ. Với AI, match.name, match.scope và match.country là null vì không có dòng tập dữ liệu nào được chọn; match.method là model_inference.

Với họ tên đầy đủ, kết quả tập dữ liệu có thể đến từ một thành phần thay vì toàn bộ chuỗi. data.input giữ nguyên giá trị đã gửi; data.name mô tả tên được trả về, còn data.match mô tả ứng viên và phạm vi tra cứu.

Quyết định bước tiếp theo cho ứng dụng của bạn

Trước tiên, hãy xử lý lỗi của yêu cầu và của từng mục, sau đó kiểm tra result_status. Với một dự đoán đơn lẻ, hãy đọc data; với một lô, hãy áp dụng cùng quyết định cho data của từng mục thành công. Giữ nguyên kết quả không xác định trong ứng dụng thay vì ép gán nhãn male hoặc female.

• Phân biệt lỗi vận hành với kết quả không xác định
• Áp dụng các quyết định này cho một lô

Chọn ngưỡng dựa trên đánh giá của chính bạn

Không có ngưỡng độ tin cậy chung nào khiến một dự đoán trở nên chính xác. Hãy đánh giá riêng observed_frequency và model_reported trên các ví dụ đại diện cho trường hợp sử dụng của bạn và được gắn nhãn độc lập. Tần suất trong tập dữ liệu và điểm do AI tự báo cáo là hai tín hiệu khác nhau, kể cả khi cả hai tình cờ đều là 0.9. Hãy đo tần suất chính sách của bạn đưa ra câu trả lời và tần suất các dự đoán được trả lời đó là đúng; với mọi trường hợp còn lại, hãy giữ kết quả không xác định hoặc chuyển sang xem xét.

Ví dụ, nếu result_status là identified nhưng confidence_kind là model_reported, hãy áp dụng chính sách AI đã được bạn đánh giá thay vì ngưỡng của tập dữ liệu. Nếu đã dùng forceToGenderize, name: null đi kèm gender khác null là hợp lệ: một bí danh có thể được suy luận mà không cần trích xuất tên thật. Hãy kiểm tra gender và result_status, không chỉ riêng name, để biết suy luận có đưa ra câu trả lời hay không. Đây vẫn là một ước tính, không phải xác minh danh tính của một người.

• Chỉ số đánh giá và giới hạn của độ tin cậy
• Hồ sơ tập dữ liệu và giới hạn của bằng chứng
• Suy luận biệt danh và name có thể là null

Hướng dẫn liên quan

• Phản hồi của lô và lỗi của từng mục
• Trạng thái tính phí và tín dụng còn lại
• Tính tương thích của phản hồi và thử lại