Aracılığıyla paylaş

Yapılandırılmış çıkışlar

Yapılandırılmış çıkışlar, modelin çıkarım API'si çağrınızın bir parçası olarak sağladığınız JSON Şeması tanımını izlemesini sağlar. Bu, geçerli JSON oluşturulacağını garanti eden ancak sağlanan şemaya sıkı sıkıya bağlı kalınamadığı eski JSON modu özelliğinin aksinedir. Yapılandırılmış çıkışlar işlev çağrısı, yapılandırılmış verileri ayıklama ve karmaşık çok adımlı iş akışları oluşturma için önerilir.

Başlarken

Python'da nesne şemalarını tanımlamak için kullanabilirsiniz Pydantic . OpenAI ve Pydantic kitaplıklarının hangi sürümüne bağlı olarak daha yeni bir sürüme yükseltmeniz gerekebilir. Bu örnekler openai 1.42.0 ve pydantic 2.8.2 karşısında test edilmiştir.

pip install openai pydantic azure-identity --upgrade

Kimlik doğrulaması için Microsoft Entra ID kullanmaya yeni başlarsanız bkz. Microsoft Foundry Modellerinde Azure OpenAI'yi Microsoft Entra ID kimlik doğrulamasıyla yapılandırma.

from pydantic import BaseModel
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="MODEL_DEPLOYMENT_NAME", # replace with the model deployment name of your gpt-4o 2024-08-06 deployment
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    response_format=CalendarEvent,
)

event = completion.choices[0].message.parsed

print(event)
print(completion.model_dump_json(indent=2))

Çıktı

name='Science Fair' date='Friday' participants=['Alice', 'Bob']
{
  "id": "chatcmpl-A1EUP2fAmL4SeB1lVMinwM7I2vcqG",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "{\n  \"name\": \"Science Fair\",\n  \"date\": \"Friday\",\n  \"participants\": [\"Alice\", \"Bob\"]\n}",
        "refusal": null,
        "role": "assistant",
        "function_call": null,
        "tool_calls": [],
        "parsed": {
          "name": "Science Fair",
          "date": "Friday",
          "participants": [
            "Alice",
            "Bob"
          ]
        }
      }
    }
  ],
  "created": 1724857389,
  "model": "gpt-4o-2024-08-06",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": "fp_1c2eaec9fe",
  "usage": {
    "completion_tokens": 27,
    "prompt_tokens": 32,
    "total_tokens": 59
  }
}

Yapılandırılmış çıkışlarla fonksiyon çağrısı

İşlev çağrısı için yapılandırılmış çıktılar, strict: true sağlanarak tek bir parametreyle etkinleştirilebilir.

Uyarı

Yapılandırılmış çıkışlar paralel işlev çağrılarıyla desteklenmez. Yapılandırılmış çıkışlar kullanılırken parallel_tool_calls, false olarak ayarlayın.

import openai
from pydantic import BaseModel
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

class GetDeliveryDate(BaseModel):
    order_id: str

tools = [openai.pydantic_function_tool(GetDeliveryDate)]

messages = []
messages.append({"role": "system", "content": "You are a helpful customer support assistant. Use the supplied tools to assist the user."})
messages.append({"role": "user", "content": "Hi, can you tell me the delivery date for my order #12345?"}) 

response = client.chat.completions.create(
    model="MODEL_DEPLOYMENT_NAME", # replace with the model deployment name of your gpt-4o 2024-08-06 deployment
    messages=messages,
    tools=tools
)

print(response.choices[0].message.tool_calls[0].function)
print(response.model_dump_json(indent=2))

Başlarken

Aşağıdaki paketleri projenize ekleyin:

  • OpenAI: Standart OpenAI .NET kitaplığı.
  • Azure. Identity: Azure SDK kitaplıklarında Microsoft Entra ID belirteç kimlik doğrulaması desteği sağlar.
dotnet add package OpenAI
dotnet add package Azure.Identity

Kimlik doğrulaması için Microsoft Entra ID kullanmaya yeniyseniz bkz. Microsoft Foundry Modellerinde Azure OpenAI'yi Microsoft Entra ID kimlik doğrulamasıyla yapılandırma.

