Headroom: ضغط سياق LLM لوكلاء البرمجة

ضغط سياق LLM مع Headroom: ترخيص Apache-2.0، والتثبيت بحسب README، ولوحة المعلومات، وقياس الرموز (tokens) بمقاييس OpenTelemetry.
Headroom : compression de contexte LLM pour agents de code

ضغط سياق LLM لوكلاء البرمجة مع Headroom: يقدّم المشروع نفسه طبقةً تضغط كل ما يقرؤه الوكيل (مخرجات الأدوات والسجلات ومقتطفات RAG والملفات والسجل) قبل أن يصل إلى النموذج. يعرض مستودع headroomlabs-ai/headroom نحو 77 500 نجمة في نهاية أكتوبر 2026، بترخيص Apache-2.0.

رموز (tokens) أقل في المدخلات تعني تكلفة أقل وعمليات ضغط أقل للسياق (compaction)، لكن بشرط ألا يُتلف الضغط المعلومة المفيدة. يلخّص هذا المقال ما يفعله المشروع بحسب README، ويعرض لوحته، ويفصّل التثبيت، ثم يشرح كيف تقيس الوفورات بنفسك بمقاييس Prometheus وOpenTelemetry. توضيح للأمانة: لم تثبّت span.observer برنامج Headroom؛ الأوامر مأخوذة من README ووثائق المشروع، واللقطات مأخوذة من المستودع.

ضغط سياق LLM مع Headroom: ما يقوله المستودع

  • الجهة: مؤسسة headroomlabs-ai؛ والوثائق مستضافة على docs.headroomlabs.ai.
  • الترخيص: Apache-2.0 (ملف LICENSE في المستودع).
  • أرقام قُرئت في 22 أكتوبر 2026: نحو 77 500 نجمة ونحو 6 000 تفرّع (fork) و3 324 إيداعًا (commit)؛ ويشير pyproject.toml في الفرع الرئيسي إلى الإصدار 0.41.0 من الحزمة headroom-ai، التي تتطلب Python 3.10 أو أحدث.
  • أربعة استخدامات بحسب README: مكتبة (compress(messages) بلغة Python أو TypeScript)، وبروكسي (headroom proxy --port 8787)، وغلاف للوكيل (headroom wrap claude وcodex وcursor وaider وopencode…)، وخادم MCP.

الآلية الموصوفة: موجّه محتوى يكتشف نوع البيانات ويختار ضاغطًا (JSON، أو شيفرة عبر الشجرة النحوية، أو نص بنموذج منشور على Hugging Face). وتُحفظ النسخ الأصلية محليًا («CCR») ويستطيع النموذج طلبها من جديد عبر الأداة headroom_retrieve. ويؤكد المشروع أن الضغط يتم على جهازك من دون إرسال المحتوى إلى مكان آخر لضغطه. وهذه فكرة قريبة من context-mode الذي يُبقي المخرجات الخام خارج السياق بآلية أخرى وترخيص آخر.

جولة في لوحة المعلومات

يفتح الأمر headroom dashboard لوحة معلومات (dashboard) والبروكسي يعمل. اللقطة أدناه من المستودع: تُظهر الحالة الصحية والطلبات المنتهية أو الفاشلة أو المحدودة والرموز الموفَّرة والتكلفة والحمل الذي يضيفه البروكسي (بالميلي ثانية) والاستخدام بحسب نوع المحتوى المحذوف («JSON Bloat» و«Repetition») والأثر في ذاكرة التخزين المؤقت للبادئة لدى المزوّد.

لوحة Headroom من المستودع: الطلبات المنتهية والرموز الموفَّرة 143.0k أي 36.9%، وحمل قدره 14 ms، واستخدام الرموز قبل الضغط وبعده، والأثر في ذاكرة البادئة المؤقتة، والطلبات الأخيرة
Source : github.com

هذه قيم مثال من المشروع، لا قياسات من span.observer. وتتوقع اللوحة أيضًا تقديرًا لرموز المخرجات الموفَّرة عند تفعيل تشكيل المخرجات (HEADROOM_OUTPUT_SHAPER=1، معطّل افتراضيًا).

