| --- |
| license: other |
| license_name: qwen-research |
| license_link: LICENSE |
| base_model: XingChen-AGI/TeleOCR |
| base_model_relation: quantized |
| pipeline_tag: image-text-to-text |
| library_name: gguf |
| tags: [gguf, ocr, crispembed, document-parsing, teleocr, qwen2.5-vl, non-commercial] |
| --- |
| # TeleOCR GGUF (CrispEmbed) |
|
|
| GGUF conversions of [XingChen-AGI/TeleOCR](https://huggingface.co/XingChen-AGI/TeleOCR/tree/b3f6a0c084db72f971e19a779d2fd8a6bc9e3b8d) |
| by XingChen-AGI / China Telecom, for [CrispEmbed](https://github.com/CrispStrobe/CrispEmbed)'s native ggml runtime. |
| All credit for the model belongs to the original authors; these files only change the storage format. |
| They target CrispEmbed's TeleOCR profile (`general.architecture = teleocr`, GGUF v1) and are not loadable by llama.cpp. |
|
|
| ## License and attribution |
|
|
| - **Non-commercial use only.** TeleOCR's vision encoder derives from [Qwen/Qwen2.5-VL-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct), which Alibaba Cloud releases under the **Qwen RESEARCH LICENSE AGREEMENT** (`LICENSE`, verbatim). That agreement governs these weights: research and evaluation use only; commercial use requires a license from Alibaba Cloud. |
| - The upstream TeleOCR card declares `apache-2.0`; that declaration (`LICENSE-APACHE-2.0`) covers the TeleOCR authors' own contributions but cannot relax the inherited Qwen terms (agreement section 3d). The lineage evidence (per-tensor weight cosines against every Qwen2.5-VL tower) is in CrispEmbed's `tests/results/licenses/qwen-vision-lineage.json`. |
| - `NOTICE` carries the attribution the Qwen agreement requires. **Built with Qwen.** |
| - CrispEmbed only loads these files with `CRISPEMBED_ACCEPT_QWEN_RESEARCH_LICENSE=1`, and its model registry requires `--accept-license qwen-research` to download them. |
| - `UPSTREAM_README.md` is the unmodified upstream model card at revision `b3f6a0c084db72f971e19a779d2fd8a6bc9e3b8d` |
| (SHA256 `176c705cd92eeb9006c048e72274741e839f2bafa2bae858e64c3277264eb0db`). |
|
|
| ## Statement of changes (Apache-2.0 section 4(b)) |
|
|
| These files were modified from the original by CrispEmbed: the safetensors weights of revision |
| `b3f6a0c084db72f971e19a779d2fd8a6bc9e3b8d` were **format-converted** to GGUF (tensor renaming, casting, tokenizer and |
| preprocessing metadata embedded) and, where noted, **quantized**. |
| No weights were trained, fine-tuned, merged or otherwise altered. |
|
|
| ## Files |
|
|
| | File | Precision | Bytes | SHA256 | |
| |---|---|---:|---| |
| | `teleocr-f16.gguf` | F16 | 2,526,109,984 | `6c52a2800e313964717cf4e5d06e0392c2b5936d8adeac423d563b8a026a2780` | |
| | `teleocr-q8_0.gguf` | Q8_0 | 2,113,233,248 | `9de7e45ce6c13ba03d3d2879f2a1bff9f8407e12808be588cf057cd2553f224b` | |
| | `teleocr-q4_k-m.gguf` | Q4_K_M | 1,923,310,816 | `e975568f8bd069b3bc81364d10b38143a834922cdf600150e7e74084bfbce293` | |
|
|
| - **F16**: F16 matrices, F32 norms/biases |
| - **Q8_0**: decoder matrices Q8_0; vision, merger and tied embedding F16 |
| - **Q4_K_M**: decoder Q4_K with ffn_down/attn_v Q6_K; vision, merger and tied embedding F16 |
| |
| ## How the files were produced |
| |
| 1. Downloaded `XingChen-AGI/TeleOCR` at the pinned revision `b3f6a0c084db72f971e19a779d2fd8a6bc9e3b8d`; the converter |
| (`models/convert-teleocr-to-gguf.py`) checks the source files, tensor names and shapes. |
| 2. Quantized variants were produced with CrispEmbed's own `crispembed-quantize` from the listed source GGUF. |
| 3. Built and uploaded by CrispEmbed commit `4132e9e2de45b825d55febafa27ebf3895043788` (workflow `ocr-gguf-publish.yml`, |
| protocol `docs/teleocr-publication-v1.json`); `manifest.json` lists every recipe, input pin, receipt and file hash. |
| |
| ## Parity status (CrispEmbed native vs. the original Python model, CPU, greedy) |
| |
| - The reference arms (f32) reproduce the original model's generated token IDs |
| **exactly** on all 6 frozen requests (`text` (66), `formula` (166), `table` (283), `code` (366), `layout` (768), `synthetic` (19) tokens), CrispEmbed commit |
| `9d24b621`, reference revision `b3f6a0c084db`. |
| - **F16** is token-ID exact on the same 6 cases (receipt `tests/results/teleocr/hosted-precision.json`); **Q8_0** is token-ID exact on the same 6 cases (receipt `tests/results/teleocr/hosted-precision.json`); **Q4_K_M** is token-ID exact on the same 6 cases (receipt `tests/results/teleocr/hosted-precision.json`). |
| - Strict intermediate numerical budgets are not met, including F32: one-ulp differences on the model's massive activations are amplified where they emerge (vision block 17); decoded IDs and text are exact. Also not verified: GPU numerical parity, other CPU/kernel combinations, mobile/WASM, aggregate OCR benchmarks beyond the six frozen cases. |
| |
| ## Usage |
| |
| TeleOCR support is experimental and default-off in CrispEmbed (CPU by default), and non-commercial only: |
| |
| ```bash |
| CRISPEMBED_TELEOCR=1 CRISPEMBED_ACCEPT_QWEN_RESEARCH_LICENSE=1 crispembed --ocr-pipeline page.png \\ |
| --ocr-engine teleocr --ocr-rec teleocr-f16.gguf |
| ``` |
| |
