Đầu ra có cấu trúc với API tương thích OpenAI: hướng dẫn JSON Schema

Hướng dẫn thực tế để áp dụng JSON Schema nghiêm ngặt trong Responses và Chat Completions, xác thực kết quả, xử lý lỗi và kiểm thử từng tuyến.

Đầu ra có cấu trúc với API tương thích OpenAI: hướng dẫn JSON Schema

Structured Outputs cho phép ứng dụng yêu cầu JSON tuân theo một lược đồ xác định, thay vì chỉ bảo mô hình “trả về JSON”. Với API tương thích OpenAI, cùng một JSON Schema có thể dùng qua Responses hoặc Chat Completions, nhưng cấu trúc bao ngoài khác nhau và phải xác minh trên đúng mô hình cùng tuyến gọi thực tế.

Mẫu triển khai an toàn trong môi trường vận hành có ba lớp: dùng strict khi mô hình hỗ trợ, phân tích cú pháp và xác thực lại JSON trong ứng dụng, sau đó áp dụng quy tắc nghiệp vụ mang tính xác định. Tuân thủ lược đồ giúp giảm lỗi định dạng nhưng không chứng minh câu trả lời đúng về mặt sự thật hoặc ngữ nghĩa.

Structured Outputs không phải chế độ JSON

Phương pháp JSON hợp lệ Bắt buộc theo lược đồ Trường hợp sử dụng
Chỉ dùng câu lệnh Không được bảo đảm Không Bản thử nghiệm chấp nhận lỗi phân tích cú pháp
Chế độ JSON Có nếu được hỗ trợ và quá trình sinh hoàn tất Không JSON linh hoạt do ứng dụng xác thực
Structured Outputs với strict: true Có, nếu xử lý trạng thái hoàn tất và từ chối Có trong phạm vi được hỗ trợ Trích xuất có kiểu và quy trình ứng dụng

Hướng dẫn OpenAI Structured Outputs khuyến nghị cách này thay cho chế độ JSON khi mô hình và điểm cuối hỗ trợ. Định dạng phản hồi có cấu trúc trả về một đối tượng dữ liệu có thể dự đoán; Function Calling yêu cầu ứng dụng thực hiện hành động. Lược đồ có thể tương tự, nhưng mã định danh lệnh gọi và thông điệp kết quả thuộc hợp đồng khác.

Định nghĩa lược đồ trước khi chọn điểm cuối

Quy trình phân loại yêu cầu hỗ trợ cần bốn trường:

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

Đặt mọi thuộc tính là bắt buộc và dùng additionalProperties: false sẽ tạo ra đối tượng ổn định cho bước xử lý sau. Điều đó không có nghĩa mọi từ khóa JSON Schema đều dùng được ở mọi nhà cung cấp. OpenAI hỗ trợ phạm vi được ghi rõ; nhà cung cấp khác có thể hỗ trợ phạm vi khác hoặc không có chế độ lược đồ nghiêm ngặt.

Gửi lược đồ bằng Responses API

Responses đặt lược đồ dưới text.format:

export MODELFLARE_API_KEY="<YOUR_API_KEY>"
export MODEL_ID="<MODEL_WITH_VERIFIED_STRUCTURED_OUTPUT_SUPPORT>"

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL_ID\",
    \"input\": \"Khách hàng bị tính phí hai lần và muốn được hoàn tiền.\",
    \"text\": {
      \"format\": {
        \"type\": \"json_schema\",
        \"name\": \"support_ticket\",
        \"schema\": {
          \"type\": \"object\",
          \"properties\": {
            \"category\": {
              \"type\": \"string\",
              \"enum\": [\"billing\", \"technical\", \"account\"]
            },
            \"priority\": {
              \"type\": \"integer\",
              \"minimum\": 1,
              \"maximum\": 3
            },
            \"requires_human\": { \"type\": \"boolean\" },
            \"summary\": { \"type\": \"string\" }
          },
          \"required\": [\"category\", \"priority\", \"requires_human\", \"summary\"],
          \"additionalProperties\": false
        },
        \"strict\": true
      }
    }
  }"