تُظهر الصورة الثانية من المستودع عدّادًا مجمَّعًا «Community savings». لا يفصّل README، في المقطع الذي اطّلعنا عليه، كيف يُجمع هذا الرقم: خذه معلومة من المشروع غير متحقق منها، واقرأ قسم الحدود عن إشارة التتبع (beacon).

صورة من مستودع Headroom: عدّاد Community savings بقيمة 59.0 مليار رمز موفَّر، وأربع بطاقات (التكلفة الموفَّرة، والطلبات المحسَّنة، والنسخ النشطة، والأيام النشطة)، ومنحنى الرموز الموفَّرة خلال 48 ساعة
Source : github.com

التثبيت خطوة بخطوة

الخطوة 1 — تثبيت واجهة سطر الأوامر

يعطي README الخيارات التالية:

uv tool install --python 3.13 "headroom-ai[all]"
pip install "headroom-ai[all]"
npm install headroom-ai     # SDK TypeScript seulement, sans CLI

وتُذكر أيضًا صورة Docker (ghcr.io/headroomlabs-ai/headroom:latest). ولتقليص المساحة المكشوفة يسرد README إضافات دقيقة ([proxy] و[mcp] و[ml] و[otel]…).

الخطوة 2 — اختيار وضع

headroom wrap claude          # enveloppe un agent de code
headroom proxy --port 8787    # proxy sans changer le code
headroom mcp install          # serveur MCP (headroom_compress, headroom_retrieve, headroom_stats)

يوضح README أن headroom wrap يشغّل بروكسي محليًا ويثبّت خادم Serena للتنقل في الشيفرة ويطلق الوكيل مهيّأً للمرور عبر Headroom؛ ويلغي headroom unwrap ذلك. اقرأ هذا الجزء قبل الاستخدام: فهو يعدّل إعدادات وكيلك.

الخطوة 3 — التحقق

headroom doctor      # contrôle de santé
headroom perf        # performances
headroom dashboard   # économies en direct (proxy lancé)

الحدود والنقاط المفتوحة

  • الأرقام أرقام المشروع: ينشر README جدولًا من أربعة سيناريوهات (من 21% إلى 57% وفورات) قيست بمُرمِّز (tokenizer) المزوّد، ويمكن إعادة إنتاجها بالأمر benchmarks/index_proof_table.py --seed 20260902. ويوضح بنفسه أن المكاسب تتوقف على تكرار البيانات، وأن النثر أو المخرجات الكثيفة أصلًا تُضغط قليلًا جدًا.
  • الدقة: تُظهر اختبارات الدقة في README عند N=100 فارقًا قدره ±0.03 يعدّه ضمن فاصل الثقة. ولا شيء يغني عن تجربة على مهامك.
  • إشارة التتبع (beacon): تشرح صفحة «Limitations» في الوثائق أن HEADROOM_BEACON مفعّلة افتراضيًا (ويمكن تعطيلها) وترسل ملخصًا مجهول الهوية (عدّادات ونسب ومعرّفات المزوّد والنموذج والنظام والمعمارية)، ولا ترسل أبدًا المطالبات (prompts) ولا الشيفرة. وتُعطَّل بـ HEADROOM_BEACON=off أو HEADROOM_TELEMETRY=off أو DO_NOT_TRACK=1. وثّق هذه النقطة في مراجعتك الأمنية.
  • بروكسي على مسار الطلبات: يرى مفاتيح المزوّد ومطالباتك. أبقه على الحلقة المحلية (loopback) وعامله كمكوّن حرج، كما تعامل خادم MCP (راجع تأمين خادم MCP).

كيف تقيس الوفورات وتراقب البروكسي؟

يتيح Headroom عدة مصادر بحسب صفحة «Metrics & Monitoring»: نقطة الوصول /stats (بصيغة JSON)، والسجل التاريخي /stats-history (مع تصدير CSV)، ومقاييس Prometheus على /metrics (مثل headroom_tokens_saved_total وheadroom_requests_failed_total)، وتصدير OpenTelemetry. وتنبّه الوثائق إلى أن headroom_requests_total يعدّ الطلبات المنتهية فقط، وإلى عدم وجود حاويات (buckets) للمدرّج التكراري: تُحسب المتوسطات بزوجي _sum و_count.

