Skip to content

README.md

Latest commit

 

History

History
260 lines (178 loc) · 29 KB

README.md

File metadata and controls

260 lines (178 loc) · 29 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 · 🌐 Все языки

📊 Цифры — измерено, а не оценено

метрика результат подтверждение
Итоговое снижение счёта 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 — конвейер в виде графа узлов: клиент → гейт → рендерер / сквозной проход → API, с частицей на каждый реальный запрос.
  • Телеметрия — одометр токенов/$ и живая временная шкала запросов; клик по любому запросу показывает, какие именно части стали изображениями, и позволяет прочитать исходный текст за каждой страницей.
  • Бенчмарки — подтверждающие данные харнесса, отрисованные из benchmarks/*/results/, по одной строке на эксперимент модель·конфигурация, и запуск бенчмарков прямо из UI: $0 dry-run стримит вывод вживую; живые прогоны остаются под гейтом, требующим вашего 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 <ref> — диапазон коммитов, --open открывает папку (macOS). Всё работает на вашей машине — путь экспорта никогда не запускает прокси и никогда не обращается к модели. Запустите omniglyph export --help, чтобы увидеть все флаги.

🧭 Честная часть

  • Это lossy-подход. Побайтово точное восстановление из изображений по природе ненадёжно. Реализованные меры смягчения: точные идентификаторы едут как текст рядом с изображением, а измеренная продакшн-конфигурация дала ноль незаметных конфабуляций — неудачные чтения абстинируются.
  • Сегодня одобрена только 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, плюс гварды docs-integrity и rebrand
Бенчмарки наборы 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.