View a markdown version of this page

Référence des API - Générateur d'applications d'IA générative sur AWS
Tableau de bord de déploiementCas d'utilisation partagé APIsCas d'utilisation du texteCas d'utilisation de Bedrock Agent

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Référence des API

Cette section fournit des références d'API pour la solution.

Tableau de bord de déploiement

API REST Méthode HTTP Fonctionnalité Appelants autorisés

/deployments

GET

Accédez à tous les déploiements.

Jeton JWT authentifié par Amazon Cognito

/deployments

POST

Crée un nouveau déploiement de cas d'utilisation.

Jeton JWT authentifié par Amazon Cognito

/deployments/{useCaseId}

GET

Obtient les détails du déploiement pour un seul déploiement.

Jeton JWT authentifié par Amazon Cognito

/deployments/{useCaseId}

PATCH

Met à jour un déploiement donné.

Jeton JWT authentifié par Amazon Cognito

/deployments/{useCaseId}

DELETE

Supprime un déploiement donné.

Jeton JWT authentifié par Amazon Cognito

/model-info/use-case-types

GET

Obtient les types de cas d'utilisation disponibles pour le déploiement

Jeton JWT authentifié par Amazon Cognito

/model-info/{useCaseType}/providers

GET

Obtient les fournisseurs de modèles disponibles pour le type de cas d'utilisation donné

Jeton JWT authentifié par Amazon Cognito

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

GET

Obtient IDs les modèles disponibles pour un fournisseur donné et un type de cas d'utilisation

Jeton JWT authentifié par Amazon Cognito

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

GET

Obtient les informations sur le modèle donné, y compris les paramètres par défaut.

Jeton JWT authentifié par Amazon Cognito
Note

Les fichiers OpenAPI et Swagger peuvent également être exportés depuis API Gateway pour faciliter l'intégration à l'API. Reportez-vous à la section Exporter une API REST depuis API Gateway.

Charges utiles POST et PATCH

Vous trouverez ci-dessous un exemple de charge utile POST envoyée au /deployments point de terminaison, qui créera un nouveau cas d'utilisation.

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

}

Pour les mises à jour, la structure est la même que ci-dessus avec quelques réserves :

  • Le nom du cas d'utilisation ne peut pas être modifié

  • Un cas d'utilisation ne peut modifier les groupes de sécurité et les sous-réseaux qu'une fois qu'il a été déployé dans un VPC. Le VPC lui-même ne peut pas être modifié.

  • Si un index Kendra a été créé pour vous en tant que base de connaissances, vous ne pouvez pas modifier la configuration de cet index (par exemple, KendraIndexName) QueryCapacityUnits

Cas d'utilisation partagé APIs

Les points de terminaison de l'API REST suivants sont disponibles pour les cas d'utilisation de Text et Bedrock Agent :

API REST Méthode HTTP Fonctionnalité Appelants autorisés

/details/{useCaseConfigKey}

GET

Obtient les détails de configuration pour un cas d'utilisation spécifique.

Jeton JWT authentifié par Amazon Cognito
WebSocket API Fonctionnalité Appelants autorisés

/$connect

Lancez WebSocket la connexion et authentifiez l'utilisateur.

Jeton JWT authentifié par Amazon Cognito

/$disconnect

Point de terminaison appelé lorsqu'une WebSocket connexion a été déconnectée.

Jeton JWT authentifié par Amazon Cognito

API des détails des cas d'utilisation

Le point de terminaison de l'API Details récupère des informations sur un cas d'utilisation spécifique :

GET /details/{useCaseConfigKey}

Ce point de terminaison renvoie les détails de configuration pour un cas d'utilisation spécifique, notamment les paramètres du modèle, les paramètres de la base de connaissances et d'autres informations de déploiement. Il nécessite un jeton JWT authentifié par Amazon Cognito pour l'autorisation.

Cas d'utilisation du texte

WebSocket API Fonctionnalité Appelants autorisés

/sendMessage

Envoie le message de chat de l'utilisateur au WebSocket pour traitement avec l'expérience LLM configurée.

Jeton JWT authentifié par Amazon Cognito
API REST Méthode HTTP Fonctionnalité Appelants autorisés

/feedback/{useCaseId}

POST

Soumet les commentaires des utilisateurs pour un cas d'utilisation spécifique.

Jeton JWT authentifié par Amazon Cognito

Charges utiles d'envoi de messages

Si vous effectuez une intégration directe à l'/sendMessageAPI, vous devez respecter les formats de charge utile de demande et de réponse suivants.

Charge utile de la demande 

{
 "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
}
Nom du paramètre Type Description

action

String

Actuellement, nous prenons uniquement en charge l'action « SendMessage » sur le WebSocket

question

String

L'entrée utilisateur à envoyer au LLM

Identifiant de conversation

String

