Upload README.md with huggingface_hub

README.md

@@ -1,119 +1,118 @@
 ---
-language:
-- en
-- zh
 license: apache-2.0
-library_name: transformers
 tags:
 - vision
 - ocr
-- multimodal
-- text-recognition
 - document-analysis
+- multimodal
+- qwen2vl
 - gguf
-- quantized
-- qwen2.5-vl
-base_model: MonkeyAI/MonkeyOCR-pro-1.2B
-model_type: qwen2vl
+- lm-studio
+model_type: vision-language
+architecture: qwen2vl
+quantization: q8_0
+languages:
+- en
+- zh
 pipeline_tag: image-text-to-text
 ---
 
-# MonkeyOCR Pro 1.2B Vision - GGUF
+# MonkeyOCR-pro-1.2B Vision GGUF
+
+A high-performance **vision-language model** specialized for **Optical Character Recognition (OCR)** and **document analysis**. This repository contains GGUF format models optimized for both general use and **LM Studio** compatibility.
+
+## 🎯 Model Capabilities
 
-This is a **vision-enabled** GGUF quantized version of MonkeyOCR Pro 1.2B, optimized for OCR and document analysis tasks.
+- ✅ **Vision-Language Processing**: Understand and process images with text
+- ✅ **OCR (Optical Character Recognition)**: Extract text from images and documents  
+- ✅ **Document Structure Analysis**: Analyze layout, tables, and formatting
+- ✅ **Multi-turn Conversations**: Chat about images and documents
+- ✅ **Multiple Languages**: Support for English, Chinese, and more
 
-## 🔥 Key Features
+## 📁 Files Included
 
-- **Vision-Language Model**: Supports both text and image inputs
-- **OCR Optimized**: Excellent performance on text recognition tasks
-- **Quantized**: Q8_0 quantization for optimal quality/size balance
-- **Large Context**: 128,000 token context length
-- **Architecture**: Based on Qwen2.5-VL
+### Standard GGUF Models
+- **`MonkeyOCR-pro-1.2B-Recognition.gguf`** (1.26 GB) - Complete vision-enabled model
+- **`MonkeyOCR-pro-1.2B.gguf`** (1.26 GB) - Alternative version
 
-## 🚀 Model Architecture
+### LM Studio Optimized
+- **`MonkeyOCR-pro-1.2B-Text-LMStudio.gguf`** (1.23 GB) - Text model for LM Studio
+- **`mmproj-MonkeyOCR-pro-1.2B-Vision-LMStudio.gguf`** (1.25 GB) - Vision projection for LM Studio
 
-- **Base Architecture**: Qwen2.5-VL (Vision-Language)
-- **Parameters**: 1.2B
-- **Quantization**: Q8_0
-- **File Size**: ~1.3GB
-- **Context Length**: 128,000 tokens
-- **Vision Support**: ✅ Enabled
+## 🎨 LM Studio Setup (Recommended)
 
-## 📊 Model Specifications
+### Step 1: Download Files
+Download both LM Studio files:
+- `MonkeyOCR-pro-1.2B-Text-LMStudio.gguf`
+- `mmproj-MonkeyOCR-pro-1.2B-Vision-LMStudio.gguf`
 
-| Specification | Value |
-|---------------|-------|
-| Model Type | Vision-Language (qwen2vl) |
-| Parameters | 1.2B |
-| Quantization | Q8_0 |
-| Vision Support | Yes |
-| OCR Optimized | Yes |
-| Context Length | 128K tokens |
-| File Format | GGUF |
+### Step 2: Install in LM Studio
+1. Copy both files to your LM Studio models directory
+2. Keep them in the same folder
+3. Open LM Studio and load the text model: `MonkeyOCR-pro-1.2B-Text-LMStudio.gguf`
+4. LM Studio will automatically detect and load the vision projection
 
-## 💻 Usage
+### Step 3: Enable Vision
+1. Start a new chat session
+2. Look for the camera/image icon in the chat interface  
+3. Upload an image and start asking questions!
 
