View a markdown version of this page

Referência de API - Criador de aplicações de IA generativa na AWS
Painel de implantaçãoCaso de uso compartilhado APIsCaso de uso de textoCaso de uso do Bedrock Agent

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.

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, {history} e {input} para implantações do Sagemaker AI que não sejam do RAG, com a adição de {context} 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_CONVERSATION 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 | 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_documento

String

Título do documento fonte retornado. Disponível somente ao usar Kendra.

id_do_documento

String

ID do documento fonte retornado. Disponível somente ao usar Kendra.

atributos_adicionais

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.