Skip to content

README.md

Latest commit

 

History

History
260 lines (178 loc) · 23.6 KB

README.md

File metadata and controls

260 lines (178 loc) · 23.6 KB
Raw

🌐 English · All languages

A real render: system prompt + tool docs packed into one dense 1568×728 page

🖼️ OmniGlyph — コンテキストを画像として扱う

バルクなコンテキストを高密度PNGページとしてレンダリングすることで、Claudeの請求額を**59〜70%**削減 — 中身は同じ、トークン数だけが激減。

モデルはテキストをトークン単位で課金しますが、画像は寸法だけで課金され、中に含まれるテキスト量は問われません。


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

CI npm version License: MIT Node ≥18

OmniRoute ファミリーの一部 · 🌐 All languages

📊 The numbers — measured, not estimated

指標 結果 根拠
エンドツーエンドの請求削減 59–70% 本番トレース、13,709リクエスト
変換ブロックあたりのトークン数 10分の1（28,080文字: 14,040 → 1,460トークン） billing sweep
課金式の精度 22件のcount_tokensプローブ（2モデル×2ティア）で残差ゼロ benchmarks/billing-sweep/results/
本番構成での完全読み取り精度 Claude Fable 5で30/30（100%） density frontier
約300件の読み取りプローブ中の無自覚な作話 0 — 読めない場合は必ずILEGIVELとして棄権 benchmarks/density-frontier/results/

モデル別スコアカード（高密度レンダーを読めるか？各アームn=30、決定論的スコアリング）:

モデル 読み取り 判定
Claude Fable 5 完全一致100% ✅ 本番採用
Claude Opus 4.8 グリフサイズ4倍で77–87% ⚠️ オプトインのセーフモード（節約率は~2倍に低下）
GPT-5.5 0/60 — しかも回答量が約40倍に膨張 ❌ ゲートで遮断、証拠あり
Gemini 2.5-flash 0/26 — 棄権せずに作話 ❌ 遮断（部分テスト、クォータ制限）

この優位性は現時点ではFable固有のものです — 他のビジョンエンコーダはまだ高密度グリフを解読できません。ベンチマークハーネスを使えば、新しいモデルを1コマンドで再テストできます。

🤔 なぜOmniGlyphなのか

長時間稼働するエージェントセッションは、毎リクエストで同じ死重を引きずります — system prompt、ツールのドキュメント、古い履歴がターンごとに再課金されるのです。OmniGlyphはローカルプロキシとして、それらのバルクな部分をマシンから送信される前に高密度PNGページへ書き換えます。

  • ヒューリスティックではなく厳密な課金計算 — プロバイダの実際の画像トークン式を計算し（残差ゼロまで実測済み）、その計算が有利な場合のみ変換します。
  • 設計上フェイルクローズ — 高密度レンダーを読めないモデルはゲートでブロックされ、ベンチマークの根拠が伴います。品質が黙って劣化することはありません。
  • プライベート、ローカルファースト — 書き換えは127.0.0.1上で完結し、それ以外の送信は一切ありません。
  • 再現可能 — 上記のすべての数値はbenchmarks/*/results/に根拠があり、1コマンドで再実行できます。

⚡ クイックスタート

npx omniglyph                                     # proxy on 127.0.0.1:47821
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude  # point Claude Code at it

Quickstart: start the proxy, check the dashboard, point Claude Code at it

どちらの使い方でも動作します:

  • 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.

🖥️ ダッシュボード

パッケージには完全なローカルダッシュボードが同梱されています — オフライン・単一ファイル・外部への通信は一切なし。6つのページがあり、リクエストが流れるたびにSSE経由でライブ更新されます。

Overview: ミッションコントロールのKPIカード、節約額のスパークライン、ライブイベントフィード

  • Overview — ミッションコントロール: 節約率、節約額（$）、レイテンシp95、キャッシュヒット、エラー、ライブフィード。
  • Live Flow — パイプラインをノードグラフとして表示: client → gate → renderer / passthrough → API、実際のリクエストごとに1つの粒子が流れます。
  • Telemetry — トークン/$のオドメーターとライブのリクエストタイムライン。任意のリクエストをクリックすると、どの部分が画像になったかを正確に確認でき、各ページの元となったソーステキストも読めます。
  • Benchmarks — benchmarks/*/results/からレンダリングされたハーネスの記録を、モデル・構成の実験ごとに1行ずつ表示。さらにUIから直接ベンチマークを実行できます: $0のドライランはその出力をライブでストリーミングし、実際に課金が発生するライブランはAPIキーと明示的なコスト確認の両方がなければ実行できません。
  • Sessions / History — 節約トークン数順のトップセッションと、ディスク上のすべてのイベント。
