Image-Text-to-Text
Transformers
Safetensors
qwen3_5
clairic
cloudflare
systemone
multimodal
structured-output
information-extraction
custom-code
conversational
Instructions to use Cloudflare/clairic with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use Cloudflare/clairic with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("image-text-to-text", model="Cloudflare/clairic") messages = [ { "role": "user", "content": [ {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"}, {"type": "text", "text": "What animal is on the candy?"} ] }, ] pipe(text=messages)# pip install -U transformers accelerate # Load model directly from transformers import AutoProcessor, AutoModelForMultimodalLM processor = AutoProcessor.from_pretrained("Cloudflare/clairic") model = AutoModelForMultimodalLM.from_pretrained("Cloudflare/clairic", device_map="auto") messages = [ { "role": "user", "content": [ {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"}, {"type": "text", "text": "What animal is on the candy?"} ] }, ] inputs = processor.apply_chat_template( messages, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt", ).to(model.device) outputs = model.generate(**inputs, max_new_tokens=256) print(processor.decode(outputs[0][inputs["input_ids"].shape[-1]:])) - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- vLLM
How to use Cloudflare/clairic with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "Cloudflare/clairic" # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Cloudflare/clairic", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }'Use Docker
docker model run hf.co/Cloudflare/clairic
- SGLang
How to use Cloudflare/clairic with SGLang:
Install from pip and serve model
# Install SGLang from pip: pip install sglang # Start the SGLang server: python3 -m sglang.launch_server \ --model-path "Cloudflare/clairic" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Cloudflare/clairic", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }'Use Docker images
docker run --gpus all \ --shm-size 32g \ -p 30000:30000 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ --env "HF_TOKEN=<secret>" \ --ipc=host \ lmsysorg/sglang:latest \ python3 -m sglang.launch_server \ --model-path "Cloudflare/clairic" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Cloudflare/clairic", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }' - Docker Model Runner
How to use Cloudflare/clairic with Docker Model Runner:
docker model run hf.co/Cloudflare/clairic
|
Download README.md from Cloudflare/clairic: direct link, hf CLI and curl.
- Browser
- Download file 6.69 kB
-
https://huggingface.co/Cloudflare/clairic/resolve/main/README.md
- Command line
-
hf download hf://Cloudflare/clairic/README.md
-
curl -L -o README.md https://huggingface.co/Cloudflare/clairic/resolve/main/README.md
6.69 kB
| license: apache-2.0 | |
| library_name: transformers | |
| base_model: Qwen/Qwen3.8-27B | |
| pipeline_tag: image-text-to-text | |
| tags: | |
| - clairic | |
| - cloudflare | |
| - systemone | |
| - multimodal | |
| - structured-output | |
| - information-extraction | |
| - custom-code | |
| # Clairic | |
| Clairic is a 27B multimodal model that turns a state and a schema of typed fields | |
| into structured answers. It supports text and image inputs, extraction, numerical | |
| estimation, and forecasting. Each field has its own value and scoring information; | |
| the response also reports input truncation and token usage. | |
| See [Clairic Flash](https://huggingface.co/Cloudflare/clairic-flash) for the other model | |
| in the Clairic family. | |
| ## Model | |
| - **Base model:** [Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B). | |
| - **Inputs:** a text or JSON state, optional images, and a mapping of field names to specifications. | |
| - **Outputs:** typed values, lists, nulls, estimates, and forecast paths. | |
| - **Scoring:** extraction confidence and null probabilities, plus optional quantiles for estimates. | |
| - **Runtime:** PyTorch and Transformers, with local Python request helpers. | |
| ## Usage | |
| Use Python 3.11 or later and install the packages listed in `requirements.txt`. Inference uses PyTorch and | |
| Transformers; `xgrammar` supplies schema constraints through a Transformers logits | |
| processor. | |
| Download the repository, load the model and processor, and call `systemone` with a | |
| System One: Extract request. | |
| ```python | |
| import sys | |
| from huggingface_hub import snapshot_download | |
| path = snapshot_download("Cloudflare/clairic") | |
| sys.path.insert(0, path) | |
| from clairic_model import load_release_model, systemone | |
| model, processor = load_release_model(path, device="cuda") | |
| response = systemone( | |
| model, | |
| processor, | |
| { | |
| "state": ( | |
| "Invoice from Northwind Supply. Issued 2026-09-02. " | |
| "Items: Pens; Paper. Total: $1080.00." | |
| ), | |
| "fields": { | |
| "vendor": {"type": "text", "instructions": "The invoice vendor."}, | |
| "total": {"type": "number", "decimals": 2}, | |
| "issued": {"type": "date"}, | |
| "items": { | |
| "type": "list", | |
| "items": "text", | |
| "instructions": "The purchased item names, in order.", | |
| }, | |
| }, | |
| }, | |
| ) | |
| print(response["answers"]) | |
| ``` | |
| ### Images | |
| Pass PIL images alongside the state. Embedded base64 image inputs are also accepted. | |
| ```python | |
| from PIL import Image | |
| response = systemone( | |
| model, | |
| processor, | |
| { | |
| "state": "Read the attached receipt.", | |
| "images": [Image.open("receipt.png")], | |
| "fields": { | |
| "merchant": {"type": "text", "instructions": "The merchant name."}, | |
| "total": {"type": "number", "decimals": 2}, | |
| }, | |
| }, | |
| ) | |
| print(response["answers"]) | |
| ``` | |
| ### Estimates and forecasts | |
| Declare a range for estimated values. Forecasts also specify a horizon and interval. | |
| Set `include_quantiles` to return the available quantiles. | |
| ```python | |
| response = systemone( | |
| model, | |
| processor, | |
| { | |
| "state": "Daily demand for the last seven days: 41, 45, 43, 47, 49, 46, 48.", | |
| "fields": { | |
| "next_day": {"type": "estimate", "min": 0, "max": 100}, | |
| "next_three_days": { | |
| "type": "forecast", | |
| "min": 0, | |
| "max": 100, | |
| "horizon": 3, | |
| "interval": "day", | |
| }, | |
| }, | |
| "options": {"include_quantiles": True}, | |
| }, | |
| ) | |
| print(response["answers"]) | |
| ``` | |
| ## Input format | |
| | Field | Description | | |
| |---|---| | |
| | `model` | Optional `clairic` or serving alias `clairic-27b`; `@cf/cloudflare/` aliases are accepted | | |
| | `state` | Source text; the Python helper serializes JSON values to text | | |
| | `images` | Optional PIL images or embedded base64 images | | |
| | `documents` | Optional embedded PDF data URIs or `content_type` / `base64` objects | | |
| | `fields` | Mapping of output field names to typed specifications | | |
| | `reference_date` | Optional ISO date for relative date instructions | | |
| | `options.include_quantiles` | Include available estimate and forecast quantiles | | |
| | `options.return_state_text` | Include the retained source text in the response | | |
| Field specifications support `text`, `number`, `date`, `time`, `datetime`, `duration`, | |
| `boolean`, `enum`, `object`, `list`, `compute`, `estimate`, and `forecast`. | |
| `instructions` describes what to return. Numeric fields can specify units and | |
| rounding; lists declare their item schema; estimates and forecasts require bounds. | |
| `nullable` defaults to true. `source_only: true` selects literal printed numbers, | |
| dates, times, datetimes, or number/date lists. `knowledge: true` permits knowledge | |
| answers for text, numbers, and supported list children. `compute` selects the typed | |
| numeric head. Unsupported options and invalid combinations are rejected. | |
| Embedded inputs are limited to 4 MiB each and 8 MiB combined. Images and rendered | |
| PDF pages share a four-image/page limit. Image `rotation` accepts 0, 90, 180, or 270 | |
| clockwise degrees after EXIF orientation. Remote media URLs are not accepted. | |
| ## Response | |
| `systemone` returns a dictionary with `model`, `answers`, `truncated`, and `usage`. | |
| Answers are keyed by the requested field names. Generated scalar extraction answers | |
| retain `valid`, `complete`, full-sequence `confidence`, and independently scored `p_null`. | |
| Uniquely matched text evidence includes character spans in `state`; image-only or | |
| ambiguous evidence has null spans. Lists preserve item order and duplicates. | |
| Estimates and forecasts include their typed values and, when requested, quantiles. | |
| Scores are model probabilities and should be evaluated for the application's own | |
| acceptance thresholds. Inspect `truncated` and any answer completeness indicators | |
| before relying on a result. | |
| Usage includes retries and supplemental work. The response model ID is `clairic`. | |
| The Python API raises validation or request errors for invalid inputs, a queue-full | |
| error for simultaneous requests, and an inference error for failed generation. | |
| Use `await model.predict_async(request)` in an async application; cancellation | |
| drains owned work before admitting another request. | |
| ## Files | |
| | File | Purpose | | |
| |---|---| | |
| | `model*.safetensors`, `model.safetensors.index.json`, `config.json` | Model weights and configuration | | |
| | `clair_head.safetensors`, `clair_head_config.json` | Typed output components | | |
| | `clairic_model.py` and supporting Python modules | Transformers loading and request handling | | |
| | Tokenizer and processor files | Text and image preprocessing | | |
| | `requirements.txt` | Python dependencies | | |
| | `LICENSE` | Apache-2.0 license | | |
| ## License | |
| Released under the Apache-2.0 license. | |