Anthropic Claude 모델을 사용한 구조화된 출력

구조화된 출력을 사용하면 Claude 모델의 생성된 출력이 특정 JSON 스키마를 정확하게 준수하도록 제한할 수 있습니다. 이는 Claude 모델의 대답이 항상 다운스트림 애플리케이션, 데이터베이스, 처리 파이프라인에 필요한 정확한 형식으로 제공되도록 하는 데 유용합니다.

구조화된 출력은 동일한 요청에서 독립적으로 또는 함께 사용할 수 있는 두 가지 보완 기능을 제공합니다.

  • JSON 출력 (output_config.format): 모델의 텍스트 대답을 제공된 스키마와 일치하는 JSON 객체로 제한합니다. 텍스트에서 구조화된 데이터를 추출하거나, 구조화된 보고서를 생성하거나, API 응답의 형식을 지정해야 하는 경우에 사용합니다.
  • 엄격한 도구 사용 (tools[].strict): 모델이 도구에 전달하는 인수가 도구의 input_schema와 일치하도록 보장합니다. 에이전트형 워크플로에서 타입 안전 함수 호출이 필요한 경우에 사용합니다.

자세한 내용은 Anthropic의 Building with Claude: Structured Outputs(Claude로 빌드: 구조화된 출력) 및 Strict tool use(엄격한 도구 사용) 문서를 참고하세요.

지원되는 Anthropic Claude 모델

Gemini Enterprise Agent Platform은 다음 Anthropic Claude 모델의 구조화된 출력을 지원합니다.

  • Claude Opus 4.7
  • Claude Sonnet 4.6
  • Claude Opus 4.6
  • (출시 예정) Claude Opus 4.5
  • (출시 예정) Claude Sonnet 4.5
  • (출시 예정) Claude Haiku 4.5

구조화된 출력에 대한 액세스 제어

기본적으로 구조화된 출력은 조직 정책 제약 조건 constraints/vertexai.allowedPartnerModelFeatures에 의해 사용 중지됩니다. 구조화된 출력을 사용 설정하려면 이 제약 조건을 구성하여 structured_outputs 기능을 명시적으로 허용해야 합니다.

또한 조직 정책 제약 조건 constraints/vertexai.allowedModels를 구성하여 Claude 모델에 대한 액세스를 제한할 수 있습니다.

조직 정책 제약 조건을 구성하는 방법에 관한 자세한 안내는 Model Garden 모델에 대한 액세스 제어를 참고하세요.

구조화된 출력 요청 보내기

JSON 출력을 요청하려면 게시자 모델 엔드포인트에 POST 요청을 전송하고 요청 본문에 output_config 매개변수를 포함합니다. output_config 파라미터는 모델의 대답이 준수해야 하는 JSON 스키마를 지정합니다.

REST

다음 샘플은 비구조화된 이메일에서 구조화된 연락처 정보를 추출하는 에이전트 플랫폼 API에 요청을 전송하는 방법을 보여줍니다. 대답은 name, email, plan_interest, demo_requested 필드가 있는 JSON 객체로 제한됩니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • LOCATION: Anthropic Claude 모델을 지원하는 리전. 전역 엔드포인트를 사용하려면 전역 엔드포인트 지정을 참고하세요.
  • MODEL: 지원되는 Claude 모델(예: claude-opus-4-7)
  • ROLE: 메시지와 연결된 역할. user 또는 assistant를 지정할 수 있습니다. 첫 번째 메시지는 user 역할을 사용해야 합니다. Claude 모델은 user와 assistant의 턴을 번갈아가며 작동합니다. 최종 메시지에서 assistant 역할을 사용하는 경우 이 메시지의 콘텐츠에서 곧바로 응답 콘텐츠가 계속됩니다. 이를 사용하여 모델 응답의 일부를 제한할 수 있습니다.
  • CONTENT: user 또는 assistant 메시지의 콘텐츠(예: 텍스트). 예를 들면 Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.입니다.
  • MAX_TOKENS: 응답에서 생성될 수 있는 토큰의 최대 개수. 토큰은 약 3.5자(영문 기준)입니다. 토큰 100개는 단어 약 60~80개에 해당합니다.

    응답이 짧을수록 낮은 값을 지정하고 잠재적으로 응답이 길면 높은 값을 지정합니다.

  • STREAM: 응답 스트리밍 여부를 지정하는 불리언. 응답을 스트리밍하려면 true로 설정하고 응답을 한 번에 반환하려면 false로 설정합니다. 구조화된 출력은 일반적으로 false와 함께 반환됩니다.

