custom fields documentation

[Puma7]

How should the prompt be structured in order to populate custom fields in Paperless AI?

The fields are created successfully, but they remain empty after processing.
Is there a specific prompt format or syntax needed to instruct the model to fill these custom fields with extracted values?

In particular, I would like to:

Automatically generate a short summary (abstract) of the document.

Extract relevant keywords, including synonyms or alternative technical terms, to improve document discoverability.

Example use case:
From a medical document, extract a short summary and tag it with terms like:

"Hypertension", including synonyms such as high blood pressure, elevated BP

"Diabetes mellitus", also known as diabetes, high blood sugar

These values should ideally be written into custom fields or tags to improve search and classification.

Any examples or guidance on how to structure the prompt to enable this functionality would be highly appreciated.

Thanks :)

[clusterzx]

You can instruct the LLM to handle custom fields as you want, BUT make sure that the LLM wont generate more than 120 chars as this is the limit of paperless-ngx for custom field values. Probally the LLM generated to much text for that field.

[Puma7]

I changed the name and it worked with 4o and 4o-mini.
Now i added openrouter and tried gemini flash lite and llama 4, but those both ignore my requests, but at least they add tags 😄
Due to high costs i stick with gemini flash lite, seams to be the best option

[KoffeinKaio]

I struggle a bit with custom fields too.

In paperless I added a custom field "keywords".
In paperless-ai i added it too, plus in the prompt.

