As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Referência de API
Esta seção fornece referências de API para a solução.
## Painel de implantação
| API REST | Método HTTP | Funcionalidade | Chamadores autorizados |
| --- | --- | --- | --- |
| `/deployments` | `GET` | Obtenha todas as implantações. | Token JWT autenticado pelo Amazon Cognito |
| `/deployments` | `POST` | Cria uma nova implantação de caso de uso. | Token JWT autenticado pelo Amazon Cognito |
| `/deployments/{useCaseId}` | `GET` | Obtém detalhes de implantação para uma única implantação. | Token JWT autenticado pelo Amazon Cognito |
| `/deployments/{useCaseId}` | `PATCH` | Atualiza uma determinada implantação. | Token JWT autenticado pelo Amazon Cognito |
| `/deployments/{useCaseId}` | `DELETE` | Exclui uma determinada implantação. | Token JWT autenticado pelo Amazon Cognito |
| `/model-info/use-case-types` | `GET` | Obtém os tipos de casos de uso disponíveis para a implantação | Token JWT autenticado pelo Amazon Cognito |
| `/model-info/{useCaseType}/providers` | `GET` | Obtém os provedores de modelos disponíveis para o determinado tipo de caso de uso | Token JWT autenticado pelo Amazon Cognito |
| `/model-info/{useCaseType}/{providerName}` | `GET` | Obtém IDs os modelos disponíveis para um determinado provedor e tipo de caso de uso | Token JWT autenticado pelo Amazon Cognito |
| `/model-info/{useCaseType}/{providerName}/{modelId}` | `GET` | Obtém as informações sobre o modelo fornecido, incluindo os parâmetros padrão. | Token JWT autenticado pelo Amazon Cognito |
**nota**
Os arquivos OpenAPI e Swagger também podem ser exportados do API Gateway para facilitar a integração com a API. Consulte [Exportar uma API REST do API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html).
**Cargas úteis POST e PATCH**
Veja abaixo um exemplo de uma carga POST para o `/deployments` endpoint, que criará um novo caso de uso.
```
{
"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
}
}
}
```
Para atualizações, a estrutura é a mesma acima, com algumas ressalvas:
+ O nome do caso de uso não pode ser alterado
+ Um caso de uso só pode alterar grupos de segurança e sub-redes depois de implantado em uma VPC. O VPC em si não pode ser alterado.
+ Se um índice Kendra foi criado para você como uma base de conhecimento, você não pode alterar a configuração desse índice (por exemplo,,) KendraIndexName QueryCapacityUnits
## Caso de uso compartilhado APIs
Os seguintes endpoints da API REST estão disponíveis para casos de uso do Text e do Bedrock Agent:
| API REST | Método HTTP | Funcionalidade | Chamadores autorizados |
| --- | --- | --- | --- |
| `/details/{useCaseConfigKey}` | `GET` | Obtém detalhes de configuração para um caso de uso específico. | Token JWT autenticado pelo Amazon Cognito |
| WebSocket API | Funcionalidade | Chamadores autorizados |
| --- | --- | --- |
| `/$connect` | Inicie a WebSocket conexão e autentique o usuário. | Token JWT autenticado pelo Amazon Cognito |
| `/$disconnect` | Endpoint chamado quando uma WebSocket conexão foi desconectada. | Token JWT autenticado pelo Amazon Cognito |
**API de detalhes do caso de uso**
O endpoint de detalhes da API recupera informações sobre um caso de uso específico:
```
GET /details/{useCaseConfigKey}
```
Esse endpoint retorna os detalhes da configuração de um caso de uso específico, incluindo parâmetros do modelo, configurações da base de conhecimento e outras informações de implantação. Ele exige um token JWT autenticado pelo Amazon Cognito para autorização.
## Caso de uso de texto
| WebSocket API | Funcionalidade | Chamadores autorizados |
| --- | --- | --- |
| `/sendMessage` | Envia a mensagem de bate-papo do usuário ao WebSocket para processamento com a experiência LLM configurada. | Token JWT autenticado pelo Amazon Cognito |
| API REST | Método HTTP | Funcionalidade | Chamadores autorizados |
| --- | --- | --- | --- |
| `/feedback/{useCaseId}` | `POST` | Envia feedback do usuário sobre um caso de uso específico. | Token JWT autenticado pelo Amazon Cognito |
**Cargas úteis de envio de mensagens**
Se você estiver se integrando diretamente à `/sendMessage` API, deverá seguir os seguintes formatos de carga útil de solicitação e resposta.
*Solicitar carga*
```
{
"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
}
```
| Nome do parâmetro | Tipo | Description |
| --- | --- | --- |
| **ação** | `String` | Atualmente, oferecemos suporte apenas à ação “SendMessage” no WebSocket |
| **pergunta** | `String` | A entrada do usuário a ser enviada ao LLM |
| **ID da conversa** | `String` | Um UUID identificando a conversa. Se não for fornecida, uma nova conversa será criada, com o ID da conversa retornado na resposta. Todas as mensagens subsequentes dessa conversa (onde você deseja que sejam retidas) devem fornecer o ID da conversa lá. history/context |
| **Modelo de prompt** | `String`[Opcional] | Substitui o modelo de prompt dessa mensagem. Se estiver vazio ou não for fornecido, usará como padrão o prompt definido no momento da implantação. Deve ter os espaços reservados adequados especificados para a configuração especificada (ou seja, \$1history\$1 e \$1input\$1 para implantações do Sagemaker AI que não sejam do RAG, com a adição de \$1context\$1 se estiver usando o RAG para todas as implantações. |
| **Token de autenticação** | `String`[Opcional] | AccessToken foi obtido do fluxo de autenticação cognito. Isso é necessário ao invocar um endpoint de websocket de chat configurado para RAG com controle de acesso baseado em função (RBAC). A lista de declarações cognito:groups nesse token JWT é usada para controlar o acesso aos documentos no índice Kendra. Esse parâmetro **não** é necessário para casos de uso que não sejam do RAG. Também **não** é necessário para casos de uso do RAG com o RBAC desativado. |
*Cargas úteis de resposta*
*Resposta à pergunta*
A WebSocket API responderá com 1 (se o streaming estiver desativado) ou vários (se o streaming estiver ativado) objetos JSON estruturados da seguinte forma para cada consulta.
```
{
"data": "some data",
"conversationId": "id",
}
```
| Nome do parâmetro | Tipo | Description |
| --- | --- | --- |
| **data** | `String` | Uma parte da resposta do LLM, se o streaming estiver ativado, ou a resposta inteira. Se estiver usando streaming, uma resposta desse formato com o conteúdo dos dados sendo *END\$1CONVERSATION* será enviada para indicar o final da resposta a uma única pergunta. |
| **ID da conversa** | `String` | O ID da conversa à qual essa resposta do SourceDocument pertence. |
*Resposta do documento de origem*
Se você configurou seu caso de uso do RAG para retornar documentos de origem, você também receberá a seguinte carga útil no final de cada resposta para cada documento de origem usado para criar a resposta.
```
{
"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"
}
```
| Nome do parâmetro | Tipo | Description |
| --- | --- | --- |
| **trecho** | `String` | Um trecho do documento fonte. |
| **location** | `String` | Localização do documento de origem. Isso dependerá das fontes de dados usadas e do tipo de base de conhecimento, mas pode ser algo como s3 URIs ou sites. |
| **pontuar** | `Number` \$1 `String` | A confiança de que o documento corresponde à pergunta feita. Isso será um float de 0 a 1 para Bedrock e uma string (por exemplo, HIGH, LOW, etc.) para Kendra. |
| **título\$1documento** | `String` | Título do documento fonte retornado. Disponível somente ao usar Kendra. |
| **id\$1do\$1documento** | `String` | ID do documento fonte retornado. Disponível somente ao usar Kendra. |
| **atributos\$1adicionais** | `String` | Esse campo conterá todos os atributos adicionais no documento, conforme personalizados em sua base de conhecimento no momento da ingestão. |
| **ID da conversa** | `String` | O ID da conversa à qual essa resposta do SourceDocument pertence. |
**Carga útil da API de feedback**
Abaixo está um exemplo de uma carga POST para o `/feedback/{useCaseId}` endpoint, que enviará feedback do usuário para um caso de uso específico:
```
{
"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"
]
}
```
## Caso de uso do Bedrock Agent
| WebSocket API | Funcionalidade | Chamadores autorizados |
| --- | --- | --- |
| `/invokeAgent` | Envia a mensagem do usuário ao WebSocket para processamento com o agente configurado. | Token JWT autenticado pelo Amazon Cognito |
### Cargas úteis do InvokeAgent
Se você estiver se integrando diretamente ao`/invokeAgent API`, deverá seguir os seguintes formatos de carga útil de solicitação e resposta.
*Carga da solicitação*
```
{
"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
}
```
| Nome do parâmetro | Tipo | Description |
| --- | --- | --- |
| **ação** | `String` | Apoiamos apenas a `invokeAgent` ação no WebSocket. |
| **Texto de entrada** | `String` | A entrada do usuário a ser enviada ao LLM. |
| **ID da conversa** | `String[Optional]` | Um UUID que identifica a conversa de forma exclusiva. Se você não fornecer esse valor, a solução criará uma nova conversa e retornará o **ID da conversa** na resposta. Todas as mensagens subsequentes nessa conversa (nas quais você deseja reter o histórico e o contexto) fornecem o **ID da conversa** lá. |
| **Token de autenticação** | `String[Optional]` | O **AccessToken foi** obtido do fluxo de autenticação do Amazon Cognito. Esse parâmetro **não** é obrigatório. Se você o fornecer, o token JWT será validado. Isso ajuda a facilitar a extensão dessa solução. |
*Cargas úteis de resposta*
*Resposta à pergunta*
A WebSocket API responderá com um (se o streaming estiver desativado) ou vários (se o streaming estiver ativado) objetos JSON estruturados da seguinte forma para cada consulta.
```
{
"data" "some data",
"conversationId": "id",
}
```
| Nome do parâmetro | Tipo | Description |
| --- | --- | --- |
| **data** | `String` | A resposta da invocação do agente. |
| **ID da conversa** | `String` | O ID da conversa. |