ONYX-APP-AI/onyx-ai-4gemma

ONYX-AI-4Gemma is the Ultra-Optimized version of the Gemma 4 architecture. This edition is specifically engineered for Low-Latency Inference and high-speed responsiveness, even on modest hardware.

By moving beyond standard quantization and implementing Raw Streaming and SDPA (Scaled Dot Product Attention), we’ve achieved response times that mimic high-end AI platforms like Grok.

---

⚡ Performance & "Light-Speed" Features

• 🚀 Instant-Response Streaming: Tokens are delivered bit-by-bit via Pure Text Streaming, eliminating waiting time and buffering.
• 🧠 SDPA Engine: Uses Scaled Dot Product Attention for ultra-fast context processing.
• ⚙️ CPU Turbo Mode: Optimized with torch.inference_mode and channels_last memory format to squeeze every bit of power from your CPU.
• 💾 Smart 4-bit NF4: Reduces memory footprint to ~10GB without sacrificing the model's core intelligence.
• 🚫 Zero-Buffering: Custom FastAPI headers (X-Accel-Buffering: no) ensure real-time interaction, perfect for Flutter and Web integrations.

⏱ Performance Metrics

Hardware	Generation Speed	Latency
Standard CPU	~5-15 tokens/sec	Low
Modern CPU (Multi-threaded)	~20-40 tokens/sec	Ultra-Low
GPU (T4/RTX)	Blazing Fast	Near-Zero

---

🚀 Technical Innovations (The ONYX Way)

• 🔥 BFloat16 Computation: Higher precision and faster math on modern processors.
• 💬 Chat-Template Native: Fully compatible with standard chat templates for seamless multi-turn conversations.
• 🕸 Anti-Buffering Architecture: Designed to work perfectly with front-end frameworks without data: prefix overhead.
• 🔎 RAG Ready: Built-in support for external knowledge injection via FAISS.

---

💻 System Requirements (The Sweet Spot)

To experience ONYX-AI-4Gemma at "Light-Speed," here are the recommended hardware specifications:

🧠 Processor (CPU)

• Architecture: x86_64 or ARM64.
• Cores: Minimum 4 Cores, Recommended 8+ Cores.
• Instruction Sets: Optimized for CPUs supporting AVX2 and BFloat16 (found in modern AMD Ryzen & Intel Core series).
• Performance Note: ONYX utilizes torch.set_num_threads to leverage every single thread of your processor for maximum generation speed.

⚡ Memory (RAM)

• Minimum: 12 GB (The model footprint is ~10GB).
• Recommended: 16 GB - 32 GB for a smooth multitasking experience and larger context handling.
• Type: DDR4 or DDR5 (Higher memory bandwidth directly translates to faster token generation).

🎮 Graphics (Optional GPU)

• While ONYX is a CPU-First powerhouse, it can run on GPUs with 12GB+ VRAM (like NVIDIA RTX 3060/4060 or T4) for even more extreme performance.

🎮 Live Demo

Experience the speed of ONYX-AI-4Gemma right now on Hugging Face Spaces:

🛠 Installation

pip install -r requirements.txt

---

💻 Usage (Gradio Chat Interface)

This model is designed to run easily with a Gradio web UI.

▶️ Full Example 1

import os
import torch
import gradio as gr
from threading import Thread
from transformers import AutoModelForCausalLM, AutoTokenizer, TextIteratorStreamer, AutoConfig

# 🚀 تسريع CPU
torch.set_num_threads(os.cpu_count())

model_id = "ONYX-APP-AI/onyx-ai-4gemma"
token = os.environ.get("HF_TOKEN")

print("--- 💎 Initializing ONYX for CPU ---")

config = AutoConfig.from_pretrained(model_id, token=token, trust_remote_code=True)
tokenizer = AutoTokenizer.from_pretrained(model_id, token=token)

print("--- 📦 Loading Model ---")

