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

# API 참조
<a name="api-reference"></a>

이 섹션에서는 솔루션에 대한 API 참조를 제공합니다.

## 배포 대시보드
<a name="deployment-dashboard-3"></a>


| REST API | HTTP 메서드 | 기능 | 승인된 호출자 | 
| --- | --- | --- | --- | 
|   `/deployments`   |   `GET`   |  모든 배포를 가져옵니다.  |  Amazon Cognito 인증 JWT 토큰  | 
|   `/deployments`   |   `POST`   |  새 사용 사례 배포를 생성합니다.  |  Amazon Cognito 인증 JWT 토큰  | 
|   `/deployments/{useCaseId}`   |   `GET`   |  단일 배포에 대한 배포 세부 정보를 가져옵니다.  |  Amazon Cognito 인증 JWT 토큰  | 
|   `/deployments/{useCaseId}`   |   `PATCH`   |  지정된 배포를 업데이트합니다.  |  Amazon Cognito 인증 JWT 토큰  | 
|   `/deployments/{useCaseId}`   |   `DELETE`   |  지정된 배포를 삭제합니다.  |  Amazon Cognito 인증 JWT 토큰  | 
|   `/model-info/use-case-types`   |   `GET`   |  배포에 사용할 수 있는 사용 사례 유형을 가져옵니다.  |  Amazon Cognito 인증 JWT 토큰  | 
|   `/model-info/{useCaseType}/providers`   |   `GET`   |  지정된 사용 사례 유형에 사용할 수 있는 모델 공급자를 가져옵니다.  |  Amazon Cognito 인증 JWT 토큰  | 
|   `/model-info/{useCaseType}/{providerName}`   |   `GET`   |  지정된 공급자 및 사용 사례 유형에 사용할 수 있는 모델의 IDs를 가져옵니다.  |  Amazon Cognito 인증 JWT 토큰  | 
|   `/model-info/{useCaseType}/{providerName}/{modelId}`   |   `GET`   |  기본 파라미터를 포함하여 지정된 모델에 대한 정보를 가져옵니다.  |  Amazon Cognito 인증 JWT 토큰  | 

**참고**  
API와 더 쉽게 통합하기 위해 API Gateway에서 OpenAPI 및 Swagger 파일을 내보낼 수도 있습니다. [API Gateway에서 REST API 내보내기를](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html) 참조하세요.

 **POST 및 PATCH 페이로드** 

새 사용 사례를 생성하는 `/deployments` 엔드포인트에 대한 POST 페이로드의 예는 아래를 참조하세요.