Live Flow Benchmarks
リクエストパイプラインをライブのノードグラフとして表示 ベンチマークの記録とUI内でのドライラン

Telemetry: オドメーターとライブのリクエストタイムライン

⚙️ 仕組み

bulky request block ──► profitability gate ──► reflow + render (1-bit 5×8 atlas)
                       (exact billing math)     ──► 1568×728 PNG pages ──► splice back, cache-friendly
  • 変換前に課金を厳密に計算: Anthropicは画像1枚あたり⌈w/28⌉ × ⌈h/28⌉ + 4トークンを課金します（28pxパッチ単位 — 残差ゼロまで実測済み）。1ページ分で28,080文字が1,460トークンとなり、約19文字/トークン（高密度テキストの場合の約2文字/トークンに対して）。ゲートは計算上有利な場合のみ変換します。
  • 変換されるもの: 静的なsystem prompt + ツールのドキュメント、折りたたまれた古い履歴、大きなツール出力。
  • 変換されないもの: あなたのメッセージ、直近のターン、モデルの出力、疎なプロース、バイト単位で正確な値（ハッシュ/IDはテキストとして併走）、そして読み取りベンチマークに失敗したモデル。

📚 ライブラリとして使う（プロキシなし）

プロキシがリクエストごとに行うすべての処理は、ドキュメント化されたインポート可能なAPIとしても利用できます:

import { renderTextToImages, transformAnthropicMessages } from "omniglyph";

// Render any text to dense 1-bit PNG pages
const { pages } = await renderTextToImages(bigToolOutput, { reflow: true });
// pages[i].png: Uint8Array · pages[i].width × pages[i].height

// Or run the full request transform yourself — gate, billing math and all
const { body, applied, reason } = await transformAnthropicMessages({
  body: requestBytes,           // the raw /v1/messages JSON body
  model: "claude-fable-5",
});

options.keepSharp(block)はブロックをテキストとして固定し、options.emitRecoverableは画像化されたブロックの元データを返します。厳密な課金計算式（anthropicImageTokens、resolveAnthropicVisionTier、openAIVisionTokens）もパッケージのルートから提供されており、これはOmniRouteが利用しているものです。純粋なJavaScriptランタイム（Nodeとedge/Workersの両方で動作）。全体のAPI一覧は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

チャットに投入するために必要なものが、すべて1つのフォルダにまとまります:

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で確認できます。

🧭 The honest part

  • これは非可逆です。 画像からのバイト単位の正確な復元は本質的に信頼できません。実施済みの緩和策: 正確な識別子は画像の隣にテキストとして流れ、実測された本番構成では無自覚な作話ゼロを達成しています — 読み取り失敗は棄権します。
  • 現時点で承認されているのはFable 5のみで、根拠付きです。GPT-5.5とGemini 2.5-flashは高密度レンダーを実測上読めません。Opus 4.8は4倍のグリフサイズが必要です。ゲートがこれを強制します。
  • 課金の罠を発見し、回避しました: 高解像度画像ティアは1ページあたり3.3倍多く課金されますが、ビジョンエンコーダは追加の解像度を受け取っていません — ページを大きくすると読み取りはむしろ悪化します。実測結果はdocs/benchmarks/BENCHMARKS.mdに記載されており、有効化されていません。
  • 価格は変動しますが、恒久的な指標はトークン削減率であり、プロキシは無料のcount_tokensによる反実仮想と照らしてリクエストごとにログを記録します。