model = AutoModelForCausalLM.from_pretrained(
    model_id,
    config=config,
    device_map="cpu",
    token=token,
    trust_remote_code=True,
    torch_dtype=torch.float32,
    low_cpu_mem_usage=True
)

# 🚀 أسرع دالة
def chat_onyx(message, history):
    messages = []

    for turn in history:
        if isinstance(turn, (list, tuple)):
            messages.append({"role": "user", "content": turn[0]})
            messages.append({"role": "assistant", "content": turn[1]})

    messages.append({"role": "user", "content": message})

    inputs = tokenizer.apply_chat_template(
        messages,
        tokenize=True,
        add_generation_prompt=True,
        return_tensors="pt",
        return_dict=True
    ).to("cpu")

    streamer = TextIteratorStreamer(
        tokenizer,
        skip_prompt=True,
        skip_special_tokens=True
    )

    generation_kwargs = dict(
        **inputs,
        streamer=streamer,
        max_new_tokens=80,   # ⚡ أسرع بكثير
        do_sample=False      # ⚡ greedy decoding أسرع
    )

    thread = Thread(target=model.generate, kwargs=generation_kwargs)
    thread.start()

    partial = ""
    for token in streamer:
        partial += token
        yield partial

with gr.Blocks() as demo:
    gr.Markdown("# 💎 ONYX AI - FAST CPU MODE")
    gr.ChatInterface(fn=chat_onyx)

demo.launch()

---

📦 Requirements

transformers>=4.40.0
bitsandbytes
accelerate
torch
gradio
sentencepiece

---

▶️ Full Example 2

import os  # استيراد مكتبة النظام للتحكم بمتغيرات البيئة والملفات
import torch  # استيراد مكتبة تورش الأساسية للتعامل مع الموديلات والحسابات
import asyncio  # استيراد مكتبة البرمجة غير المتزامنة للتعامل مع العمليات اللي بتاخد وقت
from fastapi import FastAPI, Request  # استيراد إطار العمل FastAPI لإنشاء الـ API وطلب البيانات
from fastapi.responses import StreamingResponse  # استيراد ميزة الـ Streaming لإرسال الرد كلمة بكلمة
from transformers import AutoModelForCausalLM, AutoTokenizer, TextIteratorStreamer, AutoConfig  # أدوات HuggingFace لتحميل الموديل والمحلل النصي
from threading import Thread  # استيراد الـ Threads لتشغيل توليد النص بمسار منفصل وما يعلق السيرفر

# 🚀 تقييد الخيوط (Threads) لضمان عدم احتراق المعالج بـ 100% دائمًا
os.environ["OMP_NUM_THREADS"] = "4"  # تحديد عدد الخيوط لمكتبة OpenMP لتقليل الضغط على الـ CPU
os.environ["MKL_NUM_THREADS"] = "4"  # تحديد خيوط مكتبة MKL لضمان أداء مستقر للمعالج
torch.set_num_threads(4)  # إجبار تورش على استخدام 4 خيوط فقط بدل استهلاك كامل قدرة المعالج

app = FastAPI()  # إنشاء كائن التطبيق الأساسي لـ FastAPI

MODEL_ID = "ONYX-APP-AI/onyx-ai-4gemma"  # معرف الموديل الخاص فيكي على منصة HuggingFace

print("--- 💎 Loading ONYX-4Gemma (Lite Mode) ---")  # طباعة رسالة توضيحية عند بدء تحميل الموديل

tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)  # تحميل المحلل النصي المسؤول عن تحويل النص لأرقام وبالعكس

# 🛠️ التعديل الجذري لخفض استهلاك الرام (استخدام bfloat16 بدل float32)
model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,  # تحديد الموديل المراد تحميله
    device_map="cpu",  # إجبار الموديل على العمل على المعالج (CPU) حصراً
    torch_dtype=torch.bfloat16,  # تقليل الدقة لـ 16 بت لتوفير 50% من مساحة الرام فوراً
    low_cpu_mem_usage=True,  # تفعيل وضع الاستهلاك المنخفض للذاكرة أثناء عملية التحميل
    trust_remote_code=True  # السماح بتشغيل الكود المخصص الموجود بملفات الموديل على HuggingFace
)
model.eval()  # وضع الموديل في نمط "التقييم" لإيقاف عمليات التدريب وتوفير الموارد

