Claude Certification Guide

Structured Outputs đã chính thức GA trên Claude API

24 tháng 3, 2026 · 8 phút đọc

Anthropic đã chuyển structured outputs từ beta sang general availability (GA). Nếu bạn từng phải truyền header anthropic-beta: output-128k-2025-02-19 để đảm bảo tuân thủ JSON schema, bạn có thể bỏ nó đi. Structured outputs giờ đây là một tính năng API hạng nhất, không cần cờ beta.

Lưu ý: Kỳ thi kiểm tra các mẫu structured output (Domain 4) — việc chuyển sang trạng thái GA không thay đổi các khái niệm được kiểm tra, nhưng nó có nghĩa là bạn không còn cần truyền header beta trong môi trường sản xuất nữa.

Những gì đã thay đổi từ beta sang GA

Ba điều:

  1. Không còn header beta. Header anthropic-beta không còn bắt buộc. Các tham số structured output hoạt động trực tiếp trong API tiêu chuẩn.

  2. Hỗ trợ schema mở rộng. Bản GA hỗ trợ một tập hợp tính năng JSON Schema rộng hơn bao gồm anyOf, oneOf, các định nghĩa $ref lồng nhau, và schema mảng phức tạp hơn. Trong giai đoạn beta, một số tính năng này sẽ âm thầm rơi về chế độ best-effort. Giờ đây chúng được thực thi đầy đủ.

  3. Cải thiện độ trễ biên dịch grammar. Khi bạn gửi một JSON schema, API biên dịch nó thành một grammar bị ràng buộc để định hướng việc sinh token. Trong giai đoạn beta, các schema phức tạp có thể làm tăng đáng kể độ trễ ở yêu cầu đầu tiên. Bản GA có tốc độ biên dịch nhanh hơn, đặc biệt với các schema lồng sâu hoặc có nhiều property.

Structured outputs hoạt động như thế nào

Structured outputs đảm bảo phản hồi của Claude tuân thủ một JSON schema mà bạn cung cấp. Đây không phải là kiểu dựa trên prompt — không phải kiểu "làm ơn hãy xuất ra JSON." API ràng buộc việc sinh token ở tầng giải mã sao cho đầu ra không thể vi phạm schema của bạn. Mọi key, mọi kiểu dữ liệu, mọi trường bắt buộc đều được thực thi.

Có hai cách để dùng tính năng này.

Thực thi JSON schema trực tiếp

Truyền tham số response_format cùng với schema của bạn:

pythonCopy

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Analyse this customer review and extract sentiment, key topics, and urgency level: 'The product arrived damaged and support hasn't responded in 3 days. Very frustrated.'"
        }
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "review_analysis",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "sentiment": {
                        "type": "string",
                        "enum": ["positive", "negative", "neutral", "mixed"]
                    },
                    "topics": {
                        "type": "array",
                        "items": {"type": "string"}
                    },
                    "urgency": {
                        "type": "string",
                        "enum": ["low", "medium", "high", "critical"]
                    },
                    "summary": {
                        "type": "string"
                    }
                },
                "required": ["sentiment", "topics", "urgency", "summary"],
                "additionalProperties": False
            }
        }
    }
)

Phản hồi được đảm bảo là JSON hợp lệ khớp với schema đó. Bạn sẽ luôn nhận được một sentiment từ enum, một mảng topics, một mức urgency, và một summary. Không lỗi parse, không thiếu trường, không có sự diễn giải sáng tạo nào khác đối với cấu trúc của bạn.

Structured outputs qua tool_use

Cách tiếp cận thứ hai dùng định nghĩa tool với input_schema. Khi Claude gọi một tool, đầu vào nó sinh ra đã bị ràng buộc bởi schema bạn định nghĩa trong input_schema của tool. Đây là mẫu chuẩn cho việc trích xuất có cấu trúc kể từ khi tính năng tool_use ra mắt.

pythonCopy

response = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    tools=[
        {
            "name": "extract_order_details",
            "description": "Extract structured order information from customer messages.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "Order number in format ORD-XXXXX"
                    },
                    "issue_type": {
                        "type": "string",
                        "enum": ["refund", "exchange", "tracking", "damage", "other"]
                    },
                    "amount": {
                        "type": "number",
                        "description": "Order amount if mentioned"
                    },
                    "requires_escalation": {
                        "type": "boolean"
                    }
                },
                "required": ["order_id", "issue_type", "requires_escalation"]
            }
        }
    ],
    tool_choice={"type": "tool", "name": "extract_order_details"},
    messages=[
        {
            "role": "user",
            "content": "I need a refund for order ORD-44821, it was $129.99 and arrived completely smashed."
        }
    ]
)

Dùng tool_choice để buộc chọn một tool cụ thể biến lệnh gọi tool thành một bước trích xuất có cấu trúc. Mô hình bắt buộc phải gọi tool đó, và đầu vào phải tuân thủ schema. Điều này cho bạn cùng một sự đảm bảo như response_format nhưng đi qua cơ chế tool_use.

Nên dùng cách tiếp cận nào

Dùng response_format khi bạn muốn câu trả lời trực tiếp của Claude ở dạng có cấu trúc. Dùng tool_use với việc buộc chọn tool khi bạn đang tích hợp việc trích xuất vào một luồng công việc agentic, nơi dữ liệu có cấu trúc đó sẽ được đưa vào các lệnh gọi tool hoặc bước agent tiếp theo.

Trong thực tế, tool_use phổ biến hơn trong các hệ thống sản xuất vì nó tích hợp tự nhiên với agentic tool loop. response_format gọn gàng hơn cho các tác vụ trích xuất độc lập, nơi bạn chỉ cần lấy dữ liệu có cấu trúc.

Xác thực vẫn quan trọng

Structured outputs đảm bảo tuân thủ schema — JSON sẽ hợp lệ và khớp với kiểu dữ liệu của bạn. Chúng không đảm bảo tính đúng đắn về ngữ nghĩa. Nếu bạn yêu cầu Claude trích xuất một mã đơn hàng và nó bịa ra một mã nghe có vẻ hợp lý nhưng không tồn tại, đầu ra vẫn sẽ tuân thủ schema của bạn. Nó vẫn là một chuỗi hợp lệ đúng định dạng. Chỉ là sai.

Luôn xác thực các giá trị đã trích xuất so với dữ liệu nguồn của bạn:

pythonCopy

import json
 
# Parse the structured output
tool_input = json.loads(response.content[0].input)
 
# Schema conformance is guaranteed — but verify the data
order = db.lookup_order(tool_input["order_id"])
if not order:
    # The model extracted a plausible but incorrect order ID
    handle_extraction_error(tool_input)

Đây là một điểm phân biệt quan trọng mà kỳ thi kiểm tra. Thực thi schema và xác thực ngữ nghĩa là hai mối quan tâm riêng biệt. Structured outputs xử lý điều đầu tiên. Mã ứng dụng của bạn xử lý điều thứ hai.

Điều này có ý nghĩa gì cho kỳ thi

Domain 4 kiểm tra các mẫu structured output — cụ thể là cách dùng JSON schema với API, khi nào dùng tool_use để trích xuất có cấu trúc, và cách xác thực đầu ra. Việc chuyển từ beta sang GA không thay đổi bất kỳ khái niệm nào trong số này. Các mẫu vẫn giống hệt; bạn chỉ không còn cần header beta nữa.

Các khái niệm liên quan đến kỳ thi:

  • Thiết kế schema: chọn đúng kiểu dữ liệu, dùng enum cho các giá trị bị ràng buộc, trường bắt buộc so với tùy chọn
  • tool_use như một cách trích xuất có cấu trúc: buộc gọi tool bằng tool_choice để đảm bảo đầu ra có cấu trúc
  • Phân tầng xác thực: hiểu rằng tuân thủ schema và tính đúng đắn về ngữ nghĩa là hai việc khác nhau
  • Khi nào structured outputs không phù hợp: các schema rất lớn với độ lồng sâu có thể làm tăng độ trễ; các tác vụ quá mở không được lợi từ schema cứng nhắc

Làm qua Domain 4 — Prompt Engineering & Structured Output để nắm đầy đủ, hoặc chuyển thẳng đến Task 4.4 — Structured Output để xem nội dung task cụ thể.