Przykłady formatu TOON — Wzorce danych ze świata rzeczywistego

Dokumentacja formatów uwielbia przykłady zabawkowe — trzy wiersze, wymyślone nazwy, pięć kolumn. To dobrze do nauki składni, ale nie mówi Ci, czy format obsługuje kształty, z którymi faktycznie masz do czynienia w pracy. Ten artykuł pomija zabawki. Poniżej są wzorce danych, które pojawiają się ciągle w prawdziwym tworzeniu backendu — katalogi produktów, logi audytu, tabele metryk, obiekty konfiguracji, transakcje finansowe — pokazane zarówno w JSON, jak i TOON obok siebie, abyś mógł dokładnie zobaczyć, co oszczędzasz i gdzie TOON zarabia na swoje miejsce. Wszystkie dane są realistyczne; bez foo, bar ani nazw zastępczych. Dla informacji o samym formacie, sprawdź przewodnik po składni TOON.

Katalog produktów e-commerce

Tablica produktów jest prawdopodobnie najczęściej wysyłaną rzeczą przez programistów do LLM — "sklasyfikuj te elementy", "znajdź najtańszy w każdej kategorii", "oznacz wszystko, co nie jest na stanie z ceną powyżej 50 dolarów". Oto realistyczny wycinek katalogu w JSON jako pierwszy:

[
  {"id":"PRD-1041","name":"Logitech MX Master 3S","sku":"LOG-MX3S-GRY","price":99.99,"inStock":true,"category":"Peripherals"},
  {"id":"PRD-1042","name":"Samsung 970 EVO Plus 1TB","sku":"SAM-970P-1TB","price":89.99,"inStock":true,"category":"Storage"},
  {"id":"PRD-1043","name":"Keychron K2 Pro","sku":"KEY-K2P-BLK","price":119.99,"inStock":false,"category":"Peripherals"},
  {"id":"PRD-1044","name":"Elgato Stream Deck MK.2","sku":"ELG-SD-MK2","price":149.99,"inStock":true,"category":"Streaming"},
  {"id":"PRD-1045","name":"WD Blue 2TB HDD","sku":"WD-BLU-2TB","price":54.99,"inStock":true,"category":"Storage"},
  {"id":"PRD-1046","name":"Razer DeathAdder V3","sku":"RZR-DAV3-BLK","price":69.99,"inStock":true,"category":"Peripherals"},
  {"id":"PRD-1047","name":"Focusrite Scarlett Solo","sku":"FOC-SC-SOLO","price":119.99,"inStock":false,"category":"Audio"}
]

Teraz ten sam katalog w TOON. Nagłówki kolumn są deklarowane raz; każdy wiersz to tylko wartości:

products[7]{id,name,sku,price,inStock,category}:
  PRD-1041,Logitech MX Master 3S,LOG-MX3S-GRY,99.99,true,Peripherals
  PRD-1042,Samsung 970 EVO Plus 1TB,SAM-970P-1TB,89.99,true,Storage
  PRD-1043,Keychron K2 Pro,KEY-K2P-BLK,119.99,false,Peripherals
  PRD-1044,Elgato Stream Deck MK.2,ELG-SD-MK2,149.99,true,Streaming
  PRD-1045,WD Blue 2TB HDD,WD-BLU-2TB,54.99,true,Storage
  PRD-1046,Razer DeathAdder V3,RZR-DAV3-BLK,69.99,true,Peripherals
  PRD-1047,Focusrite Scarlett Solo,FOC-SC-SOLO,119.99,false,Audio

Aktywność użytkownika / Log audytu

Logi audytu to dokładnie ten rodzaj danych, który podajesz do LLM z promptem jak "podsumuj co ten użytkownik robił w ostatniej godzinie" lub "oznacz podejrzane wzorce dostępu". Są one o wysokim wolumenie, powtarzalne, a nazwy kolumn są identyczne w każdym wierszu. Ścieżki audytu są również zwykle pierwszą rzeczą, która wysadza Twoje okno kontekstowe, gdy wklejasz je jako JSON. Oto realistyczny log 9 wierszy w TOON:

auditLog[9]{userId,action,resourceId,resourceType,timestamp,ip}:
  U-8821,LOGIN,,session,2024-11-14T08:02:11Z,203.0.113.47
  U-8821,VIEW,DOC-4490,document,2024-11-14T08:03:44Z,203.0.113.47
  U-8821,DOWNLOAD,DOC-4490,document,2024-11-14T08:03:51Z,203.0.113.47
  U-8821,VIEW,DOC-4491,document,2024-11-14T08:05:02Z,203.0.113.47
  U-8821,EDIT,DOC-4491,document,2024-11-14T08:07:39Z,203.0.113.47
  U-8821,SHARE,DOC-4491,document,2024-11-14T08:08:12Z,203.0.113.47
  U-8821,VIEW,USR-0055,user_profile,2024-11-14T08:09:58Z,203.0.113.47
  U-8821,VIEW,USR-0056,user_profile,2024-11-14T08:10:03Z,203.0.113.47
  U-8821,LOGOUT,,session,2024-11-14T08:11:22Z,203.0.113.47

