사용 Converse API

를 사용하려면 Converse API또는 Converse ConverseStream 작업을 호출하여 모델에 메시지를 보냅니다. Converse를 직접적으로 호출하려면 bedrock:InvokeModel 작업에 대한 권한이 필요합니다. ConverseStream을 직접적으로 호출하려면 bedrock:InvokeModelWithResponseStream 작업에 대한 권한이 필요합니다.

주제

요청
응답

요청

modelId 필드를 설정하여 사용하려는 모델을 지정할 수 있습니다. Amazon BedrockIDs이 지원하는 모델 목록은 섹션을 참조하세요Amazon Bedrock에서 지원되는 파운데이션 모델.

대화는 사용자와 모델이 주고받는 일련의 메시지입니다. 사용자(user role)로서 모델에 메시지를 전송하여 대화를 시작할 수 있습니다. 어시스턴트 역할을 하는 모델(assistant role)은 메시지에서 반환되는 응답을 생성합니다. 원하는 경우 모델에 사용자 역할 메시지를 추가로 전송하여 대화를 이어나갈 수 있습니다. 대화 컨텍스트를 유지하려면 모델로부터 수신한 어시스턴트 역할 메시지를 후속 요청에 포함해야 합니다.

messages 필드에 모델에게 전달하려는 메시지를 제공하면 이 메시지가 메시지 객체 배열에 매핑됩니다. 각 메시지에는 메시지의 내용과 대화에서 메시지가 수행하는 역할이 포함되어 있습니다.

참고

Amazon Bedrock은 사용자가 내용으로 제공하는 텍스트, 이미지 또는 문서를 저장하지 않습니다. 데이터는 응답을 생성하는 용도로만 사용됩니다. 사용 시 Converse API크기가 4.5MB 미만인 압축되지 않은 문서와 디코딩된 문서를 사용해야 합니다.

content 필드에 메시지의 콘텐츠를 추가하면 ContentBlock 객체 배열에 매핑됩니다. 각 내에서 다음 필드 중 하나를 지정할 ContentBlock수 있습니다(어떤 모델이 어떤 형식을 지원하는지 보려면 참조지원되는 모델 및 모델 기능).

text

text 필드는 프롬프트를 지정하는 문자열에 매핑됩니다. text 필드는 동일한에 지정된 다른 필드와 함께 해석됩니다ContentBlock.

(선택 사항) 특정 모델의 경우 cachePoint 필드를 사용하여 캐시 체크포인트를 추가하여 프롬프트 캐싱을 활용할 수 있습니다. 프롬프트 캐싱은 대화 컨텍스트 캐싱을 시작하여 비용 및 지연 시간을 절감할 수 있는 기능입니다. 자세한 내용은 더 빠른 모델 추론을 위한 신속한 캐싱 단원을 참조하십시오.

참고

Amazon Bedrock 프롬프트 캐싱은 현재 일부 고객만 사용할 수 있습니다. 미리 보기 참여에 대한 자세한 내용은 Amazon Bedrock 프롬프트 캐싱을 참조하세요.

다음은 텍스트만 포함하는 content 배열이 있는 메시지 객체를 보여줍니다ContentBlock.


{
    "role": "user | assistant",
    "content": [
        {
            "text": "string"
        }
    ]
}

다음은 텍스트와 선택적 cachePoint 필드가 포함된 content 배열이 있는 메시지 객체ContentBlock를 보여줍니다. 결과적으로 텍스트의 콘텐츠ContentBlock가 캐시에 추가됩니다.