using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;
using System.Text.Json;

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");

ChatClient client = new(
    model: "gpt-4.1",
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1")
    }
);

ChatCompletionOptions options = new()
{
    ResponseFormat = ChatResponseFormat.CreateJsonSchemaFormat(
        jsonSchemaFormatName: "math_reasoning",
        jsonSchema: BinaryData.FromBytes("""
            {
                "type": "object",
                "properties": {
                    "steps": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "explanation": { "type": "string" },
                                "output": { "type": "string" }
                            },
                            "required": ["explanation", "output"],
                            "additionalProperties": false
                        }
                    },
                    "final_answer": { "type": "string" }
                },
                "required": ["steps", "final_answer"],
                "additionalProperties": false
            }
            """u8.ToArray()),
        jsonSchemaIsStrict: true)
};

// Create a list of ChatMessage objects
ChatCompletion completion = client.CompleteChat(
    [
        new UserChatMessage("How can I solve 8x + 7 = -23?")
    ],
    options);

using JsonDocument structuredJson = JsonDocument.Parse(completion.Content[0].Text);

Console.WriteLine($"Final answer: {structuredJson.RootElement.GetProperty("final_answer")}");
Console.WriteLine("Reasoning steps:");

foreach (JsonElement stepElement in structuredJson.RootElement.GetProperty("steps").EnumerateArray())
{
    Console.WriteLine($"  - Explanation: {stepElement.GetProperty("explanation")}");
    Console.WriteLine($"    Output: {stepElement.GetProperty("output")}");
}

Başlarken

response_format, json_schema ayarlanmış ve strict: true ile ayarlanır.

curl -X POST  https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/chat/completions \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
    -d '{
        "model": "YOUR_MODEL_DEPLOYMENT_NAME",
        "messages": [
                {"role": "system", "content": "Extract the event information."},
                {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."}
            ],
            "response_format": {
                "type": "json_schema",
                "json_schema": {
                    "name": "CalendarEventResponse",
                    "strict": true,
                    "schema": {
                        "type": "object",
                        "properties": {
                            "name": {
                              "type": "string"
                            },
                            "date": {
                                "type": "string"
                            },
                            "participants": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        },
                        "required": [
                            "name",
                            "date",
                            "participants"
                        ],
                        "additionalProperties": false
                    }
                }
          }
  }'

Çıktı:

{
  "id": "chatcmpl-A1HKsHAe2hH9MEooYslRn9UmEwsag",
  "object": "chat.completion",
  "created": 1724868330,
  "model": "gpt-4o-2024-08-06",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\n  \"name\": \"Science Fair\",\n  \"date\": \"Friday\",\n  \"participants\": [\"Alice\", \"Bob\"]\n}"
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 33,
    "completion_tokens": 27,
    "total_tokens": 60
  },
  "system_fingerprint": "fp_1c2eaec9fe"
}

Yapılandırılmış çıkışlarla fonksiyon çağrısı

curl -X POST  https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/chat/completions \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_MODEL_DEPLOYMENT_NAME",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant. The current date is August 6, 2024. You help users query for the data they are looking for by calling the query function."
    },
    {
      "role": "user",
      "content": "look up all my orders in may of last year that were fulfilled but not delivered on time"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "query",
        "description": "Execute a query.",
        "strict": true,
        "parameters": {
          "type": "object",
          "properties": {
            "table_name": {
              "type": "string",
              "enum": ["orders"]
            },
            "columns": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "id",
                  "status",
                  "expected_delivery_date",
                  "delivered_at",
                  "shipped_at",
                  "ordered_at",
                  "canceled_at"
                ]
              }
            },
            "conditions": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "column": {
                    "type": "string"
                  },
                  "operator": {
                    "type": "string",
                    "enum": ["=", ">", "<", ">=", "<=", "!="]
                  },
                  "value": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "column_name": {
                            "type": "string"
                          }
                        },
                        "required": ["column_name"],
                        "additionalProperties": false
                      }
                    ]
                  }
                },
                "required": ["column", "operator", "value"],
                "additionalProperties": false
              }
            },
            "order_by": {
              "type": "string",
              "enum": ["asc", "desc"]
            }
          },
          "required": ["table_name", "columns", "conditions", "order_by"],
          "additionalProperties": false
        }
      }
    }
  ]
}'

