Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
API-Referenz
Dieser Abschnitt enthält API-Referenzen für die Lösung.
Bereitstellungs-Dashboard
| REST-API | HTTP-Methode | Funktionalität | Autorisierte Anrufer |
|---|---|---|---|
|
|
|
Holen Sie sich alle Bereitstellungen. |
Authentifiziertes JWT-Token von Amazon Cognito |
|
|
|
Erstellt eine neue Anwendungsfall-Bereitstellung. |
Authentifiziertes JWT-Token von Amazon Cognito |
|
|
|
Ruft Bereitstellungsdetails für eine einzelne Bereitstellung ab. |
Authentifiziertes JWT-Token von Amazon Cognito |
|
|
|
Aktualisiert eine bestimmte Bereitstellung. |
Authentifiziertes JWT-Token von Amazon Cognito |
|
|
|
Löscht eine bestimmte Bereitstellung. |
Authentifiziertes JWT-Token von Amazon Cognito |
|
|
|
Ruft die verfügbaren Anwendungsfalltypen für die Bereitstellung ab |
Authentifiziertes JWT-Token von Amazon Cognito |
|
|
|
Ruft die verfügbaren Modellanbieter für den angegebenen Anwendungsfalltyp ab |
Authentifiziertes JWT-Token von Amazon Cognito |
|
|
|
Ruft die IDs Modelle ab, die für einen bestimmten Anbieter und einen bestimmten Anwendungsfalltyp verfügbar sind |
Authentifiziertes JWT-Token von Amazon Cognito |
|
|
|
Ruft die Informationen über das angegebene Modell ab, einschließlich der Standardparameter. |
Authentifiziertes JWT-Token von Amazon Cognito |
Anmerkung
OpenAPI- und Swagger-Dateien können auch aus API Gateway exportiert werden, um die Integration mit der API zu vereinfachen. Siehe Exportieren einer REST-API aus dem API Gateway.
POST- und PATCH-Payloads
Im Folgenden finden Sie ein Beispiel für eine POST-Payload an den /deployments Endpunkt, wodurch ein neuer Anwendungsfall entsteht.
{ "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 } } }
Für Updates ist die Struktur dieselbe wie oben, mit einigen Einschränkungen:
-
Der Name des Anwendungsfalls kann nicht geändert werden
-
Ein Anwendungsfall kann Sicherheitsgruppen und Subnetze erst ändern, wenn er in einer VPC bereitgestellt wurde. Die VPC selbst kann nicht geändert werden.
-
Wenn ein Kendra-Index für Sie als Wissensdatenbank erstellt wurde, können Sie die Konfiguration dieses Indexes nicht ändern (z. B. KendraIndexName, QueryCapacityUnits)
Gemeinsamer Anwendungsfall APIs
Die folgenden REST-API-Endpunkte sind sowohl für Text- als auch für Bedrock Agent-Anwendungsfälle verfügbar:
| REST-API | HTTP-Methode | Funktionalität | Autorisierte Anrufer |
|---|---|---|---|
|
|
|
Ruft Konfigurationsdetails für einen bestimmten Anwendungsfall ab. |
Authentifiziertes JWT-Token von Amazon Cognito |
| WebSocket API | Funktionalität | Autorisierte Anrufer |
|---|---|---|
|
|
WebSocket Verbindung herstellen und Benutzer authentifizieren. |
Authentifiziertes JWT-Token von Amazon Cognito |
|
|
Endpunkt, der aufgerufen wird, wenn eine WebSocket Verbindung getrennt wurde. |
Authentifiziertes JWT-Token von Amazon Cognito |
Verwenden Sie die API mit Falldetails
Der Details-API-Endpunkt ruft Informationen zu einem bestimmten Anwendungsfall ab:
GET /details/{useCaseConfigKey}
Dieser Endpunkt gibt die Konfigurationsdetails für einen bestimmten Anwendungsfall zurück, einschließlich Modellparameter, Knowledgebase-Einstellungen und anderer Bereitstellungsinformationen. Für die Autorisierung ist ein von Amazon Cognito authentifiziertes JWT-Token erforderlich.
Anwendungsfall im Textformat
| WebSocket API | Funktionalität | Autorisierte Anrufer |
|---|---|---|
|
|
Sendet die Chat-Nachricht des Benutzers WebSocket zur Verarbeitung mit der konfigurierten LLM-Erfahrung an den. |
Authentifiziertes JWT-Token von Amazon Cognito |
| REST-API | HTTP-Methode | Funktionalität | Autorisierte Anrufer |
|---|---|---|---|
|
|
|
Sendet Benutzerfeedback für einen bestimmten Anwendungsfall. |
Authentifiziertes JWT-Token von Amazon Cognito |
Nutzlasten von SendMessage
Wenn Sie die /sendMessage API direkt integrieren, müssen Sie die folgenden Payload-Formate für Anfrage und Antwort einhalten.
Payload anfordern
{ "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 }
| Name des Parameters | Typ | Description |
|---|---|---|
|
Aktion |
|
Derzeit unterstützen wir nur die Aktion „SendMessage“ auf der WebSocket |
|
Frage |
|
Die Benutzereingabe, die an das LLM gesendet werden soll |
|
Konversations-ID |
|
Eine UUID, die die Konversation identifiziert. Falls nicht angegeben, wird eine neue Konversation erstellt, wobei die ConversationID in der Antwort zurückgegeben wird. Alle nachfolgenden Nachrichten in dieser Konversation (in denen Sie möchten, dass history/context sie gespeichert werden), sollten dort die ConversationID angeben. |
|
Vorlage für Eingabeaufforderung |
|
Überschreibt die Eingabeaufforderungsvorlage für diese Nachricht. Falls leer oder nicht angegeben, wird standardmäßig die bei der Bereitstellung festgelegte Aufforderung verwendet. Es müssen die richtigen Platzhalter für die angegebene Konfiguration angegeben werden (d. h. {history} und {input} für Sagemaker AI-Bereitstellungen, die nicht von RAG stammen, mit dem Zusatz {context}, wenn RAG für alle Bereitstellungen verwendet wird. |
|
AuthToken |
|
AccessToken, wie es aus dem Cognito-Authentifizierungsfluss abgerufen wurde. Dies ist erforderlich, wenn ein Chat-Websocket-Endpunkt aufgerufen wird, der für RAG mit Role Based Access Control (RBAC) konfiguriert ist. Die Cognito:groups-Anspruchsliste in diesem JWT-Token wird verwendet, um den Zugriff auf Dokumente im Kendra-Index zu kontrollieren. Dieser Parameter ist für Anwendungsfälle, die nicht RAG sind, nicht erforderlich. Er ist auch nicht für RAG-Anwendungsfälle erforderlich, bei denen RBAC deaktiviert ist. |
Payloads für Antworten
Frage & Antwort
Die WebSocket API antwortet mit einem (wenn Streaming deaktiviert ist) oder vielen (wenn Streaming aktiviert ist) JSON-Objekten, die für jede Abfrage wie folgt strukturiert sind.
{ "data": "some data", "conversationId": "id", }
| Name des Parameters | Typ | Description |
|---|---|---|
|
data |
|
Ein Teil der Antwort des LLM, wenn Streaming aktiviert ist, oder die gesamte Antwort. Bei Verwendung von Streaming wird eine Antwort dieses Formats mit dem Dateninhalt END_CONVERSATION gesendet, um das Ende der Antwort auf eine einzelne Frage anzuzeigen. |
|
Konversations-ID |
|
Die ID der Konversation, zu der diese SourceDocument-Antwort gehört. |
Antwort auf das Quelldokument
Wenn Sie Ihren RAG-Anwendungsfall für die Rückgabe von Quelldokumenten konfiguriert haben, erhalten Sie am Ende jeder Antwort für jedes Quelldokument, das zur Erstellung der Antwort verwendet wurde, außerdem die folgende Payload.
{ "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" }
| Name des Parameters | Typ | Description |
|---|---|---|
|
Auszug |
|
Ein Auszug aus dem Quelldokument. |
|
location |
|
Speicherort des Quelldokuments. Dies hängt von den verwendeten Datenquellen und der Art der Wissensdatenbank ab, kann aber auch Dinge wie S3 URIs oder Websites sein. |
|
Ergebnis |
|
Die Gewissheit, dass das Dokument der gestellten Frage entspricht. Dies wird ein Float von 0 bis 1 für Bedrock und eine Zeichenfolge (z. B. HIGH, LOW usw.) für Kendra sein. |
|
document_title |
|
Titel des zurückgegebenen Quelldokuments. Nur verfügbar, wenn Sie Kendra verwenden. |
|
document_id |
|
ID des zurückgegebenen Quelldokuments. Nur verfügbar, wenn Sie Kendra verwenden. |
|
additional_attributes |
|
Dieses Feld enthält alle zusätzlichen Attribute des Dokuments, wie sie bei der Aufnahme in Ihrer Wissensdatenbank angepasst wurden. |
|
Konversations-ID |
|
Die ID der Konversation, zu der diese SourceDocument-Antwort gehört. |
Nutzlast der Feedback-API
Im Folgenden finden Sie ein Beispiel für eine POST-Nutzlast an den /feedback/{useCaseId} Endpunkt, über die Benutzerfeedback für einen bestimmten Anwendungsfall gesendet wird:
{ "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" ] }
Anwendungsfall Bedrock Agent
| WebSocket API | Funktionalität | Autorisierte Anrufer |
|---|---|---|
|
|
Sendet die Nachricht des Benutzers an den WebSocket zur Verarbeitung mit dem konfigurierten Agenten. |
Authentifiziertes JWT-Token von Amazon Cognito |
Agent-Nutzlasten aufrufen
Wenn Sie direkt mit dem integrieren/invokeAgent API, müssen Sie die folgenden Payload-Formate für Anfrage und Antwort einhalten.
Anforderungs-Nutzlast
{ "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 }
| Parametername | Typ | Description |
|---|---|---|
|
Aktion |
|
Wir unterstützen nur die |
|
Text eingeben |
|
Die Benutzereingabe, die an das LLM gesendet werden soll. |
|
Konversations-ID |
|
Eine UUID, die die Konversation eindeutig identifiziert. Wenn Sie diesen Wert nicht angeben, erstellt die Lösung eine neue Konversation und gibt die ConversationID in der Antwort zurück. Alle nachfolgenden Nachrichten in dieser Konversation (in der Sie Verlauf und Kontext beibehalten möchten) geben dort die ConversationID an. |
|
AuthToken |
|
AccessToken, wie es aus dem Amazon Cognito Cognito-Authentifizierungsablauf abgerufen wurde. Dieser Parameter ist nicht erforderlich. Wenn Sie es angeben, wird das JWT-Token validiert. Dies erleichtert die Erweiterung dieser Lösung. |
Payloads für Antworten
Antwort auf die Frage
Die WebSocket API antwortet mit einem (wenn Streaming deaktiviert ist) oder vielen (wenn Streaming aktiviert ist) JSON-Objekten, die für jede Abfrage wie folgt strukturiert sind.
{ "data" "some data", "conversationId": "id", }
| Parametername | Typ | Description |
|---|---|---|
|
data |
|
Die Antwort vom Agentenaufruf. |
|
Konversations-ID |
|
Die ID der Konversation. |
