Skip to content

README.md

Latest commit

 

History

History
260 lines (178 loc) · 28.4 KB

README.md

File metadata and controls

260 lines (178 loc) · 28.4 KB
Raw

🌐 English · All languages

Реальний рендер: системний промпт + документація інструментів, упаковані в одну щільну сторінку 1568×728

🖼️ OmniGlyph — Контекст як зображення

Скороти свій рахунок за Claude на 59–70%, рендерячи громіздкий контекст як щільні PNG-сторінки — той самий вміст, але за частку токенів.

Моделі тарифікують текст за токенами, але тарифікують зображення за його розмірами — незалежно від того, скільки тексту в ньому міститься.


59–70% Bill Cut 10x Fewer Tokens 100% Read Accuracy Zero Confabulations

CI npm version License: MIT Node ≥18

Частина родини OmniRoute · 🌐 Усі мови

📊 The numbers — measured, not estimated

метрика результат підтвердження
Скорочення рахунку наскрізно 59–70% продакшн-трейс, 13 709 запитів
Токенів на конвертований блок у 10× менше (28 080 символів: 14 040 → 1 460 токенів) billing sweep
Точність формули тарифікації нульовий залишок у 22 пробах count_tokens, 2 моделі × 2 тарифи benchmarks/billing-sweep/results/
Точність точного читання, продакшн-конфігурація 30/30 (100%) на Claude Fable 5 density frontier
Мовчазні конфабуляції у ~300 пробах читання 0 — кожен промах абстинується як ILEGIVEL benchmarks/density-frontier/results/

Оцінна карта моделей (чи може вона читати щільні рендери? n=30 на плече, детермінований підрахунок):

модель читання вердикт
Claude Fable 5 100% точно ✅ продакшн-ціль
Claude Opus 4.8 77–87% за розміру гліфа ×4 ⚠️ безпечний режим за бажанням (економія падає до ~2×)
GPT-5.5 0/60 — і роздуває свої відповіді ~у 40× під час спроб ❌ заблоковано гейтом, з доказами
Gemini 2.5-flash 0/26 — і конфабулює замість того, щоб утриматися ❌ заблоковано (частковий тест, обмеження квоти)

Перевага сьогодні специфічна для Fable — інші енкодери зору поки не розпізнають щільні гліфи. Тестовий стенд бенчмарків переперевіряє будь-яку нову модель однією командою.

🤔 Чому OmniGlyph?

Кожна довготривала сесія агента тягне однаковий мертвий вантаж у кожному запиті: системний промпт, документацію інструментів і стару історію — які перетарифіковуються за токен, на кожному ходу. OmniGlyph — це локальний проксі, який переписує ці громіздкі частини у щільні PNG-сторінки ще до того, як вони покинуть вашу машину:

  • Точна математика тарифікації, а не евристика — обчислює реальну формулу токенів зображення провайдера (виміряну до нульового залишку) і конвертує лише тоді, коли математика на її боці.
  • Fail-closed за задумом — моделі, які не можуть читати щільні рендери, блокуються гейтом, з підтвердженнями бенчмарків. Жодної тихої втрати якості.
  • Приватність і локальність насамперед — переписування відбувається на 127.0.0.1; нічого зайвого нікуди не надсилається.
  • Відтворюваність — кожна цифра вище має підтвердження в benchmarks/*/results/, яке можна перезапустити однією командою.

⚡ Швидкий старт

npx omniglyph                                     # проксі на 127.0.0.1:47821
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude  # направте Claude Code на нього

Швидкий старт: запуск проксі, перевірка дашборду, направлення Claude Code на нього

Працює в обох випадках:

  • API-ключ (оплата за токен): ваш рахунок падає на 59–70% наскрізно.
  • Сесія за підпискою: ви не платите менше, але ліміти використання рахуються в токенах — тож ваші ліміти розтягуються приблизно у 2–3×.

Дашборд за адресою http://127.0.0.1:47821/: заощаджені токени, кожна конвертація тексту в зображення поруч, вимикач, живі чіпи моделей. Відповіді стрімляться як зазвичай — стискається лише запит, ніколи вивід моделі.

🔌 Використання з клієнтами Claude

Start the proxy in one terminal, then point the client at it.

Claude Code CLI (macOS/Linux):

npx omniglyph
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude

Claude Code CLI (Windows PowerShell):

npx omniglyph
$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:47821"
claude

Claude Desktop uses the same ANTHROPIC_BASE_URL environment variable for its bundled Claude Code runtime — start omniglyph first, then launch Claude Desktop from an environment where ANTHROPIC_BASE_URL is set to http://127.0.0.1:47821.

🖥️ Дашборд

Повноцінний локальний дашборд постачається всередині пакета — офлайн, один файл, жодних зовнішніх запитів. Шість сторінок, які оновлюються наживо через SSE у міру проходження запитів:

Огляд: KPI-картки центру керування, спарклайн заощаджень і потік подій наживо

  • Огляд — центр керування: % заощадження, заощаджені $, затримка p95, влучання кешу, помилки, потік подій наживо.
  • Live Flow — конвеєр у вигляді графа вузлів: клієнт → гейт → рендерер / passthrough → API, з часткою на кожен реальний запит.
  • Телеметрія — одометр токенів/$ і жива часова шкала запитів; клацніть на будь-якому запиті, щоб побачити, які саме частини стали зображеннями, і прочитати вихідний текст за кожною сторінкою.
  • Бенчмарки — підтвердження харнесу, відрендерені з benchmarks/*/results/, по одному рядку на експеримент модель·конфігурація, і запуск бенчмарків прямо з UI: dry-run за $0 стрімлять свій вивід наживо; живі запуски залишаються за гейтом, що вимагає вашого API-ключа та явного підтвердження вартості.
  • Sessions / History — топ сесій за заощадженими токенами та кожна подія на диску.
