JSON 모드를 사용하는 방법 알아보기

JSON 모드를 사용하면 채팅 완료의 일부로 유효한 JSON 개체를 반환하도록 모델의 응답 형식을 설정할 수 있습니다. 이전에는 유효한 JSON을 생성할 수 있었지만 응답 일관성에 문제가 발생하여 잘못된 JSON 개체가 생성될 수 있었습니다.

JSON 모드는 유효한 JSON 출력을 보장하지만 출력이 특정 스키마와 일치해야 하는 것은 아닙니다. 스키마 보장이 필요한 경우 구조적 출력을 사용합니다.

참고

JSON 모드는 계속 지원되지만 가능하면 구조화된 출력을 사용하는 것이 좋습니다. JSON 모드 구조화된 출력과 마찬가지로 유효한 JSON을 생성하지만 특정 JSON 스키마를 사용하도록 모델을 제한할 수 있는 추가 혜택이 있습니다.

참고

현재 구조적 출력은 사용자 고유의 데이터 가져오기 시나리오에서 지원되지 않습니다.

JSON 모드 지원

JSON 모드는 현재 다음 모델에서만 지원됩니다.

API 지원

JSON 모드에 대한 지원은 API 버전 2023-12-01-preview에 처음 추가되었습니다.

예제

예제를 실행하기 전에 다음을 수행합니다.

  • YOUR-RESOURCE-NAME Azure OpenAI 리소스 이름으로 대체합니다.
  • 모델 배포의 이름으로 YOUR-MODEL_DEPLOYMENT_NAME을(를) 바꾸십시오.

다음 예제에서는 직접 REST 상호 작용을 위해 Python 및 .NET SDK 및 PowerShell에서 JSON 모드를 사용하는 방법을 보여 줍니다.

import os
from openai import OpenAI

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

response = client.chat.completions.create(
  model="YOUR-MODEL_DEPLOYMENT_NAME", # Model = should match the deployment name you chose for your model deployment
  response_format={ "type": "json_object" },
  messages=[
    {"role": "system", "content": "You are a helpful assistant designed to output JSON."},
    {"role": "user", "content": "Who won the world series in 2020?"}
  ]
)
print(response.choices[0].message.content)

출력

{
  "winner": "Los Angeles Dodgers",
  "event": "World Series",
  "year": 2020
}

JSON 모드를 성공적으로 사용하려면 다음 요구 사항이 모두 충족되는지 확인합니다.

  • 요청에 응답 형식을 json_object 설정합니다. Python에서는 response_format={ "type": "json_object" }를 전달하고 .NET에서는 ChatResponseFormat.CreateJsonObjectFormat()를 사용하며 PowerShell에서는 response_format = @{type = 'json_object'}를 설정합니다.
  • 메시지 대화의 어딘가에 "JSON"이라는 단어를 포함합니다(일반적으로 시스템 메시지).

메시지 대화의 일부로 JSON을 생성해야 하는 모델에 대한 지침을 포함합니다. 시스템 메시지의 일부로 이 명령을 추가합니다. OpenAI에 따르면 이 명령을 추가하지 않으면 모델이 "연속되지 않은 공백 스트림을 생성하고 토큰 제한에 도달할 때까지 요청이 지속적으로 실행될 수 있습니다."

메시지에 "JSON"을 포함하지 않으면 응답은 다음과 같습니다.

출력

BadRequestError: Error code: 400 - {'error': {'message': "'messages' must contain the word 'json' in some form, to use 'response_format' of type 'json_object'.", 'type': 'invalid_request_error', 'param': 'messages', 'code': None}}

기타 고려 사항

응답을 구문 분석하기 전에 finish_reason에서 length 값을 확인해야 합니다. 모델은 부분 JSON을 생성할 수 있습니다. 즉, 모델의 출력이 요청의 일부로 설정된 사용 가능한 max_tokens보다 크거나 대화 자체가 토큰 제한을 초과했습니다.

JSON 모드는 유효한 JSON을 생성하고 오류 없이 구문 분석합니다. 그러나 프롬프트에서 요청된 경우에도 출력이 특정 스키마와 일치하도록 보장할 수 없습니다.

문제 해결

  • finish_reasonlength라면, max_tokens를 늘리거나 프롬프트 길이를 줄인 후 다시 시도해 보세요. 부분 JSON을 분석하지 마십시오.
  • 스키마 보장이 필요한 경우 구조적 출력으로 전환합니다.