Un UUID identifiant la conversation. S'il n'est pas fourni, une nouvelle conversation sera créée, avec le ConversationID renvoyé dans la réponse. Tous les messages suivants de cette conversation (dans lesquels vous souhaitez qu' history/context ils soient conservés) doivent contenir le ConversationID.

Modèle d'invite

String[Facultatif]

Remplace le modèle d'invite pour ce message. S'il est vide ou non fourni, l'invite définie par défaut au moment du déploiement sera utilisée. Les espaces réservés appropriés doivent être spécifiés pour la configuration donnée (c'est-à-dire {history} et {input} pour les déploiements d'IA autres que RAG Sagemaker, avec l'ajout de {context} si vous utilisez RAG pour tous les déploiements).

Jeton d'authentification

String[Facultatif]

AccessToken a été obtenu à partir du flux d'authentification cognito. Cela est nécessaire lors de l'appel d'un point de terminaison Websocket de chat configuré pour RAG avec un contrôle d'accès basé sur les rôles (RBAC). La liste de réclamations cognito:groups contenue dans ce jeton JWT est utilisée pour contrôler l'accès aux documents de l'index Kendra. Ce paramètre n'est pas obligatoire pour les cas d'utilisation autres que RAG. Il n'est pas non plus requis pour les cas d'utilisation de RAG pour lesquels le RBAC est désactivé.

Charges utiles de réponse

Réponse à la question

L' WebSocket API répondra avec 1 (si le streaming est désactivé) ou plusieurs (si le streaming est activé) objets JSON structurés comme suit pour chaque requête.

{
 "data": "some data",
 "conversationId": "id",
}
Nom du paramètre Type Description

data

String

Une partie de la réponse du LLM si le streaming est activé, ou la totalité de la réponse. Si vous utilisez le streaming, une réponse de ce format dont le contenu des données est END_CONVERSATION sera envoyée pour indiquer la fin de la réponse à une seule question.

Identifiant de conversation

String

L'ID de la conversation à laquelle appartient cette réponse SourceDocument.

Réponse au document source

Si vous avez configuré votre cas d'utilisation de RAG pour renvoyer les documents sources, vous recevrez également la charge utile suivante à la fin de chaque réponse pour chaque document source utilisé pour créer la réponse.

{
 "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"
}
Nom du paramètre Type Description

extrait

String

Extrait du document source.

location

String

Emplacement du document source. Cela dépendra des sources de données utilisées et du type de base de connaissances, mais il peut s'agir de choses comme s3 URIs ou de sites Web.

score

Number | String

La certitude que le document correspond à la question posée. Il s'agira d'un float de 0 à 1 pour Bedrock et d'une chaîne (par exemple HIGH, LOW, etc.) pour Kendra.

titre_document

String

Titre du document source renvoyé. Disponible uniquement lorsque vous utilisez Kendra.

identifiant_document

String

ID du document source renvoyé. Disponible uniquement lorsque vous utilisez Kendra.

attributs_supplémentaires

String

Ce champ contiendra tous les attributs supplémentaires du document tels que personnalisés dans votre base de connaissances lors de l'ingestion.

Identifiant de conversation

String

L'ID de la conversation à laquelle appartient cette réponse SourceDocument.

Charge utile de l'API Feedback

Vous trouverez ci-dessous un exemple de charge utile POST envoyée au /feedback/{useCaseId} point de terminaison, qui soumettra les commentaires des utilisateurs pour un cas d'utilisation spécifique :

{
  "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"
  ]
}

Cas d'utilisation de Bedrock Agent

WebSocket API Fonctionnalité Appelants autorisés

/invokeAgent

Envoie le message de l'utilisateur au WebSocket pour traitement avec l'agent configuré.

Jeton JWT authentifié par Amazon Cognito

Charges utiles d'InvokeAgent

Si vous effectuez une intégration directe avec le/invokeAgent API, vous devez respecter les formats de charge utile de demande et de réponse suivants.

Charge utile de la requête 

{
"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
}
Nom du paramètre Type Description

action

String

Nous soutenons uniquement l'invokeAgentaction sur le WebSocket.

Texte de saisie

String

Entrée utilisateur à envoyer au LLM.

Identifiant de conversation

String[Optional]

Un UUID qui identifie la conversation de manière unique. Si vous ne fournissez pas cette valeur, la solution crée une nouvelle conversation et renvoie le ConversationId dans la réponse. Tous les messages suivants de cette conversation (dans lesquels vous souhaitez conserver l'historique et le contexte) contiennent le ConversationID.

Jeton d'authentification

String[Optional]

AccessToken a été obtenu à partir du flux d'authentification Amazon Cognito. Ce paramètre n'est pas obligatoire. Si vous le fournissez, le jeton JWT sera validé. Cela permet de faciliter l'extension de cette solution.

Charges utiles de réponse

Réponse à la question

L' WebSocket API répondra avec un (si le streaming est désactivé) ou plusieurs (si le streaming est activé) objets JSON structurés comme suit pour chaque requête.

{
 "data" "some data",
 "conversationId": "id",
 }
Nom du paramètre Type Description

data

String

La réponse à l'invocation de l'agent.

Identifiant de conversation

String

L'identifiant de la conversation.