Image-Text-to-Text
Transformers
Safetensors
qwen3_5
clairic
cloudflare
systemone
multimodal
structured-output
information-extraction
custom-code
conversational
Instructions to use Cloudflare/clairic-flash with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use Cloudflare/clairic-flash with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("image-text-to-text", model="Cloudflare/clairic-flash") 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-flash") model = AutoModelForMultimodalLM.from_pretrained("Cloudflare/clairic-flash", 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-flash with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "Cloudflare/clairic-flash" # 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-flash", "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-flash
- SGLang
How to use Cloudflare/clairic-flash 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-flash" \ --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-flash", "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-flash" \ --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-flash", "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-flash with Docker Model Runner:
docker model run hf.co/Cloudflare/clairic-flash
Download clairic_runtime/api.py from Cloudflare/clairic-flash: direct link, hf CLI and curl.
- Browser
- Download file 6.86 kB
-
https://huggingface.co/Cloudflare/clairic-flash/resolve/main/clairic_runtime/api.py
- Command line
-
hf download hf://Cloudflare/clairic-flash/clairic_runtime/api.py
-
curl -L -o api.py https://huggingface.co/Cloudflare/clairic-flash/resolve/main/clairic_runtime/api.py
6.86 kB
| """Clairic request and response schemas.""" | |
| from __future__ import annotations | |
| import base64 | |
| import io | |
| from dataclasses import dataclass | |
| from typing import Any, LiteralString, cast | |
| from .embedded import ( | |
| MAX_IMAGE_BYTES, | |
| MAX_IMAGES, | |
| MAX_IMAGES_BYTES, | |
| EmbeddedImageError, | |
| decoded_base64_size, | |
| normalize_embedded_image, | |
| validate_image_count, | |
| validate_total_image_bytes, | |
| ) | |
| from PIL import Image, ImageOps | |
| from pydantic import ( | |
| BaseModel, | |
| ConfigDict, | |
| Field, | |
| StrictStr, | |
| field_validator, | |
| model_validator, | |
| ) | |
| from pydantic_core import PydanticCustomError | |
| from .documents import ClairDocument | |
| MODEL_ID = "clairic" | |
| def _image_error(error: EmbeddedImageError) -> PydanticCustomError: | |
| # Every code and message originates from fixed literals in the shared helper. | |
| return PydanticCustomError( | |
| cast(LiteralString, error.code), cast(LiteralString, str(error)) | |
| ) | |
| class ClairImage(BaseModel): | |
| """An embedded PNG, JPEG, or WebP image validated before it reaches the processor.""" | |
| model_config = ConfigDict(extra="forbid", frozen=True) | |
| content_type: StrictStr | |
| base64: StrictStr | |
| rotation: int = 0 | |
| def parse_image(cls, value: object) -> object: | |
| try: | |
| rotation = 0 | |
| explicit_rotation = isinstance(value, dict) and "rotation" in value | |
| if explicit_rotation: | |
| value = dict(value) # type: ignore[call-overload] # explicit_rotation guards the dict input. | |
| rotation = value.pop("rotation") # type: ignore[attr-defined] | |
| if type(rotation) is not int or rotation not in (0, 90, 180, 270): | |
| raise EmbeddedImageError( | |
| "invalid_image", | |
| "rotation must be 0, 90, 180 or 270 clockwise degrees", | |
| ) | |
| normalized = normalize_embedded_image( | |
| value, strict=True, max_image_bytes=MAX_IMAGE_BYTES | |
| ) | |
| return ( | |
| {**normalized, "rotation": rotation} | |
| if explicit_rotation | |
| else normalized | |
| ) | |
| except EmbeddedImageError as error: | |
| raise _image_error(error) from error | |
| def to_pil(self) -> Image.Image: | |
| from .orientation import orient_document | |
| with Image.open(io.BytesIO(base64.b64decode(self.base64))) as image: | |
| result = ImageOps.exif_transpose(image) | |
| if "A" in result.getbands() or "transparency" in result.info: | |
| # Render visible document pixels before discarding alpha. Hidden | |
| # RGB values can otherwise erase opaque black text completely. | |
| rgba = result if result.mode == "RGBA" else result.convert("RGBA") | |
| result = Image.new("RGB", rgba.size, "white") | |
| result.paste(rgba, mask=rgba.getchannel("A")) | |
| else: | |
| result = result.convert("RGB") | |
| if "rotation" in self.model_fields_set: | |
| return ( | |
| result.rotate(-self.rotation, expand=True) | |
| if self.rotation | |
| else result | |
| ) | |
| return orient_document(result) | |
| def decoded_size(self) -> int: | |
| return decoded_base64_size(self.base64) | |
| class PredictOptions(BaseModel): | |
| model_config = ConfigDict(extra="forbid") | |
| include_quantiles: bool = False | |
| return_state_text: bool = False | |
| class PredictRequest(BaseModel): | |
| """A state (any text), optional images, and any number of typed fields. Field specs are checked against | |
| the field schema when the request is encoded.""" | |
| model_config = ConfigDict(extra="forbid") | |
| model: StrictStr | None = None | |
| state: StrictStr = "" | |
| images: tuple[ClairImage, ...] = Field( | |
| default=(), json_schema_extra={"maxItems": MAX_IMAGES} | |
| ) | |
| documents: tuple[ClairDocument, ...] = Field(default=(), max_length=MAX_IMAGES) | |
| fields: dict[StrictStr, dict[StrictStr, Any]] | |
| reference_date: StrictStr | None = None | |
| options: PredictOptions = Field(default_factory=PredictOptions) | |
| def check_image_count(cls, value: object) -> object: | |
| try: | |
| return validate_image_count(value, max_images=MAX_IMAGES) | |
| except EmbeddedImageError as error: | |
| raise _image_error(error) from error | |
| def check_content(self) -> PredictRequest: | |
| if not self.fields: | |
| raise PydanticCustomError( | |
| "empty_fields", "fields must declare at least one field" | |
| ) | |
| if not self.state.strip() and not self.images and not self.documents: | |
| raise PydanticCustomError( | |
| "empty_state", "state must be non-empty when no images are sent" | |
| ) | |
| try: | |
| validate_total_image_bytes( | |
| ( | |
| decoded_base64_size(item.base64) | |
| for item in (*self.images, *self.documents) | |
| ), | |
| max_bytes=MAX_IMAGES_BYTES, # type: ignore[attr-defined] # Both validated media types have base64. | |
| ) | |
| except EmbeddedImageError as error: | |
| raise _image_error(error) from error | |
| return self | |
| class PredictOutput: | |
| answers: dict[str, dict[str, Any]] | |
| truncated: bool | |
| state_tokens: int | |
| image_tokens: int | |
| schema_tokens: int | |
| input_tokens: int | |
| passes: int | |
| state_text: str | None = None | |
| output_tokens: int = 0 | |
| def _without_quantiles(answer: dict[str, Any]) -> dict[str, Any]: | |
| answer = {key: value for key, value in answer.items() if key != "quantiles"} | |
| if isinstance(answer.get("steps"), list): | |
| answer["steps"] = [_without_quantiles(step) for step in answer["steps"]] | |
| return answer | |
| def serialize_response( | |
| request: PredictRequest, output: PredictOutput, model_id: str | |
| ) -> dict[str, Any]: | |
| answers = { | |
| name: answer | |
| if request.options.include_quantiles | |
| else _without_quantiles(answer) | |
| for name, answer in output.answers.items() | |
| } | |
| content: dict[str, Any] = { | |
| "model": model_id, | |
| "answers": answers, | |
| "truncated": output.truncated, | |
| "usage": { | |
| "state_tokens": output.state_tokens, | |
| "image_tokens": output.image_tokens, | |
| "schema_tokens": output.schema_tokens, | |
| "input_tokens": output.input_tokens, | |
| "output_tokens": output.output_tokens, | |
| "passes": output.passes, | |
| }, | |
| } | |
| if request.options.return_state_text and output.state_text is not None: | |
| content["state_text"] = output.state_text | |
| return content | |