Skip to main content
Annotations let you create a curated library of perfect responses for specific questions. When users ask similar questions, Dify returns your pre-written answers instead of generating new responses, ensuring consistency and eliminating AI hallucinations for critical topics.

​
When to Use Annotations

Enterprise Standards Create definitive answers for policy questions, product information, or customer service scenarios where consistency is critical. Rapid Prototyping Quickly improve demo applications by curating high-quality responses without retraining models or complex prompt engineering. Quality Assurance Ensure certain sensitive or important questions always receive your approved responses rather than potentially variable AI-generated content.

​
How Annotations Work

When annotation reply is enabled:
  1. User asks a question
  2. System searches existing annotations for semantic matches
  3. If a match above the similarity threshold is found, returns the curated response
  4. If no match, proceeds with normal AI generation
  5. Track which annotations get used and how often
This creates a “fast path” for known good answers while maintaining AI flexibility for new questions.

​
Setting Up Annotations

Enable in App Configuration Navigate to Orchestrate → Add Features and enable annotation reply. Configure the similarity threshold and embedding model for matching. Similarity Threshold: Higher values require closer matches. Start with moderate settings and adjust based on hit rates. Embedding Model: Used to vectorize questions for semantic matching. Changing the model regenerates all embeddings.

​
Creating Annotations

From Conversations In debug mode or logs, click on AI responses and edit them into the perfect answer. Save as an annotation for future use. Bulk Import Download the template, create Q&A pairs in the specified format, and upload for batch annotation creation. Manual Entry Add annotations directly in the Logs & Annotations interface with custom questions and responses.

​
Managing Annotation Quality

Hit Tracking Monitor which annotations are matched, how often they’re used, and the similarity scores of matches. This shows which annotations provide value. Continuous Refinement Review hit history to improve annotation coverage and accuracy. Questions that consistently miss your annotations indicate gaps in coverage. A/B Testing Compare user satisfaction rates before and after annotation implementation to measure impact.

​
Annotation Analytics

Hit Rate Analysis Track which annotations are frequently matched and which are never used. Remove unused annotations and expand successful patterns. Question Patterns Identify common user question types that would benefit from annotation coverage. Match Quality Review similarity scores to ensure annotations are triggering for appropriate questions without false matches.