Prompt:

 `You are a personalized document analyzer. Your task is to analyze documents and extract relevant information.

Analyze the document content and extract the following information into a structured JSON object:

1. title: Create a concise, meaningful title for the document
2. correspondent: Identify the sender/institution but do not include addresses
3. tags: Select up to 4 relevant thematic tags
4. document_date: Extract the document date (format: YYYY-MM-DD)
5. document_type: Determine a precise type that classifies the document (e.g. Invoice, Contract, Employer, Information and so on)
6. language: Determine the document language (e.g. "de" or "en")
7. keywords: Generate a number of keywords a user can search for
      
Important rules for the analysis:

For tags:
- FIRST check the existing tags before suggesting new ones
- Use only relevant categories
- Maximum 4 tags per document, less if sufficient (at least 1)
- Avoid generic or too specific tags
- Use only the most important information for tag creation
- The output language is the one used in the document! IMPORTANT!

For the title:
- Short and concise, NO ADDRESSES
- Contains the most important identification features
- For invoices/orders, mention invoice/order number if available
- The output language is the one used in the document! IMPORTANT!

For the correspondent:
- Identify the sender or institution
  When generating the correspondent, always create the shortest possible form of the company name (e.g. "Amazon" instead of "Amazon EU SARL, German branch")

For the document date:
- Extract the date of the document
- Use the format YYYY-MM-DD
- If multiple dates are present, use the most relevant one

For the language:
- Determine the document language
- Use language codes like "de" for German or "en" for English
- If the language is not clear, use "und" as a placeholder

For the keywords:
- generate a number of keywords so a user can easier find documents
- separator them by comma (,)
- minimum 4, maximum 10
- keep below 120 characters! IMPORTANT!
- The output language is the one used in the document! IMPORTANT!

LLM out:

ai-1              | Repsonse from AI service: {
ai-1              |   document: {
ai-1              |     title: 'Bestellung Freddy Fresh Pizza 28.02.2021',
ai-1              |     correspondent: 'Freddy Fresh Pizza',
ai-1              |     tags: [ 'Bestellung', 'Pizza', 'Lieferung', 'Essen' ],
ai-1              |     document_type: 'Bestellung',
ai-1              |     document_date: '2021-02-28',
ai-1              |     language: 'de',
ai-1              |     keywords: 'Freddy Fresh, Pizza, Bestellung, Lieferung, Essen, 28.02.2021, 102,86€'
ai-1              |   },
ai-1              |   metrics: { promptTokens: 1669, completionTokens: 176, totalTokens: 1845 },
ai-1              |   truncated: false
ai-1              | }

As far as I can see the LLM does its job - however, the field remains empty in paperless.

Any tipps?

[KoffeinKaio]

i tried:
having the field already on the document (but empty) in paperless -> nothing is written in it after processing
NOT having the field added in paperless to documents -> its not added in processing
deleting the field in paperless -> its not created

modifying the json to have the field "keywords" as normal key and wrapped inside custom_fields{} -> nothing is added

Paperless-ngx-Version
2.15.3

EDIT:
it seems paperless-ai does create the custom field on restart - but still doesnt fill it

[Bleala]

I'm having the same problem as you.

1.  `title`: Create a concise, meaningful title for the document in German.
2.  `correspondent`: Identify the primary sender or involved institution, but do not include addresses.
3.  `tags`: Select up to 5 relevant thematic tags in German.
4.  `document_date`: Extract the main date of the document (format: DD.MM.YYYY).
5.  `document_type`: Determine a precise German term that classifies the document (e.g., Rechnung, Vertrag, Gehaltszettel, Lieferschein, Bescheid, Information).
6.  `language`: Determine the document's primary language (e.g., "de" or "en").
7.  `Gesamtbetrag`: If the document is an invoice, order, or financial statement, extract the total monetary amount. Use a float or integer.

The response from the LLM does include the correct Gesamtbetrag.

Repsonse from AI service: {
  document: {
    title: 'Hetzner Rechnung R0016369393 vom 28.07.2022',
    correspondent: 'Hetzner',
    tags: [ 'Rechnung', 'IT', 'Server', 'Cloud' ],
    document_type: 'Rechnung',
    document_date: '28.07.2022',
    language: 'de',
    Gesamtbetrag: 13.9
  },
  metrics: { promptTokens: 4870, completionTokens: 135, totalTokens: 5351 },
  truncated: false
}

But Paperless AI ignores that in the final update.

[DEBUG] Final update data: {
  tags: [ 39, 1, 256, 262, 33, 44 ],
  title: 'Hetzner Rechnung R0016369393 vom 28.07.2022',
  created: '2022-07-27T22:00:00.000Z',
  document_type: 1,
  language: 'de'
}
2025-05-16T23:16:16: PM2 log: [PM2][WORKER] Reset the restart delay, as app paperless-ai has been up for more than 30000ms
[SUCCESS] Updated document 270 with: {
  tags: [ 39, 1, 256, 262, 33, 44 ],
  title: 'Hetzner Rechnung R0016369393 vom 28.07.2022',
  created: '2022-07-27T22:00:00.000Z',
  document_type: 1,
  language: 'de'
}

Paperless AI also does create the custom field Gesamtbetrag in Paperless.
And I checked the box for Custom Fields in the Paperless AI settings.

So:
Paperless AI does create the custom field.
Field already in document --> nothing is written
Field not in document --> is not added

I also tried different names for the custom field, always the same outcome.

Versions:
Paperless NGX: 2.15.3
Paperless AI: 2.7.6 and 2.7.8

@clusterzx do you have an idea, how we could solve our issue?

[clusterzx]

You dont define it via prompt. You define it via the custom field settings.

[Bleala]

Hi @clusterzx

I have defined it in the custom field settings, as you can see.

The custom field also has been created in Paperless-NGX from Paperless-AI.

[DEBUG] Successfully created custom field "Gesamtbetrag" with ID 23
Validating Paperless config for: https://paperless.example.com/api/documents/
AI provider: custom
Custom AI config: {
  baseURL: 'redacted',
  apiKey: 'redacted',
  model: 'redacted'
}
[DEBUG] Refreshing custom field cache...
[DEBUG] Custom field cache refreshed. Found 1 fields.
[DEBUG] Found custom field "Gesamtbetrag" in cache with ID 23

So as I understand, Paperless AI should match the LLM Response from Gesamtbetrag to the custom field Gesamtbetrag.
Or did I setup something wrong?

According to the logs the Gesamtbetrag is correct.

Repsonse from AI service: {
  document: {
    title: 'Hetzner Rechnung R0016685179 vom 28.08.2022',
    correspondent: 'Hetzner',
    tags: [ 'IT', 'Cloud', 'Server', 'Rechnung' ],
    document_type: 'Rechnung',
    document_date: '28.08.2022',
    language: 'de',
    Gesamtbetrag: 13.88
  },
  metrics: { promptTokens: 5195, completionTokens: 184, totalTokens: 5810 },
  truncated: false
}

But the final update data does ignore that, as it seems.

[DEBUG] Final update data: {
  tags: [ 39, 256, 33, 262, 1, 44 ],
  title: 'Hetzner Rechnung R0016685179 vom 28.08.2022',
  created: '2022-08-27T22:00:00.000Z',
  document_type: 1,
  language: 'de'
}
[SUCCESS] Updated document 287 with: {
  tags: [ 39, 256, 33, 262, 1, 44 ],
  title: 'Hetzner Rechnung R0016685179 vom 28.08.2022',
  created: '2022-08-27T22:00:00.000Z',
  document_type: 1,
  language: 'de'
}

Maybe I missed something somewhere, do you have an idea?

Edit:
This would be my complete promt.

You are a specialized, highly accurate document analysis AI. Your primary mission is to meticulously analyze documents and extract key information, presenting it in a structured JSON object. Strive for utmost precision and adhere strictly to the formatting and content guidelines provided.

Analyze the content of the provided document and extract the following information into a single, well-formed JSON object:

1.  `title`: Create a concise, meaningful title for the document in German.
2.  `correspondent`: Identify the primary sender or involved institution, but do not include addresses.
3.  `tags`: Select up to 5 relevant thematic tags in German.
4.  `document_date`: Extract the main date of the document (format: DD.MM.YYYY).
5.  `document_type`: Determine a precise German term that classifies the document (e.g., Rechnung, Vertrag, Gehaltszettel, Lieferschein, Bescheid, Information).
6.  `language`: Determine the document's primary language (e.g., "de" or "en").
7.  `Gesamtbetrag`: If the document is an invoice, order, or financial statement, extract the total monetary amount. Use a float or integer.

Important General Rules for the Analysis:

JSON Structure: Ensure the output is always a valid JSON object with the specified keys. If a field is optional and no relevant information is found, omit the key or use `null` as its value, as specified per field.
Handling Missing Information: If a mandatory field's information cannot be reliably extracted, use a specific placeholder like "nicht extrahierbar" or "nicht gefunden" for string-based fields, unless otherwise specified. For dates, if unfindable, use `null`.
Prioritize Explicit Information: Base extractions on information explicitly stated in the document. Avoid making assumptions or inferring information beyond what is clearly present.
Multi-page Documents: Analyze the entire document to ensure all relevant information is considered.

Field-Specific Instructions:

For `title` (Output language: German - IMPORTANT!):
    * Must be short, concise, and highly descriptive.
    * Must NOT include addresses or parts of addresses.
    * Must contain the most important identifying features of the document.
    * For invoices, orders, or similar transactional documents:
        * ALWAYS include the correspondent (short form).
        * ALWAYS include the `document_type`.
        * If available, include the invoice/order number (from `invoice_number` or `document_number`).
        * If available, include the invoice/order date (from `document_date`).
        * Example: "Rechnung Müller GmbH RE20230515 vom 15.05.2023".
        * If no specific number is available, use correspondent, type, and date: "Angebot Schmidt AG vom 10.04.2023".
    * For other documents, focus on correspondent, type, and key subject/reference if available. Example: "Vertrag Max Mustermann mit Energie AG - Stromlieferung" or "Bescheid Finanzamt - Einkommensteuer 2022".

For `correspondent`:
    * Consistency is Key: FIRST, check if a similar correspondent (name variation) has been processed before or exists in a known list. Aim to use a canonical/standardized form if possible. If not, generate as per rules below.
    * Identify the primary sender, company, authority, or main institution involved in the document. This is often the entity *issuing* the document or the primary party the document is about.
    * Shortest Recognizable Form: ALWAYS generate the shortest possible, yet still clearly identifiable, form of the company or institution name.
        * Examples: "Amazon" instead of "Amazon EU SARL, German Branch"; "Raiffeisen" instead of "Raiffeisen Bank International AG"; "Finanzamt" instead of "Finanzamt Österreich"; "Uni Wien" instead of "Universität Wien Fakultät für Wirtschaftswissenschaften".
        * Remove legal suffixes like "GmbH", "AG", "KG", "GesbR", "e.U." etc., *unless* critical for differentiation or part of a very common name (e.g., if there's "Müller Bau" and "Müller Bau GmbH" as distinct entities, retain; otherwise, prefer "Müller Bau"). Strive for the most common public-facing name.
    * Do NOT include addresses, department names (unless it's the core identifier, e.g. "Abteilung X Stadt Y"), or contact persons.

For `tags` (Output language: German - IMPORTANT!):
    * Consistency is Key: FIRST, check against a list of existing tags if provided, and prioritize using them. Suggest new tags ONLY IF TRULY NECESSARY and the existing ones are insufficient.
    * Use only relevant thematic categories that describe the document's core subject or purpose.
    * Maximum 5 tags per document. Use fewer if sufficient (minimum 2 tags).
    * Avoid generic tags like "Dokument" or "Wichtig".
    * Avoid tags that are too specific if a more general, applicable tag exists (e.g., use "Versicherung" instead of "KFZ-Haftpflichtversicherung Polizzennummer XY123" – the policy number belongs in `document_number`).
    * Focus on the *content and purpose*, not just named entities already captured elsewhere (like correspondent). Good examples: "Steuer", "Wohnung", "Gesundheit", "Finanzen", "Auto", "Vertrag", "Reise", "Bildung", "Arbeit", "Versicherung".
    * Do not use dates as tags.

For `document_date`:
    * Extract the primary date of the document. This is usually the date the document was created, issued, or signed.
    * Format: DD.MM.YYYY.
    * If multiple dates are present (e.g., creation date, due date, service period):
        * For invoices: use the invoice issue date.
        * For contracts: use the contract signing date or effective date if clearly stated.
        * For letters/correspondence: use the date the letter was written.
        * For official notices/bescheide: use the date of issuance.
        * If still ambiguous, use the latest date that appears to be the main "document date".
    * If no date can be found, the value should be `null`.

For `document_type` (Output language: German - IMPORTANT!):
    * Consistency is Key: FIRST, check against a list of existing document types if provided, and prioritize using them. Suggest new types ONLY IF TRULY NECESSARY.
    * Determine a precise, common German term that best classifies the document's nature or purpose.
    * Be specific but not overly granular if a common category exists.
    * Examples: "Rechnung", "Angebot", "Lieferschein", "Mahnung", "Vertrag", "Kündigung", "Gehaltszettel", "Kontoauszug", "Depotauszug", "Versicherungspolizze", "Versicherungsantrag", "Amtliches Schreiben", "Bescheid", "Protokoll", "Newsletter", "Werbung", "Anleitung", "Garantie", "Befund", "Einladung".
    * If no specific type fits well, use a more general but still descriptive term like "Korrespondenz" (for general letters) or "Information". Avoid "Sonstiges" if a better term can be found.

For `language`:
    * Determine the primary language of the document content.
    * Use ISO 639-1 language codes (e.g., "de" for German, "en" for English, "fr" for French).
    * If the language cannot be clearly determined or is mixed without a clear primary language, use "undefined" as a placeholder.

For `Gesamtbetrag`:
    * If the document is an invoice, credit note, order, bank statement, or any other document where a clear total monetary sum is central, extract this total amount.
    * Output as a numerical value (integer or float, e.g., 123.45 or 123).
    * Look for terms like "Gesamtbetrag", "Total", "Summe", "Endbetrag", "Rechnungssumme".
    * If not applicable or not found, omit this field or use `null`.
    * keep below 120 characters! IMPORTANT!

[clusterzx]

Hi @clusterzx

I have defined it in the custom field settings, as you can see.

The custom field also has been created in Paperless-NGX from Paperless-AI.

[DEBUG] Successfully created custom field "Gesamtbetrag" with ID 23

Validating Paperless config for: https://paperless.example.com/api/documents/

AI provider: custom

Custom AI config: {

  baseURL: 'redacted',

  apiKey: 'redacted',

  model: 'redacted'

}

[DEBUG] Refreshing custom field cache...

[DEBUG] Custom field cache refreshed. Found 1 fields.

[DEBUG] Found custom field "Gesamtbetrag" in cache with ID 23

So as I understand, Paperless AI should match the LLM Response from Gesamtbetrag to the custom field Gesamtbetrag.

Or did I setup something wrong?

According to the logs the Gesamtbetrag is correct.

Repsonse from AI service: {

  document: {

    title: 'Hetzner Rechnung R0016685179 vom 28.08.2022',

    correspondent: 'Hetzner',

    tags: [ 'IT', 'Cloud', 'Server', 'Rechnung' ],

    document_type: 'Rechnung',

    document_date: '28.08.2022',

    language: 'de',

    Gesamtbetrag: 13.88

  },

  metrics: { promptTokens: 5195, completionTokens: 184, totalTokens: 5810 },

  truncated: false

}

But the final update data does ignore that, as it seems.

[DEBUG] Final update data: {

  tags: [ 39, 256, 33, 262, 1, 44 ],

  title: 'Hetzner Rechnung R0016685179 vom 28.08.2022',

  created: '2022-08-27T22:00:00.000Z',

  document_type: 1,

  language: 'de'

}

[SUCCESS] Updated document 287 with: {

  tags: [ 39, 256, 33, 262, 1, 44 ],

  title: 'Hetzner Rechnung R0016685179 vom 28.08.2022',

  created: '2022-08-27T22:00:00.000Z',

  document_type: 1,

  language: 'de'

}

Maybe I missed something somewhere, do you have an idea?

Edit:

This would be my complete promt.

You are a specialized, highly accurate document analysis AI. Your primary mission is to meticulously analyze documents and extract key information, presenting it in a structured JSON object. Strive for utmost precision and adhere strictly to the formatting and content guidelines provided.



Analyze the content of the provided document and extract the following information into a single, well-formed JSON object:



1.  `title`: Create a concise, meaningful title for the document in German.

2.  `correspondent`: Identify the primary sender or involved institution, but do not include addresses.

3.  `tags`: Select up to 5 relevant thematic tags in German.

4.  `document_date`: Extract the main date of the document (format: DD.MM.YYYY).

5.  `document_type`: Determine a precise German term that classifies the document (e.g., Rechnung, Vertrag, Gehaltszettel, Lieferschein, Bescheid, Information).

6.  `language`: Determine the document's primary language (e.g., "de" or "en").

7.  `Gesamtbetrag`: If the document is an invoice, order, or financial statement, extract the total monetary amount. Use a float or integer.



Important General Rules for the Analysis:



JSON Structure: Ensure the output is always a valid JSON object with the specified keys. If a field is optional and no relevant information is found, omit the key or use `null` as its value, as specified per field.

Handling Missing Information: If a mandatory field's information cannot be reliably extracted, use a specific placeholder like "nicht extrahierbar" or "nicht gefunden" for string-based fields, unless otherwise specified. For dates, if unfindable, use `null`.

Prioritize Explicit Information: Base extractions on information explicitly stated in the document. Avoid making assumptions or inferring information beyond what is clearly present.

Multi-page Documents: Analyze the entire document to ensure all relevant information is considered.



Field-Specific Instructions:



For `title` (Output language: German - IMPORTANT!):

    * Must be short, concise, and highly descriptive.

    * Must NOT include addresses or parts of addresses.

    * Must contain the most important identifying features of the document.

    * For invoices, orders, or similar transactional documents:

        * ALWAYS include the correspondent (short form).

        * ALWAYS include the `document_type`.

        * If available, include the invoice/order number (from `invoice_number` or `document_number`).

        * If available, include the invoice/order date (from `document_date`).

        * Example: "Rechnung Müller GmbH RE20230515 vom 15.05.2023".

        * If no specific number is available, use correspondent, type, and date: "Angebot Schmidt AG vom 10.04.2023".

    * For other documents, focus on correspondent, type, and key subject/reference if available. Example: "Vertrag Max Mustermann mit Energie AG - Stromlieferung" or "Bescheid Finanzamt - Einkommensteuer 2022".



For `correspondent`:

    * Consistency is Key: FIRST, check if a similar correspondent (name variation) has been processed before or exists in a known list. Aim to use a canonical/standardized form if possible. If not, generate as per rules below.

    * Identify the primary sender, company, authority, or main institution involved in the document. This is often the entity *issuing* the document or the primary party the document is about.

    * Shortest Recognizable Form: ALWAYS generate the shortest possible, yet still clearly identifiable, form of the company or institution name.

        * Examples: "Amazon" instead of "Amazon EU SARL, German Branch"; "Raiffeisen" instead of "Raiffeisen Bank International AG"; "Finanzamt" instead of "Finanzamt Österreich"; "Uni Wien" instead of "Universität Wien Fakultät für Wirtschaftswissenschaften".

        * Remove legal suffixes like "GmbH", "AG", "KG", "GesbR", "e.U." etc., *unless* critical for differentiation or part of a very common name (e.g., if there's "Müller Bau" and "Müller Bau GmbH" as distinct entities, retain; otherwise, prefer "Müller Bau"). Strive for the most common public-facing name.

    * Do NOT include addresses, department names (unless it's the core identifier, e.g. "Abteilung X Stadt Y"), or contact persons.



For `tags` (Output language: German - IMPORTANT!):

    * Consistency is Key: FIRST, check against a list of existing tags if provided, and prioritize using them. Suggest new tags ONLY IF TRULY NECESSARY and the existing ones are insufficient.

    * Use only relevant thematic categories that describe the document's core subject or purpose.

    * Maximum 5 tags per document. Use fewer if sufficient (minimum 2 tags).

    * Avoid generic tags like "Dokument" or "Wichtig".

    * Avoid tags that are too specific if a more general, applicable tag exists (e.g., use "Versicherung" instead of "KFZ-Haftpflichtversicherung Polizzennummer XY123" – the policy number belongs in `document_number`).

    * Focus on the *content and purpose*, not just named entities already captured elsewhere (like correspondent). Good examples: "Steuer", "Wohnung", "Gesundheit", "Finanzen", "Auto", "Vertrag", "Reise", "Bildung", "Arbeit", "Versicherung".

    * Do not use dates as tags.



For `document_date`:

    * Extract the primary date of the document. This is usually the date the document was created, issued, or signed.

    * Format: DD.MM.YYYY.

    * If multiple dates are present (e.g., creation date, due date, service period):

        * For invoices: use the invoice issue date.

        * For contracts: use the contract signing date or effective date if clearly stated.

        * For letters/correspondence: use the date the letter was written.

        * For official notices/bescheide: use the date of issuance.

        * If still ambiguous, use the latest date that appears to be the main "document date".

    * If no date can be found, the value should be `null`.



For `document_type` (Output language: German - IMPORTANT!):

    * Consistency is Key: FIRST, check against a list of existing document types if provided, and prioritize using them. Suggest new types ONLY IF TRULY NECESSARY.

    * Determine a precise, common German term that best classifies the document's nature or purpose.

    * Be specific but not overly granular if a common category exists.

    * Examples: "Rechnung", "Angebot", "Lieferschein", "Mahnung", "Vertrag", "Kündigung", "Gehaltszettel", "Kontoauszug", "Depotauszug", "Versicherungspolizze", "Versicherungsantrag", "Amtliches Schreiben", "Bescheid", "Protokoll", "Newsletter", "Werbung", "Anleitung", "Garantie", "Befund", "Einladung".

    * If no specific type fits well, use a more general but still descriptive term like "Korrespondenz" (for general letters) or "Information". Avoid "Sonstiges" if a better term can be found.



For `language`:

    * Determine the primary language of the document content.

    * Use ISO 639-1 language codes (e.g., "de" for German, "en" for English, "fr" for French).

    * If the language cannot be clearly determined or is mixed without a clear primary language, use "undefined" as a placeholder.



For `Gesamtbetrag`:

    * If the document is an invoice, credit note, order, bank statement, or any other document where a clear total monetary sum is central, extract this total amount.

    * Output as a numerical value (integer or float, e.g., 123.45 or 123).

    * Look for terms like "Gesamtbetrag", "Total", "Summe", "Endbetrag", "Rechnungssumme".

    * If not applicable or not found, omit this field or use `null`.

    * keep below 120 characters! IMPORTANT!

I suggest to remove the Gesamtbetrag from the prompt completely. As seen in a previous reply of you the field is added directly in the response as Gesamtbetrag: xx.x

That's wrong as it should have the custom_fields:{} array.

[Bleala]

Thanks for your reply @clusterzx

I removed the Gesamtbetrag from my prompt completely and tried again.

Paperless AI start:

[DEBUG] Refreshing custom field cache...
[DEBUG] Custom field cache refreshed. Found 1 fields.
[DEBUG] Found custom field "Gesamtbetrag" in cache with ID 23

Now the AI response looks like this:

Repsonse from AI service: {
  document: {
    title: 'Hetzner Rechnung R0016685179 vom 28.08.2022',
    correspondent: 'Hetzner',
    tags: [ 'Rechnung', 'IT', 'Server', 'Cloud' ],
    document_type: 'Rechnung',
    document_date: '28.08.2022',
    language: 'de'
  },
  metrics: { promptTokens: 4474, completionTokens: 121, totalTokens: 4909 },
  truncated: false
}

And the update data like this:

[DEBUG] Final update data: {
  tags: [ 39, 1, 256, 262, 33, 44 ],
  title: 'Hetzner Rechnung R0016685179 vom 28.08.2022',
  created: '2022-08-27T22:00:00.000Z',
  document_type: 1,
  language: 'de'
}
[SUCCESS] Updated document 287 with: {
  tags: [ 39, 1, 256, 262, 33, 44 ],
  title: 'Hetzner Rechnung R0016685179 vom 28.08.2022',
  created: '2022-08-27T22:00:00.000Z',
  document_type: 1,
  language: 'de'
}

The Gesamtbetrag custom field is not added to the document.

So I guess removing it comletely from the prompt does not work also.

[clusterzx]

May I ask which LLM you are using? I sometimes heard that ollama models are quite bad in performing for custom fields. But I did test it myself with llama3.2 and got-4o-mini and it worked.

Sorry :/

[Bleala]

Currently I'm using Gemini with the gemini-2.5-flash-preview-04-17 model, as the result are far better than with OpenAIs 4o or 4o-mini.

But as you mentioned that there are problems with certain models (and for my sanity 😄 ) I tried the 4o-mini model from OpenAI with the exact same promt I posted before and it worked!

AI Respone:

Repsonse from AI service: {
  document: {
    title: 'Rechnung Hetzner Online R0016685179 vom 28.08.2022',
    correspondent: 'Hetzner Online',
    tags: [ 'Rechnung', 'Cloud', 'Finanzen', 'IT', 'Zahlung' ],
    document_type: 'Rechnung',
    document_date: '28.08.2022',
    language: 'de',
    custom_fields: { '0': [Object] }
  },
  metrics: { promptTokens: 4308, completionTokens: 125, totalTokens: 4433 },
  truncated: false
}

Paperless AI logs:

[DEBUG] Final update data: {
  tags: [
     39,   1, 33, 267,
    256, 266, 44
  ],
  title: 'Rechnung Hetzner Online R0016685179 vom 28.08.2022',
  created: '2022-08-27T22:00:00.000Z',
  document_type: 1,
  custom_fields: [ { field: 24, value: '13.88' } ],
  language: 'de'
}
[SUCCESS] Updated document 287 with: {
  tags: [
     39,   1, 33, 267,
    256, 266, 44
  ],
  title: 'Rechnung Hetzner Online R0016685179 vom 28.08.2022',
  created: '2022-08-27T22:00:00.000Z',
  document_type: 1,
  custom_fields: [ { field: 24, value: '13.88' } ],
  language: 'de'
}

Paperless Screenshot (I tried to use the Gesamtbetrag as a normal text, not as currency this time):

Soooo good to know that it works, but why does it not work with Gemini, do you have an idea?

Edit:
I can confirm that with Gemini this does not work.
I only changed 4o-mini to gemini-2.5-flash-preview-04-17 and the AI response looks like this:

Repsonse from AI service: {
  document: {
    title: 'Rechnung Hetzner Online R0016685179 vom 28.08.2022',
    correspondent: 'Hetzner Online',
    tags: [ 'IT', 'Cloud', 'Server', 'Rechnung' ],
    document_type: 'Rechnung',
    document_date: '28.08.2022',
    language: 'de',
    Gesamtbetrag: 13.88
  },
  metrics: { promptTokens: 4803, completionTokens: 138, totalTokens: 5207 },
  truncated: false
}

So definitely a problem with Gemini somewhere.

[clusterzx]

I really have no clue tbh 😆 When I release the new RAG Feature to chat about all Documents at once I will dig into this here again.

[Bleala]

Thanks @clusterzx, I really appreciate your effort! ❤️

I hope you will find a solution for this, it would be nice, if this works with Gemini too.

[clusterzx]

Thanks @clusterzx, I really appreciate your effort! ❤️

I hope you will find a solution for this, it would be nice, if this works with Gemini too.

Ehrensachen 😃

[Anaxagoras-bc]

I think i figured out part of this issue, in doing so i think i discovered 2 bugs....

1 of the bugs is relevant to this issue. The custom fields only seem to get updated when hitting the "scan now" button on the dashboard, not when manually scanning a document via the "manual" tab on the left. I have not yet set up auto scanning sicne i'm still testing paperless-AI. See bug #599

The other bug is when hitting "scan now" the existing tags are not sent to the LLM, but when doing a manual scan the existing tags are sent to the llm. see bug #600

Looking at the logs @Bleala provided between the an llm that worked and didn't work, i noticed the custom value is an array vs a decimal. I"m using lm studio and configured a structured output. This made my local llm start using an array for the custom value I named mine "Total". paperless ngx is now being updated with the value.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "The title of the document."
    },
    "correspondent": {
      "type": "string",
      "description": "The name of the correspondent related to the document."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "A list of tags associated with the document."
    },
    "document_type": {
      "type": "string",
      "description": "The type of document, e.g., 'invoice', 'report', 'email'."
    },
    "document_date": {
      "type": "string",
      "format": "date",
      "description": "The date of the document in YYYY-MM-DD format."
    },
    "custom_fields": {
      "type": "array",
      "Total": {
        "type": "number",
        "multipleOf": 0.01
      },
      "description": "Custom Fields"
    },
    "language": {
      "type": "string",
      "description": "The language of the document in ISO 639-1 format."
    }
  },
  "required": [
    "title",
    "document_type",
    "correspondent",
    "tags",
    "document_date",
    "custom_fields",
    "language"
  ]
}

[kurzschlussmeister]

It would be amazing, if some of you can share their promts including custom field. I tried a lot of combination yet, but without any visability in paperless-ngx.

My setting: Using gpt-4omini. custom fieldsare createted in paperless-ngx as well as in paperless-ai.
I tried a lot of promt combinations already

[Kanne87]

That worked fir me:
{
"title": "...",
"document_date": "TT-MM-YYYY",
"document_type": "...",
"correspondent": "...",
"tags": ["..."],
"custom_fields": [
{ "field_name": "Betrag", "value": "0.00" },
{ "field_name": "Betriebsausgabe", "value": "" }
]
}

[MarioWMan]

It worked theoretically also with gemini 2.5 flash, but I had to add the expected json structure into my prompt.
BUT sometimes it popup a error. Have a look on my comment, bug report and solution below.
#820 (comment) and #831