Live Flow Бенчмарки
Конвеєр запиту у вигляді живого графа вузлів Підтвердження бенчмарків та dry-run прямо в UI

Телеметрія: одометр і жива часова шкала запитів

⚙️ Як це працює

громіздкий блок запиту ──► гейт прибутковості ──► reflow + рендер (1-бітний атлас 5×8)
                          (точна математика тарифікації) ──► PNG-сторінки 1568×728 ──► зшивання назад, зручне для кешу
  • Тарифікація обчислюється точно, до конвертації: Anthropic тарифікує ⌈w/28⌉ × ⌈h/28⌉ + 4 токени на зображення (патчі 28 px — виміряно до нульового залишку). Повна сторінка несе 28 080 символів за 1 460 токенів ≈ 19 символів/токен, проти ~2 символів/токен для щільного тексту. Гейт конвертує лише тоді, коли математика на його боці.
  • Що конвертується: статичний системний промпт + документація інструментів, стара згорнута історія, великі виводи інструментів.
  • Що ніколи не конвертується: ваші повідомлення, останні ходи, вивід моделі, розріджена проза, побайтово точні значення (хеші/ID їдуть поруч як текст), і будь-яка модель, яка провалила бенчмарк читання.

📚 Використання як бібліотеки (без проксі)

Усе, що проксі робить із кожним запитом, доступне також як документований, імпортований API:

import { renderTextToImages, transformAnthropicMessages } from "omniglyph";

// Відрендерити будь-який текст у щільні 1-бітні PNG-сторінки
const { pages } = await renderTextToImages(bigToolOutput, { reflow: true });
// pages[i].png: Uint8Array · pages[i].width × pages[i].height

// Або самостійно запустити повну трансформацію запиту — гейт, математику тарифікації і все інше
const { body, applied, reason } = await transformAnthropicMessages({
  body: requestBytes,           // сире JSON-тіло /v1/messages
  model: "claude-fable-5",
});

options.keepSharp(block) закріплює блоки як текст; options.emitRecoverable повертає оригінали блоків, перетворених у зображення. Точна математика тарифікації постачається і в корені пакета (anthropicImageTokens, resolveAnthropicVisionTier, openAIVisionTokens) — саме це використовує OmniRoute. Чисте середовище виконання на JS (Node і edge/Workers). Повний перелік експортів: src/core/index.ts.

📤 Офлайн-експорт — без проксі, без Claude Code

Не на Claude Code? Відрендеріть контекст у PNG-сторінки локально і вставте їх у Cursor, ChatGPT чи будь-який чат, що приймає завантаження зображень. Без проксі, без API-ключа, без налаштованого акаунта:

npx omniglyph export --include "*.ts" src/   # render a folder to image pages
cat big.log | npx omniglyph export --stdin   # …or pipe any text through

Ви отримуєте одну теку з усім необхідним, щоб перетягнути в чат:

OmniGlyph-export-<hash>/
  page-001.png …   the rendered image pages — attach these
  factsheet.txt    verbatim precision tokens (paths, SHAs, ids, numbers)
  prompt.txt       a paste-ready instruction that points the model at the pages
  manifest.json    metadata + the text-vs-image token report (% saved)

