기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Converse API에 가드레일 포함
가드레일을 사용하여 Converse API로 만든 대화형 앱을 보호할 수 있습니다. 예를 들어 Converse API로 채팅 앱을 만드는 경우, 가드레일을 사용하여 사용자가 입력한 부적절한 콘텐츠와 모델에서 생성된 부적절한 콘텐츠를 차단할 수 있습니다. Converse API에 대한 자세한 내용은 [Converse API를 사용한 추론](conversation-inference.md) 섹션을 참조하세요.
**Topics**
+ [가드레일을 사용하여 Converse API 직접 호출](#guardrails-use-converse-api-call)
+ [Converse API를 사용할 때 응답 처리](#guardrails-use-converse-api-response)
+ [가드레일과 함께 Converse API를 사용하기 위한 예제 코드](#converse-api-guardrail-example)
## 가드레일을 사용하여 Converse API 직접 호출
가드레일을 사용하려면 [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 또는 [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)(스트리밍 응답용) 작업을 직접적으로 호출할 때 가드레일에 대한 구성 정보를 포함해야 합니다. 필요에 따라 가드레일이 메시지에서 특정 콘텐츠를 평가하도록 선택할 수도 있습니다. 가드레일 및 Converse API와 함께 사용할 수 있는 모델에 대한 자세한 내용은 [모델을 한눈에](model-cards.md) 참조하세요.
**Topics**
+ [Converse API와 함께 작동하도록 가드레일 구성](#guardrails-use-converse-api-call-configure)
+ [메시지의 특정 콘텐츠만 평가](#guardrails-use-converse-api-call-message)
+ [Converse API로 전송된 시스템 프롬프트 보호](#guardrails-use-converse-api-call-message-system-guard)
+ [메시지 및 시스템 프롬프트 가드레일 동작](#guardrails-use-converse-api-call-message-system-message-guard)
### Converse API와 함께 작동하도록 가드레일 구성
`guardrailConfig` 입력 파라미터에서 가드레일의 구성 정보를 지정합니다. 구성에는 사용하려는 가드레일의 ID와 버전이 포함됩니다. 가드레일에 대한 추적을 활성화하여 가드레일이 차단한 콘텐츠에 대한 정보를 확인할 수도 있습니다.
다음 예제와 같이 `Converse` 작업에서 `guardrailConfig`는 [GuardrailConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConfiguration.html) 객체입니다.
```
{
"guardrailIdentifier": "{{Guardrail ID}}",
"guardrailVersion": "{{Guardrail version}}",
"trace": "enabled"
}
```
`ConverseStream`을 사용하는 경우 [GuardrailStreamConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailStreamConfiguration.html) 객체를 전달합니다. 필요한 경우 `streamProcessingMode` 필드를 사용하여 스트리밍 응답 청크를 반환하기 전에 모델이 가드레일 평가를 완료하도록 지정할 수 있습니다. 또는 가드레일이 백그라운드에서 평가를 계속하는 동안 모델이 비동기식으로 응답하도록 할 수 있습니다. 자세한 내용은 [콘텐츠를 필터링하도록 스트리밍 응답 동작 구성](guardrails-streaming.md) 단원을 참조하십시오.
### 메시지의 특정 콘텐츠만 평가
[메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html)를 모델에 전달하면 가드레일이 메시지의 내용을 평가합니다. `guardContent`([GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)) 필드를 사용하여 메시지의 특정 부분을 평가할 수도 있습니다.
**작은 정보**
`guardContent` 필드를 사용하는 것은 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 및 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)에 입력 태그를 사용하는 것과 유사합니다. 자세한 내용은 [사용자 입력에 태그를 적용하여 콘텐츠 필터링](guardrails-tagging.md) 단원을 참조하십시오.
예를 들어, 다음 가드레일은 `guardContent` 필드의 콘텐츠만 평가하며 메시지의 나머지 부분은 평가하지 않습니다. 이는 다음 예제와 같이 가드레일이 대화에서 최근 메시지만 평가하도록 하는 데 유용합니다.
**중요**
메시지에 `guardContent` 블록을 포함하면 가드레일은 `guardContent` 블록 내의 콘텐츠*만* 평가합니다. 래핑되지 않은 다른 모든 콘텐츠 블록`guardContent`은 완전히 건너뛰고 가드레일에 의해 평가되지 않습니다.
```
[
{
"role": "user",
"content": [
{
"text": "Create a playlist of 2 pop songs."
}
]
},
{
"role": "assistant",
"content": [
{
"text": "Sure! Here are two pop songs:\n1. \"Bad Habits\" by Ed Sheeran\n2. \"Blinding Lights\" by The Weeknd\n\nWould you like to add any more songs to this playlist?"
}
]
},
{
"role": "user",
"content": [
{
"guardContent": {
"text": {
"text": "Create a playlist of 2 heavy metal songs."
}
}
}
]
}
]
```
`guardContent`의 또 다른 사용 사례는 가드레일이 평가할 필요가 없는 추가 컨텍스트를 메시지에 제공하는 것입니다. 다음 예제에서 가드레일은 `"Create a playlist of heavy metal songs"`만 평가하고 `"Only answer with a list of songs"`는 무시합니다.
```
messages = [
{
"role": "user",
"content": [
{
"text": "Only answer with a list of songs."
},
{
"guardContent": {
"text": {
"text": "Create a playlist of heavy metal songs."
}
}
}
]
}
]
```
콘텐츠가 `guardContent` 블록에 없는 경우 반드시 평가되지 않는다는 의미는 아닙니다. 이 동작은 가드레일이 사용하는 필터링 정책에 따라 달라집니다.
다음 예제는 [컨텍스트 근거 검사](guardrails-contextual-grounding-check.md)(`qualifiers` 필드 기반)가 있는 두 `guardContent` 블록을 보여줍니다. 가드레일의 컨텍스트 근거 검사는 이러한 블록의 콘텐츠만 평가합니다. 그러나 가드레일에 "background"라는 단어를 차단하는 [단어 필터](guardrails-content-filters.md)도 있는 경우 "Some additional background information"이라는 텍스트는 `guardContent` 블록에 없더라도 여전히 평가됩니다.
```
[{
"role": "user",
"content": [{
"guardContent": {
"text": {
"text": "London is the capital of UK. Tokyo is the capital of Japan.",
"qualifiers": ["grounding_source"]
}
}
},
{
"text": "Some additional background information."
},
{
"guardContent": {
"text": {
"text": "What is the capital of Japan?",
"qualifiers": ["query"]
}
}
}
]
}]
```
### Converse API로 전송된 시스템 프롬프트 보호
Converse API로 전송하는 시스템 프롬프트와 함께 가드레일을 사용할 수 있습니다. 시스템 프롬프트를 보호하려면 다음 예제와 같이 API에 전달하는 시스템 프롬프트에서 `guardContent`([SystemContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)) 필드를 지정합니다.
```
[
{
"guardContent": {
"text": {
"text": "Only respond with Welsh heavy metal songs."
}
}
}
]
```
`guardContent` 필드를 제공하지 않으면 가드레일은 시스템 프롬프트 메시지를 평가하지 않습니다.
### 메시지 및 시스템 프롬프트 가드레일 동작
가드레일이 `guardContent` 필드를 평가하는 방법은 시스템 프롬프트와 사용자가 전달하는 메시지 사이에서 다르게 작동합니다.
| | 시스템 프롬프트에 가드레일 블록이 있는 경우 | 시스템 프롬프트에 가드레일 블록이 없는 경우 |
| --- | --- | --- |
| **메시지에 가드레일 블록이 있는 경우** | 시스템: 가드레일이 가드레일 블록의 콘텐츠를 조사합니다.
메시지: 가드레일이 가드레일 블록의 콘텐츠를 조사합니다. | 시스템: 가드레일이 아무것도 조사하지 않습니다.
메시지: 가드레일이 가드레일 블록의 콘텐츠를 조사합니다. |
| **메시지에 가드레일 블록이 있는 경우** | 시스템: 가드레일이 가드레일 블록의 콘텐츠를 조사합니다.
메시지: 가드레일이 모든 것을 조사합니다. | 시스템: 가드레일이 아무것도 조사하지 않습니다.
메시지: 가드레일이 모든 것을 조사합니다. |
## Converse API를 사용할 때 응답 처리
Converse 작업을 직접적으로 호출하면 가드레일은 사용자가 보내는 메시지를 평가합니다. 가드레일이 차단된 콘텐츠를 감지하면 다음과 같이 진행됩니다.
+ 응답의 `stopReason` 필드가 `guardrail_intervened`로 설정됩니다.
+ 추적을 활성화한 경우 `trace`([ConverseTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseTrace.html)) 필드에서 추적을 사용할 수 있습니다. `ConverseStream`을 사용하면 작업이 반환하는 메타데이터([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html))에 추적이 저장됩니다.
+ 가드레일에 구성한 차단된 콘텐츠 텍스트는 `output`([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)) 필드에 반환됩니다. `ConverseStream`을 사용하면 차단된 콘텐츠 텍스트는 스트리밍된 메시지에 저장됩니다.
다음 부분 응답은 차단된 콘텐츠 텍스트와 가드레일 평가의 추적을 보여줍니다. 가드레일이 메시지에서 *Heavy metal*이라는 용어를 차단했습니다.
```
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"text": "Sorry, I can't answer questions about heavy metal music."
}
]
}
},
"stopReason": "guardrail_intervened",
"usage": {
"inputTokens": 0,
"outputTokens": 0,
"totalTokens": 0
},
"metrics": {
"latencyMs": 721
},
"trace": {
"guardrail": {
"inputAssessment": {
"3o06191495ze": {
"topicPolicy": {
"topics": [
{
"name": "Heavy metal",
"type": "DENY",
"action": "BLOCKED"
}
]
},
"invocationMetrics": {
"guardrailProcessingLatency": 240,
"usage": {
"topicPolicyUnits": 1,
"contentPolicyUnits": 0,
"wordPolicyUnits": 0,
"sensitiveInformationPolicyUnits": 0,
"sensitiveInformationPolicyFreeUnits": 0,
"contextualGroundingPolicyUnits": 0
},
"guardrailCoverage": {
"textCharacters": {
"guarded": 39,
"total": 72
}
}
}
}
}
}
}
}
```
## 가드레일과 함께 Converse API를 사용하기 위한 예제 코드
이 예제에서는 `Converse` 및 `ConverseStream` 작업과의 대화를 보호하는 방법을 보여줍니다. 이 예제에서는 모델이 헤비 메탈 장르의 노래를 포함하는 재생 목록을 만들지 못하도록 하는 방법을 보여줍니다.
**대화를 보호하는 방법**
1. [가드레일 생성](guardrails-components.md)의 지침에 따라 가드레일을 만듭니다.
+ **이름** - *Heavy metal*을 입력합니다.
+ **주제에 대한 정의** - *Avoid mentioning songs that are from the heavy metal genre of music*(헤비 메탈 장르의 노래는 언급하지 마세요)이라고 입력합니다.
+ **샘플 문구 추가** - *Create a playlist of heavy metal songs*(헤비 메탈 노래 재생 목록을 만들어 주세요)라고 입력합니다.
9단계에서 다음을 입력합니다.
+ **차단된 프롬프트에 표시되는 메시지** - *Sorry, I can't answer questions about heavy metal music*(헤비 메탈 음악에 대한 질문에는 답변을 드릴 수 없습니다)이라고 입력합니다.
+ **차단된 응답에 대한 메시지** - *Sorry, the model generated an answer that mentioned heavy metal music*(모델이 헤비 메탈 음악을 언급하는 답변을 생성했습니다)이라고 입력합니다.
다른 가드레일 옵션도 구성할 수 있지만 이 예제에서는 필요하지 않습니다.
1. [가드레일 버전 생성](guardrails-versions-create.md)의 지침에 따라 가드레일 버전을 만듭니다.
1. 다음 코드 예제([Converse](#converse-api-guardrail-example-converse) 및 [ConverseStream](#converse-api-guardrail-example-converse-stream))에서 다음 변수를 설정합니다.
+ `guardrail_id` - 1단계에서 만든 가드레일의 ID입니다.
+ `guardrail_version` - 2단계에서 만든 가드레일의 버전입니다.
+ `text` – `Create a playlist of heavy metal songs.`를 사용합니다.
1. 예제 코드를 실행합니다. 출력에는 가드레일 평가와 출력 메시지(`Text: Sorry, I can't answer questions about heavy metal music.`)가 표시되어야 합니다. 가드레일 입력 평가는 모델이 입력 메시지에서 *heavy metal*이라는 용어를 감지했음을 보여줍니다.
1. (선택 사항) `text`의 값을 *List all genres of rock music*(락 음악의 모든 장르를 나열해 주세요)으로 변경하여 가드레일이 모델이 생성하는 부적절한 텍스트를 차단하는지 테스트합니다. 예제를 다시 실행합니다. 응답에 출력 평가가 표시됩니다.
------
#### [ Converse ]
다음 코드는 `Converse` 작업에 가드레일을 사용합니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use a guardrail with the Converse API.
"""
import logging
import json
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
messages,
guardrail_config):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
messages JSON): The message to send to the model.
guardrail_config : Configuration for the guardrail.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages,
guardrailConfig=guardrail_config
)
return response
def main():
"""
Entrypoint for example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
# The model to use.
model_id="meta.llama3-8b-instruct-v1:0"
# The ID and version of the guardrail.
guardrail_id = "Your guardrail ID"
guardrail_version = "DRAFT"
# Configuration for the guardrail.
guardrail_config = {
"guardrailIdentifier": guardrail_id,
"guardrailVersion": guardrail_version,
"trace": "enabled"
}
text = "Create a playlist of 2 heavy metal songs."
context_text = "Only answer with a list of songs."
# The message for the model and the content that you want the guardrail to assess.
messages = [
{
"role": "user",
"content": [
{
"text": context_text,
},
{
"guardContent": {
"text": {
"text": text
}
}
}
]
}
]
try:
print(json.dumps(messages, indent=4))
bedrock_client = boto3.client(service_name='bedrock-runtime')
response = generate_conversation(
bedrock_client, model_id, messages, guardrail_config)
output_message = response['output']['message']
if response['stopReason'] == "guardrail_intervened":
trace = response['trace']
print("Guardrail trace:")
print(json.dumps(trace['guardrail'], indent=4))
for content in output_message['content']:
print(f"Text: {content['text']}")
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ ConverseStream ]
다음 코드는 `ConverseStream` 작업에 가드레일을 사용합니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use a guardrail with the ConverseStream operation.
"""
import logging
import json
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def stream_conversation(bedrock_client,
model_id,
messages,
guardrail_config):
"""
Sends messages to a model and streams the response.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
messages (JSON) : The messages to send.
guardrail_config : Configuration for the guardrail.
Returns:
Nothing.
"""
logger.info("Streaming messages with model %s", model_id)
response = bedrock_client.converse_stream(
modelId=model_id,
messages=messages,
guardrailConfig=guardrail_config
)
stream = response.get('stream')
if stream:
for event in stream:
if 'messageStart' in event:
print(f"\nRole: {event['messageStart']['role']}")
if 'contentBlockDelta' in event:
print(event['contentBlockDelta']['delta']['text'], end="")
if 'messageStop' in event:
print(f"\nStop reason: {event['messageStop']['stopReason']}")
if 'metadata' in event:
metadata = event['metadata']
if 'trace' in metadata:
print("\nAssessment")
print(json.dumps(metadata['trace'], indent=4))
def main():
"""
Entrypoint for streaming message API response example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
# The model to use.
model_id = "amazon.nova-micro-v1:0"
# The ID and version of the guardrail.
guardrail_id = "Change to your guardrail ID"
guardrail_version = "DRAFT"
# Configuration for the guardrail.
guardrail_config = {
"guardrailIdentifier": guardrail_id,
"guardrailVersion": guardrail_version,
"trace": "enabled",
"streamProcessingMode" : "sync"
}
text = "Create a playlist of heavy metal songs."
# The message for the model and the content that you want the guardrail to assess.
messages = [
{
"role": "user",
"content": [
{
"text": text,
},
{
"guardContent": {
"text": {
"text": text
}
}
}
]
}
]
try:
bedrock_client = boto3.client(service_name='bedrock-runtime')
stream_conversation(bedrock_client, model_id, messages,
guardrail_config)
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
else:
print(
f"Finished streaming messages with model {model_id}.")
if __name__ == "__main__":
main()
```
------