Odpowiednik JSON powtarzałby "userId", "action", "resourceId", "resourceType", "timestamp", i "ip" we wszystkich dziewięciu wierszach — 54 powtórzenia kluczy dla sześciu nazw pól. W TOON pojawiają się dokładnie raz. Dla logów audytu z setkami wpisów to różnica między zmieszczeniem danych w Twoim prompcie a nie.

Dane API Rate Limit / Metryki

Metryki operacyjne — percentyle opóźnień, wskaźniki błędów, przepustowość — to kolejne naturalne dopasowanie dla TOON. Dane są ciężkie numerycznie i idealnie tabelaryczne. Możesz wysłać to do LLM z pytaniem "które endpointy mają opóźnienie p99 powyżej 500ms?" lub "gdzie wskaźnik błędów rośnie?" To kształt danych, który zwykle wychodzi z Node.js pipeline metryk lub scrape Prometheusa:

apiMetrics[8]{endpoint,method,p50ms,p99ms,errorRate,callsPerDay}:
  /api/v2/products,GET,42,118,0.002,84200
  /api/v2/products/:id,GET,38,95,0.001,31500
  /api/v2/orders,POST,210,880,0.015,4800
  /api/v2/orders/:id,GET,55,201,0.003,19200
  /api/v2/cart,PUT,95,430,0.008,22100
  /api/v2/search,GET,310,1240,0.021,61000
  /api/v2/users/:id,GET,29,88,0.001,9700
  /api/v2/checkout,POST,540,2100,0.034,3200

LLM może natychmiast odpowiedzieć na pytania o tę tabelę bez żadnego narzutu kontekstowego. Zauważ, że /api/v2/search i /api/v2/checkout wyróżniają się wysokim p99 i podwyższonymi wskaźnikami błędów — dokładnie ten rodzaj wzorca, który LLM może natychmiast wskazać, gdy prezentujesz dane w przejrzysty sposób.

Zagnieżdżony obiekt konfiguracyjny

TOON obsługuje więcej niż dane tabelaryczne. Dla obiektów strukturalnych — tego rodzaju rzeczy, które znajdziesz w konfiguracji runtime aplikacji — TOON używa notacji obiektowej inline z zagnieżdżoną strukturą. Pomyśl o tym jako odpowiedniku formatów serializacji takich jak TOML lub YAML, ale lżejszy. Oto realistyczna konfiguracja aplikacji pokazująca ustawienia serwera, bazy danych i flagi funkcji:

{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "tlsEnabled": true,
    "requestTimeoutMs": 30000
  },
  "database": {
    "host": "db.internal.example.com",
    "port": 5432,
    "name": "commerce_prod",
    "poolSize": 20,
    "sslRequired": true
  },
  "features": {
    "newCheckoutFlow": true,
    "recommendationEngine": false,
    "darkMode": true,
    "betaDashboard": false
  }
}

Ta sama konfiguracja w notacji obiektowej TOON — klucze są bez cudzysłowów, zagnieżdżanie używa nawiasów klamrowych inline:

{
  server:{host:0.0.0.0,port:8080,tlsEnabled:true,requestTimeoutMs:30000},
  database:{host:db.internal.example.com,port:5432,name:commerce_prod,poolSize:20,sslRequired:true},
  features:{newCheckoutFlow:true,recommendationEngine:false,darkMode:true,betaDashboard:false}
}

Transakcje finansowe

Dane finansowe to kolejny przypadek użycia LLM o wysokiej wartości: wskazówki dotyczące wykrywania oszustw, sprawdzanie uzgodnień, kategoryzacja. Mieszanina identyfikatorów ciągów, kwot numerycznych, kodów walut, enumów statusów i znaczników czasu dobrze mapuje się na format tabelaryczny TOON. Oto realistyczny wycinek transakcji:

transactions[9]{txId,amount,currency,from,to,status,timestamp}:
  TXN-88201,1250.00,GBP,ACC-1041,ACC-2209,settled,2024-11-14T09:15:00Z
  TXN-88202,89.99,USD,ACC-3301,ACC-0047,settled,2024-11-14T09:16:34Z
  TXN-88203,4500.00,EUR,ACC-2001,ACC-5512,pending,2024-11-14T09:18:02Z
  TXN-88204,22.50,USD,ACC-0099,ACC-3301,settled,2024-11-14T09:21:47Z
  TXN-88205,750.00,GBP,ACC-5512,ACC-1041,failed,2024-11-14T09:25:10Z
  TXN-88206,12000.00,USD,ACC-7700,ACC-2001,pending,2024-11-14T09:28:55Z
  TXN-88207,310.00,EUR,ACC-1041,ACC-0099,settled,2024-11-14T09:31:22Z
  TXN-88208,55.00,USD,ACC-3301,ACC-7700,settled,2024-11-14T09:33:40Z
  TXN-88209,8900.00,GBP,ACC-2209,ACC-5512,flagged,2024-11-14T09:37:15Z

