View a markdown version of this page

Guida di riferimento alle API - Generative AI Application Builder su AWS
Dashboard di implementazioneCaso d'uso condiviso APIsCaso di utilizzo del testoCaso d'uso di Bedrock Agent

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Guida di riferimento alle API

Questa sezione fornisce i riferimenti API per la soluzione.

Dashboard di implementazione

REST API Metodo HTTP Funzionalità Chiamanti autorizzati

/deployments

GET

Ottieni tutte le implementazioni.

Token JWT autenticato da Amazon Cognito

/deployments

POST

Crea una nuova distribuzione di use case.

Token JWT autenticato da Amazon Cognito

/deployments/{useCaseId}

GET

Ottiene i dettagli di distribuzione per una singola distribuzione.

Token JWT autenticato da Amazon Cognito

/deployments/{useCaseId}

PATCH

Aggiorna una determinata distribuzione.

Token JWT autenticato da Amazon Cognito

/deployments/{useCaseId}

DELETE

Elimina una determinata distribuzione.

Token JWT autenticato da Amazon Cognito

/model-info/use-case-types

GET

Ottiene i tipi di casi d'uso disponibili per la distribuzione

Token JWT autenticato da Amazon Cognito

/model-info/{useCaseType}/providers

GET

Ottiene i fornitori di modelli disponibili per il tipo di caso d'uso specificato

Token JWT autenticato da Amazon Cognito

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

GET

Ottiene i IDs modelli disponibili per un determinato provider e tipo di caso d'uso

Token JWT autenticato da Amazon Cognito

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

GET

Ottiene le informazioni sul modello specificato, inclusi i parametri predefiniti.

Token JWT autenticato da Amazon Cognito
Nota

I file OpenAPI e Swagger possono anche essere esportati da API Gateway per una più facile integrazione con l'API. Vedi Esportazione di un'API REST da API Gateway.

Payload POST e PATCH

Di seguito è riportato un esempio di payload POST sull'/deploymentsendpoint, che creerà un nuovo caso d'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
 }
 }

}

Per gli aggiornamenti, la struttura è la stessa di cui sopra con alcune avvertenze:

  • Il nome del caso d'uso non può essere modificato

  • Uno use case può modificare i gruppi di sicurezza e le sottoreti solo dopo essere stato distribuito in un VPC. Il VPC stesso non può essere modificato.

  • Se un indice Kendra è stato creato per te come knowledge base, non puoi modificare la configurazione di quell'indice (ad esempio,,) KendraIndexName QueryCapacityUnits

Caso d'uso condiviso APIs

I seguenti endpoint dell'API REST sono disponibili per i casi d'uso di Text e Bedrock Agent:

REST API Metodo HTTP Funzionalità Chiamanti autorizzati

/details/{useCaseConfigKey}

GET

Ottiene i dettagli di configurazione per un caso d'uso specifico.

Token JWT autenticato da Amazon Cognito
WebSocket API Funzionalità Chiamanti autorizzati

/$connect

Avvia la WebSocket connessione e autentica l'utente.

Token JWT autenticato da Amazon Cognito

/$disconnect

Endpoint chiamato quando una WebSocket connessione è stata interrotta.

Token JWT autenticato da Amazon Cognito

Usa l'API Case Details

L'endpoint dell'API details recupera informazioni su un caso d'uso specifico:

GET /details/{useCaseConfigKey}

Questo endpoint restituisce i dettagli di configurazione per un caso d'uso specifico, inclusi i parametri del modello, le impostazioni della knowledge base e altre informazioni sulla distribuzione. Richiede un token JWT autenticato da Amazon Cognito per l'autorizzazione.

Caso di utilizzo del testo

WebSocket API Funzionalità Chiamanti autorizzati

/sendMessage

Invia il messaggio di chat dell'utente a WebSocket per l'elaborazione con l'esperienza LLM configurata.

Token JWT autenticato da Amazon Cognito
REST API Metodo HTTP Funzionalità Chiamanti autorizzati

/feedback/{useCaseId}

POST

Invia il feedback degli utenti per un caso d'uso specifico.

Token JWT autenticato da Amazon Cognito

Payload SendMessage

Se ti stai integrando direttamente con l'/sendMessageAPI, devi rispettare i seguenti formati di payload di richiesta e risposta.

Richiedi Payload 

