Chuyển đến nội dung
Đầu ra có cấu trúc

Đầu ra có cấu trúc

Yêu cầu câu trả lời dưới dạng JSON: một đối tượng JSON bất kỳ, hoặc JSON theo schema bạn gửi. Hãy dùng khi chương trình, chứ không phải con người, đọc phản hồi.

POST https://api.shannon-ai.com/v1/chat/completions

import json
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

response = client.chat.completions.create(
    model="Kimi-K3-3BIT-REAP",
    messages=[
        {"role": "user", "content": "Extract the person: John Doe, 30 years old, engineer."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "occupation": {"type": "string"},
                },
                "required": ["name", "age", "occupation"],
            },
        },
    },
)

# The JSON arrives as text in message.content: parse it, then check it.
try:
    person = json.loads(response.choices[0].message.content)
except json.JSONDecodeError:
    person = None  # ask again, or report the failure

print(person)

JSON là văn bản của câu trả lời, trong choices[0].message.content:

200 JSON
{
  "id": "chatcmpl-0c4e7a1b9d2f4e6a8b3c5d7e9f1a2b3c",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "Kimi-K3-3BIT-REAP",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"name\":\"John Doe\",\"age\":30,\"occupation\":\"engineer\"}",
        "reasoning_content": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 96,
    "completion_tokens": 19,
    "total_tokens": 115,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 0}
  }
}

Các chế độ của response_format

response_format là một trường của /v1/chat/completions. Không có nó, câu trả lời là văn bản thông thường.

Chế độ Giá trị Bạn nhận được gì
Đối tượng JSON {"type": "json_object"} Câu trả lời là JSON không có hình dạng quy định. Hãy nêu trong prompt những key bạn muốn.
JSON schema {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} Câu trả lời tuân theo schema bạn gửi: các key, kiểu và trường bắt buộc của nó.
Strict "strict": true Một trường của json_schema, không phải chế độ thứ ba. Nó là true trừ khi bạn gửi false.
Trường Loại Mặc định Mô tả Áp dụng bởi
type string json_object hoặc json_schema. Bắt buộc bên trong response_format. text được chấp nhận và cho câu trả lời văn bản thông thường. Mọi model nhận chế độ này
json_schema.schema object JSON Schema mà câu trả lời tuân theo. Hãy gửi nó bất cứ khi nào type là json_schema. Mọi model nhận chế độ này
json_schema.name string Nhãn cho schema, như trong định dạng OpenAI. Các model open-weight hosted
json_schema.strict boolean true Câu trả lời có phải tuân theo schema chính xác hay không. Các model Shannon áp dụng mọi schema ở chế độ strict. Các model open-weight hosted

Chế độ đối tượng JSON không cần schema. Hãy nêu các key trong prompt:

Nội dung yêu cầu
{
  "model": "shannon-3",
  "messages": [
    {
      "role": "user",
      "content": "Name the capital of France. Answer as JSON with the keys city and country."
    }
  ],
  "response_format": {"type": "json_object"}
}

Hỗ trợ theo từng model

Model json_object json_schema
Mọi model Shannon (shannon-*) Có Có
Các model open-weight hosted, trừ những model được nêu bên dưới Có Có
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP Có —

GET /v1/models báo cáo điều tương tự cho từng id: capabilities.json_schema trên mọi model, và capabilities.response_format trên các model open-weight hosted. Model và giá

Các từ khóa schema được hỗ trợ

Những gì model nhận được từ schema của bạn phụ thuộc vào model và endpoint:

Model /v1/chat/completions /v1/responses
Các model Shannon Tập con từ khóa bên dưới, được áp dụng ở chế độ strict. Schema đúng như bạn gửi, được áp dụng ở chế độ strict.
Các model open-weight hosted Schema đúng như bạn gửi. strict là true trừ khi bạn gửi nó. Schema đúng như bạn gửi. strict là true trừ khi bạn gửi nó.

Tập con từ khóa của các model Shannon trên /v1/chat/completions:

Từ khóa Cách nó được đọc
Từ khóa được đọc type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref Được phân giải từ $defs hoặc definitions ở cấp cao nhất của schema. Các từ khóa viết cạnh $ref, như description, được giữ lại. Tham chiếu không có định nghĩa tương ứng được đọc là {"type": "object"}.
allOf Các thành viên được gộp thành một schema. Khi hai thành viên đặt cùng một từ khóa, thành viên sau được ưu tiên.
oneOf Được đọc như anyOf.
Schema tham chiếu đến chính nó Được mở rộng đến 24 cấp. Cấp sâu hơn được đọc là {"type": "object"}.
Ngoài tập con Mọi từ khóa khác, ví dụ additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not và if / then / else. Chúng không nằm trong schema mà model nhận.

