Skip to content

README.md

Latest commit

 

History

History
260 lines (178 loc) · 27.7 KB

README.md

File metadata and controls

260 lines (178 loc) · 27.7 KB
Raw

🌐 English · All languages

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

🖼️ OmniGlyph — بستر (context) به‌شکل تصویر

هزینهٔ 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 درخواست
توکن به‌ازای هر بلاک تبدیل‌شده ۱۰ برابر کمتر (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
ساخته‌شدن خیالی و بی‌صدا (confabulation) در حدود 300 پروب خواندن 0 — هر خطا به‌صورت صادقانه به‌عنوان ILEGIVEL امتناع می‌کند benchmarks/density-frontier/results/

کارنامهٔ مدل‌ها (آیا می‌توانند رندرهای فشرده را بخوانند؟ n=30 برای هر بازو، امتیازدهی قطعی):

مدل خواندن نتیجه
Claude Fable 5 100% دقیق ✅ هدف تولید
Claude Opus 4.8 77 تا 87 درصد با اندازهٔ گلیف ۴ برابر ⚠️ حالت ایمن اختیاری (صرفه‌جویی به ~۲ برابر کاهش می‌یابد)
GPT-5.5 0/60 — و پاسخ‌هایش را حدود ۴۰ برابر متورم می‌کند ❌ توسط گیت مسدود شده، با اثبات
Gemini 2.5-flash 0/26 — و به‌جای امتناع، ساخته‌ی خیالی تولید می‌کند ❌ مسدود (تست جزئی، محدود به سهمیه)

این برتری امروز مختص Fable است — سایر رمزگذارهای بینایی هنوز قادر به تفکیک گلیف‌های فشرده نیستند. مجموعهٔ بنچمارک هر مدل جدید را با یک دستور مجدداً آزمایش می‌کند.

🤔 چرا OmniGlyph؟

هر نشست طولانی‌مدت عامل (agent) در هر درخواست همان بار مرده را با خود می‌کشد: system prompt، مستندات ابزارها، و تاریخچهٔ قدیمی — که در هر نوبت دوباره بر اساس توکن صورت‌حساب می‌شود. OmniGlyph یک پراکسی محلی است که این بخش‌های حجیم را پیش از خروج از دستگاه شما به صفحات PNG فشرده تبدیل می‌کند:

  • ریاضیات دقیق صورت‌حساب، نه ابتکاری (heuristic) — فرمول واقعی توکن تصویر هر ارائه‌دهنده را محاسبه می‌کند (اندازه‌گیری‌شده تا باقی‌ماندهٔ صفر) و فقط زمانی تبدیل می‌کند که ریاضیات به نفع باشد.
  • طراحی 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 را به آن اشاره دهید

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

به هر دو شکل کار می‌کند:

  • کلید API (پرداخت به‌ازای هر توکن): صورت‌حساب شما ۵۹ تا ۷۰ درصد سرتاسری کاهش می‌یابد.
  • نشست اشتراکی (subscription): هزینهٔ کمتری نمی‌پردازید، اما محدودیت‌های مصرف بر اساس توکن شمارش می‌شوند — پس محدودیت‌های شما حدود ۲ تا ۳ برابر کش می‌آید.

داشبورد در آدرس http://127.0.0.1:47821/: توکن‌های صرفه‌جویی‌شده، هر تبدیل متن به تصویر کنار هم، کلید خاموش/روشن (kill switch)، تراشه‌های زندهٔ مدل. پاسخ‌ها به‌طور معمول استریم می‌شوند — فقط درخواست فشرده می‌شود، هرگز خروجی مدل.

🔌 استفاده با کلاینت‌های 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، اصابت‌های کش، خطاها، فید زنده.
  • جریان زنده — خط لوله به‌صورت نمودار گره‌ای: کلاینت ← گیت ← رندرکننده / عبور مستقیم (passthrough) ← API، با یک ذره به‌ازای هر درخواست واقعی.
  • تله‌متری — یک شمارشگر تجمعی توکن/دلار و جدول زمانی زندهٔ درخواست‌ها؛ روی هر درخواست کلیک کنید تا دقیقاً ببینید کدام بخش‌ها به تصویر تبدیل شده‌اند و متن مبدأ پشت هر صفحه را بخوانید.
  • بنچمارک‌ها — رسیدهای اجرای بنچمارک که از benchmarks/*/results/ رندر شده‌اند، یک ردیف به‌ازای هر آزمایش model·config، و بنچمارک‌ها را از داخل رابط کاربری اجرا کنید: اجراهای $0 dry-run خروجی خود را به‌صورت زنده استریم می‌کنند؛ اجراهای واقعی همچنان پشت کلید API شما به‌همراه تأیید صریح هزینه محدود می‌مانند.
  • جلسات / تاریخچه — برترین جلسات بر اساس توکن‌های صرفه‌جویی‌شده و هر رویداد ذخیره‌شده روی دیسک.
جریان زنده بنچمارک‌ها
خط لولهٔ درخواست به‌صورت نمودار گره‌ای زنده رسیدهای بنچمارک و اجراهای آزمایشی درون رابط کاربری

تله‌متری: شمارشگر و جدول زمانی زندهٔ درخواست‌ها

⚙️ چگونه کار می‌کند

بلاک حجیم درخواست ──► گیت سودآوری ──► reflow + رندر (اطلس ۱-بیتی ۵×۸)
                       (ریاضیات دقیق صورت‌حساب)     ──► صفحات PNG با اندازهٔ 1568×728 ──► چسباندن مجدد، سازگار با کش
  • صورت‌حساب پیش از تبدیل، دقیقاً محاسبه می‌شود: Anthropic به‌ازای هر تصویر ⌈w/28⌉ × ⌈h/28⌉ + 4 توکن صورت‌حساب می‌کند (پچ‌های ۲۸ پیکسلی — اندازه‌گیری‌شده تا باقی‌ماندهٔ صفر). یک صفحهٔ کامل 28,080 کاراکتر را در 1,460 توکن جای می‌دهد ≈ ۱۹ کاراکتر بر توکن، در برابر حدود ۲ کاراکتر بر توکن برای متن فشرده. گیت فقط زمانی تبدیل می‌کند که ریاضیات به نفع باشد.
  • چه چیزی تبدیل می‌شود: system prompt ثابت + مستندات ابزارها، تاریخچهٔ جمع‌شدهٔ قدیمی، خروجی‌های بزرگ ابزارها.
  • چه چیزی هرگز تبدیل نمی‌شود: پیام‌های شما، نوبت‌های اخیر، خروجی مدل، نثر پراکنده، مقادیر بایت-دقیق (هش‌ها/شناسه‌ها به‌صورت متن در کنار آن سوار می‌شوند)، و هر مدلی که در بنچمارک خواندن رد شده باشد.

📚 استفاده به‌صورت کتابخانه (بدون پراکسی)

هر کاری که پراکسی به‌ازای هر درخواست انجام می‌دهد، به‌صورت یک API مستندشده و قابل import هم در دسترس است:

import { renderTextToImages, transformAnthropicMessages } from "omniglyph";

// هر متنی را به صفحات 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 از آن استفاده می‌کند. زمان اجرای خالص جاوااسکریپت (Node و edge/Workers). سطح کامل: src/core/index.ts.

📤 برون‌ریزی آفلاین — بدون پراکسی، بدون Claude Code

از Claude Code استفاده نمی‌کنید؟ بستر (context) را به‌صورت محلی به صفحات 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 را اجرا کنید.

🧭 The honest part (بخش صادقانه)

  • این روش با اُفت کیفیت (lossy) است. بازیابی بایت-دقیق از تصاویر ذاتاً غیرقابل‌اتکاست. راهکارهای کاهشی اعمال‌شده: شناسه‌های دقیق به‌صورت متن کنار تصویر حرکت می‌کنند، و پیکربندی تولیدی اندازه‌گیری‌شده صفر ساخته‌ی خیالی بی‌صدا تولید کرده — خواندن‌های ناموفق امتناع می‌کنند.
  • امروز فقط Fable 5 تأیید شده است، با رسید. GPT-5.5 و Gemini 2.5-flash به‌طور قابل‌اندازه‌گیری قادر به خواندن رندرهای فشرده نیستند؛ Opus 4.8 به گلیف‌های ۴ برابر بزرگ‌تر نیاز دارد. گیت این را اعمال می‌کند.
  • یک تلهٔ صورت‌حساب پیدا کردیم و از آن اجتناب کردیم: لایهٔ تصویر با وضوح بالا به‌ازای هر صفحه ۳.۳ برابر بیشتر صورت‌حساب می‌شود، اما رمزگذار بینایی وضوح اضافی را دریافت نمی‌کند — صفحات بزرگ‌تر بدتر خوانده می‌شوند. اندازه‌گیری‌شده، مستندسازی‌شده در docs/benchmarks/BENCHMARKS.md، فعال نشده.
  • قیمت‌ها تغییر می‌کنند؛ معیار پایدار همان کاهش توکن است، که پراکسی آن را به‌ازای هر درخواست در برابر یک ضدواقعیت (counterfactual) رایگان count_tokens ثبت می‌کند.

🧠 پرسش‌های متداول

وسط یک نشست فعالش کردم و مصرف جهش کرد — چرا؟ نشستی که بدون OmniGlyph اجرا شده، کل پیشوندش نزد Anthropic به‌صورت متن با نرخ خواندن ۰٫۱× کش شده است؛ نخستین درخواست تصویری همهٔ آن را به‌صورت یک نوشتن تازهٔ کش با نرخ ۱٫۲۵× در یک پرامپت دوباره پرداخت می‌کرد. پراکسی در برابر این محافظت می‌کند: نشستی که هرگز آن را تصویری نکرده، این هزینهٔ یک‌باره را به دروازهٔ سربه‌سر می‌دهد و فقط وقتی به تصویر می‌رود که هنوز به‌صرفه باشد — وگرنه نشست متنی می‌ماند و صرفه‌جویی از نشست تازهٔ بعدی شما آغاز می‌شود.

آیا ۵۹ تا ۷۰ درصد سرتاسری است، یا فقط روی درخواست‌هایی که لمس شده‌اند؟ سرتاسری — کل صورت‌حساب. اکثر ابزارهای فشرده‌سازی صرفه‌جویی را فقط روی بخشی که لمس کرده‌اند گزارش می‌دهند، که عدد را غلوآمیز نشان می‌دهد. مخرج کسر ما همهٔ درخواست‌هاست: درخواست‌های کوچکی که گیت به‌درستی دست‌نخورده رها کرده، همهٔ نوشتن‌ها و خواندن‌های کش، و همهٔ توکن‌های خروجی (که پراکسی هرگز فشرده نمی‌کند). عدد فقط-فشرده‌شده بالاتر است و جداگانه ذکر می‌شود، هرگز به‌عنوان سرخط.

صرفه‌جویی چگونه اندازه‌گیری می‌شود؟ هر دو طرف همان درخواست، در همان لحظه. برای هر POST به مسیر /v1/messages، پراکسی یک پروب رایگان count_tokens روی بدنهٔ اصلی فشرده‌نشده (ضدواقعیت) به‌موازات ارسال واقعی شلیک می‌کند، و بلاک مصرف واقعاً صورت‌حساب‌شدهٔ ارائه‌دهنده را از پاسخ می‌خواند — هر دو در همان ردیف رویداد فرود می‌آیند. قیمت‌گذاری کش به‌طور یکسان روی هر دو طرف اعمال می‌شود، پس تخفیف کش خنثی می‌شود و نمی‌تواند دوباره به‌عنوان «صرفه‌جویی» شمرده شود. فرمول در src/core/baseline.ts قرار دارد؛ آن را از رخدادنامهٔ (events log) خودتان بازاستخراج کنید.

چرا یک خطا باید ساخته‌ی خیالی (confabulation) باشد نه خطای خواندن؟ چون بینایی مدل، OCR نیست: صفحه به patch embedding تبدیل می‌شود، هرگز به کاراکترهای مجزا، پس هیچ اطمینان به‌ازای هر گلیف وجود ندارد که بتواند به‌صراحت شکست بخورد — وقتی پیکسل‌ها یک گلیف را کم‌مشخص می‌کنند، اولویت زبانی (language prior) شکاف را با چیزی محتمل پر می‌کند. همین سازوکار دقیقاً دلیلی است که OmniGlyph در این باره fail-closed است: مقادیر بایت-دقیق همیشه به‌صورت متن کنار تصویر سوار می‌شوند، مدل‌هایی که بد می‌خوانند توسط گیت مسدود می‌شوند، و پیکربندی تولیدی اندازه‌گیری‌شده در حدود ۳۰۰ پروب خواندن صفر ساخته‌ی خیالی بی‌صدا تولید کرده — خواندن‌های ناموفق امتناع می‌کنند.

در مورد کارهای بایت-دقیق (هش‌ها، شناسه‌ها، رازها) چطور؟ نوبت‌های اخیر و شناسه‌های دقیق طبق طراحی به‌صورت متن باقی می‌مانند. برای بارهای کاری که کاملاً بایت-دقیق هستند، آن‌ها را به یک مدل خارج از فهرست مجاز (allowlist) هدایت کنید (مثلاً یک subagent روی مدل دیگری از Claude) — هر چیزی خارج از allowlist، بدون تغییر و بایت‌به‌بایت یکسان عبور می‌کند.

آیا DeepSeek-OCR این موضوع را قطعی نکرد که این روش کار می‌کند؟ آن ثابت کرد که کانال کار می‌کند — با یک جفت رمزگذار/رمزگشا که برای همین کار آموزش دیده. تردید از زمانی نشأت می‌گیرد که هیچ مدل تولیدی آماده‌ای قادر به خواندن رندرهای فشرده نبود؛ آن وضعیت تغییر کرده، و کارنامهٔ مدل‌ها در بالا دقیقاً نشان می‌دهد امروز چه کسی آن‌ها را می‌خواند، با رسید. مجموعهٔ بنچمارک هر مدل جدید را با یک دستور مجدداً آزمایش می‌کند — گیت از داده پیروی می‌کند، نه از هیاهو.

آیا می‌توانم بدون Claude Code از آن استفاده کنم — Cursor، ChatGPT، یک لولهٔ ساده؟ بله، به دو روش. به‌عنوان یک پراکسی، با هر کلاینتی که به شما اجازه می‌دهد URL پایهٔ API را تنظیم کنید کار می‌کند (ANTHROPIC_BASE_URL، یا URL پایهٔ OpenAI) — Claude Code، اسکریپت‌های خودتان، هر چیزی روی HTTP. و برای ابزارهایی که نمی‌توانند از پراکسی استفاده کنند، برون‌ریزی آفلاین بالا بستر (context) را به صفحات PNG رندر می‌کند که با دست می‌چسبانید — omniglyph export --stdin حتی مستقیماً از یک لولهٔ Unix می‌خواند.

دقیقاً چگونه متن را به تصویر تبدیل می‌کند؟ متن را reflow می‌کند و آن را با یک اطلس گلیف ۱-بیتی ۵×۸ پیکسلی روی صفحات فشردهٔ PNG با ابعاد 1568×728 نقاشی می‌کند — یک بیت بر پیکسل، بدون هموارسازی لبه‌ها (anti-aliasing)، پس مدل صفحه را بر اساس ابعادش صورت‌حساب می‌کند، نه بر اساس تعداد کاراکترهایی که داخلش هستند. چگونه کار می‌کند در بالا خط لوله را دارد؛ سند بنچمارک‌ها هندسه را دارد و اینکه چرا فشرده‌تر همیشه ارزان‌تر نیست.

🔬 هر عدد را بازتولید کنید

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)

The two benchmark harnesses running in dry-run mode

روش‌شناسی کامل و هر جدول نتیجه: docs/benchmarks/BENCHMARKS.md. رسیدهای خام هر پاسخ: benchmarks/*/results/*.jsonl.

🚀 خانوادهٔ OmniRoute

OmniGlyph همچنین به‌عنوان یک موتور فشرده‌سازی بومی درون OmniRoute — دروازهٔ رایگان هوش مصنوعی — عرضه می‌شود. در آنجا به‌عنوان موتور omniglyph اجرا می‌شود (حالت مستقل تکی یا هم‌پشته با سایر موتورها)، همراه با گیت‌های fail-closed و حسابداری توکن آگاه از تصویر.

🛠️ پشتهٔ فناوری

لایه فناوری
زبان TypeScript (strict), ESM
زمان اجرا Node ≥18 · Cloudflare Workers (wrangler.toml)
رندر اطلس گلیف ۱-بیتی اختصاصی (برگرفته از Spleen/Unifont، مجوزها در assets/) → PNG
تست‌ها Vitest — TDD، به‌همراه گاردهای docs-integrity و rebrand
بنچمارک‌ها مجموعه‌های benchmarks/ (billing-sweep، density-frontier) با رسیدهای JSONL

چیدمان پروژه

مسیر چیست
src/ پراکسی: pipeline تبدیل، صورت‌حساب دقیق به‌ازای هر ارائه‌دهنده، رندرر، هاست‌ها (Node + Cloudflare Workers)
benchmarks/ مجموعه‌هایی که هر عدد بالا را تولید کرده‌اند — قابل اجرای مجدد
docs/ BENCHMARKS · ARCHITECTURE · ROADMAP

📧 پشتیبانی و انجمن

🙏 سپاسگزاری

OmniGlyph بر شانه‌های یک پروژهٔ خاص ایستاده — این بخش، تشکر همیشگی ماست.

پروژه چگونه OmniGlyph را شکل داد
pxpipe · teamchong کشفی که کل این پروژه بر پایهٔ آن ساخته شده. pxpipe با رسید ثابت کرد که کانال بینایی یک LLM تولیدی می‌تواند بستر متنی فشرده را با کسری از هزینهٔ توکن حمل کند — و اینکه تبدیل باید به‌ازای هر درخواست با ریاضیات دقیق صورت‌حساب تصمیم‌گیری شود، هرگز بر اساس حدس و گمان. رندر ۱-بیتی فشرده، گیت سودآوری، ضدواقعیت count_tokens، فهرست مجاز مدل‌های fail-closed، و فرهنگ مستندسازی «پیش از ادعا، اندازه بگیر» همگی نخستین‌بار آنجا پایه‌گذاری شدند. OmniGlyph مستقیماً از آن پایگاه کد سرچشمه می‌گیرد (MIT — خط کپی‌رایت اصلی در LICENSE ما باقی می‌ماند).
Spleen · Frederic Cambus خانوادهٔ فونت بیت‌مپ ۵×۸ که اطلس گلیف ۱-بیتی فشردهٔ ما از آن گرفته شده (مجوز در assets/).
GNU Unifont · Unifoundry پوشش گلیف‌های خارج از محدودهٔ Spleen در همان اطلس (مجوز در assets/).

اگر OmniGlyph را مفید یافتید، به پروژهٔ بالادستی هم ستاره بدهید — این کشف، کشف آن‌هاست. 🙏

📄 مجوز

MIT — به LICENSE مراجعه کنید.