Se hai lavorato con Large Language Models (LLM), sai che JSON è la lingua franca dello scambio di dati. Tuttavia, sai anche che JSON è notoriamente "loquace". Tutte quelle parentesi graffe, virgolette e chiavi ripetute consumano la finestra di contesto, aumentano la latenza e fanno lievitare i costi dell'API.

È qui che TOON (The Object-Oriented Notation) brilla. Sebbene la libreria TypeScript sia ottima per il codice dell'applicazione, a volte è sufficiente eseguire rapidamente le operazioni nel terminale. Che tu stia eseguendo il debug di un prompt, preparando un set di dati o semplicemente curioso di sapere quanti soldi potresti risparmiare sui token, la CLI @toon-format/toon è il tuo nuovo migliore amico.

In questa guida esamineremo come sfruttare l'interfaccia della riga di comando TOON per integrare l'ottimizzazione dei dati direttamente nei flussi di lavoro della shell.

Preparazione

Uno degli aspetti migliori dei moderni strumenti JavaScript è che spesso non è necessario "installare" nulla per iniziare. Se vuoi solo provare TOON su un singolo file, puoi usare npx per eseguire direttamente il binario:

"bash." npx @toon-format/cli input.json -o output.toon

Tuttavia, se prevedi di utilizzarlo frequentemente (e una volta che vedrai i risparmi sui token, probabilmente lo farai), un'installazione globale è la strada da percorrere. Ti dà accesso al comando conciso "toon" ovunque nel tuo sistema.

"bash." npm install -g @toon-format/cli #o pnpm aggiungi -g @toon-format/cli

Una volta installato, sei pronto per iniziare a ridurre i tuoi dati.

La magia del rilevamento automatico

La CLI TOON è progettata per essere intelligente riguardo a ciò che stai cercando di fare. Raramente è necessario dirgli esplicitamente di codificare o decodificare; esamina le estensioni dei file per decidere.

Se gli dai un file .json, presuppone che tu voglia codificarlo in TOON. Se fornisci un file .toon, passa alla modalità di decodifica per restituirti JSON.

"bash."

Codifica automaticamente in TOON

toon data.json -o compresso.toon

Decodifica automaticamente in JSON

toon compresso.toon -o restaurato.json

Ma dove la CLI dimostra davvero il suo valore è nella "filosofia Unix": piccoli strumenti collegati in modo lasco. Poiché la CLI TOON legge dall'input standard (stdin) e scrive sull'output standard (stdout), puoi reindirizzare i dati direttamente attraverso di essa.

"bash."

Collega JSON direttamente a TOON

cat large-dataset.json | toon > dati.toon

Visualizza un oggetto veloce per vedere come appare in TOON

echo '{"nome": "Ada", "ruolo": "admin"}' | cartone animato

Quando si inviano dati tramite stdin, la CLI utilizza per impostazione predefinita la modalità encode. Se devi decodificare un flusso di dati TOON proveniente da un altro processo, aggiungi semplicemente il flag --decode (o -d).

Analisi del risparmio dei token

L'ottimizzazione dei formati dei dati spesso implica indovinelli. "Se rimuovo gli spazi bianchi, quanto risparmio?" "E se passassi a YAML?"

La CLI TOON elimina le congetture con il flag --stats. Durante la codifica, questa opzione calcola il conteggio stimato dei token e mostra immediatamente il risparmio. Ciò ha un valore inestimabile quando si pianifica il budget per chiamate LLM ad alto volume.

"bash." toon context.json --stats

Potresti vedere un output che indica una riduzione delle dimensioni del 30% o 40%. Non si tratta solo di spazio su disco; ovvero una latenza inferiore del 40% e un costo inferiore del 40% sui token di input.

Ottimizzazione avanzata: delimitatori e formattazione

Per impostazione predefinita, TOON utilizza le virgole per separare gli elementi dell'array, in modo simile a JSON. Tuttavia, diversi tokenizzatori LLM si comportano diversamente con la punteggiatura. A volte, un carattere di tabulazione o una barra verticale (|) è più efficiente in termini di token rispetto a una virgola.

La CLI ti consente di scambiare i delimitatori al volo. Se hai a che fare con dati tabulari, il passaggio a un delimitatore di tabulazione può rendere l'output più pulito e l'elaborazione più efficiente.

Per un elenco di prodotti, questo trasforma l'output da un elenco separato da virgole in una struttura pulita, separata da tabulazioni, che assomiglia quasi a un foglio di calcolo, che molti modelli analizzano eccezionalmente bene.

"bash."

Usa le tabulazioni per gli elementi dell'array

toon elementi.json --delimiter "\t" -o elementi.toon

::: suggerimento Suggerimento professionale: I delimitatori di tabulazione spesso riducono la necessità di virgolette di escape e possono comportare una migliore tokenizzazione per i dati numerici. Se stai elaborando set di dati di grandi dimensioni, prova --delimiter "\t" per sfruttare al massimo l'efficienza. :::

Struttura comprimibile con chiusura a chiave

Una delle funzionalità più recenti (introdotte nella specifica v1.5) disponibili nella CLI è Key Folding. I dati JSON sono spesso profondamente annidati, con chiavi wrapper come "data.response.items" che aggiungono profondità strutturale senza aggiungere significato.

La CLI consente di "ripiegare" queste chiavi nidificate in un unico percorso con notazione punti, appiattindo la gerarchia e salvando i token su rientro e parentesi graffe.

"bash." toon deep-structure.json --key-folding safe -o flat.toon

Questo trasforma gli oggetti nidificati:

{ "utente": { "profilo": { "id": 1 } } } 

In una rappresentazione TOON concisa:

utente.profilo.id: 1 

Se in seguito è necessario riconvertirlo in JSON completo, è possibile utilizzare il flag --expand-paths safe durante la decodifica per ricostruire perfettamente la struttura profonda dell'oggetto.

integrazione nelle pipeline

Il vero potere della CLI TOON arriva quando lo connetti con altri strumenti come "curl" e "jq". Puoi recuperare i dati da un'API, filtrarli fino all'essenziale e convertirli in TOON in un'unica riga, pronti per essere incollati in un prompt o inviati a un endpoint di inferenza.

In questo flusso di lavoro, recuperi i dati, estrai solo gli utenti attivi, li converti in un formato TOON delimitato da pipe e ottieni un rapporto statistico su quanti token hai appena salvato.

"bash." curl -s https://api.example.com/users \ | jq '.data.active_users' \ | toon --stats --delimiter "|"

Riepilogo

@toon-format/cli è più di un semplice convertitore di file; è una cintura di utilità per l'era LLM. Spostando l'elaborazione dei dati sulla riga di comando, puoi eseguire iterazioni più velocemente, visualizzare immediatamente le ottimizzazioni e integrare formati efficienti in termini di token nei flussi di lavoro di progettazione esistenti.

Che tu stia preparando documenti RAG (Retrieval-Augmented Generation) o semplicemente cercando di inserire un enorme BLOB JSON in una piccola finestra di contesto, dai una svolta alla CLI. Il tuo budget in token ti ringrazierà.