구조화된 출력을 사용하면 모델이 항상 특정 스키마를 준수하는 출력을 생성할 수 있습니다. 예를 들어 모델에 응답 스키마를 제공하여 응답이 유효한 JSON을 생성하도록 할 수 있습니다. Vertex AI 서비스형 모델(MaaS)에서 사용할 수 있는 모든 개방형 모델은 구조화된 출력을 지원합니다.
구조화된 출력 기능에 관한 자세한 개념 정보는 구조화된 출력 소개를 참조하세요.
구조화된 출력 사용
다음 사용 사례에서는 모델 출력이 name, date, participants 속성이 있는 JSON 객체임을 보장하는 응답 스키마를 설정합니다. Python 코드는 OpenAI SDK와 Pydantic 객체를 사용하여 JSON 스키마를 생성합니다.
from pydantic import BaseModel
from openai import OpenAI
client = OpenAI()
class CalendarEvent(BaseModel):
name: str
date: str
participants: list[str]
completion = client.beta.chat.completions.parse(
model="MODEL_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=CalendarEvent,
)
print(completion.choices[0].message.parsed)
모델 출력은 다음 JSON 스키마를 준수합니다.
{ "name": STRING, "date": STRING, "participants": [STRING] }
'앨리스와 밥은 금요일에 과학 박람회에 갈 거야'라는 프롬프트가 제공되면 모델은 다음과 같은 응답을 생성할 수 있습니다.
{
"name": "science fair",
"date": "Friday",
"participants": [
"Alice",
"Bob"
]
}
상세 예시
다음 코드는 재귀 스키마의 예시입니다. UI 클래스에는 children 목록이 포함되어 있으며, 이 목록은 UI 클래스일 수도 있습니다.
from pydantic import BaseModel
from openai import OpenAI
from enum import Enum
from typing import List
client = OpenAI()
class UIType(str, Enum):
div = "div"
button = "button"
header = "header"
section = "section"
field = "field"
form = "form"
class Attribute(BaseModel):
name: str
value: str
class UI(BaseModel):
type: UIType
label: str
children: List["UI"]
attributes: List[Attribute]
UI.model_rebuild() # This is required to enable recursive types
class Response(BaseModel):
ui: UI
completion = client.beta.chat.completions.parse(
model="MODEL_NAME",
messages=[
{"role": "system", "content": "You are a UI generator AI. Convert the user input into a UI."},
{"role": "user", "content": "Make a User Profile Form"}
],
response_format=Response,
)
print(completion.choices[0].message.parsed)
모델 출력은 이전 스니펫에 지정된 Pydantic 객체의 스키마를 따릅니다. 이 예시에서 모델은 다음 UI 양식을 생성할 수 있습니다.
Form
Input
Name
Email
Age
응답은 다음과 같습니다.
ui = UI(
type=UIType.div,
label='Form',
children=[
UI(
type=UIType.div,
label='Input',
children=[],
attributes=[
Attribute(name='label', value='Name')
]
),
UI(
type=UIType.div,
label='Input',
children=[],
attributes=[
Attribute(name='label', value='Email')
]
),
UI(
type=UIType.div,
label='Input',
children=[],
attributes=[
Attribute(name='label', value='Age')
]
)
],
attributes=[
Attribute(name='name', value='John Doe'),
Attribute(name='email', value='john.doe@example.com'),
Attribute(name='age', value='30')
]
)
JSON 객체 응답 가져오기
response_format 필드를 { "type": "json_object" }로 설정하여 문법적으로 유효한 JSON 객체만 출력하도록 모델을 제한할 수 있습니다. 이를 JSON 모드라고도 합니다. JSON 모드는 함수 호출 또는 JSON 입력이 필요한 기타 다운스트림 작업에 사용할 JSON을 생성할 때 유용합니다.
JSON 모드가 사용 설정되면 모델은 유효한 JSON 객체로 파싱되는 문자열만 생성하도록 제한됩니다. 이 모드는 출력이 구문상 올바른 JSON인지 확인하지만 특정 스키마를 적용하지는 않습니다. 모델이 특정 스키마를 따르는 JSON을 출력하도록 하려면 다음 예와 같이 프롬프트에 안내를 포함해야 합니다.
다음 샘플에서는 JSON 모드를 사용 설정하고 특정 구조의 JSON 객체를 반환하도록 모델에 지시하는 방법을 보여줍니다.
Python
이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Vertex AI Python API 참고 문서를 참조하세요.
Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
이 샘플을 실행하기 전에 OPENAI_BASE_URL 환경 변수를 설정해야 합니다.
자세한 내용은 인증 및 사용자 인증 정보를 참고하세요.
from openai import OpenAI client = OpenAI() response = client.chat.completions.create( model="MODEL", response_format={ "type": "json_object" }, messages=[ {"role": "user", "content": "List 5 rivers in South America. Your response must be a JSON object with a single key \"rivers\", which has a list of strings as its value."}, ] ) print(response.choices[0].message.content)
MODEL을 사용할 모델 이름으로 바꿉니다(예: meta/llama3-405b-instruct-maas).
REST
환경을 설정하면 REST를 사용하여 텍스트 프롬프트를 테스트할 수 있습니다. 다음 샘플은 요청을 게시자 모델 엔드포인트에 전송합니다.
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- LOCATION: 개방형 모델을 지원하는 리전입니다.
- MODEL: 사용할 모델 이름(예:
meta/llama3-405b-instruct-maas)
HTTP 메서드 및 URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions
JSON 요청 본문:
{
"model": "MODEL",
"response_format": {
"type": "json_object"
},
"messages": [
{
"role": "user",
"content": "List 5 rivers in South America. Your response must be a JSON object with a single key \"rivers\", which has a list of strings as its value."
}
]
}
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"
PowerShell
요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content
다음과 비슷한 JSON 응답이 수신됩니다.