feat(genapi): add recommendations for structured outputs usage (#4791)

* feat(genapi): add recommendations for structured outputs usage

* feat(genapi): update recommandations in troubleshooting

* feat(genapi): add link on structured outputs recommandations

* Update pages/generative-apis/how-to/use-structured-outputs.mdx

---------

Co-authored-by: Benedikt Rollik <[email protected]>

Author: fpagny

pages/generative-apis/how-to/use-structured-outputs.mdx

@@ -132,6 +132,14 @@ Output example:
 }
 ```
 
+<Message type="tip">
+    Structured outputs accuracy may vary between models. For instance, with Llama models, we suggest adding a description of the field looked for in `response_format` and in `system` or `user` messages. In our example this would mean adding a system prompt similar to:
+    ```bash
+    "content": "The following is a voice message transcript. Provide the message title, summary and action items. Only answer in JSON using '{' as the first character.",
+    ```
+    For additional optimization or troubleshooting, see [Structured output (e.g., JSON) is not working correctly](/generative-apis/troubleshooting/fixing-common-issues/#structured-output-eg-json-is-not-working-correctly).
+</Message>
+
 ### Using structured outputs with JSON schema (manual definition)
 
 Alternatively, users can manually define the JSON schema inline when calling the model.

pages/generative-apis/troubleshooting/fixing-common-issues.mdx

@@ -63,13 +63,24 @@ Below are common issues that you may encounter when using Generative APIs, their
 
 ## Structured output (e.g., JSON) is not working correctly
 
-### Cause
+### Description
+- Structured output response contains invalid JSON
+- Structured output response is valid JSON but content is less relevant
+
+### Causes
 - Incorrect field naming in the request, such as using `"format"` instead of the correct `"response_format"` field.
 - Lack of a JSON schema, which can lead to ambiguity in the output structure.
+- Maximum tokens is lower than what the model response needs to be complete.
+- Temperature is not set or set too high.
+
 
 ### Solution
 - Ensure the proper field `"response_format"` is used in the query.
 - Provide a JSON schema in the request to guide the model's structured output.
+- Ensure the `max_tokens` value is higher than the response `completion_tokens` value. If this is not the case, the model answer may be stripped down before it can finish the proper JSON structure (and lack closing JSON brackets `}` for example). Note that if the `max_tokens` value is not set in the query, [default values apply for each models](/generative-apis/reference-content/supported-models/).
+- Ensure the `temperature` value is set with a lower range value for the model. If this is not the case, the model answer may output invalid JSON characters. Note that if the `temperature` value is not set in the query, [default values apply for each models](/generative-apis/reference-content/supported-models/). As examples:
+  - for `llama-3.3-70b-instruct`, `temperature` should be set lower than `0.6`
+  - for `mistral-nemo-instruct-2407	`, `temperature` should be set lower than `0.3`
 - Refer to the [documentation on structured outputs](/generative-apis/how-to/use-structured-outputs/) for examples and additional guidance.