Converse에 가드레일 포함 API - Amazon Bedrock
가드레일을 API 사용하여 Converse 호출Converse 사용 시 응답 처리 API가드레일과 API 함께 Converse를 사용하기 위한 예제 코드

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Converse에 가드레일 포함 API

가드레일을 사용하여 Converse 로 생성한 대화형 앱을 보호할 수 있습니다API. 예를 들어 Converse 를 사용하여 채팅 앱을 생성하는 경우 가드레일을 사용하여 사용자가 입력한 부적절한 콘텐츠와 모델에서 생성된 부적절한 콘텐츠를 차단할 API수 있습니다. Converse에 대한 자세한 내용은 섹션을 API참조하세요Converse API 작업과 대화 수행.

가드레일을 API 사용하여 Converse 호출

가드레일을 사용하려면 Converse 또는 ConverseStream (스트리밍 응답) 작업을 호출할 때 가드레일에 대한 구성 정보를 포함합니다. 필요에 따라 가드레일을 평가하려는 메시지에서 특정 콘텐츠를 선택할 수 있습니다. 가드레일 및 Converse와 함께 사용할 수 있는 모델에 대한 자세한 내용은 섹션을 API참조하세요지원되는 모델 및 모델 기능.

Converse와 함께 작동하도록 가드레일 구성 API

guardrailConfig 입력 파라미터에서 가드레일의 구성 정보를 지정합니다. 구성에는 사용하려는 가드레일의 ID와 버전이 포함됩니다. 가드레일이 차단한 콘텐츠에 대한 정보를 제공하는 가드레일에 대한 추적을 활성화할 수도 있습니다.

다음 예제와 같이 Converse 작업에서 guardrailConfig는 GuardrailConfiguration 객체입니다.

{
        "guardrailIdentifier": "Guardrail ID",
        "guardrailVersion": "Guardrail version",
        "trace": "enabled"
}

를 사용하는 경우 GuardrailStreamConfiguration 객체를 ConverseStream전달합니다. 선택적으로 streamProcessingMode 필드를 사용하여 스트리밍 응답 청크를 반환하기 전에 모델이 가드레일 평가를 완료하도록 지정할 수 있습니다. 또는 가드레일이 백그라운드에서 평가를 계속하는 동안 모델을 비동기식으로 응답할 수 있습니다. 자세한 내용은 콘텐츠를 필터링하기 위한 스트리밍 응답 동작 구성 단원을 참조하십시오.

를 사용하여 유해한 콘텐츠를 평가하기 위한 메시지 보호 APIs

메시지(메시지 )를 모델에 전달하면 가드레일이 메시지의 내용을 평가합니다. 선택적으로 guardContent (GuardrailConverseContentBlock) 필드를 지정하여 메시지에서 선택한 콘텐츠를 보호할 수 있습니다. 가드레일은 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. \"All Of The Lights\" by Kanye West\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."
                    }
                }
            }
        ]
    }
]

또 다른 용도는 가드레일이 추가 컨텍스트를 평가하지 않고 메시지에 대한 추가 컨텍스트를 제공하는 것입니다.

[
    {
        "role": "user",
        "content": [
            {
                "text": "Only answer with a list of songs."
            },
            {
                "guardContent": {
                    "text": {
                        "text": "Create a playlist of heavy metal songs."
                    }
                }
            }
        ]
    }
]
참고

guardContent 필드를 사용하는 것은 InvokeModel 및 에서 입력 태그를 사용하는 것과 유사합니다InvokeModelWithResponseStream. 자세한 내용은 사용자 입력에 태그를 적용하여 콘텐츠를 필터링합니다. 단원을 참조하십시오.

Converse로 전송된 시스템 프롬프트 보호 API

Converse 에 보내는 시스템 프롬프트와 함께 가드레일을 사용할 수 있습니다API. 시스템 프롬프트를 보호하려면 다음 예제와 API같이 에 전달하는 시스템 프롬프트에서 guardContent (SystemContentBlock) 필드를 지정합니다.

[
    {
        "guardContent": {
            "text": {
                "text": "Only respond with Welsh heavy metal songs."
            }
        }
    }
]

guardContent 필드를 제공하지 않으면 가드레일에서 시스템 프롬프트 메시지를 평가하지 않습니다.

메시지 및 시스템 프롬프트 가드레일 동작