```
{
 "UseCaseName": "usecase1",
 "UseCaseDescription": "Description of the use case to be deployed. For display purposes", // optional
 "DefaultUserEmail": "placeholder@example.com", // optional, if not provided, the Cognito Group and User will not be created
 "DeployUI": true, // optional
 "VpcParams": {
 "VpcEnabled": true,
 "CreateNewVpc": false,
 // provide these if not creating new vpc
 "ExistingVpcId": "vpc-id",
 "ExistingPrivateSubnetIds": ["subnet-1", "subnet-2"],
 "ExistingSecurityGroupIds": ["sg-1", "sg-2"]
 },
 "ConversationMemoryParams": {
 "ConversationMemoryType": "DynamoDB",
 "HumanPrefix": "user", // optional
 "AiPrefix": "ai", // optional
 "ChatHistoryLength": 10 // optional
 },
 "KnowledgeBaseParams": {
 "KnowledgeBaseType": "Bedrock",
 // one of the following based on selected provider
 "BedrockKnowledgeBaseParams": {
 "BedrockKnowledgeBaseId": "my-bedrock-kb",
 "RetrievalFilter": {}, // optional
 "OverrideSearchType": "HYBRID" // optional
 },
 "KendraKnowledgeBaseParams": {
 "AttributeFilter": {}, // optional
 "RoleBasedAccessControlEnabled": true, // optional
 "ExistingKendraIndexId": "12345678-abcd-1234-abcd-1234567890ab",
 // provide the following in place of ExistingKendraIndexId if you want the solution to deploy an index for you
 "KendraIndexName": "index",
 "QueryCapacityUnits": 1, // optional
 "StorageCapacityUnits": 1, // optional
 "KendraIndexEdition": "DEVELOPER" // optional
 },
 "NoDocsFoundResponse": "Sorry, I couldn't find any relevant information for your query.", // optional
 "NumberOfDocs": 3, // optional
 "ScoreThreshold": 0.7, // optional
 "ReturnSourceDocs": true // optional
 },
 "LlmParams": {
 "ModelProvider": "Bedrock | SAGEMAKER",
 // one of the following based on selected provider
 "BedrockLlmParams": {
 "ModelId": "model-id", // use this for on demand models. Can't use with ModelArn
 "ModelArn": "model-arn", // use this for provisioned/custom models. Can't use with ModelId,
 "InferenceProfileId": "profile-id"
 "GuardrailIdentifier": "arn:aws:bedrock:us-east-1:123456789012:guardrail/my-guardrail", // optional
 "GuardrailVersion": "1" // optional. Required if GuardrailIdentifier provided.
 },
 "SageMakerLlmParams": {
 "EndpointName": "some-endpoint",
 "ModelInputPayloadSchema": {},
 "ModelOutputJSONPath": "$."
 },
 // optional. Passes on arbitrary params to the underlying LLM.
 "ModelParams": {
 "param1": {
 "Value": "value1",
 "Type": "string"
 },
 "param2": {
 "Value": 1,
 "Type": "integer"
 }
 },
 // optional
 "PromptParams": {
 "PromptTemplate": "some template",
 "UserPromptEditingEnabled": true,
 "MaxPromptTemplateLength": 1000,
 "MaxInputTextLength": 1000,
 "DisambiguationPromptTemplate": "some disambiguation template",
 "DisambiguationEnabled": true
 },
 "Temperature": 1.0, // optional
 "Streaming": true, // optional
 "RAGEnabled": true, // optional. Must be true if providing KnowledgeBaseParams above.
 "Verbose": false // optional
 },
 "AgentParams": {
 "AgentType": "Bedrock",
 "BedrockAgentParams": {
 "AgentId": "agent-id",
 "AgentAliasId": "alias-id",
 "EnableTrace": true
 }
 },
 // optional
 "AuthenticationParams": {
 "AuthenticationProvider": "Cognito",
 "CognitoParams": {
 "ExistingUserPoolId": "user-pool-id",
 "ExistingUserPoolClientId": "client-id" // optional. If not provided, the solution will create a client for you in the provided pool
 }
 }

}
```

업데이트의 경우 구조는 위와 동일하며 몇 가지 주의 사항이 있습니다.
+ 사용 사례 이름은 변경할 수 없습니다.
+ 사용 사례는 VPC에 배포된 후에만 보안 그룹 및 서브넷을 변경할 수 있습니다. VPC 자체는 변경할 수 없습니다.
+ Kendra 인덱스가 지식 기반으로 생성된 경우 해당 인덱스의 구성을 변경할 수 없습니다(예: KendraIndexName, QueryCapacityUnits).

## 공유 사용 사례 APIs
<a name="shared-use-case-apis"></a>

텍스트 및 Bedrock Agent 사용 사례 모두에 사용할 수 있는 REST API 엔드포인트는 다음과 같습니다.


| REST API | HTTP 메서드 | 기능 | 승인된 호출자 | 
| --- | --- | --- | --- | 
|   `/details/{useCaseConfigKey}`   |   `GET`   |  특정 사용 사례에 대한 구성 세부 정보를 가져옵니다.  |  Amazon Cognito 인증 JWT 토큰  | 


| WebSocket API | 기능 | 승인된 호출자 | 
| --- | --- | --- | 
|   `/$connect`   |  WebSocket 연결을 시작하고 사용자를 인증합니다.  |  Amazon Cognito 인증 JWT 토큰  | 
|   `/$disconnect`   |  WebSocket 연결이 끊어졌을 때 호출되는 엔드포인트입니다.  |  Amazon Cognito 인증 JWT 토큰  | 

 **사용 사례 세부 정보 API** 

세부 정보 API 엔드포인트는 특정 사용 사례에 대한 정보를 검색합니다.

```
GET /details/{useCaseConfigKey}
```

이 엔드포인트는 모델 파라미터, 지식 기반 설정 및 기타 배포 정보를 포함하여 특정 사용 사례에 대한 구성 세부 정보를 반환합니다. 권한 부여를 위해 Amazon Cognito 인증 JWT 토큰이 필요합니다.

## 텍스트 사용 사례
<a name="chat-use-case-2"></a>


| WebSocket API | 기능 | 승인된 호출자 | 
| --- | --- | --- | 
|   `/sendMessage`   |  구성된 LLM 환경으로 처리하기 위해 사용자의 채팅 메시지를 WebSocket으로 전송합니다.  |  Amazon Cognito 인증 JWT 토큰  | 


