Model Selection UI#

The Set Default Model page in RAGFlow's user settings lets users assign system-wide defaults for six model roles: Chat, Embedding, Image-to-Text, ASR (speech recognition), Rerank, and TTS. The UI is built from two primary components: ModelTreeSelect (a reusable picker) and SystemSetting (the page-level form).

Key Files#

ModelTreeSelect Component#

ModelTreeSelect (model-tree-select.tsx) is the central reusable component. Given a list of modelTypes, it:

1. Fetches added models via useFetchAllAddedModels, optionally scoped to ownerTenantId.
2. Builds a three-level tree via buildModelTree: Provider → Instance → Model. Leaf nodes carry { provider_name, instance_name, model_name } in their data field and render a LlmIcon + display name.
3. Handles legacy IDs: Legacy string IDs (modelName@instanceName@providerName) are mapped to current model_id-based IDs at runtime via legacyIdMap, preserving backward compatibility.
4. Renders using the base TreeSelect primitive with defaultExpandAll and optional search.

Field-to-Type Mapping#

ModelTypeMap defines which model types each form field accepts:

This map is used both in ModelTreeSelect (to filter which models appear) and in FieldToModelType (to resolve the API payload's model_type).

Form Field Wrapper#

ModelTreeSelectFormField wraps ModelTreeSelect in a react-hook-form <FormField>, adding label, tooltip, and validation message support. Use this variant when embedding the picker inside an <Form> context.

SystemSetting Component#

SystemSetting composes ModelFieldItem rows — one per model role — and manages state through three layers:

1. localStorage (key: ragflow-system-model-settings) — Written on every change via savePersistedValues, read on mount via loadPersistedValues. Survives page refreshes and bridges gaps when the backend hasn't returned a value yet.
2. API response — useFetchDefaultModelDictionary fetches current defaults from GET /api/v1/models/default and converts the array to a dictionary keyed by field name.
3. Empty string fallback — Used when neither localStorage nor the API has a value.

getValue applies this resolution order: localStorage → API → ''.

On change, handleFieldChange immediately updates local state (for instant UI feedback), then calls useSetDefaultModel to persist via the API. llm_id (Chat Model) is the only required field; all others allow clearing 1.

Data Flow#

useFetchAllAddedModels
        │
        ▼
  buildModelTree() ──► Provider → Instance → Model (tree)
        │
        ▼
   TreeSelect (base primitive)
        │
        ▼
  ModelTreeSelect ◄── ModelTypeMap (filters by role)
        │
        ▼
  ModelFieldItem ◄── SystemSetting (getValue / handleFieldChange)
        │
        ▼
  useSetDefaultModel → POST /api/v1/models/default

Extension Points#

• Use ModelTreeSelect standalone (outside a form) — pass value + onChange directly and set modelTypes to any subset from ModelTypeMap.
• Use ModelTreeSelectFormField inside a <Form> — just pass name matching the react-hook-form field.
• Custom leaf rendering — buildModelTree accepts an optional renderLeafLabel callback 2 for custom node display.
• Tenant scoping — pass ownerTenantId to ModelTreeSelect to fetch models for a specific tenant 3.