가져온 모델에 대한 고급 API 기능

이 페이지에서는 2025년 11월 11일 이후에 가져온 모델에 사용할 수 있는 고급 기능의 세부 예제를 제공합니다. 이러한 기능에는 제어 생성을 위한 구조화된 출력, 다중 이미지 처리에 대한 향상된 비전 지원, 신뢰도 인사이트에 대한 로그 확률, GPT-OSS 모델용 도구 호출이 포함됩니다.

구조화된 출력

구조화된 출력을 사용하면 특정 형식, 스키마 또는 패턴에 따라 생성을 제어할 수 있습니다. 이 기능은 모델의 응답이 사전 정의된 제약 조건을 준수하도록 하여 일관된 데이터 형식, API 통합 또는 자동 처리 파이프라인이 필요한 애플리케이션에 이상적입니다.

사용자 지정 모델 가져오기의 구조화된 출력은 다음 두 가지 파라미터를 통해 지원됩니다.

response_format - json_object 및 json_schema 유형 지원
structured_outputs - json, regexchoice, 및 grammar 유형 지원

참고

사용자 지정 모델 가져오기에서 구조화된 출력을 사용하는 경우 고객은 생성 중 제약 조건 검증으로 인한 성능 장단점을 예상해야 합니다. choice 및와 같은 간단한 제약 조건은 영향을 최소화json_object하는 반면 및 json_schema와 같은 복잡한 제약 조건은 지연 시간을 크게 늘리고 처리량을 줄일 grammar 수 있습니다. 최적의 성능을 위해 가능하면 더 간단한 제약 유형을 사용하고 심하게 중첩되지 않고 스키마를 평탄하게 유지하세요.

다음 예제에서는 다양한 API 형식에서 구조화된 출력 지원을 보여줍니다. Pydantic 모델 정의는 다음과 같습니다.


from pydantic import BaseModel
from enum import Enum

class CarType(str, Enum):
    sedan = "sedan"
    suv = "SUV"
    truck = "Truck"
    coupe = "Coupe"

class CarDescription(BaseModel):
    brand: str
    model: str
    car_type: CarType

BedrockCompletion

BedrockCompletion은 json_object 및 json_schema 유형에서만 response_format 파라미터를 사용하여 구조화된 출력을 지원합니다.

예: JSON 스키마


payload = {
    "prompt": "Generate a JSON with the brand, model and car_type of the most iconic car from the 90's",
    "response_format": {
        "type": "json_schema",
        "json_schema": CarDescription.model_json_schema()
    }
}

response = client.invoke_model(
    modelId='your-model-arn',
    body=json.dumps(payload),
    accept='application/json',
    contentType='application/json'
)

response_body = json.loads(response['body'].read())

응답 예제:


{
    "generation": "{\n    \"brand\": \"Ferrari\",\n    \"model\": \"F40\",\n    \"car_type\": \"SUV\"\n  }",
    "prompt_token_count": 22,
    "generation_token_count": 30,
    "stop_reason": "stop",
    "logprobs": null
}

OpenAICompletion

OpenAICompletion은 response_format (json_object, json_schema) 및 structured_outputs (json, regex, choice, grammar) 파라미터를 모두 지원합니다. max_tokens 대신 max_gen_len를 사용하여 OpenAICompletion으로 요청을 라우팅합니다.

예: 구조화된 출력 - 선택


payload = {
    "prompt": "Classify the sentiment of this sentence. Amazon Bedrock CMI is Amazing!",
    "max_tokens": 10,
    "structured_outputs": {
        "choice": ["positive", "negative"]
    }
}

response = client.invoke_model(
    modelId='your-model-arn',
    body=json.dumps(payload),
    accept='application/json',
    contentType='application/json'
)

response_body = json.loads(response['body'].read())

응답 예제:


{
    "id": "cmpl-01f94c4652d24870bbb4d5418a01c384",
    "object": "text_completion",
    "choices": [
        {
            "index": 0,
            "text": "positive",
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 17,
        "completion_tokens": 4
    }
}

OpenAIChatCompletion

OpenAIChatCompletion은 response_format (json_object, json_schema) 및 structured_outputs (json, regex, choice, grammar) 파라미터를 모두 지원합니다.

예: 응답 형식 - JSON 스키마


payload = {
    "messages": [
        {"role": "user", "content": "Generate a JSON with the brand, model and car_type of the most iconic car from the 90's"}
    ],
    "max_tokens": 100,
    "response_format": {
        "type": "json_schema",
        "json_schema": {
            "name": "car-description",
            "schema": CarDescription.model_json_schema()
        }
    }
}

response = client.invoke_model(
    modelId='your-model-arn',
    body=json.dumps(payload),
    accept='application/json',
    contentType='application/json'
)

response_body = json.loads(response['body'].read())

응답 예제:


{
    "id": "chatcmpl-cae5a43b0a924b8eb434510cbf978a19",
    "object": "chat.completion",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "{\"brand\": \"Dodge\", \"model\": \"Viper\", \"car_type\": \"Coupe\"}"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 56,
        "completion_tokens": 23
    }
}

비전 지원

비전 기능을 사용하면 복잡한 시각적 분석 작업에 대한 향상된 다중 이미지 지원을 통해 텍스트 입력과 함께 이미지를 처리할 수 있습니다. 사용자 지정 모델 가져오기는 이제 이전 단일 이미지 제한에서 향상된 요청당 최대 3개의 이미지를 지원합니다.

지원되는 API: OpenAIChatCompletion만 해당. 2025년 11월 11일 이후에 가져온 모든 모델은 비전 기능을 위해이 API로 기본 설정됩니다.

이미지 요구 사항:

Base64 인코딩 필요 - 이미지 URLs 인해 요청 실패 발생
요청당 최대 3개의 이미지
고해상도 이미지는 처리 시간과 메모리 사용량을 크게 늘립니다.

주의

고해상도 이미지는 처리 시간, 메모리 사용량을 크게 늘리며 시간 초과 오류를 일으킬 수 있습니다. 다중 고해상도 이미지는 성능에 기하급수적으로 영향을 미칩니다. 최적의 성능을 위해 이미지 크기를 적절하게 조정하고 가능하면 세부 수준을 낮춥니다.

OpenAIChatCompletion

예: 다중 이미지 처리


import json
import boto3
import base64

client = boto3.client('bedrock-runtime', region_name='us-east-1')

# Load and encode images
with open('/path/to/car_image_1.jpg', 'rb') as f:
    image_data_1 = base64.b64encode(f.read()).decode('utf-8')

with open('/path/to/car_image_2.jpg', 'rb') as f:
    image_data_2 = base64.b64encode(f.read()).decode('utf-8')

payload = {
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant that can analyze images."
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Spot the difference between the two images?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data_1}"
                    }
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data_2}"
                    }
                }
            ]
        }
    ],
    "max_tokens": 300,
    "temperature": 0.5
}

response = client.invoke_model(
    modelId='your-model-arn',
    body=json.dumps(payload),
    accept='application/json',
    contentType='application/json'
)

response_body = json.loads(response['body'].read())

응답 예제:


{
    "id": "chatcmpl-ccae8a67e62f4014a9ffcbedfff96f44",
    "object": "chat.completion",
    "created": 1763167018,
    "model": "667387627229-g6vkuhd609s4",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "There are no differences between the two images provided. They appear to be identical.",
                "refusal": null,
                "annotations": null,
                "audio": null,
                "function_call": null,
                "tool_calls": [],
                "reasoning_content": null
            },
            "logprobs": null,
            "finish_reason": "stop",
            "stop_reason": null,
            "token_ids": null
        }
    ],
    "service_tier": null,
    "system_fingerprint": null,
    "usage": {
        "prompt_tokens": 2795,
        "total_tokens": 2812,
        "completion_tokens": 17,
        "prompt_tokens_details": null
    },
    "prompt_logprobs": null,
    "prompt_token_ids": null,
    "kv_transfer_params": null
}

로그 확률