| REST API | HTTP 메서드 | 기능 | 승인된 호출자 | 
| --- | --- | --- | --- | 
|   `/feedback/{useCaseId}`   |   `POST`   |  특정 사용 사례에 대한 사용자 피드백을 제출합니다.  |  Amazon Cognito 인증 JWT 토큰  | 

 **sendMessage 페이로드** 

`/sendMessage` API와 직접 통합하는 경우 다음 요청 및 응답 페이로드 형식을 준수해야 합니다.

 *페이로드 요청* 

```
{
 "action": "sendMessage",
 "question": "the message to send to the api",
 "conversationId": "", // If not provided, a new conversation will be created, with the conversationId returned in the response. All subsequent messages in that conversation (where history is retained), should provide the conversationId there.
 "promptTemplate": "", // Optional. Overrides the configured prompt
 "authToken": "XXXX" // Optional. accessToken from cognito flow. Required for RAG with RBAC
}
```


| 파라미터 이름 | Type | 설명 | 
| --- | --- | --- | 
|   **action**   |   `String`   |  현재는 WebSocket에 대한 "sendMessage" 작업만 지원합니다.  | 
|   **질문**   |   `String`   |  LLM으로 전송할 사용자 입력  | 
|   **conversationId**   |   `String`   |  대화를 식별하는 UUID입니다. 제공되지 않으면 새 대화가 생성되고 응답에 conversationId가 반환됩니다. 해당 대화의 모든 후속 메시지(기록/컨텍스트를 보존하려는 경우)는 여기에 conversationId를 제공해야 합니다.  | 
|   **promptTemplate**   |   `String` [선택 사항]  |  이 메시지에 대한 프롬프트 템플릿을 재정의합니다. 비어 있거나 제공되지 않은 경우는 배포 시 기본적으로 프롬프트 세트로 설정됩니다. 모든 배포에 RAG를 사용하는 경우 \$1context\$1를 추가하여 지정된 구성(예: 비 RAG Sagemaker AI 배포의 경우 \$1history\$1 및 \$1input\$1)에 대해 적절한 자리 표시자를 지정해야 합니다.  | 
|   **authToken**   |   `String` [선택 사항]  |  cognito 인증 흐름에서 얻은 accessToken입니다. 이는 역할 기반 액세스 제어(RBAC)를 사용하여 RAG에 대해 구성된 채팅 웹 소켓 엔드포인트를 호출할 때 필요합니다. 이 JWT 토큰의 cognito:groups 클레임 목록은 Kendra 인덱스의 문서에 대한 액세스를 제어하는 데 사용됩니다. 이 파라미터는 비 RAG 사용 사례에 필요하지 **않습니다**. RBAC가 비활성화된 RAG 사용 사례에는 필요하지 **않습니다**.  | 

 *응답 페이로드* 

 *질문 응답* 

WebSocket API는 각 쿼리에 대해 다음과 같이 구조화된 1개(스트리밍이 비활성화된 경우) 또는 여러 개(스트리밍이 활성화된 경우)의 JSON 객체로 응답합니다.

```
{
 "data": "some data",
 "conversationId": "id",
}
```


| 파라미터 이름 | Type | 설명 | 
| --- | --- | --- | 
|   **data**   |   `String`   |  스트리밍이 활성화된 경우 LLM의 응답 청크 또는 전체 응답입니다. 스트리밍을 사용하는 경우 데이터 콘텐츠가 *END\$1CONVERSATION*인이 형식의 응답이 전송되어 단일 질문에 대한 응답의 끝을 나타냅니다.  | 
|   **conversationId**   |   `String`   |  이 sourceDocument 응답이 속한 대화의 ID입니다.  | 

 *소스 문서 응답* 

소스 문서를 반환하도록 RAG 사용 사례를 구성한 경우 응답을 생성하는 데 사용되는 각 소스 문서에 대한 모든 응답이 끝날 때 다음 페이로드도 받게 됩니다.

```
{
 "sourceDocument": {
 "excerpt": "some excerpt from the",
 "location": "s3://fake-bucket/test.txt",
 "score": 0.500,
 "document_title": null,
 "document_id": null,
 "additional_attributes": null
 },
 "conversationId": "some-id"
}
```


