> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-docs-revamp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Risposte strutturate

> Usare risposte strutturate con l'API Venice

Venice ha incluso gli output strutturati tramite "response\_format" come campo disponibile nell'API. Questo campo ti consente di generare risposte ai tuoi prompt che seguono un formato specifico predefinito. Con questo nuovo metodo, è meno probabile che i modelli generino allucinazioni con chiavi o valori errati all'interno della risposta, fenomeno più frequente quando si tentava tramite manipolazione del system prompt o tramite function calling.

Il campo "response\_format" per gli output strutturati utilizza il formato dell'API OpenAI ed è descritto ulteriormente nella guida OpenAI [qui](https://platform.openai.com/docs/guides/structured-outputs). OpenAI ha anche pubblicato un articolo introduttivo sull'uso degli output strutturati all'interno dell'API specificamente [qui](https://openai.com/index/introducing-structured-outputs-in-the-api/). Trattandosi di funzionalità avanzata, ci sono alcune "gotcha" in fondo a questa pagina da seguire.

Questa funzionalità non è disponibile nativamente per tutti i modelli. Consulta la sezione modelli [qui](https://docs.venice.ai/api-reference/endpoint/models/list?playground=open) e cerca "supportsResponseSchema" per i modelli applicabili.

```json theme={"dark"}
    {
      "id": "venice-uncensored",
      "type": "text",
      "object": "model",
      "created": 1726869022,
      "owned_by": "venice.ai",
      "model_spec": {
        "availableContextTokens": 32768,
        "capabilities": {
          "supportsFunctionCalling": true,
          "supportsResponseSchema": true,
          "supportsWebSearch": true
        },
```

### Come usare le risposte strutturate

Per utilizzare correttamente il campo "response\_format", puoi definire il tuo schema con varie "properties", che rappresentano categorie di output, ciascuna con tipi di dati configurati individualmente. Questi oggetti possono essere annidati per creare strutture di output più avanzate.

Ecco un esempio di chiamata API che usa response\_format per spiegare il processo passo-passo della risoluzione di un'equazione matematica.

Puoi vedere che le properties sono state configurate per richiedere sia "steps" sia "final\_answer" all'interno della risposta. Nel nesting, la categoria steps consiste sia di una "explanation" sia di un "output", entrambi stringhe.

```json theme={"dark"}
curl --request POST \
  --url https://api.venice.ai/api/v1/chat/completions \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "venice-uncensored",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful math tutor."
    },
    {
      "role": "user",
      "content": "solve 8x + 31 = 2"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "math_response",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "explanation": {
                  "type": "string"
                },
                "output": {
                  "type": "string"
                }
              },
              "required": ["explanation", "output"],
              "additionalProperties": false
            }
          },
          "final_answer": {
            "type": "string"
          }
        },
        "required": ["steps", "final_answer"],
        "additionalProperties": false
      }
    }
  }
}

```

Ecco la risposta ricevuta dal modello. Puoi vedere che la struttura ha seguito i requisiti, fornendo prima gli "steps" con la "explanation" e l'"output" di ciascuno step, e poi la "final answer".

```json theme={"dark"}
{
  "steps": [
    {
      "explanation": "Subtract 31 from both sides to isolate the term with x.",
      "output": "8x + 31 - 31 = 2 - 31"
    },
    {
      "explanation": "This simplifies to 8x = -29.",
      "output": "8x = -29"
    },
    {
      "explanation": "Divide both sides by 8 to solve for x.",
      "output": "x = -29 / 8"
    }
  ],
  "final_answer": "x = -29 / 8"
}

```

Sebbene questo sia un esempio semplice, può essere estrapolato a casi d'uso più avanzati come: estrazione dati, esercizi di chain of thought, generazione di UI, categorizzazione dati e molti altri.

### Gotcha

Ecco alcuni requisiti chiave da tenere a mente quando usi gli output strutturati tramite response\_format:

* Le richieste iniziali che usano response\_format possono impiegare più tempo a generare una risposta. Le richieste successive non avranno la stessa latenza della richiesta iniziale.

* Per query più grandi, il modello può fallire il completamento se vengono raggiunti `max_tokens` o il timeout del modello, o se vengono violati i rate limit

* Un formato di schema errato comporterà errori al completamento, solitamente per timeout

* Sebbene response\_format garantisca che il modello produca un output in un modo specifico, non garantisce che il modello fornisca le informazioni corrette al suo interno. Il contenuto è determinato dal prompt e dalle prestazioni del modello.

* Gli output strutturati tramite response\_format non sono compatibili con le chiamate parallele di funzioni

* Importante: tutti i campi o parametri devono includere un tag `required`. Per rendere un campo opzionale, devi aggiungere un'opzione `null` all'interno del `type` del campo, in questo modo: `"type": ["string", "null"]`&#x20;

* È possibile rendere i campi opzionali fornendo opzioni `null` all'interno del campo required per consentire una risposta vuota.

* Importante: `additionalProperties` deve essere impostato a false affinché response\_format funzioni correttamente

* Importante: `strict` deve essere impostato a true affinché response\_format funzioni correttamente