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 clairic_runtime/recurrent_metadata.py from Cloudflare/clairic: direct link, hf CLI and curl.
- Browser
- Download file 5.32 kB
-
https://huggingface.co/Cloudflare/clairic/resolve/main/clairic_runtime/recurrent_metadata.py
- Command line
-
hf download hf://Cloudflare/clairic/clairic_runtime/recurrent_metadata.py
-
curl -L -o recurrent_metadata.py https://huggingface.co/Cloudflare/clairic/resolve/main/clairic_runtime/recurrent_metadata.py
5.32 kB
| """Share read-only recurrent packing metadata during one inference forward.""" | |
| from __future__ import annotations | |
| from collections.abc import Callable, Iterator | |
| from contextlib import contextmanager | |
| from contextvars import ContextVar | |
| from typing import Any | |
| import torch | |
| class _Forward: | |
| def __init__(self, hook_owner: torch.nn.Module | None = None) -> None: | |
| self.hook_owner = hook_owner | |
| self.unversioned_mask_allowed: bool | None = None | |
| self.hook_checks = 0 | |
| self.key: tuple[Any, ...] | None = None | |
| self.mask: torch.Tensor | None = None | |
| self.packed: tuple[torch.Tensor, torch.Tensor] | None = None | |
| self.slots_key: tuple[Any, ...] | None = None | |
| self.slots: torch.Tensor | None = None | |
| self.materializations = 0 | |
| self.hits = 0 | |
| self.slots_materializations = 0 | |
| self.slots_hits = 0 | |
| def clear(self) -> None: | |
| self.key, self.mask, self.packed = None, None, None | |
| self.slots_key, self.slots = None, None | |
| self.hook_owner, self.unversioned_mask_allowed = None, None | |
| _current: ContextVar[_Forward | None] = ContextVar("clairic_recurrent_metadata", default=None) | |
| _MAX_BYTES = 8 * 1024**2 | |
| def scope(hook_owner: torch.nn.Module | None = None) -> Iterator[None]: | |
| """Drop all added references on success, cancellation, or model failure.""" | |
| state = _Forward(hook_owner) | |
| token = _current.set(state) | |
| try: | |
| yield | |
| finally: | |
| state.clear() | |
| _current.reset(token) | |
| def _eligible(mixed: torch.Tensor) -> _Forward | None: | |
| state = _current.get() | |
| if (state is None or not mixed.is_cuda or mixed.dtype != torch.bfloat16 | |
| or mixed.ndim != 3 or torch.is_grad_enabled() | |
| or not torch.is_inference_mode_enabled() or torch.compiler.is_compiling()): | |
| return None | |
| return state | |
| def _no_forward_hooks(owner: torch.nn.Module | None) -> bool: | |
| """Admit only a known hook-free tree and hook-free global registries.""" | |
| if not isinstance(owner, torch.nn.Module): | |
| return False | |
| registry = torch.nn.modules.module | |
| for name in ("_global_forward_pre_hooks", "_global_forward_hooks"): | |
| hooks = getattr(registry, name, None) | |
| if hooks is None or hooks: | |
| return False | |
| for module in owner.modules(): | |
| for name in ("_forward_pre_hooks", "_forward_hooks"): | |
| hooks = getattr(module, name, None) | |
| if hooks is None or hooks: | |
| return False | |
| return True | |
| def packed_indices(mixed: torch.Tensor, mask: torch.Tensor | None, | |
| original: Callable[[torch.Tensor, torch.Tensor | None], | |
| tuple[torch.Tensor, torch.Tensor]] | |
| ) -> tuple[torch.Tensor, torch.Tensor]: | |
| """Reuse the original helper's exact results for an unchanged current mask.""" | |
| state = _eligible(mixed) | |
| batch, length = mixed.shape[:2] | |
| required = batch * length * 8 + (2 * batch + 1) * 4 | |
| if state is None or required > _MAX_BYTES: | |
| return original(mixed, mask) | |
| stream = torch.cuda.current_stream(mixed.device).cuda_stream | |
| mask_key: tuple[Any, ...] = () | |
| if mask is not None: | |
| try: | |
| version = mask._version | |
| except RuntimeError: | |
| version = None | |
| if version is None: | |
| if state.unversioned_mask_allowed is None: | |
| state.hook_checks += 1 | |
| state.unversioned_mask_allowed = _no_forward_hooks(state.hook_owner) | |
| if not state.unversioned_mask_allowed: | |
| state.key, state.mask, state.packed = None, None, None | |
| return original(mixed, mask) | |
| mask_key = (id(mask), version, mask.data_ptr(), mask.storage_offset(), | |
| mask.device, mask.dtype, tuple(mask.shape), tuple(mask.stride())) | |
| key = (batch, length, mixed.device, stream, mask_key) | |
| if state.key == key and state.mask is mask and state.packed is not None: | |
| state.hits += 1 | |
| return state.packed | |
| state.key, state.mask, state.packed = None, None, None | |
| if state.slots_key != (batch, mixed.device, stream): | |
| state.slots_key, state.slots = None, None | |
| packed = original(mixed, mask) | |
| retained = sum(value.numel() * value.element_size() for value in packed) | |
| if retained + batch * 4 <= _MAX_BYTES: | |
| state.key, state.mask, state.packed = key, mask, packed | |
| state.materializations += 1 | |
| return packed | |
| def sequence_slots(mixed: torch.Tensor) -> torch.Tensor: | |
| """Reuse the same identity slot vector in each recurrent layer.""" | |
| state = _eligible(mixed) | |
| batch = mixed.shape[0] | |
| retained = (sum(value.numel() * value.element_size() for value in state.packed) | |
| if state is not None and state.packed is not None else 0) | |
| if state is None or retained + batch * 4 > _MAX_BYTES: | |
| return torch.arange(batch, dtype=torch.int32, device=mixed.device) | |
| key = (batch, mixed.device, torch.cuda.current_stream(mixed.device).cuda_stream) | |
| if state.slots_key != key or state.slots is None: | |
| state.slots = torch.arange(batch, dtype=torch.int32, device=mixed.device) | |
| state.slots_key = key | |
| state.slots_materializations += 1 | |
| else: | |
| state.slots_hits += 1 | |
| return state.slots | |