Gửi tới POST https://modelflare.dev/v1/responses với Authorization: Bearer <YOUR_API_KEY>. Nội dung sinh ra nằm trong các mục đầu ra có kiểu. SDK có thể cung cấp hàm hỗ trợ, nhưng máy khách HTTP vẫn phải tìm phần văn bản đã hoàn tất và phân tích cú pháp JSON một cách tường minh.

Gửi cùng lược đồ bằng Chat Completions

Chat Completions dùng response_format.json_schema:

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL_ID\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"Khách hàng bị tính phí hai lần và muốn được hoàn tiền.\"
      }
    ],
    \"response_format\": {
      \"type\": \"json_schema\",
      \"json_schema\": {
        \"name\": \"support_ticket\",
        \"schema\": {
          \"type\": \"object\",
          \"properties\": {
            \"category\": {
              \"type\": \"string\",
              \"enum\": [\"billing\", \"technical\", \"account\"]
            },
            \"priority\": {
              \"type\": \"integer\",
              \"minimum\": 1,
              \"maximum\": 3
            },
            \"requires_human\": { \"type\": \"boolean\" },
            \"summary\": { \"type\": \"string\" }
          },
          \"required\": [\"category\", \"priority\", \"requires_human\", \"summary\"],
          \"additionalProperties\": false
        },
        \"strict\": true
      }
    }
  }"

JSON thường là chuỗi tại choices[0].message.content và vẫn cần được phân tích cú pháp.

Mục đích Responses API Chat Completions
Vị trí lược đồ text.format response_format.json_schema
Loại định dạng text.format.type response_format.type
Tên lược đồ text.format.name response_format.json_schema.name
Nội dung lược đồ text.format.schema response_format.json_schema.schema
Chế độ nghiêm ngặt text.format.strict response_format.json_schema.strict
Kết quả Mục đầu ra / hàm hỗ trợ SDK choices[0].message.content

Lớp tương thích của Modelflare chuyển đổi hai cấu trúc bao ngoài trên các tuyến OpenAI/Codex được hỗ trợ, nhưng không thể tạo ra Structured Outputs trong mô hình thượng nguồn vốn không có tính năng này. Với Chat Completions được chuyển tiếp nguyên trạng, hợp đồng của nhà cung cấp là nguồn tham chiếu chính.

Xác thực cấu trúc và ý nghĩa riêng biệt

{
  "category": "billing",
  "priority": 2,
  "requires_human": true,
  "summary": "Khách hàng báo bị tính phí hai lần và yêu cầu hoàn tiền."
}

Xác thực cấu trúc

Trình xác thực JSON Schema kiểm tra các thuộc tính bắt buộc, thuộc tính ngoài dự kiến, kiểu dữ liệu, giá trị liệt kê và phạm vi. Ngay cả khi nhà cung cấp cam kết tuân thủ nghiêm ngặt, bước xác thực trong ứng dụng vẫn bảo vệ hệ thống trước tuyến không được hỗ trợ, lỗi tích hợp, đầu ra bị cắt ngắn và thay đổi hợp đồng.

Xác thực ngữ nghĩa và nghiệp vụ

Lược đồ không biết khách hàng có thật sự bị tính phí hai lần, priority: 2 có đúng hay ai được phép duyệt hoàn tiền. Hãy xem đối tượng là một đề xuất phân loại, so sánh với dữ liệu đáng tin cậy, rồi thực thi quyền hạn và giới hạn tài chính bằng mã xác định. JSON hợp lệ không được phép vượt qua cơ chế phân quyền, tính phí hoặc ranh giới bảo mật.

Xử lý đầu ra không đầy đủ và ngoại lệ

Từ chối

Kiểm tra trạng thái phản hồi và cách biểu diễn từ chối trước khi tìm JSON. Từ chối vì lý do an toàn không phải lỗi phân tích cú pháp.

