Running w/ scissors... Need best path forward.

[FrankXLT]

So just a month ago, I started going paperless. I loaded up a Paperless stack on my Synology DS1821 I got from Marius Hosting using Portainer. It has the normal stuff. I did minimal setup, started scanning, made some iterative changes, and found myself more happy than frustrated with my setup. It still required a bit of care and feeding. I pumped nearly a thousand documents in already.

On a whim during a commute, I asked Gemini if there were any mods for PaperlessNGX that used a previously trained model for categorizing, tagging, etc. It sent me down a wonderful rabbithole of locally hosted models for OCR via Paperless-GPT and document processing via Paperless-AI. I forget the link, but it was the ollama for Paperless-AI and one of the models for OCR. It made sense, but seemed a bit slow and limiting since I running everything via docker on Synology. It wasn't really giving me the answers I was looking for. The things it was focusing on just didn't make sense.

So after another commute, where I was exploring what kinds of changes I should make, Gemini recommended that I revisit scaling back to just Paperless-GPT and using a cloud hosted model. I asked if Gemini could do it, it said yes and told me to do the paid tier to ensure my data was not used to train any models.

So I gave it a rip. Wow. Very nice OCR results. Not sure I understand what I am doing with the document processing. That is where I need help. So here is my docker compose that is running in my paperless stack.

  paperless-gpt:
    image: icereed/paperless-gpt:latest
    container_name: paperless-gpt
    restart: unless-stopped
    depends_on:
      - paperless
    ports:
      - 3002:8080
    environment:
      PAPERLESS_BASE_URL: http://192.168.1.210:8777
      PAPERLESS_API_TOKEN: redacted

      LLM_PROVIDER: googleai
      LLM_MODEL: gemini-3.1-flash-lite-preview
      LLM_LANGUAGE: English
      VISION_LLM_PROVIDER: googleai
      VISION_LLM_MODEL: gemini-3.1-flash-lite-preview
      GOOGLEAI_API_KEY: redacted

      USE_VISION_FOR_OCR: true
      AUTO_GENERATE_TITLE: true
      AUTO_GENERATE_CORRESPONDENT: true
      AUTO_GENERATE_DOCUMENT_TYPE: true
      AUTO_GENERATE_TAGS: true

      PDF_REPLACE: false
      AUTO_OCR: true
      AUTO_OCR_TAG: paperless-gpt-ocr-auto
      AUTO_TAG: paperless-gpt-auto
      MANUAL_TAG: paperless-gpt-manual
      PDF_OCR_TAGGING: true
      PDF_OCR_COMPLETE_TAG: paperless-gpt-ocr-complete
      PDF_UPLOAD: true
      LOG_LEVEL: DEBUG
    volumes:
      - /volume2/docker/paperlessngx/paperless-gpt/prompts:/app/prompts:rw

I setup my workflow to tag new documents with.

Based on everything I can tell, all new documents are being processed with Google's OCR no problem. I couldn't tell if the document processing was working. When I did the paperless-gpt-manual for about 100 documents, it gave me outstanding results that aligned with how I was using document types already and tags. I know how the prompts work, so that make sense on why that works so well.

So on a recent whim, I went and assigned all 960 documents to paperless-gpt-auto and paperless-gpt-ocr-auto. 959 still have the paperless-gpt-auto tag. 809 have paperless-gpt-ocr-complete. Now I haven't really dived into it much, but when I look at some of the results, I don't think it processed any documents. It only OCR'd them. The new documents I have added since then have more tags than I am expecting and I can't tell if it is from the model or not because I have been running with scissors. I realized that all of the correspondents, tags, and document types I had established prior to incorporating real AI models all had the default NGX provided models settings on. So a bunch of the manual training I did is now incorporated into NGX's models and it is just bad.

So I need to slow down and figure out what to do next. I kind of need help with a plan of attack. I am assuming I need to figure out a way to test and see if the the normal consumption is getting through both the Gemini OCR and document processing. I am assuming logs, but unsure of where to go for that and what to look for. I assume I will want to remove all of my currently assigned Tags and Document Types, and reset all of the entries to be None:Disabled Matching. Is my docker compose correct? Anything else obvious that I missed? Any other best practices?

Thanks!

[phaset]

My Notion notes for use of Paperless-GPT 0.25.1 will probably be helpful to you.

In summary: I've come up with a group of tags that guides you through two rounds of LLM calls. First for OCR, and then for classify. I then strip these extra tags via workflow, as tags make a hacky state machine / DAG.