가드레일이 guardContent 필드를 평가하는 방법은 시스템 프롬프트와 메시지에서 전달하는 메시지 간에 다르게 작동합니다.

시스템 프롬프트에 Guardrail 블록이 있음 시스템 프롬프트에 Guardrail 블록이 없음

메시지에 Guardrail 블록이 있음

시스템: Guardrail은 Guardrail 블록의 콘텐츠를 조사합니다.

메시지: Guardrail은 Guardrail 블록의 콘텐츠를 조사합니다.

시스템: Guardrail은 아무것도 조사하지 않습니다.

메시지: Guardrail은 Guardrail 블록의 콘텐츠를 조사합니다.

메시지에 Guardrail 블록이 없음

시스템: Guardrail은 Guardrail 블록의 콘텐츠를 조사합니다.

메시지: Guardrail이 모든 것을 조사합니다.

시스템: Guardrail은 아무것도 조사하지 않습니다.

메시지: Guardrail이 모든 것을 조사합니다.

Converse 사용 시 응답 처리 API

Converse 작업을 호출하면 가드레일은 사용자가 보내는 메시지를 평가합니다. 가드레일이 차단된 콘텐츠를 감지하면 다음이 발생합니다.

  • 응답의 stopReason 필드는 로 설정됩니다guardrail_intervened.

  • 추적을 활성화한 경우 trace (ConverseTrace) 필드에서 추적을 사용할 수 있습니다. ConverseStream를 사용하면 작업이 반환하는 메타데이터(ConverseStreamMetadataEvent)에 추적이 있습니다.

  • 가드레일에 구성한 차단된 콘텐츠 텍스트가 output (ConverseOutput) 필드에 반환됩니다. 차단ConverseStream된 콘텐츠 텍스트는 스트리밍된 메시지에 있습니다.

다음 부분 응답은 차단된 콘텐츠 텍스트와 가드레일 평가의 추적을 보여줍니다. 가드레일이 메시지에서 중금속이라는 용어를 차단했습니다.

{
    "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
                            }
                        }
                    }
                }
            }
        }
    }
}

가드레일과 API 함께 Converse를 사용하기 위한 예제 코드

이 예제에서는 Converse 및 ConverseStream 작업과의 대화를 보호하는 방법을 보여줍니다. 이 예제에서는 모델이 중금속 장르의 노래를 포함하는 재생 목록을 생성하지 못하도록 하는 방법을 보여줍니다.

대화를 보호하려면

  1. 의 지침에 따라 가드레일을 생성합니다가드레일 생성. 6a단계에서 다음 정보를 입력하여 거부된 주제를 생성합니다.

    • 이름 - 중금속 을 입력합니다.

    • 주제에 대한 정의 - 중금속 장르의 음악에서 가져온 노래를 언급하지 않도록 입력하세요.

    • 샘플 구문 추가 - 중금속 노래 재생 목록 생성을 입력합니다.

    9단계에서 다음을 입력합니다.

    • 차단된 프롬프트에 표시된 메시지 - 죄송합니다. 중금속 음악에 대한 질문에 답할 수 없습니다를 입력합니다.

    • 차단된 응답에 대한 메시징 - 죄송합니다. 모델이 중금속 음악을 언급하는 응답을 생성했습니다를 입력합니다.

    다른 가드레일 옵션을 구성할 수 있지만 이 예제에서는 필요하지 않습니다.

  2. 의 지침에 따라 가드레일 버전을 생성합니다가드레일 버전 생성.

  3. 다음 코드 예제(Converse 및 ConverseStream)에서 다음 변수를 설정합니다.

    • guardrail_id - 1단계에서 생성한 가드레일의 ID입니다.

    • guardrail_version - 2단계에서 생성한 가드레일의 버전입니다.

    • text - 사용 Create a playlist of heavy metal songs.

  4. 코드 예제를 실행합니다. 출력에는 가드레일 평가와 출력 메시지 가 표시되어야 합니다Text: Sorry, I can't answer questions about heavy metal music.. 가드레일 입력 평가는 모델이 입력 메시지에서 중금속이라는 용어를 탐지했음을 보여줍니다.

  5. (선택 사항) 의 값을 로 변경하여 가드레일이 모델이 생성하는 부적절한 텍스트를 차단text하는지 테스트합니다. 록 음악의 모든 장르 나열. 예제를 다시 실행합니다. 응답에 출력 평가가 표시됩니다.

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.titan-text-express-v1"

    # 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()