Scientific PDF Translate — Setup Guide

AnyLLMTranslate Layout-preserving PDF translation via a local Docker bridge (pdf2zh)

Overview

PDF Translate in AnyLLMTranslate runs through a small local service called the Scientific PDF bridge. It wraps pdf2zh and preserves layout, math, and formulas. The bridge listens on http://127.0.0.1:17890 and uses your existing provider pool — no second API key.

There is no in-browser "Fast" PDF path: the bridge must be running for PDF Translate to appear in the viewer.

Two ways to run it. Pick one: Quick Start downloads a prebuilt image (~1 min, recommended for most users). Build from source compiles the image from this repo (for developers).

Prerequisites

Docker:
- macOS / Windows: Docker Desktop (start it before the steps below)
- Linux: Docker Engine + the docker compose plugin — e.g. sudo apt install docker.io docker-compose-v2 (Ubuntu/Debian)
Terminal — macOS/Linux: Terminal; Windows: PowerShell (or Git Bash for the shell script).
The bridge image is ~2 GB when pulled/built — first run takes a moment.

Quick Start — pull the prebuilt image

Recommended. No repository clone, no build. Docker pulls a ready-made image from the GitHub Container Registry.

1. Create a compose file

Save this as docker-compose.scientific-pdf.yml in any empty folder:

services:
  scientific-pdf-bridge:
    image: ghcr.io/nguyensitrung/anyllm-scientific-pdf-bridge:latest
    container_name: anyllm-scientific-pdf
    ports:
      - "17890:17890"
    environment:
      MOCK_TRANSLATE: "${MOCK_TRANSLATE:-0}"
      JOB_TTL_SECONDS: "${JOB_TTL_SECONDS:-3600}"
      SCIENTIFIC_PDF_DATA_DIR: /data
      HF_ENDPOINT: "${HF_ENDPOINT:-}"
      HF_HOME: /root/.cache/huggingface
    volumes:
      - scientific-pdf-data:/data
      - scientific-pdf-models:/root/.cache
    restart: unless-stopped

volumes:
  scientific-pdf-data:
  scientific-pdf-models:

2. Start it

docker compose -f docker-compose.scientific-pdf.yml up -d

The first pull downloads ~2 GB; subsequent starts are instant.

3. Verify

curl -sS http://127.0.0.1:17890/health

Expect: {"status":"ok","version":"1.0.0","pdf2zh":"available"} — then continue at Connect in the extension.

Build from source (developer path)

Use this if you develop the bridge, or prefer to build everything yourself. You need git plus the prerequisites above.

1. Clone the repo

git clone https://github.com/NguyenSiTrung/AnyLLMTranslate.git
cd AnyLLMTranslate

2. Build and start (helper script)

chmod +x scripts/scientific-pdf-docker.sh
./scripts/scientific-pdf-docker.sh up

The script stops any existing container, builds the image, starts it, and waits for /health. First build takes several minutes (Python packages + pdf2zh). The build log should include pdf2zh import ok.

Manual compose (equivalent, Windows-friendly)

docker compose -f docker-compose.scientific-pdf.yml down
docker compose -f docker-compose.scientific-pdf.yml up -d --build
curl -sS http://127.0.0.1:17890/health

Verify the bridge

Container: docker ps --filter name=anyllm-scientific-pdf should list it as Up.
Health: curl -sS http://127.0.0.1:17890/health → {"status":"ok",…}.
Logs (if something looks wrong): docker logs -f anyllm-scientific-pdf.

Connect in the extension

Open Options → Advanced → Scientific PDF.
Toggle Enable PDF bridge on. Leave the server URL at the default http://127.0.0.1:17890.
Click Set up… → follow the wizard (health poll + connection test).
Open a PDF in the built-in viewer — wait for Bridge ready — then click Translate.

Jobs use your active provider pool (including rate limits and concurrency). Progress and logs appear in a modal; results download as mono / dual / side-by-side PDFs.

Everyday commands

With the repo cloned (script) or with the compose file (manual):

# script (repo root)
./scripts/scientific-pdf-docker.sh start    # start without rebuild
./scripts/scientific-pdf-docker.sh down     # stop
./scripts/scientific-pdf-docker.sh status   # container + health
./scripts/scientific-pdf-docker.sh logs     # follow logs (Ctrl+C)

# manual (any folder with the compose file)
docker compose -f docker-compose.scientific-pdf.yml up -d
docker compose -f docker-compose.scientific-pdf.yml down

After a reboot, Docker Desktop must be started, then re-run the up command — the container restarts automatically (restart: unless-stopped), but the Docker daemon needs to be up.

Updates & rebuilds

Prebuilt image (Quick Start)

docker compose -f docker-compose.scientific-pdf.yml pull
docker compose -f docker-compose.scientific-pdf.yml up -d

Source build

Extension UI changes never need a Docker rebuild. Rebuild only when bridge code or the Dockerfile changed:

git pull
./scripts/scientific-pdf-docker.sh rebuild

Troubleshooting

Symptom	Fix
`curl` connection refused	Container not running → `docker compose … up -d`, then check `docker ps`.
Wizard shows "Offline"	Same — check the container and port `17890`.
`TextTranslateRequest` / pdf2zh import crash	Rebuild with the current Dockerfile (Tencent SDK pin).
`RateLimError` in logs	Use a chat/instruct model; lower concurrency; check provider RPM.
First job is very slow	Normal — fonts/models download once into the Docker volumes.
Permission denied on `docker.sock`	Use Docker Desktop user permissions, or `sudo docker …` on Linux.

Privacy

Scientific jobs send the full PDF and short-lived provider credentials to the configured server URL — default loopback only. Prefer http://127.0.0.1:17890. See the full Privacy Policy for every data type the extension handles and where it goes.