🧠 よくある質問（FAQ）

セッションの途中で有効化したら使用量が急増しました — なぜ？ OmniGlyph なしで進んでいたセッションは、プレフィックス全体が Anthropic にテキストとして 0.1× の読み取りレートでキャッシュされています。画像化された最初のリクエストは、その全部を 1 回のプロンプトで 1.25× の新規キャッシュ書き込みとして再支払いさせてしまいます。プロキシはこれを防ぎます：一度も画像化していないセッションでは、この一回限りのコストを損益分岐ゲートに加算し、それでも得な場合にのみ画像へ切り替えます — そうでなければセッションはテキストのまま維持され、節約は次の新しいセッションから始まります。

59〜70%はエンドツーエンドの数値ですか、それとも変換対象になったリクエストだけの数値ですか？ エンドツーエンドです — 請求額全体を指します。多くの圧縮ツールは変換した部分だけの削減率を報告するため、数値が実態より良く見えます。私たちの分母はすべてのリクエストです: ゲートが正しく変換対象外とした小さなリクエスト、すべてのキャッシュの書き込みと読み取り、そして（プロキシが決して圧縮しない）すべての出力トークンを含みます。圧縮対象だけに絞った数値はより高くなりますが、それは別枠で示すのみで、見出しの数値としては使いません。

節約率はどうやって測定していますか？ 同一リクエストの両面を、同じ瞬間に測定します。すべての/v1/messagesのPOSTに対して、プロキシは元の未圧縮ボディに対する無料のcount_tokensプローブ（反実仮想）を実際の転送と並行して発行し、レスポンスからプロバイダが実際に課金した使用量ブロックを読み取ります — 両方とも同じイベント行に記録されます。キャッシュ料金は両サイドに同一に適用されるため、キャッシュの割引は相殺され、「節約」として二重計上されることはありません。計算式はsrc/core/baseline.tsにあり、自分のイベントログから再導出できます。

読み取りミスが「読み取りエラー」ではなく「作話」になるのはなぜですか？ モデルのビジョンはOCRではないからです: ページはパッチ埋め込みになるだけで、離散的な文字にはなりません。そのため、1文字ごとの確信度に基づいて大きく失敗するという仕組みが存在しません — ピクセルがグリフを一意に決定できない場合、言語モデルの事前分布がもっともらしい何かでその隙間を埋めてしまいます。この仕組みこそが、OmniGlyphがフェイルクローズである理由です: バイト単位で正確な値は常に画像の隣にテキストとして流れ、誤読するモデルはゲートで遮断され、実測された本番構成では約300件の読み取りプローブ中ゼロ件の無自覚な作話でした — 読み取り失敗は棄権します。

バイト単位で正確な作業（ハッシュ、ID、秘密情報）はどうなりますか？ 直近のターンと正確な識別子は、設計上つねにテキストのままです。ワークロードがすべてバイト単位で正確である必要がある場合は、許可リストに含まれないモデル（例えば別のClaudeモデル上のサブエージェント）に振り分けてください — 許可リスト外のものはすべて、バイト単位で完全に同一のまま素通りします。

DeepSeek-OCRによって、この手法が有効かどうかはすでに決着していたのでは？ DeepSeek-OCRが証明したのは経路が機能することです — そのために専用に訓練されたエンコーダ/デコーダのペアを使っています。懐疑論は、市販の本番モデルが高密度レンダーを読めなかった時代のものです。状況は変わり、上記のモデル別スコアカードが、今日どのモデルが読めるかを根拠付きで正確に示しています。ベンチマークハーネスを使えば、新しいモデルを1コマンドで再テストできます — ゲートは誇張ではなくデータに従います。