-This model can be used with any GGUF-compatible inference engine that supports vision models:
+## 🔧 Usage Examples
 
-### llama.cpp
-```bash
-# Make sure you have llama.cpp built with vision support
-./llama-cli -m MonkeyOCR-pro-1.2B-Recognition.gguf --image your_image.jpg -p "Describe this image"
+### OCR Tasks
+```
+User: [uploads image] Extract all text from this document
+Assistant: I can see text in the image. Here's what I extracted:
+[Provides accurate OCR results]
+```
+
+### Document Analysis
+```
+User: [uploads form] Analyze the structure of this form
+Assistant: This appears to be a [form type] with the following structure:
+- Header section with title
+- Main content area with fields for...
+- Footer with signature area
 ```
 
-### Python with llama-cpp-python
-```python
-from llama_cpp import Llama
-
-# Load the model
-llm = Llama(
-    model_path="MonkeyOCR-pro-1.2B-Recognition.gguf",
-    chat_format="qwen2vl",
-    n_ctx=2048,
-    verbose=False
-)
-
-# Use with image
-response = llm.create_chat_completion(
-    messages=[{
-        "role": "user", 
-        "content": [
-            {"type": "text", "text": "What text do you see in this image?"},
-            {"type": "image_url", "image_url": {"url": "path/to/your/image.jpg"}}
-        ]
-    }]
-)
+### Vision Q&A
+```
+User: [uploads chart] What does this chart show?
+Assistant: This chart displays [detailed analysis of the visual content]
 ```
 
-## 🎯 Use Cases
+## ⚙️ Technical Specifications
 
-- **Document OCR**: Extract text from scanned documents
-- **Image Text Recognition**: Read text in natural images
-- **Form Processing**: Analyze structured documents
-- **Receipt/Invoice Processing**: Extract information from receipts
-- **Multi-language Text Recognition**: Support for English and Chinese
-- **Vision-Language Tasks**: General multimodal understanding
+- **Architecture**: Qwen2.5-VL (qwen2vl)
+- **Model Size**: 1.2B parameters
+- **Quantization**: Q8_0 (8-bit)
+- **Context Length**: 8,196 tokens
+- **Vision Encoder**: CLIP-based projection
+- **Input Support**: Images, text, multimodal conversations
 
-## ⚠️ Requirements
+## 🔧 Configuration Details
 
-- Compatible inference engine with vision support (llama.cpp, etc.)
-- Sufficient RAM (recommend 4GB+ available)
-- For image processing: PIL/Pillow for image handling
+The model includes proper vision token configuration:
+- Image Token ID: 151655 (`<|image_pad|>`)
+- Video Token ID: 151656 (`<|video_pad|>`)
+- Vision Start: 151652 (`<|vision_start|>`)
+- Vision End: 151653 (`<|vision_end|>`)
 
-## 🔧 Technical Details
+## 🚀 Performance
 
-- **Original Model**: MonkeyAI/MonkeyOCR-pro-1.2B
-- **Conversion**: llama.cpp convert_hf_to_gguf.py
-- **Vision Components**: Integrated vision encoder
-- **Tokenizer**: Qwen2 tokenizer with vision tokens
-- **Special Tokens**: Image token (151665), Video token (151656)
+- **Fast inference** with Q8_0 quantization
+- **High accuracy** OCR capabilities
+- **Efficient memory usage** (~1.2-1.3 GB VRAM)
+- **Multi-language support** for global documents
 
 ## 📝 License
 
-This model follows the Apache 2.0 license of the original MonkeyOCR model.
+Apache 2.0 - Free for commercial and research use
 
 ## 🙏 Credits
 
-- Original model by MonkeyAI
-- GGUF conversion using llama.cpp
-- Vision capabilities preserved through Qwen2.5-VL architecture
+Based on the MonkeyOCR model architecture with optimizations for GGUF format and LM Studio compatibility.
+
+---
+
+**For best vision performance, use the LM Studio optimized files!** 🎯