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

API 참조

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

배포 대시보드

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

}

업데이트의 경우 구조는 위와 동일하며 몇 가지 주의 사항이 있습니다.

공유 사용 사례 APIs

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

사용 사례 세부 정보 API

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

GET /details/{useCaseConfigKey}

이 엔드포인트는 모델 파라미터, 지식 기반 설정 및 기타 배포 정보를 포함하여 특정 사용 사례에 대한 구성 세부 정보를 반환합니다. 권한 부여를 위해 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
}

응답 페이로드

질문 응답

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

{
 "data": "some data",
 "conversationId": "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"
}

피드백 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 사용 사례

invokeAgent 페이로드

와 직접 통합하는 경우 다음 요청 및 응답 페이로드 형식을 준수해야 /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
}

응답 페이로드

질문 응답

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

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