Bina-0.1-Koochik-GGUF

Bina 0.1 Koochik GGUF — بینا کوچک

F16 model + matching vision projector + patched runtime + Python launcher. No manual compilation or patching is needed on platforms with a bundled runtime. Python 3.9+ and your GPU vendor's Vulkan driver are required (macOS uses CPU). Windows also needs the Microsoft Visual C++ 2015–2022 x64 runtime if it is not already installed: https://aka.ms/vs/17/release/vc_redist.x64.exe.

Complete offline bundle

Download Bina-0.1-Koochik-GGUF-complete.zip from this repository and extract it. It contains the model, projector, all three runtimes, launcher, web interface, checksums, license and build/validation records. Run python3 run_bina.py page.png (Windows: py -3 run_bina.py page.png) from the extracted directory. No Hugging Face download or login is then needed.

One-line quick starts

Linux / macOS, OCR an image (replace page.png):

curl -fL https://huggingface.co/Reza2kn/Bina-0.1-Koochik-GGUF/resolve/main/run_bina.py -o run_bina.py && python3 run_bina.py page.png

Windows PowerShell, OCR an image:

Invoke-WebRequest https://huggingface.co/Reza2kn/Bina-0.1-Koochik-GGUF/resolve/main/run_bina.py -OutFile run_bina.py; if ($?) { py -3 run_bina.py page.png }

Browser UI, after downloading the launcher:

python3 run_bina.py --server

On Windows use py -3 run_bina.py --server. Open http://127.0.0.1:8080, select an image, and click Read image.

The first launch downloads about 1.34 GB of model files plus the runtime to the launcher's directory, verifies SHA-256, and starts inference. Subsequent launches work offline from that directory. Use --cpu for CPU inference. Input is an image file; PDF rendering and multi-page processing are not included.

Default context is 8,192 and maximum image tokens is 4,096 for more manageable memory usage. To restore the source image ceiling, pass --context 32768 --image-max-tokens 16384; this uses considerably more memory. Output can truncate at --max-tokens (default 2,048). Results may differ at reduced image resolution.

Compatibility: Stock llama.cpp, Ollama, and other unpatched GGUF loaders do not support this tokenizer. Use this launcher's runtime. F16 avoids K-quants, but Vulkan compatibility still depends on GPU/driver support. Check startup logs for the selected Vulkan device.

راه‌اندازی سریع

نیازی به کامپایل یا اعمال پچ نیست؛ لانچر، مدل و فایل بینایی و نسخهٔ آمادهٔ اجرا را دانلود می‌کند. برای ویندوز از دستور PowerShell بالا و برای لینوکس از دستور اول استفاده کنید. به‌جای page.png مسیر تصویر خود را بگذارید. برای اجرای پردازندهٔ مرکزی --cpu و برای رابط مرورگر --server را اضافه کنید.

Prebuilt runtimes and validation

• Linux x64: Vulkan build made on Ubuntu 24.04; requires glibc 2.39+, libstdc++, and a Vulkan driver/loader (on Ubuntu: sudo apt install libvulkan1). Verified model and vision encoder offload on NVIDIA RTX 5080 Laptop GPU, with exact reference text on one Persian crop.
• Windows x64: prebuilt Vulkan executables and DLLs included. Both executables passed startup/version checks on the Windows 2022 build runner. Windows GPU inference has not been tested. Reproducible build: https://github.com/Reza2kn/bina-llama-runtime.
• Apple Silicon macOS 26+: CPU build tested on macOS 26. No Metal/GPU acceleration in this package.

The launcher and its image OCR endpoint passed the same crop test on macOS. The web interface was verified as served; automated browser rendering was unavailable in the build environment. Tokenizer validation covers 2,043 cases with zero mismatches. This is not a full-page quality benchmark or a guarantee for every GPU.

Conversion and validation details

This package contains an F16 GGUF language model and F16 vision projector converted from Reza2kn/Bina-0.1-Koochik-FP16, revision 6282587c9a904d306f388d7b830212dbf55fa752.