JSON Şeması desteği ve sınırlamaları

Azure OpenAI yapılandırılmış çıkışları, OpenAI ile aynı JSON Schema alt kümesini destekler.

Desteklenen türler

  • Dize
  • Sayı
  • Boolean
  • Tamsayı
  • Nesne
  • Dizi
  • enum
  • herhangiBiri

Uyarı

Kök nesneler anyOf türünde olamaz.

Tüm alanlar zorunlu olmalıdır

Tüm alanlar veya işlev parametreleri gerektiği gibi eklenmelidir. Aşağıdaki örnekte, location ve unit her ikisi de "required": ["location", "unit"] altında belirtilmiştir.

{
    "name": "get_weather",
    "description": "Fetches the weather in the given location",
    "strict": true,
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The location to get the weather for"
            },
            "unit": {
                "type": "string",
                "description": "The unit to return the temperature in",
                "enum": ["F", "C"]
            }
        },
        "additionalProperties": false,
        "required": ["location", "unit"]
    }
}

Gerekirse, null ile bir birleşim türü kullanarak isteğe bağlı bir parametreyi taklit etmek mümkündür. Bu örnekte, bu işlem "type": ["string", "null"], satırı ile gerçekleştirilir.

{
    "name": "get_weather",
    "description": "Fetches the weather in the given location",
    "strict": true,
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The location to get the weather for"
            },
            "unit": {
                "type": ["string", "null"],
                "description": "The unit to return the temperature in",
                "enum": ["F", "C"]
            }
        },
        "additionalProperties": false,
        "required": [
            "location", "unit"
        ]
    }
}

İç içe yerleştirme derinliği

Bir şemanın toplam 100 nesne özelliği olabilir ve en fazla beş iç içe yerleştirme düzeyi olabilir

additionalProperties: false her zaman nesnelerde ayarlanmalıdır

Bu özellik, bir nesnenin JSON Şemasında tanımlanmamış başka anahtar değer çiftlerine sahip olup olmadığını denetler. Yapılandırılmış çıkışları kullanmak için bu değeri false olarak ayarlamanız gerekir.

Anahtar sıralama

Yapılandırılmış çıkışlar, sağlanan şemayla aynı şekilde sıralanır. Çıkış sırasını değiştirmek için çıkarım isteğinizin bir parçası olarak gönderdiğiniz şemanın sırasını değiştirin.

Desteklenmeyen türe özgü anahtar sözcükler

Türü Desteklenmeyen Anahtar Sözcük
Dize minimum uzunluk
maksimumUzunluk
pattern
format
Sayı minimum
maksimum
multipleOf
Objects desenÖzellikleri
değerlendirilmemişÖzellikler
propertyNames
minÖzellikler
maksimumÖzellikler
Diziler değerlendirilmemiş öğeler
içerir
minİçerir
maksimum içerir
minItems
maksimum öğe sayısı
benzersiz öğeler

anyOf kullanan iç içe şemalar genel JSON Şeması alt kümesine uymalıdır

Örnek desteklenen anyOf şema:

{
    "type": "object",
    "properties": {
        "item": {
            "anyOf": [
                {
                    "type": "object",
                    "description": "The user object to insert into the database",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "The name of the user"
                        },
                        "age": {
                            "type": "number",
                            "description": "The age of the user"
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "name",
                        "age"
                    ]
                },
                {
                    "type": "object",
                    "description": "The address object to insert into the database",
                    "properties": {
                        "number": {
                            "type": "string",
                            "description": "The number of the address. Eg. for 123 main st, this would be 123"
                        },
                        "street": {
                            "type": "string",
                            "description": "The street name. Eg. for 123 main st, this would be main st"
                        },
                        "city": {
                            "type": "string",
                            "description": "The city of the address"
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "number",
                        "street",
                        "city"
                    ]
                }
            ]
        }
    },
    "additionalProperties": false,
    "required": [
        "item"
    ]
}