Đầu ra bị cắt ngắn và giới hạn đầu ra

Nếu quá trình sinh dừng trước khi đối tượng được đóng, lược đồ không thể khôi phục phần còn thiếu. Kiểm tra trạng thái hoàn tất và lý do dừng, rồi đặt giới hạn đầu ra đủ dùng nhưng có mức trần.

Từ khóa không được hỗ trợ

Bắt đầu với đối tượng, mảng, kiểu nguyên thủy, giá trị liệt kê, thuộc tính bắt buộc và thuộc tính bổ sung được khai báo rõ ràng. Xem tài liệu nhà cung cấp trước khi dùng tham chiếu, đệ quy, kiểu hợp phức tạp hoặc quy tắc xác thực nâng cao.

Độ trễ khi dùng lược đồ lần đầu

Một số nhà cung cấp xử lý trước và lưu lược đồ mới vào bộ nhớ đệm. Hãy tái sử dụng lược đồ ổn định, có phiên bản và đo riêng lần sử dụng đầu tiên với trạng thái ổn định.

Mô hình hoặc tuyến gọi không tương thích

Điểm cuối có thể nhận Chat Completions thông thường nhưng từ chối json_schema hoặc bỏ qua strict. Phản hồi 200 có JSON không chứng minh việc tuân thủ nghiêm ngặt. Phải thử cả dữ liệu đầu vào không hợp lệ và trường hợp biên.

Chạy ma trận tương thích

Kiểm thử Bằng chứng cần lưu
Đối tượng bắt buộc tối thiểu Trạng thái, mô hình, tuyến, đối tượng đã phân tích, kết quả xác thực
Mọi giá trị liệt kê Sinh và phân tích từng giá trị
Thiếu thông tin Giá trị thay thế có giới hạn hoặc yêu cầu làm rõ
Đầu vào liên quan an toàn Định dạng từ chối và cách ứng dụng xử lý
Giới hạn đầu ra thấp Trạng thái hoàn tất và xử lý đầu ra bị cắt
Tính năng không được hỗ trợ Lỗi rõ ràng hoặc ràng buộc bị bỏ qua
Cấu trúc Responses và Chat Đối tượng ứng dụng tương đương
Lặp lại lược đồ ổn định Lần sử dụng đầu tiên so với trạng thái ổn định

Giữ nguyên lược đồ, câu lệnh, khu vực, chế độ truyền phát và giới hạn đầu ra, đồng thời ghi ngày kiểm thử.

Chọn điểm cuối sau khi thử quy trình

Dùng Responses cho các mục đầu ra có kiểu, sự kiện truyền phát hoặc quy trình công cụ rộng hơn. Dùng Chat Completions cho tích hợp dựa trên thông điệp khi tuyến hỗ trợ response_format. Xem Responses API và Chat Completions.

Dù chọn cách nào:

  1. giữ một bản JSON Schema chuẩn duy nhất và có phiên bản;
  2. chỉ thay cấu trúc bao ngoài, không thay ý nghĩa;
  3. xác thực phản hồi đã hoàn tất;
  4. áp dụng quy tắc nghiệp vụ xác định sau khi xác thực cấu trúc;
  5. theo dõi riêng lỗi phân tích cú pháp, từ chối, đầu ra bị cắt và lỗi tương thích.

Bắt đầu chuyển đổi với Hướng dẫn API tương thích OpenAI, và dùng Hướng dẫn truyền phát AI API cho luồng không đầy đủ. Kiểm tra Mô hình & Giá, sau đó thử Structured Outputs trên tuyến thực tế mà khóa API sẽ sử dụng.

Structured Outputs giới hạn phản hồi của mô hình thành một giao diện ứng dụng đáng tin cậy hơn, nhưng không thay thế việc xác minh sự thật, phân quyền hay logic tính phí. Tuyên bố “tương thích OpenAI” vẫn cần được kiểm thử theo từng tính năng.