The bundled runtimes already include the required patch. Stock llama.cpp binaries do not understand surya-wordlevel. This is a working conversion for testing, not a claim of validation on the recipient's GPU. Vulkan has not been tested on that hardware. F16 weights do not use K-quants.

Files

• Bina-0.1-Koochik-F16.gguf: language model.
• mmproj-Bina-0.1-Koochik-F16.gguf: matching vision projector; required for images.
• surya-wordlevel.patch: converter and runtime tokenizer support.
• SHA256SUMS: checksums.
• tokenizer-parity.json: 2,043 test cases, zero token-ID mismatches.
• ocr-result.json: real Persian crop OCR through llama-server, completed at EOS.
• ocr-comparison.json: exact output-text match with the original checkpoint on one Persian printed crop. This is a smoke test, not a broad OCR accuracy benchmark.

Exact build provenance

Official llama.cpp commit: 3057bb66c86c46d5781e50e85462a760ba7d1feb. Version output: 0.4.0-dev (build 1, commit 3057bb6) plus surya-wordlevel.patch.

Bina's architecture is Qwen3.5, but its tokenizer is WordLevel with Split(Regex("."), Isolated) and Fuse decoding. Substituting Qwen BPE rules changes token IDs. The patch preserves the 65,425-token vocabulary, the original added-token behavior, Unicode character boundaries, consecutive-LF behavior, and unknown-token handling. It writes EOS ID 2 from the tokenizer/generation configuration, not the stale nested EOS ID 248044. --no-mtp is required because the checkpoint contains no MTP tensors despite its configuration advertising an MTP layer.

Optional: build from source with Vulkan

Install CMake, a C++ compiler, Git, and the Vulkan SDK/development packages for your OS. Use the matching GPU vendor driver.

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
git checkout 3057bb66c86c46d5781e50e85462a760ba7d1feb
git apply ../surya-wordlevel.patch
cmake -S . -B build -DGGML_VULKAN=ON -DGGML_CUDA=OFF -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j 4 --target llama-mtmd-cli llama-server

On Windows, executables may be under build/bin/Release/. On Linux they are normally under build/bin/.

./build/bin/llama-mtmd-cli \
  -m ../Bina-0.1-Koochik-F16.gguf \
  --mmproj ../mmproj-Bina-0.1-Koochik-F16.gguf \
  --image page.png \
  --image-min-tokens 64 --image-max-tokens 16384 \
  -p 'OCR this image to HTML. Each block is a div with data-label and data-bbox (x0 y0 x1 y1, normalized 0-1000).' \
  -c 32768 -n 2048 --temp 0 -ngl 99

The image-token limits match the source processor's 65,536–16,777,216 pixel bounds (32×32 pixels per merged image token). Large images and context increase memory usage. Reduce the maximum image tokens/context or GPU layer count if necessary. -ngl 0 selects CPU inference for diagnosis. Verify the startup log identifies Vulkan and the expected device; a generated GGUF does not itself guarantee GPU compatibility.

Reproduce conversion

With the patched source and the pinned HF snapshot downloaded as source/:

python convert_hf_to_gguf.py source --no-mtp --outtype f16 --outfile Bina-0.1-Koochik-F16.gguf
python convert_hf_to_gguf.py source --mmproj --outtype f16 --outfile mmproj-Bina-0.1-Koochik-F16.gguf

The original tokenizer and checkpoint were not modified. The patch is deliberately scoped to this WordLevel tokenizer; stock Qwen conversion is unchanged.

License

Weights inherit the source Bina/Surya modified AI PUBS OpenRAIL-M terms; the complete upstream license is included as LICENSE. This includes use restrictions and revenue/funding conditions. Upstream model: https://huggingface.co/datalab-to/surya-ocr-2; Bina fine-tuning lineage: https://huggingface.co/Reza2kn/surya-ocr-2-persian-lora-7m. This release changes the storage/runtime format to F16 GGUF and adds a compatible tokenizer runtime; it does not retrain the model. The llama.cpp patch follows the upstream llama.cpp MIT license. Do not relabel the model weights as MIT or Apache-2.0.