Summary Index#

Summary Index is Dify's two-tier vector storage mechanism for RAG retrieval. Each DocumentSegment (chunk) can have an LLM-generated summary that is independently embedded and stored in the vector database alongside the chunk's own embedding. During retrieval, a user query may match the summary vector; the system then resolves the original_chunk_id link and returns the original chunk content — the summary acts as a higher-signal proxy document without replacing the source text.

The feature activates only when all three conditions hold 1:

1. document.need_summary is True
2. dataset.indexing_technique == "high_quality" (economy mode excluded)
3. dataset.summary_index_setting.enable == True

qa_model documents are always skipped 2.

Data Model & Configuration#

DocumentSegmentSummary (PostgreSQL) is the per-chunk summary record 3. Key fields:

In the vector store, summary documents carry the metadata is_summary=True and original_chunk_id (the segment UUID) 4. These attributes must be declared in the Vector class init; without them, backends like Weaviate silently omit the fields and summary hits degrade to ordinary results.

SummaryIndexSettingDict is stored as a JSON column on Dataset and typed in index_processor_base.py. Fields: enable, model_name, model_provider_name, summary_prompt (falls back to DEFAULT_GENERATOR_SUMMARY_PROMPT with {language} interpolation).

Generation Pipeline#

document_indexing_task
  └─ (on completion) generate_summary_index_task.delay() [dataset_summary queue]
       └─ SummaryIndexService.generate_summaries_for_document()
            ├─ batch_create_summary_records() → NOT_STARTED stubs
            └─ per segment: generate_and_vectorize_summary()
                 ├─ ParagraphIndexProcessor.generate_summary() [LLM call]
                 └─ vectorize_summary() [embed + write to VDB]

After normal document indexing completes, document_indexing_task enqueues generate_summary_index_task on the dataset_summary Celery queue (separate from the main dataset queue) 1.

generate_summaries_for_document() batch-creates NOT_STARTED stub records upfront for status tracking 5, then iterates over segments — errors on individual segments are caught and logged without aborting the rest 6.

vectorize_summary() embeds the summary text, writes it to the vector DB with duplicate_check=False (upsert semantics), retries up to 3× with exponential backoff on connection errors 7, and updates DocumentSegmentSummary.status to COMPLETED on success 8.

Vision support: ParagraphIndexProcessor.generate_summary() extracts images from SegmentAttachmentBinding or inline markdown ![]() links when the configured model supports vision 1.

Manual triggers:

• POST /datasets/<dataset_id>/documents/generate-summary — enqueues the Celery task per document.
• SummaryIndexService.update_summary_for_segment() — used when a user edits a segment's summary manually; runs synchronously so the updated summary is immediately searchable.

Retrieval Mechanics#

Vector search returns a mixed result set that may include regular chunk documents and summary documents (is_summary=True). RetrievalService.format_retrieval_documents() processes them in two passes:

1. First pass — for each document with is_summary=True, extract original_chunk_id and save the relevance score to summary_score_map (taking the max if the same segment is hit multiple times) 9.

2. Second pass — query DocumentSegment by original_chunk_id 10, batch-fetch the corresponding DocumentSegmentSummary records 11, and attach the summary text to the result.

The summary's score propagates to the original chunk: if a segment was only reached via summary, summary_score_map supplies the score; if it was reached both via summary and a direct vector match, the higher score wins 12.

The final RetrievalSegments object carries segment (original chunk), score, and summary (summary content string, if any). This means callers receive the original chunk text — not the summary text — for answer synthesis, while the summary provides both the retrieval signal and optional display context.

Cleanup Gap: Orphaned Summary Data on Re-upload#

Bug — tracked in #36937 13

When an existing document is re-uploaded, Dify routes it through DuplicateDocumentIndexingTask. This task:

• ✅ Deletes old DocumentSegment records and their vectors (via index_processor.clean())
• ❌ Does not clean up DocumentSegmentSummary records or their vectors
• ❌ Does not enqueue generate_summary_index_task after re-indexing

As a result, the old summary rows accumulate in PostgreSQL and the old summary vectors remain in the vector store. Using the "Regenerate Summary" button adds new summary records on top of the stale ones. An identical gap exists in document_indexing_update_task (issue #35950) 13.

Root cause: The summary index was added to the initial indexing flow (document_indexing_task) but the duplicate-upload and document-update paths were never updated accordingly.

Correct fix (two additions to DuplicateDocumentIndexingTask):

1. Before re-indexing: Call SummaryIndexService.delete_summaries_for_segments() to delete both PG rows and vector embeddings for the old segments.
2. After re-indexing succeeds: Enqueue generate_summary_index_task.delay() with the same conditional guard used in document_indexing_task (high-quality indexing + summary_index_setting.enable + need_summary == True).

Key Files#