Principle:Langgenius Dify Annotation System
| Knowledge Sources | Dify |
|---|---|
| Domains | Frontend, AI, Knowledge |
| Last Updated | 2026-02-12 07:00 GMT |
Overview
The Dify annotation system provides predefined question-and-answer pairs that serve as canned responses within chat applications, enabling deterministic replies for known queries without invoking the LLM.
Description
Annotations in Dify are curated Q&A pairs that application builders define to handle frequently asked questions or to enforce specific responses for particular user inputs. When a user message matches an annotation with sufficient similarity (as measured by an embedding model), the annotation reply is returned directly instead of being processed through the LLM pipeline. This mechanism reduces latency, lowers API costs, and ensures consistent answers for known queries.
The frontend annotation service module (service/annotation.ts) exposes a complete CRUD API for managing annotations. Functions include fetchAnnotationConfig to retrieve scoring thresholds and embedding model settings, updateAnnotationStatus to enable or disable annotation reply with configurable score thresholds and embedding model parameters, addAnnotation and editAnnotation for individual entries, and annotationBatchImport for bulk CSV uploads. The module also supports asynchronous job monitoring through queryAnnotationJobStatus and checkAnnotationBatchImportProgress, since enabling annotations or batch importing triggers background indexing jobs on the backend.
The annotation system relies on vector similarity search using a configurable embedding model. Application builders can set a score threshold that controls how closely a user query must match an annotation before the canned response is triggered. This threshold balances between coverage (lower thresholds match more loosely) and precision (higher thresholds require closer matches), giving builders fine-grained control over when the system bypasses the LLM.
Usage
Use this principle when:
- Implementing or extending annotation management interfaces in the application settings
- Working with the annotation reply scoring and embedding model configuration
- Adding bulk import/export functionality for Q&A pairs
Theoretical Basis
The annotation system implements a Retrieval-Augmented Generation (RAG) variant where the retrieval step can short-circuit generation entirely. By using vector embeddings and cosine similarity to match user queries against predefined answers, the system applies nearest-neighbor search principles. The configurable score threshold embodies the classic precision-recall tradeoff from information retrieval theory.