{
 "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 parametro Tipo Description

action

String

Attualmente supportiamo solo l'azione «SendMessage» su WebSocket

domanda

String

L'input dell'utente da inviare al LLM

ID di conversazione

String

Un UUID che identifica la conversazione. Se non viene fornito, verrà creata una nuova conversazione, con il ConversationID restituito nella risposta. Tutti i messaggi successivi di quella conversazione (in cui desideri che vengano mantenuti), devono history/context fornire lì il ConversationID.

Modello di prompt

String [Opzionale]

Sostituisce il modello di prompt per questo messaggio. Se vuoto o non fornito, verrà utilizzato per impostazione predefinita il prompt impostato al momento della distribuzione. Deve avere i segnaposto appropriati specificati per la configurazione data (ad esempio {history} e {input} per le implementazioni AI non RAG Sagemaker, con l'aggiunta di {context} se si utilizza RAG per tutte le implementazioni.

AuthToken

String [Opzionale]

AccessToken ottenuto dal flusso di autenticazione cognito. Ciò è necessario quando si richiama un endpoint websocket di chat configurato per RAG con Role Based Access Control (RBAC). L'elenco dei claim cognito:groups in questo token JWT viene utilizzato per controllare l'accesso ai documenti nell'indice Kendra. Questo parametro non è richiesto per casi d'uso diversi da RAG. Inoltre, non è necessario per i casi d'uso RAG con RBAC disabilitato.

Payload di risposta

Risposta alla domanda

L' WebSocket API risponderà con 1 (se lo streaming è disabilitato) o molti (se lo streaming è abilitato) oggetti JSON strutturati come segue per ogni query.

{
 "data": "some data",
 "conversationId": "id",
}
Nome parametro Tipo Description

dati

String

Una parte della risposta del LLM, se lo streaming è abilitato, o l'intera risposta. Se si utilizza lo streaming, verrà inviata una risposta di questo formato con il contenuto dei dati END_CONVERSATION per indicare la fine della risposta a una singola domanda.

ConversationID

String

L'ID della conversazione a cui appartiene questa risposta SourceDocument.

Risposta del documento di origine

Se avete configurato lo use case RAG per restituire documenti di origine, riceverete anche il seguente payload alla fine di ogni risposta per ogni documento sorgente utilizzato per creare la risposta.

{
 "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 parametro Tipo Description

estratto

String

Un estratto dal documento sorgente.

posizione

String

Ubicazione del documento di origine. Ciò dipenderà dalle fonti di dati utilizzate e dal tipo di knowledge base, ma potrebbero essere cose come s3 URIs o siti Web.

punteggio

Number | String

La certezza che il documento corrisponda alla domanda posta. Questo sarà un float da 0 a 1 per Bedrock e una stringa (ad esempio HIGH, LOW, ecc.) per Kendra.

titolo_documento

String

Titolo del documento sorgente restituito. Disponibile solo quando usi Kendra.

document_id

String

ID del documento sorgente restituito. Disponibile solo quando usi Kendra.

attributi_aggiuntivi

String

Questo campo conterrà tutti gli attributi aggiuntivi del documento, così come personalizzati nella Knowledge Base al momento dell'inserimento.

ConversationID

String

L'ID della conversazione a cui appartiene questa risposta SourceDocument.

Payload dell'API di feedback

Di seguito è riportato un esempio di payload POST sull'/feedback/{useCaseId}endpoint, che invierà il feedback degli utenti per un caso d'uso specifico:

{
  "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 d'uso di Bedrock Agent

WebSocket API Funzionalità Chiamanti autorizzati

/invokeAgent

Invia il messaggio dell'utente a WebSocket per l'elaborazione con l'agente configurato.

Token JWT autenticato da Amazon Cognito

Carichi utili InvokeAgent

Se ti stai integrando direttamente con/invokeAgent API, devi rispettare i seguenti formati di payload di richiesta e risposta.

Payload della richiesta 

{
"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 del parametro Tipo Description

action

String

Supportiamo solo l'invokeAgentazione su. WebSocket

Testo di input

String

L'input dell'utente da inviare al LLM.

ID di conversazione

String[Optional]

Un UUID che identifica in modo univoco la conversazione. Se non fornisci questo valore, la soluzione crea una nuova conversazione e restituisce il ConversationID nella risposta. Tutti i messaggi successivi di quella conversazione (in cui desideri conservare la cronologia e il contesto) forniscono lì il ConversationID.

AuthToken

String[Optional]

AccessToken è stato ottenuto dal flusso di autenticazione di Amazon Cognito. Questo parametro non è obbligatorio. Se lo fornisci, il token JWT verrà convalidato. Questo aiuta a semplificare l'estensione di questa soluzione.

Carichi utili di risposta

Risposta alla domanda

L' WebSocket API risponderà con uno (se lo streaming è disabilitato) o più (se lo streaming è abilitato) oggetti JSON strutturati come segue per ogni query.

{
 "data" "some data",
 "conversationId": "id",
 }
Nome del parametro Tipo Description

dati

String

La risposta della chiamata dell'agente.

ConversationID

String

L'ID della conversazione.