danvics/docling-studio
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
docling-studio/docs/design/254-optim-taille-image-latest-local.md
Pier-Jean Malandrino 975f4057e8 docs(#254): scaffold design doc for local image size optim
2026-05-06 09:55:36 +02:00

15 KiB
Raw Blame History

Design: Optim taille image latest-local (sortir reasoning, multi-stage, dockerignore)

  • Issue: #254
  • Title on issue: [ENHANCEMENT] Optim taille image latest-local (sortir reasoning, multi-stage, dockerignore)
  • Author: Pier-Jean Malandrino
  • Date: 2026-05-06
  • Status: Draft
  • Target milestone: 0.6.0 — Doc-centric ingest
  • Impacted layers: <backend: domain | api | services | persistence | infra> · <frontend: features/ | shared | app> · · <infra/CI>
  • Audit dimensions likely touched: <pick from: Hexagonal Architecture · DDD · Clean Code · KISS · DRY · SOLID · Decoupling · Security · Tests · CI/Build · Documentation · Performance>
  • ADR spawned?: (write an ADR when choosing a library, moving a boundary, or deciding not to do something — see docs/architecture/adr-guide.md)

1. Problem

L'image latest-local empile aujourd'hui beaucoup de surface : torch + torchvision (CPU, ~800 Mo–1.2 Go), docling>=2.80, et — par effet de bord — docling-agent + mellea qui sont déclarés dans requirements.txt et donc tirés aussi par la cible remote (qui devrait être lightweight).

Le Dockerfile actuel souffre par ailleurs de plusieurs problèmes de build qui pénalisent la taille et le temps de rebuild : COPY . . se fait dans la stage base, donc toute modification de code Python invalide les layers pip install de la stage local (rebuild complet de torch à chaque commit) ; pas de stage builder isolée → pip + caches restent dans l'image finale ; .dockerignore minimal — pas d'exclusion de tests/, data/, uploads/, docs/, etc. ; reasoning (R&D, gated par REASONING_ENABLED) embarqué inconditionnellement dans toutes les images.

2. Goals

  • Baseline mesurée et notée dans le design doc (docker images + docker history du top-3 layers).
  • docling-agent + mellea retirés de document-parser/requirements.txt, déplacés dans document-parser/requirements-reasoning.txt.
  • Dockerfile multi-stage (builder + cible finale) avec COPY . . repoussé après les pip install.
  • Build-arg WITH_REASONING=false (défaut) supporté dans la cible local.
  • .dockerignore étendu (tests/, data/, uploads/, docs/, *.iml, package-lock.json, node_modules/, tools/migrate_06.py).
  • Évaluation de torchvision documentée (gardé ou retiré, justifié).
  • Volume HF cache documenté dans docker-compose.yml et docker-compose.dev.yml.
  • Smoke test : conversion locale OK sans reasoning ; reasoning OK avec WITH_REASONING=true + REASONING_ENABLED=true + Ollama joignable.
  • pytest tests/ -v passe dans le container final.
  • Réduction taille ≥ 30 % vs baseline (chiffrée dans la PR).

3. Non-goals

  • Pas de réécriture du LocalConverter ni de suppression du threading.Lock global → suivi perf séparé (issue dédiée à ouvrir si besoin).
  • Pas de bake-in des modèles Docling dans l'image — le compromis taille est trop défavorable. Le cache HF reste mountable via volume ; un tools/prefetch_models.py opt-in pourra arriver dans un autre issue.
  • Pas d'optim de l'image embedding-service — autre image, autre périmètre.
  • Pas de tuning HF Space deploy — HF Space déploie latest-remote, pas latest-local.
  • Pas de changement du moteur OCR livré par Docling.
  • Pas de modification de l'API publique ni du schéma SQLite — change additif/build-only.

4. Context & constraints

5. Proposed design

5.1 Domain

5.2 Persistence

5.3 Infra adapters

5.4 Services

5.5 API

5.6 Frontend — feature module

5.7 Cross-cutting (feature flags, i18n, shared types)

6. Alternatives considered

Alternative A —

  • Summary:
  • Why not:

Alternative B —

  • Summary:
  • Why not:

7. API & data contract

8. Risks & mitigations

Risk Audit dimension Likelihood Impact How we notice Mitigation / rollback

9. Testing strategy

10. Rollout & observability

11. Open questions

  • ...
  • ...

12. References

  • Issue: https://github.com/scub-france/Docling-Studio/issues/254
  • Related PRs / commits:
  • ADRs: <ADR-NNN or "none planned">
  • Project docs:
    • Architecture: docs/architecture.md
    • Coding standards: docs/architecture/coding-standards.md
    • ADR guide / template: docs/architecture/adr-guide.md, docs/architecture/adr-template.md
    • Audit master: docs/audit/master.md
    • E2E conventions: e2e/CONVENTIONS.md
  • External: <specs, upstream issues, dashboards, third-party docs>