Query the knowledge base and return results or generate responses

To learn how to query your knowledge base, select the tab corresponding to your method of choice and follow the steps.

Console

To test your knowledge base

1. Sign in to the AWS Management Console, and open the Amazon Bedrock console at https://console.aws.amazon.com/bedrock/.

2. From the left navigation pane, select Knowledge base.

3. In the Knowledge bases section, do one of the following actions:

   • Choose the radio button next to the knowledge base you want to test and select Test knowledge base. A test window expands from the right.

   • Choose the knowledge base that you want to test. A test window expands from the right.

4. Select or clear Generate responses for your query depending on your use case.

   • To return information retrieved directly from your knowledge base, turn off Generate responses. Amazon Bedrock will return text chunks from your data sources that are relevant to the query.

   • To generate responses based on information retrieved from your knowledge base, turn on Generate responses. Amazon Bedrock will generate responses based on your data sources and cites the information it provides with footnotes.

5. If you turn on Generate responses, choose Select model to choose a model to use for response generation. Then select Apply.

6. (Optional) Select the configurations icon ( ) to open up Configurations. You can modify the following configurations:

   • Search type – Specify how your knowledge base is queried. For more information, see Search type.

   • Maximum number of retrieved results – Specify the maximum number of results to retrieve. For more information, see Maximum number of retrieved results.

   • Filters – Specify up to 5 filter groups and up to 5 filters within each group to use with the metadata for your files. For more information, see Metadata and filtering.

   • Knowledge base prompt template – If you turn on Generate responses, you can replace the default prompt template with your own to customize the prompt that's sent to the model for response generation. For more information, see Knowledge base prompt template.

   • Guardrails – If you turn on Generate responses, you can test how guardrails works with the prompts and responses for your knowledge base. For more information, see Guardrails.

7. Enter a query in the text box in the chat window and select Run to return responses from the knowledge base.

8. You can examine the response in the following ways.

   • If you didn't generate responses, the text chunks are returned directly in order of relevance.

   • If you generated responses, select a footnote to see an excerpt from the cited source for that part of the response. Choose the link to navigate to the S3 object containing the file.

   • To see details about the chunks cited for each footnote, select Show source details. You can carry out the following actions in the Source details pane:

     • To see the configurations that you set for query, expand Query configurations.

     • To view details about a source chunk, expand it by choosing the right arrow ( ) next to it. You can see the following information:

       • The raw text from the source chunk. To copy this text, choose the copy icon ( ). To navigate to the S3 object containing the file, choose the external link icon ( ).

       • The metadata associated with the source chunk. The attribute keys and values are defined in the .metadata.json file that's associated with the source document. For more information, see Metadata file requirements.

Chat options

1. If you are generating responses, you can select Change model to use a different model for response generation. If you change the model, the text in the chat window will be completely cleared.

2. Switch between generating responses for your query and returning direct quotations by selecting or clearing Generate responses. If you change the setting, the text in the chat window will be completely cleared.

3. To clear the chat window, select the broom icon ( ).

4. To copy all the output in the chat window, select the copy icon ( ).

API

Retrieve

To query a knowledge base and only return relevant text from data sources, send a Retrieve request (see link for request and response formats and field details) with an Agents for Amazon Bedrock runtime endpoint.

The following table briefly describes the parameters and request body (for detailed information and the request structure, see the see Retrieve request syntax:

Variable	Required?	Use case
knowledgeBaseId	Yes	To specify the knowledge base to query
retrievalQuery	Yes	Contains a text field to specify the query
nextToken	No	To return the next batch of responses
retrievalConfiguration	No	To include query configurations for customizing the vector search.

The following table briefly describes the response body (for detailed information and the response structure, see the Retrieve response syntax:

Variable	Use case
retrievalResults	Contains the source chunks, Amazon S3 location of the source, and a relevancy score for the chunk.
nextToken	To use in another request to return the next batch of results.

RetrieveAndGenerate

To query a knowledge base and use a foundation model to generate responses based off the results from the data sources, send a RetrieveAndGenerate request with a Agents for Amazon Bedrock runtime endpoint.

The following table briefly describes the parameters and request body (for detailed information and the request structure, see the RetrieveAndGenerate request syntax):

Variable	Required?	Use case
input	Yes	Contains a text field to specify the query
retrieveAndGenerateConfiguration	Yes	For specifying the knowledge base to query, the model to use for response generation, and optional query configurations.
sessionId	No	Use the same value to continue the same session and maintain information
sessionConfiguration	No	To include a KMS key for encryption of the session

The following table briefly describes the response body (for detailed information and the response structure, see the Retrieve response syntax):

Variable	Use case
citations	Contains parts of the generated response in each object within the generatedResponsePart, and the source chunk in the content object and the Amazon S3 location of the source in the location object of the retrievedReferences object.
guardrailAction	Specifies if there is a guardrail used in the response.
output	Contains the whole generated response.
sessionId	Contains the ID of the session, which you can reuse in another request to maintain the same conversation

Note

If you receive an error that the prompt exceeds the character limit while generating responses, you can shorten the prompt in the following ways:

• Reduce the maximum number of retrieved results (this shortens what is filled in for the $search_results$ placeholder in the Knowledge base prompt template).

• Recreate the data source with a chunking strategy that uses smaller chunks (this shortens what is filled in for the $search_results$ placeholder in the Knowledge base prompt template).

• Shorten the prompt template.

• Shorten the user query (this shortens what is filled in for the $query$ placeholder in the Knowledge base prompt template).