로그 확률은 시퀀스에서 각 토큰의 가능성을 나타내며, log(p)로 계산됩니다. 여기서 p는 컨텍스트에서 이전 토큰이 주어진 모든 위치에서 토큰의 확률입니다. 로그 확률은 애디티브이므로 시퀀스 확률은 개별 토큰 로그 확률의 합계와 동일하므로 평균 토큰당 점수별로 세대 순위를 매기는 데 유용합니다. 사용자 지정 모델 가져오기는 항상 요청된 토큰에 대한 원시 로그프로브 값을 반환합니다.

주요 애플리케이션에는 로그 확률이 사용자 지정 신뢰도 임계값을 활성화하는 분류 작업, 신뢰도 점수를 사용하여 할루시네이션을 줄이는 검색 Q&A 시스템, 토큰 가능성에 따른 자동 완성 제안, 프롬프트 간 모델 성능을 비교하기 위한 복잡성 계산이 포함됩니다. 로그 프로브는 토큰 수준 분석 기능도 제공하므로 개발자는 모델이 고려한 대체 토큰을 검사할 수 있습니다.

참고

Logprob은 캐시되지 않습니다. 프롬프트 logprobs가 필요한 요청의 경우 시스템은 접두사 캐시를 무시하고 전체 프롬프트의 미리 채우기를 다시 계산하여 logprobs를 생성합니다. 이는 logprobs를 사용할 때 명백한 성능 장단점을 나타냅니다.

로그 확률 지원은 API 형식에 따라 다릅니다.

BedrockCompletion - 출력 토큰만
OpenAICompletion - 프롬프트 및 출력 토큰
OpenAIChatCompletion - 프롬프트 및 출력 토큰

BedrockCompletion

BedrockCompletion은 출력 토큰 로그 프로브만 지원합니다. 그러면 각 출력 토큰에 대해 상위 1개의 로그프로브가 반환됩니다.


payload = {
    "prompt": "How is the rainbow formed?",
    "max_gen_len": 10,
    "temperature": 0.5,
    "return_logprobs": True
}

response = client.invoke_model(
    modelId='your-model-arn',
    body=json.dumps(payload),
    accept='application/json',
    contentType='application/json'
)

response_body = json.loads(response['body'].read())

응답 예(잘림):


{
    "generation": " A rainbow is formed when sunlight passes through water dro",
    "prompt_token_count": 7,
    "generation_token_count": 10,
    "stop_reason": "length",
    "logprobs": [
        {
            "362": -2.1413702964782715
        },
        {
            "48713": -0.8180374503135681
        },
        {
            "374": -0.09657637774944305
        },
        ...
    ]
}

OpenAIChatCompletion

OpenAIChatCompletion은 프롬프트 및 출력 토큰 로그 프로브를 모두 지원합니다. top_logprobs=N 및를 설정할 수 있습니다. prompt_logprobs=N 여기서 N은 각 위치에서 가장 가능성이 높은 N 토큰의 로그 확률을 나타내는 정수입니다.


payload = {
    "messages": [
        {
            "role": "user",
            "content": "How is the rainbow formed?"
        }
    ],
    "max_tokens": 10,
    "temperature": 0.5,
    "logprobs": True,
    "top_logprobs": 1,
    "prompt_logprobs": 1
}

response = client.invoke_model(
    modelId='your-model-arn',
    body=json.dumps(payload),
    accept='application/json',
    contentType='application/json'
)

response_body = json.loads(response['body'].read())

응답 예(잘림):


{
    "id": "chatcmpl-xxx",
    "object": "chat.completion",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "A rainbow is formed..."
            },
            "logprobs": {
                "content": [
                    {
                        "token": "A",
                        "logprob": -0.07903262227773666,
                        "bytes": [65],
                        "top_logprobs": [
                            {
                                "token": "A",
                                "logprob": -0.07903262227773666,
                                "bytes": [65]
                            }
                        ]
                    },
                    {
                        "token": " rainbow",
                        "logprob": -0.20187227427959442,
                        "bytes": [32, 114, 97, 105, 110, 98, 111, 119],
                        "top_logprobs": [...]
                    },
                    ...
                ]
            },
            "finish_reason": "length"
        }
    ],
    "usage": {
        "prompt_tokens": 41,
        "completion_tokens": 10,
        "total_tokens": 51
    }
}

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

가져온 모델 간접 호출

사용자 지정 채팅 템플릿 및 토큰화기