Wklej to do promptu obok "oznacz transakcje powyżej £5 000 lub ze statusem flagged lub failed" a model odpowie w kilka sekund. Reprezentacja TOON jest wystarczająco kompaktowa, że bez trudu zmieściłbyś kilkaset wierszy w jednym prompcie nie przekraczając limitów kontekstu na większości modeli.

Łączenie danych tabelarycznych i obiektowych w jednym dokumencie

Oto coś, czego ani JSON, ani CSV nie obsługuje czysto: dokument mający zarówno nagłówek metadanych (pojedynczy obiekt konfiguracyjny) jak i tabelę danych w tym samym payloadzie. Pomyśl o raporcie z blokiem kontekstu na górze — kto go wygenerował, jaki okres obejmuje, jakie filtry zostały zastosowane — a następnie rzeczywiste wiersze danych. W JSON musiałbyś owinąć wszystko w obiekt koperty z kluczem "meta" i kluczem "rows", co dodaje kolejną warstwę zagnieżdżania. CSV w ogóle tego nie potrafi. TOON obsługuje to natywnie:

{report:weekly_sales,generatedAt:2024-11-14T10:00:00Z,region:EMEA,currency:EUR,generatedBy:analytics-service}

salesByRep[6]{repId,repName,deals,revenue,avgDealSize,quota}:
  REP-101,Marta Kowalski,14,84200.00,6014.28,75000
  REP-102,James Okafor,11,61500.00,5590.90,75000
  REP-103,Yuki Tanaka,18,102400.00,5688.88,90000
  REP-104,Sofia Andersen,9,47800.00,5311.11,75000
  REP-105,Liam Byrne,16,93100.00,5818.75,90000
  REP-106,Priya Nair,21,118600.00,5647.61,100000

Pierwsza linia to obiekt TOON — metadane raportu. Pusta linia oddziela go od sekcji tabelarycznej, która następuje. Pojedyncze wywołanie decode() z @toon-format/toon zwraca oba. Możesz wysłać cały ten dokument do LLM z pytaniem takim jak "którzy przedstawiciele są na dobrej drodze do osiągnięcia kwoty?" i ma wszystko czego potrzebuje: kontekst raportu i dane, w jednym kompaktowym payloadzie.

Używanie pakietu npm

Wszystkie te przykłady można kodować i dekodować programatycznie. @toon-format/toon to implementacja referencyjna. Zainstaluj ją w dowolnym projekcie Node.js lub przeglądarki:

npm install @toon-format/toon

Następnie zakoduj swoje dane przed wysłaniem ich do dowolnego API LLM i dekoduj odpowiedź na wyjściu:

import { encode, decode } from '@toon-format/toon';

const transactions = [
  { txId: 'TXN-88201', amount: 1250.00, currency: 'GBP', from: 'ACC-1041', to: 'ACC-2209', status: 'settled', timestamp: '2024-11-14T09:15:00Z' },
  { txId: 'TXN-88202', amount: 89.99,   currency: 'USD', from: 'ACC-3301', to: 'ACC-0047', status: 'settled', timestamp: '2024-11-14T09:16:34Z' },
  // ...more rows
];

// Compact TOON string — send this to your LLM prompt
const toonPayload = encode(transactions);

// When the LLM returns TOON, decode back to a JS array
const decoded = decode(toonPayload);
console.log(decoded[0].status); // "settled"

Podsumowanie

Wzorce powyżej — katalogi produktów, logi audytu, tabele metryk, obiekty konfiguracji, dane finansowe, mieszane dokumenty nagłówek+tabela — obejmują ogromną większość danych strukturalnych które programiści faktycznie wysyłają do LLM. TOON dobrze obsługuje je wszystkie, a oszczędności tokenów są znaczące w każdym przypadku. Podstawowa zasada jest prosta: JSON powtarza nazwy kluczy w każdym wierszu; TOON nie. Dla serializacji danych tabelarycznych trafiającej do okna kontekstowego LLM, to powtórzenie to czyste marnotrawstwo.

Aby przekonwertować istniejący JSON do TOON, użyj konwertera JSON do TOON. Aby przejść w drugą stronę po zwróceniu TOON przez LLM, użyj konwertera TOON do JSON. Formatter TOON czyści i waliduje ciągi TOON, a Walidator TOON wykryje błędy składniowe przed dotarciem do Twojego pipeline'u. Pakiet npm @toon-format/toon obsługuje kodowanie i dekodowanie w dwóch liniach kodu — wszystkie powyższe przykłady działają od razu.