AWS nova documentation change
Summary
Restructured troubleshooting documentation by removing detailed error handling content and replacing it with links to dedicated HTML pages for each model type (text, image, video, speech, tools). Removed implementation details about RAI policy enforcement, error messages, and tool configuration examples.
Security assessment
The changes primarily reorganize documentation structure rather than address security vulnerabilities. While the removed content included references to RAI policy enforcement (security-related content), this is a documentation relocation rather than a security fix. No new security documentation was added - existing content was moved to separate pages.
Diff
diff --git a/nova/latest/userguide/troubleshooting.md b/nova/latest/userguide/troubleshooting.md index aa3596149..776adb74c 100644 --- a//nova/latest/userguide/troubleshooting.md +++ b//nova/latest/userguide/troubleshooting.md @@ -5,2 +4,0 @@ -Understanding modelsImage generation modelsVideo generation modelsSpeech modelsTool usage - @@ -13,167 +11 @@ This section collects all of the troubleshooting and error handling advice that - * Understanding models - - * Image generation models - - * Video generation models - - * Speech models - - * Tool usage - - - - -## Understanding models - -The way errors are communicated back to the client varies depending on the type of error that occurs. In this section, we focus only on the error conditions that are unique to the Amazon Nova model. The three primary types of errors you will want to handle in your application code are **input validation** errors, **Responsible AI (RAI) input deflection** errors, and **RAI output deflection** errors. - -Input validation errors occur when you use an unsupported value for an input parameter. For example, an out-of-bounds value for temperature, or incorrect format of the input `image`. All input validation errors are expressed as a **ValidationException** which contains a message string describing the cause of the problem. - -**RAI input deflection** errors occur when any of the input text values or images are determined to violate the AWS Responsible AI policy. These errors are expressed as a **ValidationException** with one of the following messages: - - * **Input text** validation message: "This request has been blocked by our content filters. Please adjust your text prompt to submit a new request." - - * **Input image** validation message: "This request has been blocked by our content filters. Please adjust your input image to submit a new request." - - * **Input Video** validation message: "This request has been blocked by our content filters. Please adjust your input video to submit a new request." - - - - -RAI output deflection errors occur when an the output is generated but it is determined to be misaligned with the AWS Responsible AI policy. When this occurs, an exception is not used. Instead, a successful response is returned, and its structure contains an `error` field which is a string with one of the following values: - - * **Output text** validation message: "The generated text has been blocked by our content filters." - - - - -## Image generation models - -There are three primary types of errors that you want to handle in your application code. These are input validation errors, AWS Responsible AI (RAI) input deflection errors, and RAI output deflection errors. These errors are unique to Amazon Nova Canvas. - -Input validation errors occur when you use an unsupported value for an input parameter. For example, a width value that doesn't match one of the supported resolutions, an input image that exceeds the maximum allowed size, or a `maskImage` that contains colors other than pure black and white. All input validation errors are expressed as a `ValidationException` which contains a message string describing the cause of the problem. - -RAI input deflection errors occur when any of the input text values or images are determined to violate the AWS Responsible AI policy. These errors are expressed as a `ValidationException` with one of the following messages: - - * Input text validation message - "This request has been blocked by our content filters. Please adjust your text prompt to submit a new request." - - * Input image validation message - "This request has been blocked by our content filters. Please adjust your input image to submit a new request." - - - - -RAI output deflection errors occur when an image is generated but it is misaligned with the AWS Responsible AI policy. When this occurs, an exception is not used. Instead, a successful response is returned, and its structure contains an error field which is a string with one of the following values: - - * If all requested images violate RAI policy - "All of the generated images have been blocked by our content filters." - - * If some, but not all, requested images violate RIA policy - "Some of the generated images have been blocked by our content filters." - - - - -## Video generation models - -There are three primary types of errors that you want to handle in your application code. These are input validation errors, AWS Responsible AI (RAI) input deflection errors, and RAI output deflection errors. These errors are unique to Amazon Nova Reel. - -Input validation errors occur if your request is malformed or if you use an unsupported value for an input parameter—for example, a `duration` value that does not match one of the supported values or an input `image` that is not exactly 1280x720 resolution. All input validation errors are expressed as a **ValidationException** which contains a message string describing the cause of the problem. This exception will be raised when calling the `start_async_invoke()` method of the Amazon Bedrock Runtime. - -RAI input deflection errors occur when the input text value or input image are determined to violate [AWS core dimensions of responsible AI](https://aws.amazon.com/ai/responsible-ai/). These errors are expressed as a **ValidationException** with one of the following messages: - - * **Input text** validation message: "This request has been blocked by our content filters. Please adjust your text prompt to submit a new request." - - * **Input image** validation message: "This request has been blocked by our content filters. Please adjust your input image to submit a new request." - - - - -RAI output deflection errors occur when a video is generated but it is determined to be misaligned with [our core dimensions of responsible AI](https://aws.amazon.com/ai/responsible-ai/). When this occurs, an exception is not used. Instead, the job is marked as "Failed" and the file is never written to Amazon S3. When querying the status of the job (for example, using `get_invoke()`), the response will have a `status` field value of "Failed" and a `failureMessage` field value of "The generated video has been blocked by our content filters." - -## Speech models - -When errors occur, we recommend trying the following steps: - - 1. Send the `promptEnd` event. - - 2. Send the `sessionEnd` event. - - 3. If the audio streaming has started, also send the `contentEnd` event. - - - - -Completing these steps also frees GPU resources and memory. - -When handling long conversations or recovering from errors, you can implement conversation resumption using the following approach: - - 1. Set up chat history storage to preserve conversation context from previous interactions. You can find chat history example in our [Amazon Nova samples Github repo](https://github.com/aws-samples/amazon-nova-samples/tree/main/speech-to-speech/repeatable-patterns/chat-history-logger). - - 2. Handle conversation timeouts proactively: - - * When approaching the maximum connection duration, end the current request and start a new one. - - * Include the saved chat history in the new request to maintain conversation continuity. - - 3. Format resumed conversations properly: - - * Place the chat history after the system prompt but before any new user input. - - * Include previous messages with the proper user and assistant roles. - - * Ensure that the first message in the chat history is from the user. - -You can find chat resumption example in our [Amazon Nova samples Github repo](https://github.com/aws-samples/amazon-nova-samples/tree/main/speech-to-speech/repeatable-patterns/resume-conversation). - - - - -###### When to use conversation resumption - -The conversation resumption approach is particularly helpful for error recovery in the following scenarios: - - * After you receive a `ModelTimeoutException` with the message "Model has timed out in processing the request". - - * When you need to restore context after an unexpected disconnection. - - - - -## Tool usage - -You might see different errors when working with tools and Amazon Nova models. Here are a few examples and tips to help you troubleshoot. - -`An error occurred (ModelErrorException) when calling the Converse operation: The model produced an invalid sequence as part of ToolUse. Please refer to the model tool use troubleshooting guide.` - -**Validate your inference parameters** \- Amazon Nova models have more success calling tools when using greedy decoding. To enable greedy decoding, set the temperature parameters to 0. - - - inferenceConfig={ - "temperature": 0 - } - - additionalModelRequestFields={"inferenceConfig": {"topK": 1}} - -**Increase the maximum token count** \- It is common for tool outputs to require a large token output, ensure that the max tokens set is large enough to accommodate the expected return schema. If the model response is larger than your max token count, it will trigger an exception. You can set the maximum tokens in the `inferenceConfig` parameter: - - - inferenceConfig={ - "maxTokens": 3000 - } - -**Review the system prompt** \- To improve the accuracy of tool calling, Amazon Nova uses chain-of-thought reasoning when calling a tool. You will see this output in the response in <thinking> tags. We do not recommended trying to remove this functionality. Instead, we recommend that you drop the output if you do not need it in your application. - -`An error occurred (ValidationException) when calling the Converse operation` - -The passed tool configuration does not comply to the required conventions. Refer to the [Converse API spec](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-runtime/client/converse.html) for specifications for all parameters. - -If it looks like tools are being ignored by the model, make sure you are following the correct JSON schema for the tool config: - - * Top level schema must of of type [Object](https://json-schema.org/understanding-json-schema/reference/object) - - * Only three fields are supported in top-level Object - `type` (must be set to "object"), `properties`, and `required` - - * Common unsupported fields at the top level are: `$schema`, `description`, `title`, and `additionalProperties` - - - - -If a tool is not being returned when expected, it is recommended to leverage the `tool_choice` API parameter. + * [Understanding models](./text-troubleshooting.html) @@ -181 +13 @@ If a tool is not being returned when expected, it is recommended to leverage the - * **Tool** : The specified tool will be called once. + * [Image generation models](./image-troubleshooting.html) @@ -183,7 +15 @@ If a tool is not being returned when expected, it is recommended to leverage the - { - "toolChoice": { - "tool": { - "name": "name_of_tool" - } - } - } + * [Video generation models](./video-troubleshooting.html) @@ -191 +17 @@ If a tool is not being returned when expected, it is recommended to leverage the - * **Any** : One of the provided tools will be called at least once. + * [Speech models](./speech-troubleshooting.html) @@ -193,5 +19 @@ If a tool is not being returned when expected, it is recommended to leverage the - { - "toolChoice": { - "any": {} - } - } + * [Tool usage](./tools-troubleshooting.html) @@ -208 +30 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -Monitoring