Implementation:Langgenius Dify RetrievalConfig Type

Knowledge Sources	Dify
Domains	RAG Information Retrieval Search Configuration TypeScript Types
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete type definitions for retrieval strategy configuration provided by the Dify frontend model and type layers.

Description

This implementation documents the TypeScript type definitions and enum constants that define the shape of retrieval configuration objects in the Dify frontend. Unlike callable API functions, these are pattern definitions -- they establish the data contracts that retrieval-related components, hooks, and service functions all conform to.

The key types and enums are spread across two files:

• web/models/datasets.ts -- defines WeightedScoreEnum, RerankingModeEnum, and DEFAULT_WEIGHTED_SCORE preset configurations.
• web/types/app.ts -- defines the RetrievalConfig interface that is used as the canonical retrieval configuration object throughout the application.

Together, these types encode all the tuning parameters for RAG retrieval: search method, reranking strategy, result limits, score thresholds, and weighted score blending.

Usage

Import these types and enums when:

• Building or consuming retrieval configuration forms in the UI.
• Calling service functions that accept a RetrievalConfig parameter (e.g., hitTesting, dataset update endpoints).
• Implementing components that display or edit reranking modes or weighted score settings.
• Validating retrieval configuration objects before submission to the API.

Code Reference

Source Location

• Repository: Dify
• File: web/models/datasets.ts (lines 700--875, retrieval config types area)
• File: web/types/app.ts (RetrievalConfig interface)

Key Type Definitions

WeightedScoreEnum

export enum WeightedScoreEnum {
  SemanticFirst = 'semantic_first',
  KeywordFirst = 'keyword_first',
  Customized = 'customized',
}

RerankingModeEnum

export enum RerankingModeEnum {
  RerankingModel = 'reranking_model',
  WeightedScore = 'weighted_score',
}

DEFAULT_WEIGHTED_SCORE

export const DEFAULT_WEIGHTED_SCORE = {
  [WeightedScoreEnum.SemanticFirst]: {
    semantic: 0.7,
    keyword: 0.3,
  },
  [WeightedScoreEnum.KeywordFirst]: {
    semantic: 0.3,
    keyword: 0.7,
  },
  [WeightedScoreEnum.Customized]: {
    semantic: 0.5,
    keyword: 0.5,
  },
}

RetrievalConfig

// From web/types/app.ts
export interface RetrievalConfig {
  search_method: 'semantic_search' | 'full_text_search' | 'hybrid_search'
  reranking_enable: boolean
  reranking_model?: {
    reranking_provider_name: string
    reranking_model_name: string
  }
  reranking_mode?: RerankingModeEnum
  weights?: {
    semantic: number
    keyword: number
  }
  top_k: number
  score_threshold_enabled: boolean
  score_threshold?: number
}

Import

import { RetrievalConfig } from '@/types/app'
import {
  WeightedScoreEnum,
  RerankingModeEnum,
  DEFAULT_WEIGHTED_SCORE,
} from '@/models/datasets'

I/O Contract

Because this implementation describes type definitions rather than a callable function, the I/O contract describes the fields that consumers set (inputs) and the resulting configuration object (output).

Inputs (User-Configured Fields)

Name	Type	Required	Description
search_method	'full_text_search' | 'hybrid_search'	Yes	The primary retrieval algorithm to use when querying the knowledge base
reranking_enable	boolean	Yes	Whether to apply a second-pass reranking step to initial retrieval results
reranking_model	{ reranking_provider_name: string, reranking_model_name: string }	No (required if reranking_enable is true and reranking_mode is RerankingModel)	The external reranking model to use for second-pass scoring
reranking_mode	RerankingModeEnum	No (relevant when reranking is enabled)	Whether to use an external reranking model or weighted score blending
weights	{ semantic: number, keyword: number }	No (relevant for hybrid search with weighted score mode)	The blend weights for combining semantic and keyword scores; must sum to 1.0
top_k	number	Yes	Maximum number of segments to return from retrieval (typical range: 1--10)
score_threshold_enabled	boolean	Yes	Whether to filter out results below the score threshold
score_threshold	number	No (required if score_threshold_enabled is true)	Minimum relevance score (0.0--1.0) for a result to be included

Outputs (Complete Configuration Object)

Name	Type	Description
RetrievalConfig	object	A complete retrieval configuration object that is persisted on the dataset and passed to retrieval endpoints (e.g., hit testing, RAG query execution)

Usage Examples

Constructing a Default Retrieval Configuration

import { RetrievalConfig } from '@/types/app'
import { RerankingModeEnum, WeightedScoreEnum, DEFAULT_WEIGHTED_SCORE } from '@/models/datasets'

const defaultConfig: RetrievalConfig = {
  search_method: 'hybrid_search',
  reranking_enable: true,
  reranking_mode: RerankingModeEnum.WeightedScore,
  weights: DEFAULT_WEIGHTED_SCORE[WeightedScoreEnum.SemanticFirst],
  top_k: 5,
  score_threshold_enabled: true,
  score_threshold: 0.5,
}

Switching Between Reranking Modes

import { RerankingModeEnum } from '@/models/datasets'

const handleRerankingModeChange = (mode: RerankingModeEnum) => {
  if (mode === RerankingModeEnum.RerankingModel) {
    setConfig(prev => ({
      ...prev,
      reranking_mode: mode,
      reranking_model: {
        reranking_provider_name: 'cohere',
        reranking_model_name: 'rerank-english-v2.0',
      },
      weights: undefined,
    }))
  } else {
    setConfig(prev => ({
      ...prev,
      reranking_mode: mode,
      reranking_model: undefined,
      weights: DEFAULT_WEIGHTED_SCORE[WeightedScoreEnum.SemanticFirst],
    }))
  }
}

Using Weighted Score Presets

import { WeightedScoreEnum, DEFAULT_WEIGHTED_SCORE } from '@/models/datasets'

// Apply a preset
const applyPreset = (preset: WeightedScoreEnum) => {
  const weights = DEFAULT_WEIGHTED_SCORE[preset]
  setConfig(prev => ({ ...prev, weights }))
}

applyPreset(WeightedScoreEnum.SemanticFirst)
// weights: { semantic: 0.7, keyword: 0.3 }

applyPreset(WeightedScoreEnum.KeywordFirst)
// weights: { semantic: 0.3, keyword: 0.7 }

applyPreset(WeightedScoreEnum.Customized)
// weights: { semantic: 0.5, keyword: 0.5 } -- user can then adjust

Passing Configuration to Hit Testing

import { hitTesting } from '@/service/datasets'
import type { RetrievalConfig } from '@/types/app'

const runTest = async (datasetId: string, query: string, config: RetrievalConfig) => {
  const results = await hitTesting({
    datasetId,
    queryText: query,
    retrieval_model: config,
  })
  return results.records
}

Related Pages

Implements Principle

• Principle:Langgenius_Dify_Retrieval_Configuration

Requires Environment

• Environment:Langgenius_Dify_Vector_Database_Environment