本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 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 字符  | 

**注意**  
OpenAPI 和 Swagger 檔案也可以從 API Gateway 匯出，以便與 API 整合。請參閱[從 API Gateway 匯出 REST API](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html)。

 **POST 和 PATCH 承載** 

如需端點的 POST 承載範例`/deployments`，請參閱下文，這會建立新的使用案例。

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

下列 REST API 端點適用於文字和 Bedrock 代理程式使用案例：


| 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`   |  將使用者的聊天訊息傳送至 WebSocket，以使用設定的 LLM 體驗進行處理。  |  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 | 說明 | 
| --- | --- | --- | 
|   **動作**   |   `String`   |  目前我們僅支援 WebSocket 上的「sendMessage」動作  | 
|   **問題**   |   `String`   |  要傳送至 LLM 的使用者輸入  | 
|   **conversationId**   |   `String`   |  識別對話的 UUID。如果未提供，則會建立新的對話，並在回應中傳回 conversationId。該對話中的所有後續訊息 （您希望保留歷史記錄/內容的位置） 應在該對話中提供 conversationId。  | 
|   **promptTemplate**   |   `String` 【選用】  |  覆寫此訊息的提示範本。如果為空或未提供， 將預設為部署時設定的提示。必須為指定的組態指定適當的預留位置 （即非 RAG Sagemaker AI 部署的 \$1history\$1 和 \$1input\$1，如果所有部署都使用 RAG，則新增 \$1context\$1。  | 
|   **authToken**   |   `String` 【選用】  |  從 cognito 驗證流程取得的 accessToken。使用角色型存取控制 (RBAC) 調用針對 RAG 設定的聊天 Websocket 端點時，這是必要的。此 JWT 字符中的 cognito：groups 宣告清單用於控制對 Kendra 索引中文件的存取。非 RAG 使用案例**不需要**此參數。停用 RBAC 的 RAG 使用案例也**不需要**。  | 

 *回應承載* 

 *問題回應* 

WebSocket API 將以 1 （如果停用串流） 或多個 （如果啟用串流） JSON 物件回應，每個查詢的結構如下。

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


| 參數名稱 | Type | 說明 | 
| --- | --- | --- | 
|   **資料**   |   `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`   |  來源文件的摘錄。  | 
|   **位置**   |   `String`   |  來源文件的位置。這取決於使用的資料來源和知識庫類型，但可能是 s3 URIs 或網站之類的內容。  | 
|   **分數**   |   `Number` \$1 `String`   |  文件對應到所問問題的可信度。對於 Bedrock，這將是從 0 到 1 的浮點數，對於 Kendra 則為字串 （例如 HIGH、LOW 等）。  | 
|   **document\$1title**   |   `String`   |  傳回來源文件的標題。僅適用於使用 Kendra 時。  | 
|   **document\$1id**   |   `String`   |  傳回來源文件的 ID。僅適用於使用 Kendra 時。  | 
|   **additional\$1attributes**   |   `String`   |  此欄位將包含文件上的所有其他屬性，如擷取時的知識庫所自訂。  | 
|   **conversationId**   |   `String`   |  此 sourceDocument 回應所屬的對話 ID。  | 

 **意見回饋 API 承載** 

以下是端點的 POST 承載範例`/feedback/{useCaseId}`，它會針對特定使用案例提交使用者意見回饋：

```
{
  "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 | 說明 | 
| --- | --- | --- | 
|   **動作**   |   `String`   |  我們僅支援 WebSocket 上的 `invokeAgent`動作。  | 
|   **inputText**   |   `String`   |  要傳送至 LLM 的使用者輸入。  | 
|   **conversationId**   |   `String[Optional]`   |  唯一識別對話的 UUID。如果您不提供此值，解決方案會建立新的對話，並在回應中傳回 **conversationId**。該對話中的所有後續訊息 （您要保留歷史記錄和內容的位置） 都會在該處提供 **conversationId**。  | 
|   **authToken**   |   `String[Optional]`   |   從 Amazon Cognito 驗證流程取得的 **accessToken**。**不需要**此參數。如果您提供它，則會驗證 JWT 字符。這有助於更輕鬆地擴展此解決方案。  | 

 *回應承載* 

 *問題回應* 

WebSocket API 將以一個 （如果停用串流） 或多個 （如果啟用串流） JSON 物件回應，每個查詢的結構如下。

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


| 參數名稱 | Type | 說明 | 
| --- | --- | --- | 
|   **資料**   |   `String`   |  來自客服人員調用的回應。  | 
|   **conversationId**   |   `String`   |  對話的 ID。  |