--git рендерить ваш незакомічений diff, --diff <ref> — діапазон комітів, --open відкриває теку (macOS). Усе виконується на вашій машині — шлях експорту ніколи не запускає проксі й ніколи не звертається до моделі. Запустіть omniglyph export --help, щоб побачити кожен прапорець.

🧭 The honest part

  • Це втратно. Побайтово точне відтворення із зображень за природою ненадійне. Вжиті пом'якшення: точні ідентифікатори подорожують як текст поруч із зображенням, а виміряна продакшн-конфігурація дала нуль мовчазних конфабуляцій — невдалі читання утримуються від відповіді.
  • Сьогодні схвалено лише Fable 5, з підтвердженнями. GPT-5.5 і Gemini 2.5-flash вимірювано не можуть читати щільні рендери; Opus 4.8 потребує гліфів у 4× більших. Гейт це забезпечує.
  • Ми знайшли й уникнули пастку тарифікації: тариф зображення високої роздільності тарифікує в 3,3× дорожче за сторінку, але енкодер зору не отримує додаткової роздільності — більші сторінки читаються гірше. Виміряно, задокументовано в docs/benchmarks/BENCHMARKS.md, не увімкнено.
  • Ціни змінюються; стійка метрика — це скорочення токенів, яке проксі логує на кожен запит проти безкоштовного контрфактичного count_tokens.

🧠 Часті запитання

Я ввімкнув його посеред сесії, і витрати злетіли — чому? Сесія, що працювала без OmniGlyph, має весь префікс закешований Anthropic як текст за ставкою читання 0,1×; перший запит із зображеннями заново сплатив би все це як свіжий запис кешу за 1,25× в одному промпті. Проксі захищає від цього: сесія, яку воно ніколи не переводило в зображення, додає цю разову вартість до гейта окупності й перемикається на зображення, лише якщо це досі вигідно — інакше сесія лишається текстом, а економія починається з наступної нової сесії.

Це 59–70% наскрізно, чи лише на запитах, яких воно торкнулося? Наскрізно — це весь рахунок цілком. Більшість інструментів стиснення звітують про економію лише на тій частці, яку вони обробили, що прикрашає цифру. Наш знаменник — кожен запит: дрібні, які гейт коректно залишив недоторканими, усі записи й читання кешу, а також усі вихідні токени (які проксі ніколи не стискає). Економія «лише по стиснутому» виходить вищою і наводиться окремо, але ніколи як заголовна цифра.

Як вимірюється економія? Обидві сторони одного й того самого запиту, в один і той самий момент. На кожен POST /v1/messages проксі паралельно з реальною пересилкою запускає безкоштовний пробний запит count_tokens на вихідному нестиснутому тілі (контрфактичний варіант) і зчитує з відповіді блок використання, реально виставлений провайдером до оплати, — обидва значення потрапляють у той самий рядок події. Тарифікація кешу застосовується однаково до обох сторін, тож знижка за кеш взаємно скорочується і не може бути врахована двічі як «економія». Формула міститься в src/core/baseline.ts; виведіть її заново з власного журналу подій.

Чому промах — це конфабуляція, а не помилка читання? Тому що зір моделі — це не OCR: сторінка перетворюється на патч-ембединги, а не на дискретні символи, тож немає посимвольної впевненості, на якій можна явно провалитися — коли пікселі не повністю визначають гліф, мовний пріор заповнює прогалину чимось правдоподібним. Саме цей механізм — причина, чому OmniGlyph fail-closed у цьому питанні: побайтово точні значення завжди їдуть як текст поруч із зображенням, моделі, які помиляються під час читання, блокуються гейтом, а виміряна продакшн-конфігурація не дала жодної мовчазної конфабуляції на ~300 пробах читання — невдалі читання утримуються від відповіді.

А як щодо побайтово точної роботи (хеші, ID, секрети)? Останні ходи і точні ідентифікатори за задумом залишаються текстом. Для навантажень, які повністю побайтово точні, спрямовуйте їх на модель поза allowlist (наприклад, сабагент на іншій моделі Claude) — усе, що поза allowlist, проходить наскрізь побайтово незмінним.

