Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(knowledge-compiler): honor node settings and degrade missing vector mapping (#22026)

buua43631e436c89d4d
diff --git a/internal/entity/models/base_model.go b/internal/entity/models/base_model.go
index f5d9c199b9..38728cc506 100644
--- a/internal/entity/models/base_model.go
+++ b/internal/entity/models/base_model.go
@@ -584,6 +584,8 @@ func buildRequestBody(cfg *ChatConfig, modelName string, messages []Message, str
setOpt(reqBody, "temperature", cfg.Temperature)
setOpt(reqBody, "do_sample", cfg.DoSample)
setOpt(reqBody, "top_p", cfg.TopP)
+ setOpt(reqBody, "presence_penalty", cfg.PresencePenalty)
+ setOpt(reqBody, "frequency_penalty", cfg.FrequencyPenalty)
setOpt(reqBody, "max_tokens", cfg.MaxTokens)
setOpt(reqBody, "stop", cfg.Stop)
diff --git a/internal/entity/models/types.go b/internal/entity/models/types.go
index 306d55d24d..13fedb5e1b 100644
--- a/internal/entity/models/types.go
+++ b/internal/entity/models/types.go
@@ -281,21 +281,23 @@ type URLSuffix struct {
}
type ChatConfig struct {
- Stream *bool
- Vision *bool
- Thinking *bool
- MaxTokens *int
- Temperature *float64
- TopP *float64
- DoSample *bool
- Stop *[]string
- ModelClass *string
- Effort *string
- Verbosity *string
- Tools interface{} `json:"tools,omitempty"`
- ToolChoice *string `json:"tool_choice,omitempty"`
- ToolChoiceValue any `json:"-"`
- ToolCallsResult *[]map[string]interface{} `json:"-"`
+ Stream *bool
+ Vision *bool
+ Thinking *bool
+ MaxTokens *int
+ Temperature *float64
+ TopP *float64
+ PresencePenalty *float64
+ FrequencyPenalty *float64
+ DoSample *bool
+ Stop *[]string
+ ModelClass *string
+ Effort *string
+ Verbosity *string
+ Tools interface{} `json:"tools,omitempty"`
+ ToolChoice *string `json:"tool_choice,omitempty"`
+ ToolChoiceValue any `json:"-"`
+ ToolCallsResult *[]map[string]interface{} `json:"-"`
// UsageResult receives the token usage extracted from the final
// streaming chunk when stream_options.include_usage is true.
// The ChatStreamlyWithSender driver writes to this pointer (if
diff --git a/internal/ingestion/component/knowledge_compiler/common/deps.go b/internal/ingestion/component/knowledge_compiler/common/deps.go
index 7428669f95..cdc5c7b2a1 100644
--- a/internal/ingestion/component/knowledge_compiler/common/deps.go
+++ b/internal/ingestion/component/knowledge_compiler/common/deps.go
@@ -21,28 +21,77 @@ type ChatRequest struct {
SystemPrompt string
UserPrompt string
JSONMode bool
- // Temperature is optional; nil leaves the driver default. Python's
- // knowledge compilation pins extraction at 0.1 and merge judging at 0.0,
- // so variants set it per call site.
- Temperature *float64
- // MaxTokens is an optional per-call override. Normal knowledge-compilation
- // calls use the selected model's configured max_output value.
- MaxTokens *int
- APIKey string
- BaseURL string
- // DisableThinking asks the driver to turn chain-of-thought OFF. Reasoning
- // models (MiniMax-M1/M3, kimi, qwen) otherwise spend the completion budget
- // (and minutes) on visible COT before returning the structured payload —
- // the fastest way to slow knowledge compilation to a crawl. Providers that
- // have no thinking control silently ignore it. Defaults to false, so only
- // call sites that know the model reasons opt in.
+ // These fields are per-call defaults. Run-level ChatSettings override them
+ // when the caller explicitly enables a setting in the compiler node.
+ Temperature *float64
+ TopP *float64
+ PresencePenalty *float64
+ FrequencyPenalty *float64
+ MaxTokens *int
+ // Thinking explicitly controls reasoning when non-nil. DisableThinking is a
+ // call-site default retained for compiler steps that must avoid reasoning;
+ // an explicit Thinking setting takes precedence.
+ Thinking *bool
DisableThinking bool
+ APIKey string
+ BaseURL string
// DisableRetry tells the production ChatInvoker that the caller owns
// transient-error retries (GenJSON is such a caller). It is internal
// plumbing and is not part of the user-facing model request.
DisableRetry bool
}
+// ChatSettings are caller-provided LLM overrides for every request in one
+// knowledge-compilation run. Nil values leave each call site's defaults intact;
+// ThinkingSet distinguishes an explicit "default" choice from no setting.
+type ChatSettings struct {
+ Temperature *float64
+ TopP *float64
+ PresencePenalty *float64
+ FrequencyPenalty *float64
+ MaxTokens *int
+ Thinking *bool
+ ThinkingSet bool
+}
+
+type chatSettingsInvoker struct {
+ next ChatInvoker
+ settings ChatSettings
+}
+
+// WithChatSettings applies explicit run-level settings over each compiler
+// call's defaults while preserving fields the caller did not configure.
+func WithChatSettings(next ChatInvoker, settings ChatSettings) ChatInvoker {
+ settingsEmpty := settings.Temperature == nil && settings.TopP == nil && settings.PresencePenalty == nil && settings.FrequencyPenalty == nil && settings.MaxTokens == nil && !settings.ThinkingSet
+ if next == nil || settingsEmpty {
+ return next
+ }
+ return chatSettingsInvoker{next: next, settings: settings}
+}
+
+func (c chatSettingsInvoker) Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error) {
+ if c.settings.Temperature != nil {
+ req.Temperature = c.settings.Temperature
+ }
+ if c.settings.TopP != nil {
+ req.TopP = c.settings.TopP
+ }
+ if c.settings.PresencePenalty != nil {
+ req.PresencePenalty = c.settings.PresencePenalty
+ }
+ if c.settings.FrequencyPenalty != nil {
+ req.FrequencyPenalty = c.settings.FrequencyPenalty
+ }
+ if c.settings.MaxTokens != nil {
+ req.MaxTokens = c.settings.MaxTokens
+ }
+ if c.settings.ThinkingSet {
+ req.Thinking = c.settings.Thinking
+ req.DisableThinking = false
+ }
+ return c.next.Chat(ctx, req)
+}
+
// ChatResponse holds the LLM's text answer.
type ChatResponse struct {
Content string
diff --git a/internal/ingestion/component/knowledge_compiler/common/types.go b/internal/ingestion/component/knowledge_compiler/common/types.go
index 68a99e2988..cddbfd6dcd 100644
--- a/internal/ingestion/component/knowledge_compiler/common/types.go
+++ b/internal/ingestion/component/knowledge_compiler/common/types.go
@@ -11,6 +11,7 @@ package common
import (
"errors"
"fmt"
+ "math"
"strings"
appcommon "ragflow/internal/common"
@@ -58,6 +59,7 @@ type Param struct {
LLMID string
EmbeddingModel string
+ ChatSettings ChatSettings
Language string
// SimilarityThreshold defaults to 0.99 when not provided (see Defaults).
SimilarityThreshold float64
@@ -175,6 +177,42 @@ func ParseParam(m map[string]any) (Param, error) {
if v, ok := m["llm_id"].(string); ok {
p.LLMID = v
}
+ var err error
+ if p.ChatSettings.Temperature, err = optionalFloatSetting(m, "temperature", "temperatureEnabled"); err != nil {
+ return p, err
+ }
+ if p.ChatSettings.TopP, err = optionalFloatSetting(m, "top_p", "topPEnabled"); err != nil {
+ return p, err
+ }
+ if p.ChatSettings.PresencePenalty, err = optionalFloatSetting(m, "presence_penalty", "presencePenaltyEnabled"); err != nil {
+ return p, err
+ }
+ if p.ChatSettings.FrequencyPenalty, err = optionalFloatSetting(m, "frequency_penalty", "frequencyPenaltyEnabled"); err != nil {
+ return p, err
+ }
+ if p.ChatSettings.MaxTokens, err = optionalIntSetting(m, "max_tokens", "maxTokensEnabled"); err != nil {
+ return p, err
+ }
+ if raw, ok := m["thinking"]; ok && raw != nil {
+ thinking, valid := raw.(string)
+ if !valid {
+ return p, fmt.Errorf("knowledge_compiler: thinking must be a string")
+ }
+ switch strings.TrimSpace(thinking) {
+ case "", "default":
+ p.ChatSettings.ThinkingSet = true
+ case "enabled":
+ enabled := true
+ p.ChatSettings.Thinking = &enabled
+ p.ChatSettings.ThinkingSet = true
+ case "disabled":
+ disabled := false
+ p.ChatSettings.Thinking = &disabled
+ p.ChatSettings.ThinkingSet = true
+ default:
+ return p, fmt.Errorf("knowledge_compiler: unsupported thinking setting %q", thinking)
+ }
+ }
if v, ok := m["embedding_model"].(string); ok {
p.EmbeddingModel = v
}
@@ -198,6 +236,64 @@ func ParseParam(m map[string]any) (Param, error) {
return p, nil
}
+func optionalFloatSetting(params map[string]any, key, enabledKey string) (*float64, error) {
+ if !settingEnabled(params, enabledKey) {
+ return nil, nil
+ }
+ raw, ok := params[key]
+ if !ok {
+ return nil, nil
+ }
+ value, ok := numericValue(raw)
+ if !ok {
+ return nil, fmt.Errorf("knowledge_compiler: %s must be numeric", key)
+ }
+ return &value, nil
+}
+
+func optionalIntSetting(params map[string]any, key, enabledKey string) (*int, error) {
+ if !settingEnabled(params, enabledKey) {
+ return nil, nil
+ }
+ raw, ok := params[key]
+ if !ok {
+ return nil, nil
+ }
+ value, ok := numericValue(raw)
+ maxInt := int(^uint(0) >> 1)
+ if !ok || math.Trunc(value) != value || value <= 0 || value >= float64(maxInt) {
+ return nil, fmt.Errorf("knowledge_compiler: %s must be a positive integer", key)
+ }
+ intValue := int(value)
+ return &intValue, nil
+}
+
+func settingEnabled(params map[string]any, enabledKey string) bool {
+ raw, exists := params[enabledKey]
+ if !exists {
+ return true
+ }
+ enabled, ok := raw.(bool)
+ return ok && enabled
+}
+
+func numericValue(value any) (float64, bool) {
+ switch value := value.(type) {
+ case float64:
+ return value, true
+ case float32:
+ return float64(value), true
+ case int:
+ return float64(value), true
+ case int64:
+ return float64(value), true
+ case int32:
+ return float64(value), true
+ default:
+ return 0, false
+ }
+}
+
// PlanEnabled reports whether wiki topic mode is selected. An unset value
// defaults to entity mode.
func (p Param) PlanEnabled() bool {
diff --git a/internal/ingestion/component/knowledge_compiler/component.go b/internal/ingestion/component/knowledge_compiler/component.go
index e576f838a6..1fab7e5d2d 100644
--- a/internal/ingestion/component/knowledge_compiler/component.go
+++ b/internal/ingestion/component/knowledge_compiler/component.go
@@ -162,6 +162,10 @@ func (c *KnowledgeCompilerComponent) Invoke(ctx context.Context, db *gorm.DB, in
if err != nil {
return nil, err
}
+ deps.Chat = common.WithChatSettings(deps.Chat, specParam.ChatSettings)
+ if maxTokens := specParam.ChatSettings.MaxTokens; maxTokens != nil && (deps.ModelMaxOutput <= 0 || *maxTokens < deps.ModelMaxOutput) {
+ deps.ModelMaxOutput = *maxTokens
+ }
deps.TenantID = tenantID
deps.DatasetID = datasetID
// Reserve 1% for converting and merging all products.
diff --git a/internal/ingestion/task/knowledge_compiler_wiring.go b/internal/ingestion/task/knowledge_compiler_wiring.go
index 1daeccde2f..af98517bd5 100644
--- a/internal/ingestion/task/knowledge_compiler_wiring.go
+++ b/internal/ingestion/task/knowledge_compiler_wiring.go
@@ -37,6 +37,7 @@ import (
appcommon "ragflow/internal/common"
+ "go.uber.org/zap"
"gorm.io/gorm"
)
@@ -638,14 +639,23 @@ func (c *kcChatInvoker) Chat(ctx context.Context, req kc.ChatRequest) (*kc.ChatR
// (extraction 0.1, merge judging 0.0); nil leaves the driver default.
var config *models.ChatConfig
// Build a provider config only for per-call overrides. In particular, do not
- // inject the model's configured max_output as max_tokens: knowledge
- // compilation call sites that need an output cap must set MaxTokens
- // explicitly, while the model driver remains responsible for its default.
- if req.Temperature != nil || req.MaxTokens != nil || req.DisableThinking {
+ // inject the model's configured max_output as max_tokens: call-site or
+ // compiler-node settings may override it, while the model driver remains
+ // responsible for its configured default when neither is set.
+ if req.Temperature != nil || req.TopP != nil || req.PresencePenalty != nil || req.FrequencyPenalty != nil || req.MaxTokens != nil || req.Thinking != nil || req.DisableThinking {
config = &models.ChatConfig{}
if req.Temperature != nil {
config.Temperature = req.Temperature
}
+ if req.TopP != nil {
+ config.TopP = req.TopP
+ }
+ if req.PresencePenalty != nil {
+ config.PresencePenalty = req.PresencePenalty
+ }
+ if req.FrequencyPenalty != nil {
+ config.FrequencyPenalty = req.FrequencyPenalty
+ }
if req.MaxTokens != nil {
config.MaxTokens = req.MaxTokens
}
@@ -653,7 +663,9 @@ func (c *kcChatInvoker) Chat(ctx context.Context, req kc.ChatRequest) (*kc.ChatR
// budget on visible COT before the structured reply; compilation should
// run with thinking off. MiniMaxModel maps Thinking=false to
// `thinking: {"type": "disabled"}` in the request body.
- if req.DisableThinking {
+ if req.Thinking != nil {
+ config.Thinking = req.Thinking
+ } else if req.DisableThinking {
off := false
config.Thinking = &off
}
@@ -838,17 +850,22 @@ func float64sToFloat32(in []float64) []float32 {
}
type kcWikiPageStore struct {
- docEngine engine.DocEngine
+ docEngine engine.DocEngine
+ vectorSearchUnavailable atomic.Bool
}
func (s *kcWikiPageStore) FindSimilarPages(ctx context.Context, tenantID, datasetID string, queryVec []float32, k int) ([]kc.WikiPageCandidate, error) {
if s == nil || s.docEngine == nil || len(queryVec) == 0 || k <= 0 || strings.TrimSpace(datasetID) == "" {
return nil, nil
}
+ if s.vectorSearchUnavailable.Load() {
+ return nil, nil
+ }
vec := make([]float64, len(queryVec))
for i, v := range queryVec {
vec[i] = float64(v)
}
+ vectorField := fmt.Sprintf("q_%d_vec", len(vec))
req := &enginetypes.SearchRequest{
IndexNames: []string{fmt.Sprintf("ragflow_%s", tenantID)},
KbIDs: []string{datasetID},
@@ -859,7 +876,7 @@ func (s *kcWikiPageStore) FindSimilarPages(ctx context.Context, tenantID, datase
"type_kwd": "wiki_page",
},
MatchExprs: []interface{}{&enginetypes.MatchDenseExpr{
- VectorColumnName: fmt.Sprintf("q_%d_vec", len(vec)),
+ VectorColumnName: vectorField,
EmbeddingData: vec,
EmbeddingDataType: "float",
DistanceType: "cosine",
@@ -868,7 +885,22 @@ func (s *kcWikiPageStore) FindSimilarPages(ctx context.Context, tenantID, datase
}},
}
res, err := s.docEngine.Search(ctx, req)
- if err != nil || res == nil {
+ if err != nil {
+ if isMissingVectorFieldMappingError(err, vectorField) {
+ if s.vectorSearchUnavailable.CompareAndSwap(false, true) {
+ appcommon.Warn("wiki: skipping similar-page lookup because vector field is not mapped",
+ zap.String("tenant_id", tenantID),
+ zap.String("dataset_id", datasetID),
+ zap.String("index_name", req.IndexNames[0]),
+ zap.String("vector_field", vectorField),
+ zap.Error(err),
+ )
+ }
+ return nil, nil
+ }
+ return nil, err
+ }
+ if res == nil {
return nil, err
}
out := make([]kc.WikiPageCandidate, 0, len(res.Chunks))
@@ -882,6 +914,10 @@ func (s *kcWikiPageStore) FindSimilarPages(ctx context.Context, tenantID, datase
return out, nil
}
+func isMissingVectorFieldMappingError(err error, field string) bool {
+ return err != nil && strings.Contains(err.Error(), fmt.Sprintf("field [%s] does not exist in the mapping", field))
+}
+
func (s *kcWikiPageStore) GetPageBySlug(ctx context.Context, tenantID, datasetID, slug string) (*kc.WikiPageCandidate, error) {
if s == nil || s.docEngine == nil || strings.TrimSpace(datasetID) == "" || strings.TrimSpace(slug) == "" {
return nil, nil