View a markdown version of this page

Referencia de la API - Creador de aplicaciones de IA generativa en AWS
Panel de implementaciónCaso de uso compartido APIsCaso de uso de textoCaso de uso de Bedrock Agent

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Referencia de la API

En esta sección, se proporcionan referencias de API para la solución.

Panel de implementación

API de REST Método HTTP Funcionalidad Personas que llaman autorizadas

/deployments

GET

Obtenga todos los despliegues.

Token JWT autenticado de Amazon Cognito

/deployments

POST

Crea una implementación de un nuevo caso de uso.

Token JWT autenticado de Amazon Cognito

/deployments/{useCaseId}

GET

Obtiene los detalles de la implementación de una sola implementación.

Token JWT autenticado de Amazon Cognito

/deployments/{useCaseId}

PATCH

Actualiza una implementación determinada.

Token JWT autenticado de Amazon Cognito

/deployments/{useCaseId}

DELETE

Elimina una implementación determinada.

Token JWT autenticado de Amazon Cognito

/model-info/use-case-types

GET

Obtiene los tipos de casos de uso disponibles para la implementación

Token JWT autenticado de Amazon Cognito

/model-info/{useCaseType}/providers

GET

Obtiene los proveedores de modelos disponibles para el tipo de caso de uso dado

Token JWT autenticado de Amazon Cognito

/model-info/{useCaseType}/{providerName}

GET

Obtiene IDs los modelos disponibles para un proveedor y un tipo de caso de uso determinados

Token JWT autenticado de Amazon Cognito

/model-info/{useCaseType}/{providerName}/{modelId}

GET

Obtiene la información sobre el modelo dado, incluidos los parámetros predeterminados.

Token JWT autenticado de Amazon Cognito
nota

Los archivos OpenAPI y Swagger también se pueden exportar desde API Gateway para facilitar la integración con la API. Consulte Exportar una API REST desde API Gateway.

Cargas útiles POST y PATCH

Consulte a continuación un ejemplo de una carga útil POST para el /deployments punto final, que creará un nuevo 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
 }
 }

}

En cuanto a las actualizaciones, la estructura es la misma que la anterior, con algunas advertencias:

  • El nombre del caso de uso no se puede cambiar

  • Un caso de uso solo puede cambiar los grupos de seguridad y las subredes una vez que se ha implementado en una VPC. La VPC en sí no se puede cambiar.

  • Si se creó un índice de Kendra para usted como base de conocimientos, no podrá cambiar la configuración de ese índice (por ejemplo,, KendraIndexName) QueryCapacityUnits

Caso de uso compartido APIs

Los siguientes puntos finales de la API REST están disponibles para los casos de uso de Text y Bedrock Agent:

API de REST Método HTTP Funcionalidad Personas que llaman autorizadas

/details/{useCaseConfigKey}

GET

Obtiene los detalles de configuración de un caso de uso específico.

Token JWT autenticado de Amazon Cognito
WebSocket API Funcionalidad Llamantes autorizados

/$connect

Inicie la WebSocket conexión y autentique al usuario.

Token JWT autenticado de Amazon Cognito

/$disconnect

Se llama al punto final cuando se ha WebSocket desconectado una conexión.

Token JWT autenticado de Amazon Cognito

API de detalles de casos de uso

El punto final de la API de detalles recupera información sobre un caso de uso específico:

GET /details/{useCaseConfigKey}

Este punto final devuelve los detalles de configuración de un caso de uso específico, incluidos los parámetros del modelo, la configuración de la base de conocimientos y otra información de implementación. Se requiere un token JWT autenticado de Amazon Cognito para su autorización.

Caso de uso de texto

WebSocket API Funcionalidad Llamantes autorizados

/sendMessage

Envía el mensaje de chat del usuario al WebSocket para que lo procese con la experiencia LLM configurada.

Token JWT autenticado de Amazon Cognito
API de REST Método HTTP Funcionalidad Personas que llaman autorizadas

/feedback/{useCaseId}

POST

Envía los comentarios de los usuarios para un caso de uso específico.

Token JWT autenticado de Amazon Cognito

Cargas útiles de envío de mensajes

Si te estás integrando directamente con la /sendMessage API, debes seguir los siguientes formatos de carga útil de solicitud y respuesta.

Solicita la carga útil 

{
 "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
}
Nombre del parámetro Tipo Description (Descripción)

action

String

Actualmente, solo admitimos la acción «enviar mensaje» en WebSocket

pregunta

String

La entrada del usuario para enviarla al LLM

ID de conversación

String

Un UUID que identifica la conversación. Si no se proporciona, se creará una nueva conversación y se mostrará el ID de conversación en la respuesta. Todos los mensajes subsiguientes de esa conversación (en los que desees que se history/context retengan) deberán incluir el identificador de conversación en ese mensaje.

