本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# API 参考
<a name="api-reference"></a>

本节提供解决方案的 API 参考。

## 部署控制面板
<a name="deployment-dashboard-3"></a>


| REST API | HTTP method | 功能 | 授权来电者 | 
| --- | --- | --- | --- | 
|   `/deployments`   |   `GET`   |  获取所有部署。  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 
|   `/deployments`   |   `POST`   |  创建新的用例部署。  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 
|   `/deployments/{useCaseId}`   |   `GET`   |  获取单个部署的部署详细信息。  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 
|   `/deployments/{useCaseId}`   |   `PATCH`   |  更新给定的部署。  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 
|   `/deployments/{useCaseId}`   |   `DELETE`   |  删除给定的部署。  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 
|   `/model-info/use-case-types`   |   `GET`   |  获取部署的可用用例类型  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 
|   `/model-info/{useCaseType}/providers`   |   `GET`   |  获取给定用例类型的可用模型提供者  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 
|   `/model-info/{useCaseType}/{providerName}`   |   `GET`   |  获取给 IDs 定提供者可用的模型和用例类型  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 
|   `/model-info/{useCaseType}/{providerName}/{modelId}`   |   `GET`   |  获取有关给定模型的信息，包括默认参数。  |  亚马逊 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 有效负载** 

有关`/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>

以下 REST API 端点可用于文本代理和 Bedrock Agent 用例：


| REST API | HTTP method | 功能 | 授权来电者 | 
| --- | --- | --- | --- | 
|   `/details/{useCaseConfigKey}`   |   `GET`   |  获取特定用例的配置详细信息。  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 


| WebSocket API | 功能 | 授权来电者 | 
| --- | --- | --- | 
|   `/$connect`   |  启动 WebSocket 连接并对用户进行身份验证。  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 
|   `/$disconnect`   |   WebSocket 连接断开时调用终端节点。  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 

 **用例详情 API** 

details API 端点检索有关特定用例的信息：

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

此端点返回特定用例的配置详细信息，包括模型参数、知识库设置和其他部署信息。它需要经过 Amazon Cognito 身份验证的 JWT 令牌才能进行授权。

## 文本用例
<a name="chat-use-case-2"></a>


| WebSocket API | 功能 | 授权来电者 | 
| --- | --- | --- | 
|   `/sendMessage`   |  向发送用户的聊天消息，以便按照配置 WebSocket 的 LLM 体验进行处理。  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 


| REST API | HTTP method | 功能 | 授权来电者 | 
| --- | --- | --- | --- | 
|   `/feedback/{useCaseId}`   |   `POST`   |  针对特定用例提交用户反馈。  |  亚马逊 Cognito 经过身份验证的 JWT 令牌  | 

 **发送消息有效负载** 

如果您直接与 `/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`   |  目前，我们仅支持 “SendMessage” 操作 WebSocket  | 
|   **问题**   |   `String`   |  要发送给 LLM 的用户输入  | 
|   **会话 ID**   |   `String`   |  用于标识对话的 UUID。如果未提供，则将创建一个新的对话，并在响应中返回 conversationID。该对话中的所有后续消息（您希望保留在哪里）都应在此处提供 conversationID。 history/context   | 
|   **提示模板**   |   `String`[可选]  |  覆盖此消息的提示模板。如果为空或未提供，则默认为部署时设置的提示符。必须为给定配置（即非 Rag Sagemaker AI 部署的 \$1history\$1 和 \$1input\$1）指定正确的占位符，如果所有部署都使用 RAG，则必须添加 \$1context\$1。  | 
|   **验证令牌**   |   `String`[可选]  |  AccessToken 是从认知身份验证流程中获得的。使用基于角色的访问控制 (RBAC) 调用为 RAG 配置的聊天 websocket 端点时，这是必需的。此 JWT 令牌中的 cognito: groups 声明列表用于控制对 Kendra 索引中文档的访问。非 RAG 用例**不需要**此参数。对于禁用 RBAC 的 RAG 用例，也**不是**必需的。  | 

 *响应负载* 

 *问题回答* 

对于每个查询， WebSocket API 将使用 1 个（如果禁用了流式传输）或许多（如果启用了流式传输）JSON 对象进行响应，其结构如下。

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


| 参数名称 | Type | 说明 | 
| --- | --- | --- | 
|   **data**   |   `String`   |  如果启用了流式传输，则是来自 LLM 的响应的一部分，或者是整个响应。如果使用流式传输，则将发送此格式的响应，数据内容为 *END\$1* CONVERSATION，以表明对单个问题的回答已结束。  | 
|   **会话 ID**   |   `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，这将是一个字符串（例如 HIG、LOW 等）。  | 
|   **文档标题**   |   `String`   |  返回的源文档的标题。仅在使用 Kendra 时可用。  | 
|   **文档\$1ID**   |   `String`   |  返回的源文档的 ID。仅在使用 Kendra 时可用。  | 
|   **其他属性**   |   `String`   |  该字段将包含文档上所有其他属性，这些属性是在摄取时在知识库中自定义的。  | 
|   **会话 ID**   |   `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"
  ]
}
```

## 基岩代理用例
<a name="agent-use-case-2"></a>


| WebSocket API | 功能 | 授权来电者 | 
| --- | --- | --- | 
|   `/invokeAgent`   |  向发送用户的消息， WebSocket 以便使用配置的代理进行处理。  |  亚马逊 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`   |  我们只支持对... 的`invokeAgent` WebSocket行动  | 
|   **输入文本**   |   `String`   |  要发送给 LLM 的用户输入。  | 
|   **会话 ID**   |   `String[Optional]`   |  唯一标识对话的 UUID。如果您不提供此值，则解决方案会创建一个新的对话并在响应中返回 convers **ationID**。该对话中的所有后续消息（您想保留历史和上下文）都在此处提供了 convers **ationID**。  | 
|   **验证令牌**   |   `String[Optional]`   |   A@@ **ccessToken** 是从亚马逊 Cognito 身份验证流程中获得的。此参数**不是**必需的。如果您提供了 JWT 令牌，则将对其进行验证。这有助于更轻松地扩展此解决方案。  | 

 *响应有效载荷* 

 *问题回答* 

对于每个查询， WebSocket API 将使用一个（如果禁用了流式传输）或多个（如果启用了流式传输）JSON 对象进行响应，其结构如下。

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


| 参数名称 | Type | 说明 | 
| --- | --- | --- | 
|   **data**   |   `String`   |  代理调用的响应。  | 
|   **会话 ID**   |   `String`   |  对话的 ID。  |