Structured Output

Yêu cầu mô hình trả về dữ liệu có cấu trúc để chương trình dễ phân tích và kiểm tra tính hợp lệ.

Structured Output giúp mô hình trả kết quả theo cấu trúc dữ liệu dự kiến, để chương trình dễ trích xuất trường, ghi vào cơ sở dữ liệu hoặc chuyển sang quy trình tiếp theo. Các trường hợp phổ biến gồm phân loại yêu cầu hỗ trợ, trích xuất biểu mẫu, kết quả kiểm duyệt nội dung và báo cáo phân tích có cấu trúc cố định.

Structured Output và Tool Calling giải quyết các vấn đề khác nhau

Sử dụng Structured Output khi cần mô hình trả lời có cấu trúc; sử dụng Tool Calling khi cần mô hình chọn và yêu cầu ứng dụng thực thi một hàm. Tham số công cụ cũng có thể được ràng buộc bằng Schema, nhưng thuộc chu trình gọi công cụ.

Chọn cách xuất kết quả phù hợp trước

Cách thức	Vấn đề được giải quyết	Việc ứng dụng vẫn cần làm
Yêu cầu JSON trong prompt	Cung cấp ràng buộc cơ bản cho mô hình không hỗ trợ trường chuyên dụng	Trích xuất JSON, phân tích, kiểm tra tính hợp lệ và thử lại khi thất bại
JSON Object	Yêu cầu mô hình xuất đối tượng JSON hợp lệ	Xác thực trường, kiểu dữ liệu và quy tắc nghiệp vụ
JSON Schema	Cung cấp cấu trúc đích trong yêu cầu	Xử lý phạm vi hỗ trợ của mô hình, từ chối, cắt ngắn và lỗi kiểm tra tính hợp lệ

Việc hỗ trợ JSON Object, JSON Schema hoặc tuân thủ nghiêm ngặt phụ thuộc vào mô hình và giao thức hiện tại. Không cho rằng Schema đã có hiệu lực chỉ vì yêu cầu trả về 200.

Định nghĩa Schema nhỏ và rõ ràng

Cấu trúc sau dùng để phân loại vấn đề của khách hàng thành yêu cầu hỗ trợ:

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account"]
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "summary": {
      "type": "string"
    }
  },
  "required": ["category", "priority", "summary"],
  "additionalProperties": false
}

Tên trường cần ổn định và dễ hiểu, giá trị enum phải nhất quán với mã nghiệp vụ. Tránh cấu trúc lồng quá sâu, quá nhiều nhánh tùy chọn hoặc ràng buộc biểu thức chính quy khó giải thích ngay từ đầu.

Trả kết quả có cấu trúc bằng Chat Completions

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "API Key của tôi không sử dụng được, hãy giúp tôi phân loại vấn đề."
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "category": {
              "type": "string",
              "enum": ["billing", "technical", "account"]
            },
            "priority": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3
            },
            "summary": {"type": "string"}
          },
          "required": ["category", "priority", "summary"],
          "additionalProperties": false
        }
      }
    }
  }'

strict là một phần của định dạng đích, nhưng khả năng sử dụng vẫn phụ thuộc vào mô hình. Xem các trường đầy đủ trong Chat Completions Reference.

Vị trí trường trong các giao thức

Chat chọn json_object hoặc json_schema trong response_format. Khi dùng JSON Schema, Schema nằm ở response_format.json_schema.schema.

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "schema": {"type": "object"}
    }
  }
}

Không sao chép trực tiếp các cấu trúc này sang giao thức khác. Trước khi sử dụng, xem Responses Reference và Gemini Generate Content Reference.

Vẫn phải kiểm tra tính hợp lệ sau khi phân tích

type SupportTicket = {
  category: 'billing' | 'technical' | 'account';
  priority: number;
  summary: string;
};

function parseTicket(raw: string): SupportTicket {
  const value: unknown = JSON.parse(raw);

  if (
    typeof value !== 'object' ||
    value === null ||
    !('category' in value) ||
    !('priority' in value) ||
    !('summary' in value)
  ) {
    throw new Error('Kết quả có cấu trúc thiếu trường bắt buộc');
  }

  return value as SupportTicket;
}

Ví dụ trên chỉ minh họa kiểm tra tối thiểu. Dự án thực tế cần dùng bộ kiểm tra tính hợp lệ của Schema nhất quán với mô hình dữ liệu nghiệp vụ, đồng thời kiểm tra enum, độ dài, phạm vi số và quy tắc giữa các trường.

Xử lý kết quả chưa hoàn chỉnh và không hợp lệ

Hiện tượng	Cách xử lý
Trả về văn bản thông thường	Kiểm tra mô hình hỗ trợ định dạng đích, vị trí trường và việc SDK có thay đổi yêu cầu hay không
Không phân tích được JSON	Lưu phản hồi đã che thông tin nhạy cảm và lý do dừng; thử lại có giới hạn theo chính sách nghiệp vụ
Thiếu trường bắt buộc	Coi là lỗi kiểm tra tính hợp lệ; không âm thầm dùng giá trị mặc định để che việc thiếu dữ liệu quan trọng
Đầu ra bị cắt ngắn	Điều chỉnh ngân sách đầu ra hoặc đơn giản hóa Schema; không đoán và ghép phần JSON bị thiếu
Mô hình từ chối trả lời	Xử lý từ chối riêng; không coi văn bản từ chối là đối tượng nghiệp vụ
Phân tích được Schema nhưng dữ liệu không hợp lệ về nghiệp vụ	Dùng kiểm tra quy tắc nghiệp vụ để trả lỗi rõ ràng hoặc chuyển sang xử lý thủ công

Kiểm tra trước khi đưa vào production

Schema và định nghĩa kiểu trong ứng dụng được tạo từ cùng nguồn hoặc được giữ đồng bộ.
Trước khi đổi mô hình, kiểm tra lại giao thức, tập con Schema và hỗ trợ chế độ nghiêm ngặt.
Các trường hợp lỗi phân tích, từ chối, cắt ngắn và đầu ra rỗng đều có nhánh xử lý riêng.
Kết quả có cấu trúc được kiểm tra tính hợp lệ lại trước khi ghi vào cơ sở dữ liệu hoặc kích hoạt thao tác nghiệp vụ.
Nhật ký chỉ lưu thông tin đã che dữ liệu nhạy cảm cần thiết để khắc phục sự cố.

Sau khi kiểm tra mô hình trong Danh mục mô hình, xem các trường đầy đủ trong API Reference tương ứng; khi yêu cầu thất bại, xem Lỗi và khắc phục sự cố.