기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # Converse API 사용 Converse API를 사용하려면 `Converse` 또는 `ConverseStream` 작업을 직접적으로 호출하여 모델에 메시지를 보냅니다. `Converse`를 직접적으로 호출하려면 `bedrock:InvokeModel` 작업에 대한 권한이 필요합니다. `ConverseStream`을 직접적으로 호출하려면 `bedrock:InvokeModelWithResponseStream` 작업에 대한 권한이 필요합니다. **Topics** + [ ## 요청 ](#conversation-inference-call-request) + [ ## 응답 ](#conversation-inference-call-response) **참고** 제한 사항은 InvokeModel, InvokeModelWithResponseStream, Converse 및 ConverseStream 작업에 적용됩니다. 자세한 내용은 [API 제한을](inference-api-restrictions.md) 참조하세요. ## 요청 [Amazon Bedrock 런타임 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt)로 [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 요청을 할 때 다음 필드를 포함할 수 있습니다. + **modelId** - 추론에 사용할 리소스를 지정할 수 있는 헤더의 필수 파라미터입니다. + 다음 필드를 사용하면 프롬프트를 사용자 지정할 수 있습니다. + **messages** - 프롬프트의 콘텐츠와 역할을 지정하는 데 사용합니다. + **system** - 모델의 지침 또는 컨텍스트를 정의하는 시스템 프롬프트를 지정하는 데 사용합니다. + **inferenceConfig** - 모든 모델에 공통적인 추론 파라미터를 지정하는 데 사용합니다. 추론 파라미터는 응답 생성에 영향을 미칩니다. + **additionalModelRequestFields** - 추론을 실행하는 모델과 관련된 추론 파라미터를 지정하는 데 사용합니다. + **promptVariables** – (프롬프트 관리의 프롬프트를 사용하는 경우)이 필드를 사용하여 프롬프트에서 입력할 변수와 이를 채울 값을 정의합니다. + 다음 필드를 사용하면 응답이 반환되는 방식을 사용자 지정할 수 있습니다. + **guardrailConfig** -이 필드를 사용하여 전체 프롬프트에 적용할 가드레일을 포함합니다. + **toolConfig** - 이 필드를 사용하여 모델이 응답을 생성하는 데 도움이 되는 도구를 포함합니다. + **additionalModelResponseFieldPaths** - 이 필드를 사용하여 JSON 포인터 객체로 반환할 필드를 지정합니다. + **serviceTier** -이 필드를 사용하여 특정 요청에 대한 서비스 계층을 지정합니다. + **requestMetadata** - 간접 호출 로그를 사용할 때 필터링할 수 있는 메타데이터를 포함하려면 이 필드를 사용합니다. **참고** `Converse` 또는 `ConverseStream`에서 프롬프트 관리 프롬프트를 사용하는 경우 다음 제한 사항이 적용됩니다. `additionalModelRequestFields`, `inferenceConfig`, `system` 또는 `toolConfig` 필드는 포함할 수 없습니다. `messages` 필드를 포함하면 프롬프트에 정의된 메시지 뒤에 메시지가 추가됩니다. `guardrailConfig` 필드를 포함하면 가드레일이 전체 프롬프트에 적용됩니다. [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 필드에 `guardContent` 블록을 포함하는 경우 가드레일은 해당 블록에만 적용됩니다. 섹션을 확장하여 `Converse` 요청 본문의 필드에 대해 자세히 알아봅니다. ### messages `messages` 필드는 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체의 배열로, 각 객체는 사용자와 모델 간의 메시지를 정의합니다. `Message` 객체는 다음 필드를 포함합니다. + **role** - 메시지가 `user`(모델로 전송된 프롬프트) 또는 `assistant`(모델 응답)에서 왔는지 정의합니다. + **content** - 프롬프트의 콘텐츠를 정의합니다. **참고** Amazon Bedrock은 사용자가 내용으로 제공하는 텍스트, 이미지 또는 문서를 저장하지 않습니다. 데이터는 응답을 생성하는 용도로만 사용됩니다. 후속 `Converse` 요청에서 대화에 모든 메시지를 포함시키고 `role` 필드를 사용하여 메시지가 사용자 또는 모델의 메시지인지 지정하여 대화 컨텍스트를 유지할 수 있습니다. `content` 필드는 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 객체의 배열에 매핑됩니다. 각 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 내에서 다음 필드 중 하나를 지정할 수 있습니다(모델별로 지원하는 블록을 알아보려면 [지원되는 모델 및 모델 기능](conversation-inference-supported-models-features.md) 참조). ------ #### [ text ] `text` 필드는 프롬프트를 지정하는 문자열에 매핑됩니다. `text` 필드는 동일한 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)에 지정된 다른 필드와 함께 해석됩니다. 다음은 텍스트 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)만 포함된 `content` 배열이 있는 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다. ``` { "role": "user", "content": [ { "text": "string" } ] } ``` ------ #### [ image ] `image` 필드는 [ImageBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ImageBlock.html)에 매핑됩니다. `bytes` 필드의 이미지에 대해 base64로 인코딩된 원시 바이트를 전달합니다. AWS SDK를 사용하는 경우 base64에서 바이트를 인코딩할 필요가 없습니다. `text` 필드를 제외하면 모델이 이미지를 설명합니다. 다음은 이미지 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)만 포함된 `content` 배열이 있는 예제 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다. ``` { "role": "user", "content": [ { "image": { "format": "png", "source": { "bytes": "image in bytes" } } } ] } ``` 요청 본문에 바이트를 직접 전달하는 대신 Amazon S3 URI를 지정할 수도 있습니다. 다음은 Amazon S3 URI를 통해 전달된 소스를 포함하는 콘텐츠 배열이 있는 샘플 `Message` 객체를 보여줍니다. ``` { "role": "user", "content": [ { "image": { "format": "png", "source": { "s3Location": { "uri": "s3://amzn-s3-demo-bucket/myImage", "bucketOwner": "111122223333" } } } } ] } ``` ------ #### [ document ] `document` 필드는 [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html)에 매핑됩니다. `DocumentBlock`을 포함할 경우 요청이 다음 제한 사항을 준수하는지 확인합니다. + [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체의 `content` 필드에는 문서와 관련된 프롬프트가 있는 `text` 필드도 포함해야 합니다. + `bytes` 필드의 문서에 대해 base64로 인코딩된 원시 바이트를 전달합니다. AWS SDK를 사용하는 경우 base64로 문서 바이트를 인코딩할 필요가 없습니다. + `name` 필드에는 다음 문자만 포함할 수 있습니다. + 영숫자 + 공백 문자(한 줄에 1개 이하) + 하이픈 + 괄호 + 대괄호 **참고** `name` 필드는 모델이 지침으로 잘못 해석할 여지가 있어 프롬프트 인젝션에 취약합니다. 따라서 중립 이름을 지정하는 것이 좋습니다. 문서를 사용할 때 `citations` 태그를 활성화하면 API 직접 호출의 응답으로 문서별 인용을 제공할 수 있습니다. 자세한 내용은 [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html) API를 참조하세요. 다음은 문서 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 및 필수 텍스트 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)만 포함된 `content` 배열이 있는 샘플 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다. ``` { "role": "user", "content": [ { "text": "string" }, { "document": { "format": "pdf", "name": "MyDocument", "source": { "bytes": "document in bytes" } } } ] } ``` 요청 본문에 바이트를 직접 전달하는 대신 Amazon S3 URI를 지정할 수도 있습니다. 다음은 Amazon S3 URI를 통해 전달된 소스를 포함하는 콘텐츠 배열이 있는 샘플 `Message` 객체를 보여줍니다. ``` { "role": "user", "content": [ { "text": "string" }, { "document": { "format": "pdf", "name": "MyDocument", "source": { "s3Location": { "uri": "s3://amzn-s3-demo-bucket/myDocument", "bucketOwner": "111122223333" } } } } ] } ``` ------ #### [ video ] `video` 필드는 [VideoBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_VideoBlock.html) 객체에 매핑됩니다. `bytes` 필드에 base64로 인코딩된 원시 바이트를 전달합니다. AWS SDK를 사용하는 경우 base64에서 바이트를 인코딩할 필요가 없습니다. `text` 필드를 포함하지 않으면 모델이 비디오를 설명합니다. 다음은 비디오 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)만 포함된 `content` 배열이 있는 샘플 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다. ``` { "role": "user", "content": [ { "video": { "format": "mp4", "source": { "bytes": "video in bytes" } } } ] } ``` 요청 본문에 바이트를 직접 전달하는 대신 Amazon S3 URI를 지정할 수도 있습니다. 다음은 Amazon S3 URI를 통해 전달된 소스를 포함하는 콘텐츠 배열이 있는 샘플 `Message` 객체를 보여줍니다. ``` { "role": "user", "content": [ { "video": { "format": "mp4", "source": { "s3Location": { "uri": "s3://amzn-s3-demo-bucket/myVideo", "bucketOwner": "111122223333" } } } } ] } ``` **참고** 수임된 역할에는 Amazon S3 URI에 대한 `s3:GetObject` 권한이 있어야 합니다. `bucketOwner` 필드는 선택 사항이지만 요청을 하는 계정이 Amazon S3 URI가 있는 버킷을 소유하지 않은 경우 지정해야 합니다. 자세한 내용은 [Amazon S3 버킷에 액세스 구성](s3-bucket-access.md) 단원을 참조하십시오. ------ #### [ cachePoint ] `cachePoint` 필드를 사용하여 프롬프트 캐싱을 활용하여 캐시 체크포인트를 함께 제공되는 프롬프트와 함께 메시지에 블록으로 추가할 수 있습니다. 프롬프트 캐싱은 대화 컨텍스트 캐싱을 시작하여 비용 및 지연 시간을 절감할 수 있는 기능입니다. 자세한 내용은 [더 빠른 모델 추론을 위한 프롬프트 캐싱](prompt-caching.md) 단원을 참조하십시오. 다음은 문서 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)과 함께 제공되는 필수 텍스트 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)이 포함된 `content` 배열과 문서 및 텍스트 콘텐츠를 모두 캐시에 추가하는 **cachePoint**가 있는 샘플 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다. ``` { "role": "user", "content": [ { "text": "string" }, { "document": { "format": "pdf", "name": "string", "source": { "bytes": "document in bytes" } } }, { "cachePoint": { "type": "default" } } ] } ``` ------ #### [ guardContent ] `guardContent` 필드는 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) 객체에 매핑됩니다. 이 필드를 사용하여 `guardrailConfig` 필드에 정의된 가드레일이 평가할 입력을 대상으로 지정할 수 있습니다. 이 필드를 지정하지 않으면 가드레일은 요청 본문의 모든 메시지를 평가합니다. `GuardBlock`에서 다음 유형의 콘텐츠를 전달할 수 있습니다. + **text** – 다음은 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) 텍스트만 포함하는 `content` 배열이 있는 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체의 예를 보여줍니다. ``` { "role": "user", "content": [ { "text": "Tell me what stocks to buy.", "qualifiers": [ "guard_content" ] } ] } ``` 평가할 텍스트를 정의하고 [컨텍스트 근거](guardrails-contextual-grounding-check.md)에 사용할 한정자를 포함합니다. + **image** – 다음은 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) 이미지만 포함하는 `content` 배열이 있는 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다. ``` { "role": "user", "content": [ { "format": "png", "source": { "bytes": "image in bytes" } } ] } ``` 이미지의 형식을 지정하고 이미지를 바이트 단위로 정의합니다. 가드레일 사용에 대한 자세한 내용은 [Amazon Bedrock Guardrails를 사용하여 유해한 콘텐츠 감지 및 필터링](guardrails.md) 섹션을 참조하세요. ------ #### [ reasoningContent ] `reasoningContent` 필드는 [ReasoningContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ReasoningContentBlock.html)에 매핑됩니다. 이 블록에는 함께 제공되는 `ContentBlock`에서 응답을 생성하기 위해 모델이 수행한 추론에 대한 콘텐츠가 포함되어 있습니다. 다음은 `ReasoningContentBlock` 및 함께 제공되는 텍스트 `ContentBlock`만 포함하는 `content` 배열이 있는 `Message` 객체를 보여줍니다. ``` { "role": "user", "content": [ { "text": "string" }, { "reasoningContent": { "reasoningText": { "text": "string", "signature": "string" } "redactedContent": "base64-encoded binary data object" } } ] } ``` `ReasoningContentBlock`에는 `redactedContent` 필드의 신뢰 및 안전상의 이유로 모델 공급자가 암호화한 추론의 콘텐츠 외에도 `reasoningText` 필드에 함께 제공되는 콘텐츠를 생성하는 데 사용되는 추론이 포함되어 있습니다. `reasoningText` 필드 내에서 `text` 필드는 추론을 설명합니다. `signature` 필드는 대화에 있는 모든 메시지의 해시이며 모델에서 사용하는 추론의 변조를 방지합니다. 후속 `Converse` 요청에 서명과 모든 이전 메시지를 포함해야 합니다. 메시지가 변경되면 응답에 오류가 발생합니다. ------ #### [ toolUse ] 모델이 사용할 도구에 대한 정보를 포함합니다. 자세한 내용은 [도구를 사용하여 Amazon Bedrock 모델 응답 완성](tool-use.md) 단원을 참조하십시오. ------ #### [ toolResult ] 도구를 사용하여 모델의 결과에 대한 정보를 포함합니다. 자세한 내용은 [도구를 사용하여 Amazon Bedrock 모델 응답 완성](tool-use.md) 단원을 참조하십시오. ------ 다음 `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](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)) 필드에서 요청에 대한 시스템 프롬프트 목록을 지정할 수 있습니다. ``` [ { "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. " } ] ``` ### inferenceConfig Converse API는 `inferenceConfig` 필드([InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InferenceConfiguration.html))에 설정한 추론 파라미터의 기본 세트를 지원합니다. 추론 파라미터의 기본 세트는 다음과 같습니다. + **maxTokens** - 생성된 응답에서 허용할 최대 토큰 수입니다. + **stopSequences** - 중지 시퀀스 목록입니다. 중지 시퀀스는 모델이 응답 생성을 중지하게 하는 문자 시퀀스입니다. + **temperature** - 응답을 생성하는 동안 모델이 더 높은 확률 옵션을 선택할 가능성입니다. + **topP** - 모델이 다음 토큰으로 고려할 가능성이 가장 높은 후보의 비율입니다. 자세한 내용은 [추론 파라미터를 사용하여 응답 생성에 영향을 주는 방법](inference-parameters.md) 섹션을 참조하세요. 다음 예제 JSON은 `temperature` 추론 파라미터를 설정합니다. ``` {"temperature": 0.5} ``` ### additionalModelRequestFields 사용 중인 모델에 추론 파라미터가 더 있는 경우 `additionalModelRequestFields` 필드에 JSON으로 지정하여 해당 파라미터를 설정할 수 있습니다. 다음 예제 JSON은 Anthropic Claude 모델에서 사용할 수 있지만 메시지 API의 기본 추론 파라미터는 아닌 `top_k`를 설정하는 방법을 보여줍니다. ``` {"top_k": 200} ``` ### promptVariables `modelId`의 [프롬프트 관리](prompt-management.md)에서 프롬프트를 추론 실행 대상으로 지정한 경우, 이 필드를 사용하여 프롬프트 변수에 실제 값을 입력합니다. `promptVariables` 필드는 변수를 대체할 프롬프트 및 값에 정의된 변수에 해당하는 키가 있는 JSON 객체에 매핑됩니다. 예를 들어 **Make me a *\$1\$1genre\$1\$1* playlist consisting of the following number of songs: *\$1\$1number\$1\$1*.**라는 프롬프트가 있다고 가정해 보겠습니다. 프롬프트의 ID는 `PROMPT12345`이고 해당 버전은 `1`입니다. 변수를 교체하기 위해 다음 `Converse` 요청을 보낼 수 있습니다. ``` POST /model/arn:aws:bedrock:us-east-1:111122223333:prompt/PROMPT12345:1/converse HTTP/1.1 Content-type: application/json { "promptVariables": { "genre" : "pop", "number": 3 } } ``` ### guardrailConfig 이 필드를 포함하여 [Amazon Bedrock Guardrails](guardrails.md)로 생성한 가드레일을 적용할 수 있습니다. 대화의 특정 메시지에 가드레일을 적용하려면 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)에 메시지를 포함합니다. 요청 본문에 `GuardrailConverseContentBlock`를 포함하지 않으면 `messages` 필드의 모든 메시지에 가드레일이 적용됩니다. 예제는 [Converse API에 가드레일 포함](guardrails-use-converse-api.md) 섹션을 참조하세요. ### toolConfig 이 필드를 사용하면 모델이 응답을 생성하는 데 사용할 도구를 정의할 수 있습니다. 자세한 내용은 [도구를 사용하여 Amazon Bedrock 모델 응답 완성](tool-use.md) 단원을 참조하십시오. ### additionalModelResponseFieldPaths 다음 예제와 같이 `additionalModelResponseFieldPaths` 필드에 추가 모델 파라미터의 경로를 지정할 수 있습니다. ``` [ "/stop_sequence" ] ``` API는 `additionalModelResponseFields` 필드에서 요청한 추가 필드를 반환합니다. ### requestMetadata 이 필드는 JSON 객체에 매핑됩니다. 이 객체 내에서 매핑되는 메타데이터 키와 값을 지정할 수 있습니다. 요청 메타데이터를 사용하여 모델 간접 호출 로그를 필터링할 수 있습니다. ### serviceTier 이 필드는 JSON 객체에 매핑됩니다. 특정 요청에 대한 서비스 계층을 지정할 수 있습니다. 다음 예제에서는 `serviceTier` 구조를 보여줍니다. ``` "serviceTier": { "type": "reserved" | "priority" | "default" | "flex" } ``` 요금 및 성능 특성을 포함하여 서비스 티어에 대한 자세한 내용은 섹션을 참조하세요[성능 및 비용 최적화를 위한 서비스 티어](service-tiers-inference.md). 사용 중인 모델에 따라 `system` 또는 `tools` 필드에 선택적으로 캐시 체크포인트를 추가하여 프롬프트 캐싱을 사용할 수도 있습니다. 자세한 내용은 [더 빠른 모델 추론을 위한 프롬프트 캐싱](prompt-caching.md) 단원을 참조하십시오. ## 응답 Converse API로부터 받는 응답은 직접적으로 호출하는 작업(`Converse` 또는 `ConverseStream`)에 따라 달라집니다. **Topics** + [ ### Converse 응답 ](#conversation-inference-call-response-converse) + [ ### ConverseStream 응답 ](#conversation-inference-call-response-converse-stream) ### Converse 응답 `Converse`의 응답에서 `output` 필드([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html))에는 모델이 생성하는 메시지([Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html))가 포함됩니다. 메시지 내용은 `content`([ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)) 필드에 있고 메시지에 해당하는 역할(`user` 또는 `assistant`)은 `role` 필드에 있습니다. [프롬프트 캐싱](prompt-caching.md)을 사용한 경우, 사용 필드에서 `cacheReadInputTokensCount`와 `cacheWriteInputTokensCount`는 각각 캐시에서 읽은 총 토큰 수와 캐시에 쓴 총 토큰 수를 알려줍니다. [서비스 티어를](#inference-service-tiers) 사용한 경우 응답 필드에서 `service tier`는 요청에 사용된 서비스 티어를 알려줍니다. `metrics` 필드([ConverseMetrics](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseMetrics.html))에는 직접 호출에 대한 지표가 포함됩니다. 모델이 콘텐츠 생성을 중단한 이유를 알아보려면 `stopReason` 필드를 확인하세요. `usage` 필드([TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html))를 확인하여 요청에서 모델에 전달된 토큰과 응답에서 생성된 토큰에 대한 정보를 얻을 수 있습니다. 요청에서 추가 응답 필드를 지정한 경우 API는 해당 필드를 `additionalModelResponseFields` 필드에 JSON으로 반환합니다. 다음 예제는 [요청](#conversation-inference-call-request)에서 설명한 프롬프트를 전달할 때 `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` 응답 필드에 스트림이 반환됩니다. 스트림은 이벤트를 다음과 같은 순서로 내보냅니다. 1. `messageStart` ([MessageStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStartEvent.html)). 메시지의 시작 이벤트입니다. 메시지의 역할이 포함됩니다. 1. `contentBlockStart` ([ContentBlockStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStartEvent.html)). 콘텐츠 블록 시작 이벤트입니다. 도구 사용 전용. 1. `contentBlockDelta` ([ContentBlockDeltaEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockDeltaEvent.html)). 콘텐츠 블록 델타 이벤트입니다. 다음 중 하나를 포함합니다. + `text` - 모델이 생성하는 부분 텍스트입니다. + `reasoningContent` - 모델이 응답을 생성하기 위해 수행하는 부분 추론입니다. 후속 `Converse` 요청의 모든 이전 메시지 외에도 반환된 `signature`를 제출해야 합니다. 메시지가 변경되면 응답에 오류가 발생합니다. + `toolUse` - 도구 사용을 위한 부분 입력 JSON 객체입니다. 1. `contentBlockStop` ([ContentBlockStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStopEvent.html)). 콘텐츠 블록 중지 이벤트입니다. 1. `messageStop` ([MessageStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStopEvent.html)). 메시지에 대한 중지 이벤트입니다. 모델이 출력 생성을 중단한 이유를 포함합니다. 1. `metadata` ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)). 요청에 대한 메타데이터입니다. 메타데이터에는 `usage`([TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html))의 토큰 사용량과 `metrics`([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html))의 직접 호출에 대한 지표가 포함됩니다. 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}}} ```