Trên /v1/responses: text.format

/v1/responses viết cùng yêu cầu đó là text.format. Schema nằm trực tiếp trong format, cạnh name và strict, không nằm dưới key json_schema. Với chế độ đối tượng JSON, hãy gửi {"format": {"type": "json_object"}}.

Nội dung yêu cầu
{
  "model": "Kimi-K3-3BIT-REAP",
  "input": "Extract the person: John Doe, 30 years old, engineer.",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "person",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "occupation": {"type": "string"}
        },
        "required": ["name", "age", "occupation"]
      }
    }
  }
}

JSON là text của phần output_text trong mục message:

200 JSON
{
  "output": [
    {
      "id": "msg_7e1d3c5b9a2f4d6e8c0b1a3f5e7d9c2b",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "{\"name\":\"John Doe\",\"age\":30,\"occupation\":\"engineer\"}",
          "annotations": []
        }
      ]
    }
  ]
}

Hỗ trợ theo từng model và các lỗi giống như trên /v1/chat/completions. Responses API

Trên /v1/messages: một tool làm schema

Định dạng Messages không có trường đầu ra có cấu trúc. Để lấy JSON từ cùng các model đó, hãy gọi /v1/chat/completions hoặc /v1/responses với cùng key.

Để ở lại trên /v1/messages, hãy mô tả đối tượng như một tool: đặt schema của bạn vào input_schema và nêu tên tool trong tool_choice. Khi đó input của khối tool_use là đối tượng của bạn, đã được phân tích sẵn. tool_choice có tên được áp dụng bởi các model open-weight hosted.

Nội dung yêu cầu
{
  "model": "Kimi-K3-3BIT-REAP",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Extract the person: John Doe, 30 years old, engineer."
    }
  ],
  "tools": [
    {
      "name": "record_person",
      "description": "Record the extracted person.",
      "input_schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "occupation": {"type": "string"}
        },
        "required": ["name", "age", "occupation"]
      }
    }
  ],
  "tool_choice": {"type": "tool", "name": "record_person"}
}
200 JSON
{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_4b8d2f6a1c3e4a5b9d7f0e2c4a6b8d1f",
      "name": "record_person",
      "input": {"name": "John Doe", "age": 30, "occupation": "engineer"}
    }
  ]
}

Hãy kiểm tra stop_reason là tool_use trước khi đọc khối. Gọi hàm

JSON đến như thế nào

  • JSON là một chuỗi. Phản hồi không có đối tượng đã phân tích đi kèm: hãy chạy trình phân tích JSON của bạn trên message.content.
  • Với stream: true, JSON đến thành từng đoạn delta.content. Hãy ghép chúng lại và phân tích sau khi stream kết thúc; một đoạn riêng lẻ không phải là JSON hợp lệ.
  • Model open-weight hosted trả lời yêu cầu có response_format mà không có văn bản suy luận: reasoning_content là null.

Kiểm tra những gì bạn nhận được

Schema định hướng cách model viết. API không so sánh câu trả lời hoàn chỉnh với schema của bạn, nên mã của bạn thực hiện bước kiểm tra cuối:

  • Hãy phân tích bên trong một trình xử lý lỗi, như ví dụ ở đầu trang.
  • Hãy xác thực đối tượng đã phân tích bằng cùng schema trong mã của bạn, ví dụ với thư viện JSON Schema, Pydantic hoặc Zod.
  • Một câu trả lời dài có thể kết thúc trước khi JSON hoàn chỉnh. Phản hồi không streaming chỉ báo cáo finish_reason là stop hoặc tool_calls, nên lỗi phân tích là tín hiệu. Hãy hỏi lại, hoặc yêu cầu một đối tượng nhỏ hơn.

Lỗi

Trạng thái Loại Thông báo Khi nào
400 invalid_request_error <id> does not accept response_format Model không nhận chế độ nào trong hai chế độ.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Model nhận json_object và bạn đã gửi json_schema.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … response_format không có type, hoặc không phải là đối tượng JSON.

Hai phản hồi 400 được gửi trước khi có gì bị trừ khỏi số dư của bạn. Xử lý lỗi