Plantilla de solicitud

String [Opcional]

Anula la plantilla de solicitud de este mensaje. Si está vacía o no se proporciona, se utilizará de forma predeterminada la solicitud establecida en el momento de la implementación. Debe tener los marcadores de posición adecuados especificados para la configuración dada (es decir, {historial} y {entrada} para las implementaciones de IA de Sagemaker que no sean RAG), con la adición de {contexto} si se utiliza RAG para todas las implementaciones.

AuthToken

String [Opcional]

AccessToken obtenido del flujo de autenticación de cognito. Esto es necesario cuando se invoca un punto final websocket de chat configurado para RAG con control de acceso basado en roles (RBAC). La lista de reclamos de cognito:groups de este token JWT se utiliza para controlar el acceso a los documentos del índice Kendra. Este parámetro no es obligatorio para los casos de uso que no sean de RAG. Tampoco es obligatorio para los casos de uso de RAG en los que el RBAC esté desactivado.

Cargas útiles de respuesta

Pregunta y respuesta

La WebSocket API responderá con 1 (si la transmisión está deshabilitada) o varios (si la transmisión está habilitada) objetos JSON estructurados de la siguiente manera para cada consulta.

{
 "data": "some data",
 "conversationId": "id",
}
Nombre del parámetro Tipo Description (Descripción)

data

String

Una parte de la respuesta del LLM si la transmisión está habilitada, o la respuesta completa. Si utiliza la transmisión, se enviará una respuesta de este formato con el contenido de datos END_CONVERSATION para indicar el final de la respuesta a una sola pregunta.

ID de conversación

String

El ID de la conversación a la que pertenece esta respuesta de SourceDocument.

Respuesta del documento fuente

Si ha configurado su caso de uso de RAG para devolver los documentos fuente, también recibirá la siguiente carga útil al final de cada respuesta para cada documento fuente utilizado para crear la respuesta.

{
 "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"
}
Nombre del parámetro Tipo Description (Descripción)

extracto

String

Un extracto del documento fuente.

location

String

Ubicación del documento fuente. Esto dependerá de las fuentes de datos utilizadas y del tipo de base de conocimientos, pero podrían ser cosas como s3 URIs o sitios web.

puntuación

Number | String

La confianza en que el documento corresponde a la pregunta planteada. Será un valor flotante de 0 a 1 para Bedrock y una cuerda (por ejemplo, ALTO, BAJO, etc.) para Kendra.

título_del documento

String

Título del documento fuente devuelto. Solo disponible cuando se usa Kendra.

document_id

String

ID del documento fuente devuelto. Solo disponible cuando se usa Kendra.

atributos_adicionales

String

Este campo contendrá todos los atributos adicionales del documento según los personalice en su base de conocimientos en el momento de la ingesta.

ID de conversación

String

El ID de la conversación a la que pertenece esta respuesta de SourceDocument.

Carga útil de la API de comentarios

A continuación, se muestra un ejemplo de una carga útil POST para el /feedback/{useCaseId} punto final, que enviará los comentarios de los usuarios para un 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 de Bedrock Agent

WebSocket API Funcionalidad Llamantes autorizados

/invokeAgent

Envía el mensaje del usuario al WebSocket para que lo procese con el agente configurado.

Token JWT autenticado de Amazon Cognito

Cargas útiles de InvokeAgent

Si se va a integrar directamente con el/invokeAgent API, debe seguir los siguientes formatos de carga útil de solicitud y respuesta.

Carga de solicitud 

{
"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
}
Nombre del parámetro Tipo Description (Descripción)

action

String

Solo apoyamos la invokeAgent acción en relación con. WebSocket

Texto de entrada

String

La entrada del usuario que se va a enviar al LLM.

ID de conversación

String[Optional]

Un UUID que identifica de forma exclusiva la conversación. Si no proporciona este valor, la solución crea una nueva conversación y devuelve el ID de conversación en la respuesta. Todos los mensajes subsiguientes de esa conversación (en los que desee conservar el historial y el contexto) incluyen allí el identificador de conversación.

Token de autenticación

String[Optional]

AccessToken obtenido del flujo de autenticación de Amazon Cognito. Este parámetro no es obligatorio. Si lo proporciona, se validará el token JWT. Esto ayuda a facilitar la ampliación de esta solución.

Cargas útiles de respuesta

Pregunta y respuesta

La WebSocket API responderá con uno (si la transmisión está deshabilitada) o varios (si la transmisión está habilitada) objetos JSON estructurados de la siguiente manera para cada consulta.

{
 "data" "some data",
 "conversationId": "id",
 }
Nombre del parámetro Tipo Description (Descripción)

data

String

La respuesta de la invocación del agente.

ID de conversación

String

El ID de la conversación.