# Converse API 사용
Converse API는 Amazon Nova 모델과 상호 작용하기 위한 통합 인터페이스를 제공합니다. 모델별 세부 정보를 간략화하고 모든 Amazon Nova 모델에서 멀티턴 대화, 시스템 프롬프트 및 스트리밍 응답을 처리하기 위한 일관된 방법을 제공합니다.
**Topics**
+ [요청 구조](#converse-api-request-structure)
+ [시스템 프롬프트 사용](#converse-api-system-prompt)
+ [추론 파라미터](#converse-api-inference-params)
+ [추론 사용](#converse-api-reasoning)
## 요청 구조
+ **멀티턴 대화:** 여러 교환에서 컨텍스트 유지 관리
+ **시스템 프롬프트:** 페르소나 또는 응답 지침 등의 시스템 지침
+ **문서 채팅:** 문서 또는 문서 모음과 상호 작용 및 쿼리
+ **비전:** 이미지 및 비디오 처리 및 분석
+ **도구 사용:** 모델이 외부 도구 및 API를 사용하도록 지원
+ **가드레일:** 콘텐츠 필터링 및 안전 제어 적용
+ **추론:** 복잡한 문제 해결을 위한 확장된 사고
기본 Converse API 요청에는 모델 ID 및 메시지 목록이 포함됩니다.
```
import boto3
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')
response = bedrock.converse(
modelId='us.amazon.nova-2-lite-v1:0',
messages=[
{
'role': 'user',
'content': [{'text': 'What is machine learning?'}]
}
]
)
content_list = response["output"]["message"]["content"]
# Extract the first text block
text = next((item["text"] for item in content_list if "text" in item), None)
if text is not None:
print(text)
```
## 시스템 프롬프트 사용
시스템 프롬프트는 모델에 컨텍스트 및 지침을 제공합니다.
```
import boto3
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')
response = bedrock.converse(
modelId='us.amazon.nova-2-lite-v1:0',
system=[
{'text': 'You are a helpful AI assistant specializing in cloud computing.'}
],
messages=[
{
'role': 'user',
'content': [{'text': 'Explain serverless computing.'}]
}
]
)
# Print the response text
content_list = response["output"]["message"]["content"]
text = next((item["text"] for item in content_list if "text" in item), None)
if text is not None:
print(text)
```
## 추론 파라미터
추론 파라미터를 사용하여 모델 출력을 제어합니다. 다음은 사용 가능한 추론 파라미터입니다.
+ maxTokens(정수): 생성할 최대 토큰 수(최대 65,000개)입니다. 지정하지 않으면 모델은 요청 컨텍스트를 기반으로 동적 기본값을 사용합니다.
+ temperature(float): 무작위성을 제어합니다(0.0\$11.0, 기본값 0.7). 값이 낮을수록 더 결정적인 출력이 생성됨
+ topP(float): Nucleus 샘플링 임계치(0\$11, 기본값 0.9)입니다. 값이 낮을수록 더 집중된 출력이 생성됨
+ stopSequences(배열): 발생 시 생성을 중지하는 문자의 시퀀스
예제:
```
import boto3
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')
response = bedrock.converse(
modelId='us.amazon.nova-2-lite-v1:0',
messages=[
{
'role': 'user',
'content': [{'text': 'Write a short story.'}]
}
],
inferenceConfig={
'maxTokens': 512,
'temperature': 0.7,
'topP': 0.9,
'stopSequences': ['END']
}
)
content_list = response["output"]["message"]["content"]
text = next((item["text"] for item in content_list if "text" in item), None)
if text is not None:
print(text)
```
## 추론 사용
Nova 2 Lite는 복잡한 문제 해결을 위해 확장된 사고를 지원합니다. `reasoningConfig`를 사용하여 추론을 활성화합니다.
기본적으로 추론은 단순한 쿼리에서 속도와 비용을 최적화하기 위해 비활성화됩니다. 이러한 간단한 태스크를 넘어선 작업이 필요한 경우 추론을 활성화할 수 있습니다. Nova 2에서는 세 가지 노력 수준을 통해 추론 깊이를 유연하게 제어할 수 있습니다.
낮은 수준의 노력(`maxReasoningEffort: "low"`)
적합한 작업: 체계적인 사고가 요구되는 복잡성이 늘어난 태스크. 예를 들어 모델이 기존 코드 품질을 신중하게 고려해야 하는 코드 검토 및 개선 제안, 여러 요인을 신중하게 고려해야 하는 분석 태스크 또는 방법론적 접근 방식의 이점을 활용하는 문제 해결 시나리오에 사용할 수 있습니다. 낮은 수준의 노력은 심층적인 여러 단계의 계획을 세우지 않고도 기본적인 추론을 통해 정확도가 향상되는 복합 태스크에 적합합니다.
중간 노력(`maxReasoningEffort: "medium"`)
적합한 작업: 여러 단계의 태스크 및 코딩 워크플로. 예를 들어 변경 사항을 구현하기 전에 모델이 기존 코드 구조를 이해해야 하는 소프트웨어 개발 및 디버깅, 여러 파일 또는 구성 요소에서 조정이 필요한 코드 생성, 상호 종속성이 존재하는 여러 단계의 계산이나 여러 제약 존건이 있는 태스크 계획에 사용할 수 있습니다. 중간 노력은 여러 도구를 조정하고 모델이 여러 순차적 작업에서 컨텍스트를 유지 관리해야 하는 에이전트 워크플로에 적합합니다.
높은 수준의 노력(`maxReasoningEffort: "high"`)
적합한 작업: STEM 추론 및 고급 문제 해결. 예를 들어 엄격한 단계별 확인, 심층 조사를 요구하는 과학 분석 및 연구 태스크, 여러 차원에서 아키텍처 고려 사항이 포함된 복잡한 시스템 설계 또는 중요한 영향을 미치는 중요한 의사 결정 시나리오가 필요한 고급 수학적 문제 및 증명에 사용할 수 있습니다. 높은 수준의 노력은 정교한 추론, 대안에 대한 신중한 평가, 결론에 대한 철저한 검증이 필요한 태스크에서 최대의 정확도를 제공합니다.
다음 예제에서는 여러 추론 노력 수준을 보여줍니다.
------
#### [ Low effort ]
```
import boto3
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')
response = bedrock.converse(
modelId='us.amazon.nova-2-lite-v1:0',
system=[{"text": "You are a highly capable personal assistant"}],
messages=[{
"role": "user",
"content": [{"text": "Provide a meal plan for a gluten free family of 4."}]
}],
inferenceConfig={
"temperature": 0.7,
"topP": 0.9,
"maxTokens": 10000
},
additionalModelRequestFields={
"reasoningConfig": {
"type": "enabled",
"maxReasoningEffort": "low"
}
}
)
```
------
**추론 파라미터:**
다음은 추론 파라미터임
+ `type`: `enabled` 또는 `disabled`(기본값: `disabled`)
+ `maxReasoningEffort`: `low`, `medium` 또는 `high`. 추론이 활성화된 경우에 필수입니다.
**참고**
Temperature, topP, topK는 `maxReasoningEffort`를 `high`로 설정한 상태에서 사용할 수 없습니다. 이 경우 오류가 발생합니다.
응답에는 추론 콘텐츠가 포함됩니다.
```
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"reasoningContent": {
"reasoningText": {
"text": "[REDACTED]"
}
}
},
{
"text": "Based on the premises, we can conclude..."
}
]
}
},
"stopReason": "end_turn"
}
```
**참고**
Amazon Nova 2에서 추론 콘텐츠는 `[REDACTED]`로 표시됩니다. 출력 품질 향상에 기여하므로 추론 토큰에 대한 요금은 계속 청구됩니다. 향후 릴리스에서 추론 콘텐츠를 노출하는 옵션을 유지하기 위해 이제 이 필드가 응답 구조에 포함됩니다. 모델 추론 프로세스를 설명하기 위한 최선의 접근 방식을 결정하기 위해 고객과 적극적으로 협력하고 있습니다.