Хіба DeepSeek-OCR не закрив питання, чи це працює? Він довів, що канал працює — з парою енкодер/декодер, навченою саме для цього завдання. Скептицизм родом із часів, коли жодна серійна продакшн-модель не вміла читати щільні рендери; це змінилося, і наведена вище оцінна карта моделей показує, хто саме читає їх сьогодні, з підтвердженнями. Тестовий стенд бенчмарків переперевіряє будь-яку нову модель однією командою — гейт слідує за даними, а не за хайпом.

Чи можна користуватися ним без Claude Code — Cursor, ChatGPT, звичайний пайп? Так, двома способами. Як проксі він працює з будь-яким клієнтом, що дозволяє задати базову URL-адресу API (ANTHROPIC_BASE_URL або базову URL OpenAI) — Claude Code, ваші власні скрипти, будь-що по HTTP. А для інструментів, які не вміють проксіювати, Офлайн-експорт вище рендерить контекст у PNG-сторінки, які ви вставляєте вручну — omniglyph export --stdin навіть читає прямо з Unix-пайпа.

Як воно насправді перетворює текст на зображення? Воно робить reflow тексту й малює його 1-бітним атласом гліфів 5×8 пікселів на щільних PNG-сторінках 1568×728 — один біт на піксель, без згладжування, тож модель тарифікує сторінку за її розмірами, а не за кількістю символів усередині. Як це працює вище описує конвеєр; документ бенчмарків містить геометрію і пояснення, чому щільніше не завжди дешевше.

🔬 Відтвори кожну цифру

pnpm install && pnpm test                                     # повна сюїта
node benchmarks/billing-sweep/run.mjs --dry-run               # прогнози тарифікації, $0
pnpm exec tsx benchmarks/density-frontier/run.ts --dry-run    # таблиця вартості, $0
# з ключами: ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY (або --via-cli для підписки Claude Code)

Обидва тестові стенди бенчмарків, що працюють у режимі dry-run

Повна методологія і кожна таблиця результатів: docs/benchmarks/BENCHMARKS.md. Сирі підтвердження по кожній відповіді: benchmarks/*/results/*.jsonl.

🚀 Родина OmniRoute

OmniGlyph також постачається як нативний движок стиснення всередині OmniRoute — безкоштовного AI-шлюзу. Там він працює як движок omniglyph (окремий режим або в стеку з іншими движками), з fail-closed гейтами й обліком токенів з урахуванням зображень.

🛠️ Технологічний стек

шар технологія
Мова TypeScript (strict), ESM
Середовище виконання Node ≥18 · Cloudflare Workers (wrangler.toml)
Рендеринг власний 1-бітний атлас гліфів (похідний від Spleen/Unifont, ліцензії в assets/) → PNG
Тести Vitest — TDD, плюс охоронці цілісності документації та ребрендингу
Бенчмарки тестові стенди benchmarks/ (billing-sweep, density-frontier) з JSONL-підтвердженнями

Структура проєкту

шлях що
src/ проксі: конвеєр трансформації, точна тарифікація на провайдера, рендерер, хости (Node + Cloudflare Workers)
benchmarks/ тестові стенди, що дали кожну цифру вище — можна перезапустити
docs/ BENCHMARKS · ARCHITECTURE · ROADMAP

📧 Підтримка і спільнота

🙏 Подяки

OmniGlyph стоїть на плечах одного проєкту зокрема — цей розділ є нашою незмінною подякою.

Проєкт Як він вплинув на OmniGlyph
pxpipe · teamchong Відкриття, на якому побудований увесь цей проєкт. pxpipe довів, з підтвердженнями, що канал зору продакшн-LLM здатен нести щільний текстовий контекст за малу частку вартості в токенах — і що рішення про конвертацію має ухвалюватися для кожного запиту за точною математикою тарифікації, а не «на око». Щільний 1-бітний рендеринг, гейт прибутковості, контрфактичний count_tokens, fail-closed allowlist моделей і культура документування «спершу виміряй, потім заявляй» — усе це вперше з'явилося саме там. OmniGlyph походить безпосередньо від цієї кодової бази (MIT — оригінальний рядок авторських прав залишається в нашому LICENSE).
Spleen · Frederic Cambus Родина растрових шрифтів 5×8, від якої походить наш щільний 1-бітний атлас гліфів (ліцензія в assets/).
GNU Unifont · Unifoundry Покриття для гліфів поза діапазоном Spleen у тому самому атласі (ліцензія в assets/).

Якщо OmniGlyph виявився корисним — постав зірку і апстріму теж, адже відкриття належить їм. 🙏

📄 Ліцензія

MIT — див. LICENSE.