README.md

---
library_name: transformers
license: openrail
base_model: datalab-to/surya-ocr-2
base_model_relation: quantized
tags:
  - ocr
  - persian
  - vision-language
  - qwen3_5
---

# Bina 0.1 Koochik FP16 — بینا ۰.۱ کوچک

The merged BF16 release of the Persian OCR LoRA checkpoint at step 8,000 from
[`Reza2kn/surya-ocr-2-persian-lora-7m`](https://huggingface.co/Reza2kn/surya-ocr-2-persian-lora-7m/tree/main/checkpoints/checkpoint-step-0008000),
based on [`datalab-to/surya-ocr-2`](https://huggingface.co/datalab-to/surya-ocr-2).

This repository is the immutable BF16 transcription baseline for Bina 0.1 Koochik.
Quantized/runtime-specific derivatives should be compared against this model
before being described as parity-preserving.

## Quick start (English)

Bina 0.1 Koochik is compatible with the Surya OCR 2 inference package. The easiest
supported setup is Linux (or WSL2) with an NVIDIA GPU.

### 1. Install the prerequisites

- Python 3.10 or newer
- [Docker](https://docs.docker.com/get-docker/)
- [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)

Then install or upgrade Surya:

```bash
python -m pip install -U "surya-ocr>=0.20.0"
```

### 2. Run OCR

Replace `document.pdf` with an image, a PDF, or a folder containing images/PDFs:

```bash
export SURYA_MODEL_CHECKPOINT=Reza2kn/Bina-0.1-Koochik
export SURYA_INFERENCE_BACKEND=vllm

surya_ocr ./document.pdf --output_dir ./bina-output
```

On the first run, Surya downloads the model and starts a vLLM server in Docker,
so startup can take a few minutes. For the example above, the OCR result is
written to `./bina-output/document/results.json`. Each page contains ordered
blocks with recognized HTML/text, labels, confidence scores, and bounding boxes.

Useful options:

```bash
# Process only pages 0 through 2
surya_ocr ./document.pdf --page_range 0-2 --output_dir ./bina-output

# Also save annotated page images
surya_ocr ./document.pdf --images --output_dir ./bina-output
```

### Python example

Set the environment variables before importing `surya`:

```python
import os

os.environ["SURYA_MODEL_CHECKPOINT"] = "Reza2kn/Bina-0.1-Koochik"
os.environ["SURYA_INFERENCE_BACKEND"] = "vllm"

from PIL import Image
from surya.inference import SuryaInferenceManager
from surya.recognition import RecognitionPredictor

image = Image.open("page.jpg").convert("RGB")
manager = SuryaInferenceManager()
predictor = RecognitionPredictor(manager)
result = predictor([image])[0]

for block in result.blocks:
    print(block.html)
```

> **CPU and Apple Silicon:** this repository contains BF16 weights, not a GGUF
> build. The automatic `llama.cpp` path therefore cannot run Bina 0.1 Koochik directly;
> use the NVIDIA/vLLM setup above or a Bina-specific GGUF conversion.

## راه‌اندازی سریع (فارسی)

بینا ۰.۱ کوچک با بستهٔ استنتاج Surya OCR 2 سازگار است. ساده‌ترین روش پشتیبانی‌شده،
استفاده از لینوکس (یا WSL2) و کارت گرافیک NVIDIA است.

### ۱. نصب پیش‌نیازها

- پایتون ۳.۱۰ یا جدیدتر
- [Docker](https://docs.docker.com/get-docker/)
- [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)

سپس Surya را نصب یا به‌روز کنید:

```bash
python -m pip install -U "surya-ocr>=0.20.0"
```

### ۲. اجرای OCR

به‌جای `document.pdf` می‌توانید مسیر یک تصویر، فایل PDF یا پوشه‌ای از
تصاویر/PDFها را قرار دهید:

```bash
export SURYA_MODEL_CHECKPOINT=Reza2kn/Bina-0.1-Koochik
export SURYA_INFERENCE_BACKEND=vllm

surya_ocr ./document.pdf --output_dir ./bina-output
```

در اجرای اول، Surya مدل را دانلود و سرور vLLM را در Docker راه‌اندازی می‌کند؛
بنابراین شروع کار ممکن است چند دقیقه طول بکشد. در مثال بالا، نتیجه در مسیر
`./bina-output/document/results.json` ذخیره می‌شود. خروجی هر صفحه شامل بلوک‌های
مرتب‌شده، متن/HTML تشخیص‌داده‌شده، نوع بلوک، میزان اطمینان و مختصات کادرها است.

چند گزینهٔ کاربردی:

```bash
# فقط پردازش صفحه‌های ۰ تا ۲
surya_ocr ./document.pdf --page_range 0-2 --output_dir ./bina-output

# ذخیرهٔ تصویر صفحه‌ها همراه با کادرهای تشخیص‌داده‌شده
surya_ocr ./document.pdf --images --output_dir ./bina-output
```

### نمونهٔ پایتون

متغیرهای محیطی را پیش از import کردن `surya` تنظیم کنید:

```python
import os

os.environ["SURYA_MODEL_CHECKPOINT"] = "Reza2kn/Bina-0.1-Koochik"
os.environ["SURYA_INFERENCE_BACKEND"] = "vllm"

from PIL import Image
from surya.inference import SuryaInferenceManager
from surya.recognition import RecognitionPredictor

image = Image.open("page.jpg").convert("RGB")
manager = SuryaInferenceManager()
predictor = RecognitionPredictor(manager)
result = predictor([image])[0]

for block in result.blocks:
    print(block.html)
```

> **CPU و Apple Silicon:** این مخزن شامل وزن‌های BF16 است و فایل GGUF ندارد؛
> بنابراین مسیر خودکار `llama.cpp` نمی‌تواند بینا ۰.۱ کوچک را مستقیماً اجرا کند.
> از روش NVIDIA/vLLM بالا یا یک تبدیل GGUF مخصوص بینا استفاده کنید.

## Provenance

- LoRA checkpoint: `checkpoints/checkpoint-step-0008000`
- Merged artifact path on the release host: `/home/rezo/triple-threat/hf-cache/surya-step8000-merged`
- Architecture: `Qwen3_5ForConditionalGeneration`
- Weight dtype: BF16
- `model.safetensors` SHA-256: `2193be4ef3d2366438121a15b7a1dea2bb85b24f83145e5a39bfa1f387891ada`
- `config.json` SHA-256: `e0de22be177070f206106c184d062176fcda591d9114068c42489ffc550488de`

## Intended use

Persian document OCR. The model is currently served as **بینا ۰.۱ کوچک** on
PersianVLM.com. Use deterministic decoding for baseline comparisons.

## License

This release follows the upstream Surya OCR 2 OpenRAIL license. Review the
upstream license before redistribution or deployment.


## FP16 compatibility derivative

This repository is a storage-converted FP16 derivative of Reza2kn/Bina-0.1-Koochik. It is intended for NVIDIA Pascal GPUs such as the GTX 1070 (compute capability 6.1), which cannot execute BF16.

- Source checkpoint: Reza2kn/Bina-0.1-Koochik
- Conversion: floating-point tensors BF16 to FP16; non-floating tensors unchanged
- Intended runtime: Hugging Face Transformers with FP16; use eager attention on older GPUs
- This is not a vLLM target: current vLLM NVIDIA builds require newer compute capability than Pascal
- Validate OCR output against the BF16 source for your own workload before treating it as exact parity