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](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html).
**Payload POST e PATCH**
Di seguito è riportato un esempio di payload POST sull'`/deployments`endpoint, 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'`/sendMessage`API, 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 \$1history\$1 e \$1input\$1 per le implementazioni AI non RAG Sagemaker, con l'aggiunta di \$1context\$1 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\$1CONVERSATION* 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` \$1 `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\$1documento** | `String` | Titolo del documento sorgente restituito. Disponibile solo quando usi Kendra. |
| **document\$1id** | `String` | ID del documento sorgente restituito. Disponibile solo quando usi Kendra. |
| **attributi\$1aggiuntivi** | `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'`invokeAgent`azione 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. |