@app.post("/predict")  # إنشاء نقطة نهاية (Endpoint) تستقبل طلبات POST من نوع predict
async def predict(request: Request):
    data = await request.json()  # استلام البيانات القادمة من المستخدم وتحويلها لقاموس (JSON)
    messages = data.get("messages", [])  # استخراج قائمة الرسائل (المحادثة) من الطلب
    max_tokens = data.get("max_tokens", 80)  # تحديد الحد الأقصى للكلمات المولدة، الافتراضي 80 لخفض الضغط

    try:
        # محاولة تطبيق قالب المحادثة الرسمي الخاص بالموديل (Chat Template)
        full_prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    except:
        # في حال فشل القالب، يتم دمج الرسائل يدوياً كخطة احتياطية
        full_prompt = "\n".join([m["content"] for m in messages]) + "\n\nAssistant:"

    async def generate_chunks():  # دالة داخلية لتوليد قطع النص وإرسالها تدريجياً
        try:
            # تحويل النص الكامل لـ Tensors وإرسالها للمعالج
            inputs = tokenizer(full_prompt, return_tensors="pt").to("cpu")
            # إنشاء Streamer لسحب الكلمات وحدة وحدة فور توليدها
            streamer = TextIteratorStreamer(tokenizer, skip_prompt=True, skip_special_tokens=True)
            
            # 🛠️ وضع الاستدلال الآمن (Inference Mode) لتعطيل حساب التدرجات وتقليل جهد الـ CPU
            with torch.inference_mode():
                generation_kwargs = dict(
                    **inputs,  # تمرير المدخلات المحولة
                    streamer=streamer,  # ربط الـ Streamer بعملية التوليد
                    max_new_tokens=max_tokens,  # عدد الكلمات المطلوبة
                    do_sample=False,  # تعطيل العشوائية للحصول على إجابات محددة وسريعة (Greedy Search)
                    use_cache=True,  # استخدام الذاكرة المؤقتة لتسريع التوليد (KV Cache)
                    tokenizer=tokenizer  # تمرير التوكنايزر لعملية التوليد
                )
                
                # تشغيل عملية التوليد بمسار (Thread) منفصل لضمان عدم توقف الـ Streamer
                thread = Thread(target=model.generate, kwargs=generation_kwargs)
                thread.start()
                
                # حلقة تكرار لسحب التوكنز (الكلمات) من الـ Streamer فور جهوزيتها
                for token in streamer:
                    if not token: continue  # تخطي أي توكن فارغ
                    yield token  # إرسال الكلمة فوراً للمستخدم
                    await asyncio.sleep(0.01)  # تأخير ميلي ثانية بسيط ليعطي المعالج فرصة للتنفس بين الكلمات
                    
        except Exception as e:
            yield f"\n[Error: {str(e)}]"  # إرسال رسالة الخطأ في حال حدوث أي مشكلة أثناء التوليد

    # إعادة الرد كـ Stream متواصل ليظهر عند المستخدم كلمة بكلمة
    return StreamingResponse(generate_chunks(), headers={"Content-Type": "text/event-stream"})

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=7860)

---

📦 Requirements

fastapi
uvicorn
transformers>=4.48.0
torch
accelerate
bitsandbytes>=0.46.1
sentencepiece
protobuf
tiktoken
huggingface_hub

---

🧠 Notes

• Reduce max_new_tokens for faster responses.
• Use do_sample=False for deterministic and faster output.
• For better performance, run on GPU (T4 or higher recommended).
• Large context history may slow down CPU inference.

---

⚠️ Limitations

• CPU mode is significantly slower than GPU.
• Long conversations may reduce performance.
• Quantization reduces size but not all latency overhead.

---

💎 Credits

Developed by RUI Company Project: ONYX AI System