이 예에서는 다음 구조화된 출력 필드를 사용합니다. 각 필드에 관한 자세한 내용은 요청 필드 섹션을 참고하세요.

  • output_config: 모델의 응답 구조를 제어하는 최상위 구성 블록입니다.
  • output_config.format.type: 제공된 스키마를 따르는 JSON 객체로 대답을 제한하려면 json_schema로 설정합니다.
  • output_config.format.schema: 모델의 대답에 필요한 구조를 정의하는 JSON 스키마입니다. 스키마는 지원되는 JSON 스키마 하위 집합을 준수해야 합니다.

HTTP 메서드 및 URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

JSON 요청 본문: 

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "email": {"type": "string"},
          "plan_interest": {"type": "string"},
          "demo_requested": {"type": "boolean"}
        },
        "required": ["name", "email", "plan_interest", "demo_requested"],
        "additionalProperties": false
      }
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

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/publishers/anthropic/models/MODEL:rawPredict"

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/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 수신됩니다. content 블록의 text 필드에는 output_config에 지정한 스키마를 준수하는 JSON 문자열이 포함됩니다.

요청 필드

다음 필드는 JSON 출력에만 해당합니다. 기타 요청 필드에 대한 자세한 내용은 Claude 메시지 API 참조를 참고하세요.

  • output_config: 모델 응답의 구조를 제어하는 최상위 구성 블록입니다.
  • output_config.format: 출력의 형식 정의입니다. json_schema 유형만 지원됩니다.
  • output_config.format.type: 적용할 출력 형식의 유형입니다. 응답을 JSON 객체로 제한하려면 이 값을 json_schema로 설정하세요.

  • output_config.format.schema: 모델의 응답에 필요한 구조를 정의하는 JSON 스키마입니다. 구조화된 출력은 객체에 대해 additionalProperties을 false로 설정해야 하고 숫자 또는 문자열 길이 제약 조건을 지원하지 않는 등 몇 가지 제한사항이 있는 표준 JSON 스키마를 지원합니다. 지원되는 기능과 지원되지 않는 기능의 전체 목록은 Anthropic의 JSON 스키마 제한사항 문서를 참고하세요. 스키마 내에서 일반적으로 다음을 지정합니다.

    • type: 이 수준의 값의 JSON 유형입니다 (가장 일반적인 루트 스키마의 경우 object).
    • properties: 모델이 반환해야 하는 각 필드를 설명하는 필드 이름과 유형 정의의 맵입니다.
    • required: 모델이 대답에 포함해야 하는 속성 이름 목록입니다.
    • additionalProperties: false로 설정하면 모델이 properties에 선언되지 않은 필드를 포함하지 못하도록 하는 불리언입니다.

엄격한 도구 사용

엄격한 도구 사용은 모델이 도구에 전달하는 인수가 도구의 input_schema와 일치하도록 합니다. 엄격 모드가 없으면 모델이 잘못된 유형의 인수로 도구를 호출하거나 (예: 2 대신 "2") 필수 필드를 누락할 수 있으며, 이로 인해 다운스트림 함수가 중단되고 재시도 로직이 필요할 수 있습니다. 엄격 모드가 사용 설정된 경우 API는 문법 제약 샘플링을 사용하여 다음을 보장합니다.

  • name 도구는 항상 사용자가 제공한 도구 중 하나입니다.
  • 도구 input는 항상 도구의 input_schema를 준수합니다.

