Tính năng

Structured Outputs

Trạm AI hỗ trợ structured outputs trên các model tương thích, đảm bảo response luôn tuân theo một JSON Schema cụ thể. Tính năng này đặc biệt hữu ích khi cần response nhất quán, được định dạng gọn gàng và có thể parse một cách đáng tin cậy ngay trong ứng dụng của mình.

Tổng quan

Structured outputs cho phép:

  • Áp dụng kiểm tra JSON Schema cụ thể cho response của model
  • Nhận output nhất quán, type-safe outputs
  • Tránh lỗi parsing và những trường bịa đặt
  • Đơn giản hóa việc xử lý response trong ứng dụng

Sử dụng Structured Outputs

Để dùng structured outputs, người dùng thêm tham số response_format vào request, đặt type thành json_schema và đưa schema của mình vào đối tượng json_schema:

expandable lines
1{
2  "messages": [
3    { "role": "user", "content": "What's the weather like in London?" }
4  ],
5  "response_format": {
6    "type": "json_schema",
7    "json_schema": {
8      "name": "weather",
9      "strict": true,
10      "schema": {
11        "type": "object",
12        "properties": {
13          "location": {
14            "type": "string",
15            "description": "City or location name"
16          },
17          "temperature": {
18            "type": "number",
19            "description": "Temperature in Celsius"
20          },
21          "conditions": {
22            "type": "string",
23            "description": "Weather conditions description"
24          }
25        },
26        "required": ["location", "temperature", "conditions"],
27        "additionalProperties": false
28      }
29    }
30  }
31}

Model sẽ trả về một đối tượng JSON tuân thủ nghiêm ngặt schema:

lines
1{
2  "location": "London",
3  "temperature": 18,
4  "conditions": "Partly cloudy with light drizzle"
5}

Hỗ trợ Model

Structured outputs chỉ khả dụng trên một số model nhất định.

Người dùng có thể xem danh sách các model hỗ trợ structured outputs trên trang models.

  • Các model OpenAI (GPT-4o trở về sau) Tài liệu
  • Các model Google Gemini Tài liệu
  • Các model Anthropic (Sonnet 4.5, Opus 4.1+) Tài liệu
  • Hầu hết các model mã nguồn mở
  • Tất cả các model do Fireworks cung cấp Tài liệu

Để chắc chắn model được chọn có hỗ trợ structured outputs:

  1. Kiểm tra các tham số được hỗ trợ của model trên trang models
  2. Đặt require_parameters: true trong tùy chọn provider (xem Provider Routing)
  3. Thêm response_format và đặt type: json_schema trong các tham số bắt buộc

Hướng dẫn tối ưu

  1. Thêm description: Viết mô tả rõ ràng cho từng thuộc tính trong schema để định hướng cho model
  2. Dùng strict mode: Luôn đặt strict: true để model tuân theo schema một cách chính xác

Ví dụ triển khai

Dưới đây là một ví dụ hoàn chỉnh sử dụng Fetch API:

1import OpenAI from 'openai';
2
3const openai = new OpenAI({
4  baseURL: 'https://api.staging.tram.ai.vn/v1',
5  apiKey: '<TRAM_AI_API_KEY>',
6});
7
8const response = await openai.chat.completions.create({
9  model: 'openai/gpt-4o',
10  messages: [
11    { role: 'user', content: 'What is the weather like in London?' },
12  ],
13  responseFormat: {
14    type: 'json_schema',
15    jsonSchema: {
16      name: 'weather',
17      strict: true,
18      schema: {
19        type: 'object',
20        properties: {
21          location: {
22            type: 'string',
23            description: 'City or location name',
24          },
25          temperature: {
26            type: 'number',
27            description: 'Temperature in Celsius',
28          },
29          conditions: {
30            type: 'string',
31            description: 'Weather conditions description',
32          },
33        },
34        required: ['location', 'temperature', 'conditions'],
35        additionalProperties: false,
36      },
37    },
38  },
39  stream: false,
40});
41
42const weatherInfo = response.choices[0].message.content;

Streaming với Structured Outputs

Structured outputs cũng hoạt động với response dạng streaming. Model sẽ stream từng phần JSON hợp lệ, và khi hoàn tất sẽ ghép lại thành một response hợp lệ khớp với schema.

Để bật streaming cùng structured outputs, chỉ cần thêm stream: true vào request:

lines
1{
2  "stream": true,
3  "response_format": {
4    "type": "json_schema",
5    // ... rest of your schema
6  }
7}

Xử lý lỗi

Khi dùng structured outputs, có thể gặp những tình huống sau:

  1. Model không hỗ trợ structured outputs: Request sẽ thất bại kèm một lỗi cho biết model không hỗ trợ tính năng này
  2. Schema không hợp lệ: Model sẽ trả về lỗi nếu JSON Schema không hợp lệ

Response Healing

Đối với các request không streaming dùng response_format với type: "json_schema", người dùng có thể bật plugin Response Healing để giảm rủi ro nhận JSON không hợp lệ khi model trả về định dạng chưa hoàn chỉnh. Tìm hiểu thêm trong tài liệu Response Healing.