• As of March 2026 and Paperless v0.25.1:
  • Paperless-GPT is now aware of the multimodal google models (Gemini-3.x-flash-preview) and (Gemini-3.x-flash-preview). So OCR = LLM does work with Gemini
    • If you use LLM OCR, the database receives the OCR text, but there is no creation of a local PDF with updated OCR text. If you use google DocAI, then local PDF with metadata can be created.
    • There is a bug in v0.25.1 where only the vision model is selected, and the other model variable is ignored. I opened a github issue for this: [Cannot Pick Two Different Google Models for LLM and VISION · Issue #933 · icereed/paperless-gpt](Cannot Pick Two Different Google Models for LLM and VISION #933)
  • If you want a local PDF with improved OCR (not Tesseract), what does work is Google Document AI for OCR, followed by Gemini-3-flash-preview for classification of the OCRed documents.

---

(Default) Workflows for LLM OCR and Classify combination

All paperless workflows so far are triggered on consume, or via tags. Tag Auto Matching MUST be turned off in Paperless-NGX. Tag triggered workflows are setup with tags that must be included, and tags that must not be included. This acts like a state machine to keep everything working:

1. Workflow: trigger "paperless-gpt-ocr-auto" tag (default) when document is consumed
2. Workflow: Tag “paperless-gpt-ocr-complete” is added by the OCR process in paperless-gpt
3. Workflow: If Tag “paperless-gpt-ocr-complete” is set and Tags “ocr-archive-updated” + “classify-ready” are NOT set (because no external BASH script was run like below) then the flags “paperless-gpt-auto” and “classify-ready” are added to the document. “paperless-gpt-auto” triggers the second LLM pass to identify correspondents, tags, doc type, and custom fields. As of 20260320, there is no unified OCR + classify single flow in paperless-gpt.
4. Workflow: if Tag “classify-ready” remains, but all other tags are removed: [“ocr-archive-updated,” “paperless-gpt-auto,” “paperless-gpt-ocr-auto,” “classify-ready,” and “paperless-gpt-ocr-complete,”] Then the storage path is assigned, “classify-ready,” is removed, and “pathing-updated” + “classify-sent” tags are applied. In paperless v0.25.1, the completion of classification is noted by REMOVAL of the paperless-gpt-auto flag, not setting of a completion flag. This is different than previous versions.
5. Workflow: with presence of “classify-sent,” and “pathing-updated,” tags (and absence of the others), the workflow removes the two confirmation tags and replace with "ocr-classify-pathing-completed" tag.

---

[FrankXLT]

Interesting approach. What does ocr-archive-updated do?

[phaset]

If you are using the Google DocAI workflow for paperless-gpt, then you can get back a copy of the file with the OCR text attached. According to the paperless-gpt authors, there's a limitation that prevents you overwriting the PDF/A with this updated OCR. This means that the PDF/A is OCR from Tesseract, but the postgres OCR is the google docAI. I created a BASH script that overwrites the Tesseract PDF/A with the one from Google DocAI, and it sets the flag "ocr-archive-updated" to reflect that this has been done.

That said, Gemini-3-flash-preview (not Gemini-3.1-flash-lite-preview) is super good at OCR, so I switched to that workflow:
https://docs.cloud.google.com/document-ai/docs/release-notes
https://docs.cloud.google.com/document-ai/docs/layout-parse-chunk

In the case of Gemini-3-flash, you don't get a new PDF back, so you still have the discrepancy between Tesseract PDF/A. But the database OCR text is from Gemini. I've decided to live with that, for now.

[FrankXLT]

Ok. That makes sense.

Can you talk to me more about Pathing Updated? It seems that I have to explicitly assign a path? I cannot just have paperless ngx re-evaluate the path after classify is complete? My process is as follows now:

document consume -> tag for pgpt-ocr-auto -> send to pgpt for ocr -> return with tag for ocr-complete-gpt -> tag for pgpt-tag-auto and classify-ready-pgpt at document update -> send to pgpt for classifying -> return and remove those tags and assign classify-complete-pgpt.

Now I want Paperless NGX to evaluate the storage tags based on the above process being complete.

[phaset]

I don't claim to be the paperless expert, but according to the docs:
-Define storage paths:

-Define workflows that assign storage paths:

0. Presently I am visiting the LLM twice, first for OCR, and then for classification of document tag/types/assign custom fields.
1. Classifying is needed to set the file pathing, so I do that first.
2. Then, after pathing is updated, I strip all the tags I used as poor man's state machine, which also merges the flows for LLM OCR vs DocAI OCR.
3. I leave a single tag that indicates the flows have been completed successfully: "ocr-classify-pathing-completed".

[FrankXLT]

Ahh, ok. You are only re-establishing a path after classifying. I had a few different path setup and was hoping to have PaperlessNGX reevaluate the path after classifying is complete. I will have to see if I can bash that command on command.