| 파라미터 이름 | Type | 설명 | 
| --- | --- | --- | 
|   **발췌문**   |   `String`   |  소스 문서에서 발췌한 입니다.  | 
|   **location**   |   `String`   |  소스 문서의 위치입니다. 이는 사용된 데이터 소스 및 지식 기반 유형에 따라 다르지만 s3 URIs 또는 웹 사이트와 같을 수 있습니다.  | 
|   **점수**   |   `Number` \$1 `String`   |  문서가 질문한 질문에 해당한다는 신뢰도입니다. Bedrock의 경우 0\$11의 부동 소수점이고 Kendra의 경우 문자열(예: HIGH, LOW 등)입니다.  | 
|   **document\$1title**   |   `String`   |  반환된 소스 문서의 제목입니다. Kendra를 사용할 때만 사용할 수 있습니다.  | 
|   **document\$1id**   |   `String`   |  반환된 소스 문서의 ID입니다. Kendra를 사용할 때만 사용할 수 있습니다.  | 
|   **additional\$1attributes**   |   `String`   |  이 필드에는 수집 시 지식 기반에 사용자 지정된 대로 문서의 모든 추가 속성이 포함됩니다.  | 
|   **conversationId**   |   `String`   |  이 sourceDocument 응답이 속한 대화의 ID입니다.  | 

 **피드백 API 페이로드** 

다음은 특정 사용 사례에 대한 사용자 피드백을 제출하는 `/feedback/{useCaseId}` 엔드포인트에 대한 POST 페이로드의 예입니다.

```
{
  "useCaseRecordKey": "12345678-12345678",
  "conversationId": "12345678-1234-1234-1234-123456789012",
  "messageId": "12345678-1234-1234-1234-123456789012",
  "feedback": "positive",
  "feedbackReason": ["accurate", "helpful"],
  "comment": "This response was very helpful.",
  "rephrasedQuery": "What are the key features of Amazon Bedrock?",
  "sourceDocuments": [
    "s3://bucket-name/document1.pdf",
    "s3://bucket-name/document2.pdf"
  ]
}
```

## Bedrock Agent 사용 사례
<a name="agent-use-case-2"></a>


| WebSocket API | 기능 | 승인된 호출자 | 
| --- | --- | --- | 
|   `/invokeAgent`   |  구성된 에이전트로 처리할 수 있도록 사용자의 메시지를 WebSocket으로 전송합니다.  |  Amazon Cognito 인증 JWT 토큰  | 

### invokeAgent 페이로드
<a name="invokeagent-payloads"></a>

와 직접 통합하는 경우 다음 요청 및 응답 페이로드 형식을 준수해야 `/invokeAgent API`합니다.

 *요청 페이로드* 

```
{
"action": "invokeAgent",
"inputText": "User query to the agent",
"conversationId": "", // Optional. Empty conversationId implies a new conversation. When not provided, a new conversationId will be created and returned with the response. All subsequent messages in the same conversation should provide the same conversationId (i.e. chat memory/history is maintained).
"authToken": "XXXX" // Optional. accessToken from cognito flow. If provided, it needs to be a valid JWT token associated with the user
}
```


| 파라미터 이름 | Type | 설명 | 
| --- | --- | --- | 
|   **action**   |   `String`   |  WebSocket에 대한 `invokeAgent` 작업만 지원합니다.  | 
|   **inputText**   |   `String`   |  LLM으로 전송할 사용자 입력입니다.  | 
|   **conversationId**   |   `String[Optional]`   |  대화를 고유하게 식별하는 UUID입니다. 이 값을 제공하지 않으면 솔루션은 새 대화를 생성하고 응답에 **conversationId**를 반환합니다. 해당 대화의 모든 후속 메시지(기록 및 컨텍스트를 유지하려는 경우)는 여기에 **conversationId**를 제공합니다.  | 
|   **authToken**   |   `String[Optional]`   |   **accessToken**은 Amazon Cognito 인증 흐름에서 가져옵니다. 이 파라미터는 필요하지 **않습니다**. 제공하면 JWT 토큰이 검증됩니다. 이렇게 하면이 솔루션을 더 쉽게 확장할 수 있습니다.  | 

 *응답 페이로드* 

 *질문 응답* 

WebSocket API는 각 쿼리에 대해 다음과 같이 구조화된 JSON 객체 하나(스트리밍이 비활성화된 경우) 또는 여러 개(스트리밍이 활성화된 경우)로 응답합니다.

```
{
 "data" "some data",
 "conversationId": "id",
 }
```


| 파라미터 이름 | Type | 설명 | 
| --- | --- | --- | 
|   **data**   |   `String`   |  에이전트 호출의 응답입니다.  | 
|   **conversationId**   |   `String`   |  대화의 ID입니다.  |