Claude Codeなしで使えますか — Cursor、ChatGPT、あるいは単純なパイプで？ はい、2つの方法があります。プロキシとして使えば、APIのベースURL（ANTHROPIC_BASE_URL、またはOpenAIのベースURL）を設定できるあらゆるクライアントで動作します — Claude Code、自作のスクリプト、HTTPを話すものなら何でも。そして、プロキシを使えないツール向けには、上記のオフラインエクスポートがコンテキストをPNGページにレンダリングし、それを手作業で貼り付けます — omniglyph export --stdinならUnixパイプから直接読み込むことさえできます。

実際にどうやってテキストを画像に変換しているのですか？ テキストをリフローし、1ビットの5×8ピクセルグリフアトラスで高密度な1568×728のPNGページに描画します — 1ピクセルあたり1ビット、アンチエイリアスなし。そのため、モデルはページを寸法で課金し、中に何文字含まれているかは問いません。パイプラインについては上記の仕組みを、幾何学的な詳細となぜ高密度化が必ずしも安くならないのかについてはベンチマークのドキュメントを参照してください。

🔬 すべての数値を再現する

pnpm install && pnpm test                                     # full suite
node benchmarks/billing-sweep/run.mjs --dry-run               # billing predictions, $0
pnpm exec tsx benchmarks/density-frontier/run.ts --dry-run    # cost table, $0
# with keys: ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY (or --via-cli for a Claude Code subscription)

The two benchmark harnesses running in dry-run mode

完全な手法とすべての結果テーブル: docs/benchmarks/BENCHMARKS.md。回答ごとの生の根拠: benchmarks/*/results/*.jsonl。

🚀 OmniRouteファミリー

OmniGlyphは無料のAIゲートウェイである**OmniRouteにネイティブな圧縮エンジンとしても組み込まれています**。そこではomniglyphエンジンとして動作し（単体モードでも他のエンジンと積み重ねても可）、フェイルクローズなゲートと画像対応のトークン会計を備えています。

🛠️ 技術スタック

レイヤー 技術
言語 TypeScript（strict）、ESM
ランタイム Node ≥18 · Cloudflare Workers（wrangler.toml）
レンダリング 自前の1ビットグリフアトラス（Spleen/Unifont由来、ライセンスはassets/に記載）→ PNG
テスト Vitest — TDD、加えてdocs-integrityとリブランドガード
ベンチマーク benchmarks/のハーネス（billing-sweep、density-frontier）、JSONLの根拠付き

プロジェクト構成

パス 内容
src/ プロキシ本体: 変換パイプライン、プロバイダごとの厳密な課金、レンダラー、ホスト（Node + Cloudflare Workers）
benchmarks/ 上記のすべての数値を生成したハーネス — 再実行可能
docs/ BENCHMARKS · ARCHITECTURE · ROADMAP

📧 サポート & コミュニティ

🙏 謝辞

OmniGlyphは、とりわけ1つのプロジェクトの肩の上に立っています — このセクションは、私たちの恒久的な感謝の言葉です。

プロジェクト OmniGlyphへの貢献
pxpipe · teamchong このプロジェクト全体の土台となった発見。 pxpipeは、本番運用のLLMのビジョン経路が高密度なテキストコンテキストをトークンコストのごく一部で運べること、そしてその変換は雰囲気ではなく厳密な課金計算によってリクエストごとに判断されなければならないことを、根拠とともに証明しました。高密度な1ビットレンダリング、収益性ゲート、count_tokensによる反実仮想、フェイルクローズなモデル許可リスト、そして「主張する前に実測する」というドキュメント文化は、すべてそこで最初に確立されたものです。OmniGlyphはそのコードベースから直接派生しています（MIT — オリジナルの著作権表記は私たちのLICENSEに残されています）。
Spleen · Frederic Cambus 私たちの高密度1ビットグリフアトラスが由来する5×8ビットマップフォントファミリー（ライセンスはassets/に記載）。
GNU Unifont · Unifoundry 同じアトラスにおいて、Spleenの範囲を超えるグリフをカバー（ライセンスはassets/に記載）。

OmniGlyphが役に立ったと感じたら、ぜひアップストリームにもスターを付けてください — この発見は彼らのものです。🙏

📄 ライセンス

MIT — LICENSEを参照。