Strumenti

Streaming granulare degli strumenti

Scopri come utilizzare lo streaming granulare per i parametri degli strumenti per ridurre la latenza e iniziare a ricevere parametri di grandi dimensioni più velocemente.

L'uso degli strumenti ora supporta lo streaming granulare per i valori dei parametri. Questo consente agli sviluppatori di trasmettere in streaming i parametri di uso degli strumenti senza buffering / validazione JSON, riducendo la latenza per iniziare a ricevere parametri di grandi dimensioni.

Lo streaming granulare degli strumenti è una funzionalità beta. Assicurati di valutare le tue risposte prima di utilizzarla in produzione.

Utilizza questo modulo per fornire feedback sulla qualità delle risposte del modello, sull'API stessa o sulla qualità della documentazione—non vediamo l'ora di sentirti!

Quando utilizzi lo streaming granulare degli strumenti, potresti potenzialmente ricevere input JSON non validi o parziali. Assicurati di tenere conto di questi casi limite nel tuo codice.

Come utilizzare lo streaming granulare degli strumenti

Per utilizzare questa funzionalità beta, aggiungi semplicemente l'header beta fine-grained-tool-streaming-2025-05-14 a una richiesta di uso degli strumenti e attiva lo streaming.

Ecco un esempio di come utilizzare lo streaming granulare degli strumenti con l'API:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: fine-grained-tool-streaming-2025-05-14" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 65536,
    "tools": [
      {
        "name": "make_file",
        "description": "Write text to a file",
        "input_schema": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string",
              "description": "The filename to write text to"
            },
            "lines_of_text": {
              "type": "array",
              "description": "An array of lines of text to write to the file"
            }
          },
          "required": ["filename", "lines_of_text"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Can you write a long poem and make a file called poem.txt?"
      }
    ],
    "stream": true
  }' | jq '.usage'

In questo esempio, lo streaming granulare degli strumenti consente a Claude di trasmettere in streaming le righe di una lunga poesia nella chiamata dello strumento make_file senza buffering per validare se il parametro lines_of_text è JSON valido. Questo significa che puoi vedere il parametro in streaming mentre arriva, senza dover aspettare che l'intero parametro venga bufferizzato e validato.

Con lo streaming granulare degli strumenti, i chunk di uso degli strumenti iniziano lo streaming più velocemente e sono spesso più lunghi e contengono meno interruzioni di parole. Questo è dovuto alle differenze nel comportamento di chunking.

Esempio:

Senza streaming granulare (ritardo di 15s):

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

Con streaming granulare (ritardo di 3s):

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

Poiché lo streaming granulare invia parametri senza buffering o validazione JSON, non c'è garanzia che il flusso risultante si completi in una stringa JSON valida. In particolare, se viene raggiunto il motivo di arresto max_tokens, il flusso potrebbe terminare a metà di un parametro e potrebbe essere incompleto. Generalmente dovrai scrivere un supporto specifico per gestire quando viene raggiunto max_tokens.

Gestione di JSON non valido nelle risposte degli strumenti

Quando utilizzi lo streaming granulare degli strumenti, potresti ricevere JSON non valido o incompleto dal modello. Se hai bisogno di passare questo JSON non valido di nuovo al modello in un blocco di risposta di errore, puoi avvolgerlo in un oggetto JSON per garantire una gestione corretta (con una chiave ragionevole). Per esempio:

{
  "INVALID_JSON": "<la tua stringa json non valida>"
}

Questo approccio aiuta il modello a capire che il contenuto è JSON non valido preservando i dati malformati originali per scopi di debug.

Quando avvolgi JSON non valido, assicurati di fare l'escape corretto di qualsiasi virgoletta o carattere speciale nella stringa JSON non valida per mantenere una struttura JSON valida nell'oggetto wrapper.

Come utilizzare lo streaming granulare degli strumenti

Per utilizzare questa funzionalità beta, aggiungi semplicemente l'header beta fine-grained-tool-streaming-2025-05-14 a una richiesta di uso degli strumenti e attiva lo streaming.

Ecco un esempio di come utilizzare lo streaming granulare degli strumenti con l'API:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: fine-grained-tool-streaming-2025-05-14" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 65536,
    "tools": [
      {
        "name": "make_file",
        "description": "Write text to a file",
        "input_schema": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string",
              "description": "The filename to write text to"
            },
            "lines_of_text": {
              "type": "array",
              "description": "An array of lines of text to write to the file"
            }
          },
          "required": ["filename", "lines_of_text"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Can you write a long poem and make a file called poem.txt?"
      }
    ],
    "stream": true
  }' | jq '.usage'

Esempio:

Senza streaming granulare (ritardo di 15s):

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

Con streaming granulare (ritardo di 3s):

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

Gestione di JSON non valido nelle risposte degli strumenti

{
  "INVALID_JSON": "<la tua stringa json non valida>"
}

Questo approccio aiuta il modello a capire che il contenuto è JSON non valido preservando i dati malformati originali per scopi di debug.