도구 매개변수를 검증하거나, 에이전트 워크플로를 빌드하거나, 유형 안전 함수 호출을 보장하거나, 중첩된 속성이 있는 복잡한 도구를 처리해야 하는 경우 엄격한 도구 사용을 사용하세요.

엄격한 도구 사용을 사용 설정하려면 name, description, input_schema과 함께 "strict": true을 도구 정의의 최상위 필드로 설정합니다.

REST

다음 샘플은 엄격한 get_weather 도구를 정의하는 에이전트 플랫폼 API에 요청을 보내는 방법을 보여줍니다. 모델은 location 문자열과 선택사항인 unit(celsius 또는 fahrenheit)을 사용하여 도구를 호출합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • LOCATION: Anthropic Claude 모델을 지원하는 리전. 전역 엔드포인트를 사용하려면 전역 엔드포인트 지정을 참고하세요.
  • MODEL: 지원되는 Claude 모델(예: claude-opus-4-7)
  • ROLE: 메시지와 연결된 역할. 첫 번째 메시지는 user 역할을 사용해야 합니다.
  • CONTENT: user 또는 assistant 메시지의 콘텐츠(예: 텍스트). 예를 들면 What is the weather in San Francisco?입니다.
  • MAX_TOKENS: 응답에서 생성될 수 있는 토큰의 최대 개수. 토큰은 약 3.5자(영문 기준)입니다. 토큰 100개는 단어 약 60~80개에 해당합니다.

    응답이 짧을수록 낮은 값을 지정하고 잠재적으로 응답이 길면 높은 값을 지정합니다.

  • STREAM: 응답 스트리밍 여부를 지정하는 불리언. 응답을 스트리밍하려면 true로 설정하고 응답을 한 번에 반환하려면 false로 설정합니다.

이 예시에서는 다음과 같은 엄격한 도구 사용 필드를 사용합니다. 각 필드에 관한 자세한 내용은 엄격한 도구 사용 필드 섹션을 참고하세요.

  • tools[].strict: true로 설정하면 도구의 문법 제한 샘플링을 사용 설정하는 불리언입니다. 모델은 input_schema와 일치하는 인수로 도구를 호출합니다.
  • tools[].input_schema: 모델이 도구에 전달할 수 있는 인수를 정의하는 JSON 스키마입니다. strict이 true인 경우 스키마는 JSON 출력의 output_config 스키마와 동일한 지원되는 JSON 스키마 하위 집합을 준수해야 합니다.

HTTP 메서드 및 URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

JSON 요청 본문: 

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, for example San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }
  ]
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

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/publishers/anthropic/models/MODEL:rawPredict"

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/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 수신됩니다. tool_use 콘텐츠 블록에는 키와 값 유형이 도구의 input_schema와 일치하는 input 필드가 포함되어 있습니다.

엄격한 도구 사용 필드

다음 필드는 엄격한 도구 사용에만 적용됩니다. 다른 도구 정의 필드에 관한 자세한 내용은 Anthropic의 도구 정의 문서를 참고하세요.

  • tools[].strict: true로 설정되면 도구의 문법 제한 샘플링을 사용 설정하는 불리언입니다. strict이 true인 경우 모델의 도구 입력은 input_schema의 스키마와 일치하도록 제한됩니다. 기본값은 false입니다.

  • tools[].input_schema: 모델이 도구에 전달할 수 있는 인수를 정의하는 JSON 스키마입니다. strict이 true인 경우 스키마는 JSON 출력에서 사용하는 것과 동일한 JSON 스키마 하위 집합을 준수해야 합니다. 특히 다음 작업이 필요합니다.

    • 스키마의 모든 객체에서 additionalProperties을 false로 설정합니다.
    • required 배열의 모든 속성을 나열합니다.

    지원되는 기능과 지원되지 않는 기능의 전체 목록은 Anthropic의 JSON 스키마 제한사항 문서를 참고하세요.