لتصدير OTLP ثبّت الإضافة [proxy,otel] ثم اضبط هذه المتغيرات المأخوذة من الوثائق:

مقتطف من وثائق Headroom: المتغيرات HEADROOM_OTEL_METRICS_ENABLED وHEADROOM_OTEL_METRICS_ENDPOINT وHEADROOM_OTEL_SERVICE_NAME وHEADROOM_OTEL_RESOURCE_ATTRIBUTES، ثم أمر curl على /stats مع jq .otel
Source : github.com

تذكر الوثائق العدّادات headroom.proxy.requests وheadroom.proxy.tokens.input وheadroom.proxy.tokens.output وheadroom.proxy.tokens.saved، وتوضح أن نقطة النهاية يجب أن تكون العنوان الكامل، من دون إضافة /v1/metrics تلقائيًا. وفي Dynatrace SaaS تشير صفحة Headroom إلى رمز مميّز بالنطاق metrics.ingest والمتغير OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=DELTA: وتؤكد وثائق OpenTelemetry في Dynatrace أن الخلفية لا تستوعب إلا القيم ذات الزمنية الدلتا (delta temporality). وخطوات OTLP موجودة في مراقبة وكيل برمجة في المؤسسة. أما في Dynatrace Managed فتحقق أولًا من توافر استيعاب OTLP في إصدارك.

للحصول على رقم مستقل، قارن الرموز المفوترة من جهة الوكيل مع Headroom وبدونه، كما في تكلفة وكيل الذكاء الاصطناعي بالرموز مع OpenTelemetry، مع جمع كل أنواع الرموز، بما فيها ذاكرة التخزين المؤقت.

كيف تتحقق من أن كل شيء يعمل؟

  1. يؤكد headroom doctor أن التوجيه يعمل.
  2. يرد curl http://localhost:8787/health (أمر من صفحة استكشاف الأخطاء في الوثائق).
  3. يؤكد curl -s http://localhost:8787/stats | jq .otel أن مُصدِّر OTLP نشط.

أفضل الممارسات

  • جرّب على مهمة مرجعية غنية بالمخرجات الضخمة، من ثلاث إلى خمس مرات مع البروكسي وبدونه.
  • تحقق من جودة الإجابات لا من الرموز وحدها: ضغط مفرط قد يخفي سطرًا مفيدًا.
  • ثبّت الإصدار وأعد قراءة متغيرات التتبع عند كل تحديث.
  • أبقِ الوصول إلى البروكسي محليًا ولا تكشف منفذه.

الأسئلة الشائعة

هل Headroom مفتوح المصدر؟

نعم، المستودع بترخيص Apache-2.0. لكن تحقق من الإضافات والنماذج التي تثبّتها، فلكلٍّ ترخيصه.

هل يرسل Headroom مطالباتي إلى مكان ما؟

بحسب README يتم الضغط محليًا. ويمرّر البروكسي الطلب المضغوط بطبيعة الحال إلى مزوّد LLM لديك، أما إشارة التتبع المجهولة المفعّلة افتراضيًا فموصوفة في صفحة «Limitations».

ما الوفورات المتوقعة؟

ينشر المشروع من 21% إلى 57% على أربعة سيناريوهات، ويحذّر من أن المحتوى المتكرر يربح أكثر. قِس على أحمال عملك.

الخلاصة

يطبّق Headroom ضغط سياق LLM عند البروكسي مباشرة ويوفر ما يلزم لقياسه، مع Prometheus وOpenTelemetry. أرقامه أرقام أصحابه: عليك تأكيدها على مهامك. المصادر: مستودع headroomlabs-ai/headroom ووثائق Headroom.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا للمشاريع المذكورة. العلامات التجارية المذكورة ملك لأصحابها. الأدوات تتطور بسرعة، لذا تحقق دائمًا من الأوامر والخيارات في وثائقها الرسمية.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Orca : pilotage d'une flotte d'agents de code, MIT et coûts

Orca: إدارة وكلاء البرمجة بالتوازي عبر worktrees، ترخيص MIT والتكاليف

Next Post
Ponytail skill agent : moins de code, gains à vérifier

مهارة Ponytail للوكلاء: شيفرة أقل ومكاسب تحتاج إلى تحقق

Related Posts