Developer docs / AI Fabric tutorials
Document OCR web app
- Web endpoint
- Image DSL
Optical character recognition has a reputation for being heavyweight: big models, a GPU, a finicky stack. For everyday document text it doesn't need to be any of that. Tesseract is a mature, CPU-only OCR engine that ships as a single Debian package, and in this tutorial you'll wrap it in an AI Fabric web endpoint: POST an image, get back the extracted text as JSON, plus per-word boxes and confidence scores you can use to highlight.
Because there's no model to download and no CUDA to set up, this endpoint is cheap to run and quick to cold-start. You'll scale it to zero when idle, so it costs nothing between requests and spins up on the first call.
Before you start
You need the AI Fabric CLI installed and authenticated: run blade setup once. Everything here is CPU-only, so no GPU is requested. You don't need to supply an image either: the script generates its own sample so blade run works with no setup.
Build a CPU image with Tesseract
Start from fabric/base (a small Python image, no torch), install the tesseract-ocr system package, then add the thin Python wrapper pytesseract and Pillow for image handling. pytesseract shells out to the tesseract binary, so the apt package is the part that matters:
import bladekit
app = bladekit.app("ocr-web")
# Tesseract is a battle-tested OCR engine that ships as a Debian package.
# pytesseract is a thin Python wrapper around the `tesseract` binary. No GPU,
# no torch: CPU is plenty for document OCR.
image = (
bladekit.Image.from_catalog("fabric/base")
.apt_install("tesseract-ocr")
.pip_install("pytesseract", "Pillow")
)Write the OCR endpoint
Decorate the function with both @app.web_endpoint (so it answers HTTP POSTs) and @app.function. It takes a base64-encoded image, decodes it to a PIL.Image, and runs Tesseract twice: image_to_string for the plain text, and image_to_data for per-word boxes and confidence, handy if the caller wants to draw highlights. Set min_replicas=0 so it scales to zero when idle:
@app.web_endpoint(methods=["POST"], min_replicas=0, max_replicas=4)
@app.function(image=image, timeout=60)
def ocr(item: dict) -> dict:
import base64, io
import pytesseract
from PIL import Image as PILImage
img_bytes = base64.b64decode(item["image_b64"])
img = PILImage.open(io.BytesIO(img_bytes)).convert("RGB")
text = pytesseract.image_to_string(img).strip()
# image_to_data gives per-word boxes + confidence so callers can highlight.
data = pytesseract.image_to_data(img, output_type=pytesseract.Output.DICT)
blocks = [
{"text": data["text"][i],
"confidence": float(data["conf"][i]),
"bbox": [data["left"][i], data["top"][i],
data["width"][i], data["height"][i]]}
for i in range(len(data["text"]))
if data["text"][i].strip() and float(data["conf"][i]) >= 0
]
return {"text": text, "blocks": blocks}Generate a sample image remotely
So the tutorial runs with zero setup, add a tiny helper that draws a sample image and returns it as base64. The catch: do it in a remote function, not in your local_entrypoint. Pillow lives in the image, not on your laptop, so generating the image remotely means blade run needs nothing installed locally:
@app.function(image=image)
def make_sample() -> str:
# Generate the demo image REMOTELY. Pillow lives in the image, not on your
# laptop, so `blade run` needs nothing installed locally.
import base64, io
from PIL import Image as PILImage, ImageDraw
img = PILImage.new("RGB", (480, 120), "white")
ImageDraw.Draw(img).text((20, 45), "HELLO FABRIC 2026", fill="black")
buf = io.BytesIO()
img.save(buf, format="PNG")
return base64.b64encode(buf.getvalue()).decode()Wire up a smoke test
The local_entrypoint chains the two functions: generate the sample remotely, OCR it remotely, print the text. This is the self-contained smoke test, with no external file, no local dependencies:
@app.local_entrypoint()
def main():
# Self-contained smoke test: the sample image is generated remotely, OCR'd,
# and the text printed. No external file, no local dependencies.
image_b64 = make_sample.remote()
result = ocr.remote({"image_b64": image_b64})
print("OCR text:", result["text"])Run the smoke test, then deploy
First run it locally to confirm the pipeline works. It should print HELLO FABRIC 2026:
blade run ocr_web.pyHappy with it? Deploy the endpoint to get a stable URL:
blade deploy ocr_web.pyCall it over HTTP
Endpoints are private by default, so pass your AI Fabric token. POST a base64-encoded image and you get back the full text plus the per-word blocks:
curl -X POST <URL> -H 'Authorization: Bearer <FABRIC_TOKEN>' -d '{"image_b64": "..."}'Take it for a spin
Everything above in one file, ready to run.
import bladekit
app = bladekit.app("ocr-web")
# Tesseract is a battle-tested OCR engine that ships as a Debian package.
# pytesseract is a thin Python wrapper around the `tesseract` binary. No GPU,
# no torch. CPU is plenty for document OCR.
image = (
bladekit.Image.from_catalog("fabric/base")
.apt_install("tesseract-ocr")
.pip_install("pytesseract", "Pillow")
)
@app.web_endpoint(methods=["POST"], min_replicas=0, max_replicas=4)
@app.function(image=image, timeout=60)
def ocr(item: dict) -> dict:
import base64, io
import pytesseract
from PIL import Image as PILImage
img_bytes = base64.b64decode(item["image_b64"])
img = PILImage.open(io.BytesIO(img_bytes)).convert("RGB")
text = pytesseract.image_to_string(img).strip()
# image_to_data gives per-word boxes + confidence so callers can highlight.
data = pytesseract.image_to_data(img, output_type=pytesseract.Output.DICT)
blocks = [
{"text": data["text"][i],
"confidence": float(data["conf"][i]),
"bbox": [data["left"][i], data["top"][i],
data["width"][i], data["height"][i]]}
for i in range(len(data["text"]))
if data["text"][i].strip() and float(data["conf"][i]) >= 0
]
return {"text": text, "blocks": blocks}
@app.function(image=image)
def make_sample() -> str:
# Generate the demo image REMOTELY. Pillow lives in the image, not on your
# laptop, so `blade run` needs nothing installed locally.
import base64, io
from PIL import Image as PILImage, ImageDraw
img = PILImage.new("RGB", (480, 120), "white")
ImageDraw.Draw(img).text((20, 45), "HELLO FABRIC 2026", fill="black")
buf = io.BytesIO()
img.save(buf, format="PNG")
return base64.b64encode(buf.getvalue()).decode()
@app.local_entrypoint()
def main():
# Self-contained smoke test: the sample image is generated remotely, OCR'd,
# and the text printed, with no external file and no local dependencies.
image_b64 = make_sample.remote()
result = ocr.remote({"image_b64": image_b64})
print("OCR text:", result["text"])Concepts used: Endpoint, Scale-to-zero, Run