{
    "role": "user | assistant",
    "content": [
        {
            "text": "string"
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

image

image 필드는에 매핑됩니다ImageBlock. bytes 필드의 이미지에 대해 base64로 인코딩된 원시 바이트를 전달합니다. 를 사용하는 경우 base64에서 바이트를 인코딩 AWS SDK할 필요가 없습니다.

text 필드를 제외하면 모델이 이미지를 설명합니다.

참고

Amazon Bedrock 프롬프트 캐싱은 현재 일부 고객만 사용할 수 있습니다. 미리 보기 참여에 대한 자세한 내용은 Amazon Bedrock 프롬프트 캐싱을 참조하세요.

다음은 이미지만 포함하는 content 배열이 있는 메시지 객체를 보여줍니다ContentBlock.


{
    "role": "user",
    "content": [
        {
            "image": {
                "format": "png | jpeg | gif | webp",
                "source": {
                    "bytes": "image in bytes"
                }
            }
        }
    ]
}

다음은 이미지와 선택적 cachePoint 필드가 포함된 content 배열이 있는 메시지 객체ContentBlock를 보여줍니다. 결과적으로 이미지 콘텐츠가 캐시에 추가됩니다.


{
    "role": "user",
    "content": [
        {
            "image": {
                "format": "png | jpeg | gif | webp",
                "source": {
                    "bytes": "image in bytes"
                }
            }
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

document

document 필드는에 매핑됩니다DocumentBlock. DocumentBlock을 포함할 경우 요청이 다음 제한 사항을 준수하는지 확인합니다.

메시지 객체의 content 필드에는 문서와 관련된 프롬프트가 있는 text 필드도 포함해야 합니다.
bytes 필드의 문서에 대해 base64로 인코딩된 원시 바이트를 전달합니다. 를 사용하는 경우 base64에서 문서 바이트를 인코딩 AWS SDK할 필요가 없습니다.
name 필드에는 다음 문자만 포함할 수 있습니다.
- 영숫자
- 공백 문자(한 줄에 1개 이하)
- 하이픈
- 괄호
- 대괄호
참고
name 필드는 모델이 지침으로 잘못 해석할 여지가 있어 프롬프트 인젝션에 취약합니다. 따라서 중립 이름을 지정하는 것이 좋습니다.

참고

Amazon Bedrock 프롬프트 캐싱은 현재 일부 고객만 사용할 수 있습니다. 미리 보기 참여에 대한 자세한 내용은 Amazon Bedrock 프롬프트 캐싱을 참조하세요.

다음은 문서 ContentBlock 및 필수 첨부 텍스트만 포함하는 content 배열이 있는 메시지 객체를 보여줍니다ContentBlock.


{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "document": {
                "format": "pdf | csv | doc | docx | xls | xlsx | html | txt | md",
                "name": "string",
                "source": {
                    "bytes": "document in bytes"
                }
            }
        }
    ]
}

다음은 문서ContentBlock와 필수 첨부 텍스트가 포함된 content 배열ContentBlock과 문서와 텍스트 콘텐츠를 모두 캐시에 추가하는가 cachePoint 있는 메시지 객체를 보여줍니다.


{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "document": {
                "format": "pdf | csv | doc | docx | xls | xlsx | html | txt | md",
                "name": "string",
                "source": {
                    "bytes": "document in bytes"
                }
            }
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

video

video 필드는에 매핑됩니다VideoBlock. base64로 인코딩된 bytes 필드의 원시 바이트를 전달합니다. 를 사용하는 경우 base64에서 바이트를 인코딩 AWS SDK할 필요가 없습니다.

text 필드를 포함하지 않으면 모델이 비디오를 설명합니다.

다음은 비디오만 포함하는 content 배열이 있는 메시지 객체를 보여줍니다ContentBlock.


{
    "role": "user",
    "content": [
        {
            "video": {
                "format": "mov | mkv | mp4 | webm | flv | mpeg | mpg | wmv | three_gp",
                "source": {
                    "bytes": "video in bytes"
                }
            }
        }
    ]
}

.3gp 확장명이 있는 파일의 경우 형식을 로 지정해야 합니다three_gp.

요청 본문에 바이트를 직접 전달하는 URI 대신 Amazon S3를 통해 비디오를 전달할 수도 있습니다. 다음은 Amazon S3를 통해 전달된 비디오 소스가 있는 비디오만 포함하는 콘텐츠 배열이 ContentBlock 있는 Message 객체를 보여줍니다URI.


{
    "role": "user",
    "content": [
        {
            "video": {
                "format": "mov | mkv | mp4 | webm | flv | mpeg | mpg | wmv | three_gp",
                "source": {
                    "s3Location": {
                        "uri": "s3 uri",
                        "bucketOwner": "s3 uri bucket owner"
                    }
                }
            }
        }
    ]
}

s3Location 파라미터는 미국 동부(버지니아 북부) 리전에서만 지원됩니다.

참고

수임된 역할에는 Amazon S3에 대한 s3:GetObject 권한이 있어야 합니다URI. bucketOwner 필드는 선택 사항이지만 요청을 하는 계정이 Amazon S3가 URI 있는 버킷을 소유하지 않은 경우 지정해야 합니다.

ContentBlock의 다른 필드는 도구 사용을 위한 것입니다.

role 필드에 역할을 지정합니다. 역할은 다음 중 하나일 수 있습니다.

사용자 - 모델로 메시지를 보내는 사람입니다.
어시스턴트 - 사용자의 메시지에 응답하는 모델입니다.

참고

content 필드에 적용되는 제한은 다음과 같습니다.

최대 20개의 이미지를 포함시킬 수 있습니다. 각 이미지의 크기, 높이, 너비는 각각 3.75MB, 8,000px, 8,000px 이하여야 합니다.
최대 5개 문서를 포함시킬 수 있습니다. 각 문서의 크기는 4.5MB 이하여야 합니다.
role이 user인 경우에만 이미지와 문서를 포함시킬 수 있습니다.

다음 messages 예제에서 사용자는 세 개의 가요 목록을 요청하고 모델은 노래의 목록을 생성합니다.


[
    {
        "role": "user",
        "content": [
            {
                "text": "Create a list of 3 pop songs."
            }
        ]
    },
    {
        "role": "assistant",
        "content": [
            {
                "text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"As It Was\" by Harry Styles\n2. \"Easy On Me\" by Adele\n3. \"Unholy\" by Sam Smith and Kim Petras"
            }
        ]
    }
]

시스템 프롬프트는 모델이 수행해야 하는 작업 또는 대화 중에 채택해야 하는 페르소나에 대한 지침이나 컨텍스트를 제공하는 프롬프트의 한 유형입니다. 다음 예제와 같이 system (SystemContentBlock) 필드에서 요청에 대한 시스템 프롬프트 목록을 지정할 수 있습니다.


[
    {
        "text": "You are an app that creates play lists for a radio station that plays rock and pop music. Only return song names and the artist. "
    }
]

또는 system tools 필드에 캐시 체크포인트를 추가하여 사용 중인 모델에 따라 프롬프트 캐싱을 사용할 수도 있습니다. 자세한 내용은 더 빠른 모델 추론을 위한 신속한 캐싱 단원을 참조하십시오.

참고

Amazon Bedrock 프롬프트 캐싱은 현재 일부 고객만 사용할 수 있습니다. 미리 보기 참여에 대한 자세한 내용은 Amazon Bedrock 프롬프트 캐싱을 참조하세요.

추론 파라미터

.Converse API는 inferenceConfig 필드()에서 설정한 추론 파라미터의 기본 세트를 지원합니다InferenceConfiguration. 추론 파라미터의 기본 세트는 다음과 같습니다.

maxTokens - 생성된 응답에서 허용할 최대 토큰 수입니다.
stopSequences - 중지 시퀀스 목록입니다. 중지 시퀀스는 모델이 응답 생성을 중지하게 하는 문자 시퀀스입니다.
temperature - 응답을 생성하는 동안 모델이 더 높은 확률 옵션을 선택할 가능성입니다.
topP - 모델이 다음 토큰으로 고려할 가능성이 가장 높은 후보의 비율입니다.

자세한 내용은 추론 파라미터를 사용하여 응답 생성에 영향을 주는 방법 단원을 참조하십시오.

다음 예제에서는 temperature 추론 파라미터를 JSON 설정합니다.


{"temperature": 0.5}

사용 중인 모델에 추가 추론 파라미터가 있는 경우 JSON additionalModelRequestFields 필드에 로 지정하여 해당 파라미터를 설정할 수 있습니다. 다음 예제에서는에서 사용할 수 top_k있는를 설정하는 방법을 JSON 보여줍니다.Anthropic Claude 은 메시지의 기본 추론 파라미터가 아닙니다API.


{"top_k": 200}

다음 예제와 같이 additionalModelResponseFieldPaths 필드에 추가 모델 파라미터의 경로를 지정할 수 있습니다.


[ "/stop_sequence" ]

는 필드에서 요청하는 추가 additionalModelResponseFields 필드를 API 반환합니다.

응답

에서 받는 응답 Converse API는 또는 Converse를 호출하는 작업에 따라 달라집니다ConverseStream.

Converse 응답

의 응답에서 Converse output 필드(ConverseOutput)에는 모델이 생성하는 메시지(메시지)가 포함됩니다. 메시지 콘텐츠는 content (ContentBlock) 필드에 있고 메시지에 해당하는 역할(user 또는 assistant)은 role 필드에 있습니다.

프롬프트 캐싱을 사용한 경우 사용 필드에서 캐시에서 읽고 캐시에 기록한 총 토큰 수를 각각 cacheReadInputTokensCount cacheWriteInputTokensCount 알려줍니다.

metrics 필드(ConverseMetrics)에는 호출에 대한 지표가 포함됩니다. 모델이 콘텐츠 생성을 중단한 이유를 알아보려면 stopReason 필드를 확인하세요. usage 필드()를 확인하여 요청에서 모델에 전달된 토큰과 응답에서 생성된 토큰에 대한 정보를 얻을 수 있습니다TokenUsage. 요청에서 추가 응답 필드를 지정한 경우는 필드JSON와 같이 additionalModelResponseFields 해당 필드를 API 반환합니다.

다음 예제는 요청에서 설명한 프롬프트를 전달할 때 Converse의 응답을 보여줍니다.


{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"Wannabe\" by Spice Girls\n2. \"Bitter Sweet Symphony\" by The Verve \n3. \"Don't Look Back in Anger\" by Oasis"
                }
            ]
        }
    },
    "stopReason": "end_turn",
    "usage": {
        "inputTokens": 125,
        "outputTokens": 60,
        "totalTokens": 185
    },
    "metrics": {
        "latencyMs": 1175
    }
}

ConverseStream 응답

ConverseStream을 직접적으로 호출하여 모델에서 응답을 스트리밍하면 stream 응답 필드에 스트림이 반환됩니다. 스트림은 이벤트를 다음과 같은 순서로 내보냅니다.

messageStart (MessageStartEvent). 메시지의 시작 이벤트입니다. 메시지의 역할이 포함됩니다.
contentBlockStart (ContentBlockStartEvent). 콘텐츠 블록 시작 이벤트입니다. 도구 사용 전용.
contentBlockDelta (ContentBlockDeltaEvent). 콘텐츠 블록 델타 이벤트. 모델이 생성하는 부분 텍스트 또는 도구 사용을 위한 부분 입력 json을 포함합니다.
contentBlockStop (ContentBlockStopEvent). 콘텐츠 블록 중지 이벤트입니다.
messageStop (MessageStopEvent). 메시지의 중지 이벤트입니다. 모델이 출력 생성을 중단한 이유를 포함합니다.
metadata (ConverseStreamMetadataEvent). 요청에 대한 메타데이터입니다. 메타데이터에는 (TokenUsage)의 토큰 사용량과 usage ()의 호출에 대한 지표가 포함됩니다metricsConverseStreamMetadataEvent.

ConverseStream 는 전체 콘텐츠 블록을 ContentBlockStartEvent 이벤트, 하나 이상의 ContentBlockDeltaEvent 이벤트 및 ContentBlockStopEvent 이벤트로 스트리밍합니다. contentBlockIndex 필드를 인덱스로 사용하여 콘텐츠 블록을 구성하는 이벤트를 상호 연관시킵니다.

다음 예제는 ConverseStream의 부분 응답입니다.


{'messageStart': {'role': 'assistant'}}
{'contentBlockDelta': {'delta': {'text': ''}, 'contentBlockIndex': 0}}
{'contentBlockDelta': {'delta': {'text': ' Title'}, 'contentBlockIndex': 0}}
{'contentBlockDelta': {'delta': {'text': ':'}, 'contentBlockIndex': 0}}
.
.
.
{'contentBlockDelta': {'delta': {'text': ' The'}, 'contentBlockIndex': 0}}
{'messageStop': {'stopReason': 'max_tokens'}}
{'metadata': {'usage': {'inputTokens': 47, 'outputTokens': 20, 'totalTokens': 67}, 'metrics': {'latencyMs': 100.0}}}

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

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

문서 규칙

지원되는 모델 및 모델 기능

Converse API 예제