Tanımlar desteklenir

Desteklenen örnek:

{
    "type": "object",
    "properties": {
        "steps": {
            "type": "array",
            "items": {
                "$ref": "#/$defs/step"
            }
        },
        "final_answer": {
            "type": "string"
        }
    },
    "$defs": {
        "step": {
            "type": "object",
            "properties": {
                "explanation": {
                    "type": "string"
                },
                "output": {
                    "type": "string"
                }
            },
            "required": [
                "explanation",
                "output"
            ],
            "additionalProperties": false
        }
    },
    "required": [
        "steps",
        "final_answer"
    ],
    "additionalProperties": false
}

Özyinelemeli şemalar desteklenir

Kök özyineleme için # kullanma örneği:

{
        "name": "ui",
        "description": "Dynamically generated UI",
        "strict": true,
        "schema": {
            "type": "object",
            "properties": {
                "type": {
                    "type": "string",
                    "description": "The type of the UI component",
                    "enum": ["div", "button", "header", "section", "field", "form"]
                },
                "label": {
                    "type": "string",
                    "description": "The label of the UI component, used for buttons or form fields"
                },
                "children": {
                    "type": "array",
                    "description": "Nested UI components",
                    "items": {
                        "$ref": "#"
                    }
                },
                "attributes": {
                    "type": "array",
                    "description": "Arbitrary attributes for the UI component, suitable for any element",
                    "items": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "The name of the attribute, for example onClick or className"
                            },
                            "value": {
                                "type": "string",
                                "description": "The value of the attribute"
                            }
                        },
                      "additionalProperties": false,
                      "required": ["name", "value"]
                    }
                }
            },
            "required": ["type", "label", "children", "attributes"],
            "additionalProperties": false
        }
    }

Açık özyineleme örneği:

{
    "type": "object",
    "properties": {
        "linked_list": {
            "$ref": "#/$defs/linked_list_node"
        }
    },
    "$defs": {
        "linked_list_node": {
            "type": "object",
            "properties": {
                "value": {
                    "type": "number"
                },
                "next": {
                    "anyOf": [
                        {
                            "$ref": "#/$defs/linked_list_node"
                        },
                        {
                            "type": "null"
                        }
                    ]
                }
            },
            "additionalProperties": false,
            "required": [
                "next",
                "value"
            ]
        }
    },
    "additionalProperties": false,
    "required": [
        "linked_list"
    ]
}

Uyarı

Şu anda yapılandırılmış çıktı aşağıdakilerle desteklenmiyor:

Desteklenen modeller

  • gpt-5.1-codex Sürüm: 2025-11-13
  • gpt-5.1-codex mini Sürüm: 2025-11-13
  • gpt-5.1 Sürüm: 2025-11-13
  • gpt-5.1-chat Sürüm: 2025-11-13
  • gpt-5-pro Sürüm 2025-10-06
  • gpt-5-codex Sürüm 2025-09-11
  • gpt-5 Sürüm 2025-08-07
  • gpt-5-mini Sürüm 2025-08-07
  • gpt-5-nano Sürüm 2025-08-07
  • codex-mini Sürüm 2025-05-16
  • o3-pro Sürüm 2025-06-10
  • o3-mini Sürüm 2025-01-31
  • o1 Sürüm: 2024-12-17
  • gpt-4o-mini Sürüm: 2024-07-18
  • gpt-4o Sürüm: 2024-08-06
  • gpt-4o Sürüm: 2024-11-20
  • gpt-4.1 Sürüm 2025-04-14
  • gpt-4.1-nano Sürüm 2025-04-14
  • gpt-4.1-mini Sürüm: 2025-04-14
  • o4-mini Sürüm: 2025-04-16
  • o3 Sürüm: 2025-04-16

API desteği

Yapılandırılmış çıkışlar için destek ilk olarak API sürümüne 2024-08-01-previeweklendi. En son önizleme API'lerinde ve en son GA API'sinde kullanılabilir: v1.

  • Last updated on