Skip to content

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

fix(agent): honor sampler enable flags in Go LLM and Agent components (#20259)

Eugene Kalininfb59ffc5ca13
diff --git a/internal/agent/component/agent.go b/internal/agent/component/agent.go
index a9a8b21007..c764b8e10b 100644
--- a/internal/agent/component/agent.go
+++ b/internal/agent/component/agent.go
@@ -110,6 +110,13 @@ type AgentParam struct {
Driver string
APIKey string
BaseURL string
+
+ // MaxTokensDisabled, TopPDisabled and TemperatureDisabled record a DSL
+ // *Enabled switch set to false, so runtime inputs that carry the value
+ // without its switch do not bring it back (see gateSampler).
+ MaxTokensDisabled bool
+ TopPDisabled bool
+ TemperatureDisabled bool
}
// SubAgentTool is a child Agent exposed to a parent Agent as an Eino tool.
@@ -1569,17 +1576,17 @@ func mergeAgentParam(base AgentParam, inputs map[string]any) AgentParam {
f := v
p.TopP = &f
}
+ gateSampler(inputs, "topPEnabled", &p.TopP, &p.TopPDisabled)
if v, ok := intFrom(inputs, "max_tokens"); ok {
f := v
p.MaxTokens = &f
}
- if enabled, ok := boolFrom(inputs, "maxTokensEnabled"); ok && !enabled {
- p.MaxTokens = nil
- }
+ gateSampler(inputs, "maxTokensEnabled", &p.MaxTokens, &p.MaxTokensDisabled)
if v, ok := floatFrom(inputs, "temperature"); ok {
f := v
p.Temperature = &f
}
+ gateSampler(inputs, "temperatureEnabled", &p.Temperature, &p.TemperatureDisabled)
if v, ok := stringFrom(inputs, "thinking"); ok && v != "" && v != "default" {
p.Thinking = v
}
diff --git a/internal/agent/component/agent_test.go b/internal/agent/component/agent_test.go
index ab2fc4031b..d6e6e362c1 100644
--- a/internal/agent/component/agent_test.go
+++ b/internal/agent/component/agent_test.go
@@ -1376,3 +1376,25 @@ func TestAgentDisabledMaxTokens(t *testing.T) {
}
}
}
+
+func TestAgentDisabledTemperatureAndTopP(t *testing.T) {
+ p := mergeAgentParam(AgentParam{}, map[string]any{
+ "temperature": 0.2, "temperatureEnabled": false,
+ "top_p": 0.75, "topPEnabled": false,
+ })
+ if p.Temperature != nil {
+ t.Fatalf("disabled temperature still applied: %v", *p.Temperature)
+ }
+ if p.TopP != nil {
+ t.Fatalf("disabled top_p still applied: %v", *p.TopP)
+ }
+ for _, inputs := range []map[string]any{
+ {"temperature": 0.2, "top_p": 0.75},
+ {"temperature": 0.2, "temperatureEnabled": true, "top_p": 0.75, "topPEnabled": true},
+ } {
+ p = mergeAgentParam(AgentParam{}, inputs)
+ if p.Temperature == nil || *p.Temperature != 0.2 || p.TopP == nil || *p.TopP != 0.75 {
+ t.Fatal("enabled or unflagged temperature/top_p lost")
+ }
+ }
+}
diff --git a/internal/agent/component/llm.go b/internal/agent/component/llm.go
index 8063b95681..f920dd2797 100644
--- a/internal/agent/component/llm.go
+++ b/internal/agent/component/llm.go
@@ -66,6 +66,16 @@ type LLMParam struct {
// same line verbatim.
FrequencyPenalty *float64
+ // TemperatureDisabled, TopPDisabled, MaxTokensDisabled,
+ // PresencePenaltyDisabled and FrequencyPenaltyDisabled record a DSL
+ // *Enabled switch set to false, so runtime inputs that carry the value
+ // without its switch do not bring it back (see gateSampler).
+ TemperatureDisabled bool
+ TopPDisabled bool
+ MaxTokensDisabled bool
+ PresencePenaltyDisabled bool
+ FrequencyPenaltyDisabled bool
+
// Driver is the configured provider driver to use (e.g. "openai"). When
// empty, the default ChatInvoker derives it from ModelID or uses the explicit
// test/development-only dummy driver.
@@ -1350,18 +1360,22 @@ func mergeLLMParam(base LLMParam, inputs map[string]any) LLMParam {
f := v
p.Temperature = &f
}
+ gateSampler(inputs, "temperatureEnabled", &p.Temperature, &p.TemperatureDisabled)
if v, ok := floatFrom(inputs, "top_p"); ok {
f := v
p.TopP = &f
}
+ gateSampler(inputs, "topPEnabled", &p.TopP, &p.TopPDisabled)
if v, ok := floatFrom(inputs, "presence_penalty"); ok {
f := v
p.PresencePenalty = &f
}
+ gateSampler(inputs, "presencePenaltyEnabled", &p.PresencePenalty, &p.PresencePenaltyDisabled)
if v, ok := floatFrom(inputs, "frequency_penalty"); ok {
f := v
p.FrequencyPenalty = &f
}
+ gateSampler(inputs, "frequencyPenaltyEnabled", &p.FrequencyPenalty, &p.FrequencyPenaltyDisabled)
// visual_files: accept []string or single string with embedded
// data URIs. The current implementation only walks top-level
// string values; recursive walk is a future enhancement.
@@ -1374,6 +1388,7 @@ func mergeLLMParam(base LLMParam, inputs map[string]any) LLMParam {
i := v
p.MaxTokens = &i
}
+ gateSampler(inputs, "maxTokensEnabled", &p.MaxTokens, &p.MaxTokensDisabled)
if v, ok := stringFrom(inputs, "thinking"); ok {
// Forward any non-empty, non-"default" value to match the
// lenient Python gate: hasattr(self,"thinking") and
@@ -1427,6 +1442,19 @@ func boolFrom(inputs map[string]any, name string) (bool, bool) {
return false, false
}
+// gateSampler applies the sampler switch inputs[flag] to value. The switch
+// state is kept in disabled, so a later merge whose inputs carry the value
+// without the switch still drops it. Mirrors Python's LLMParam.gen_conf, which
+// only sends a sampler value when its switch is on.
+func gateSampler[T any](inputs map[string]any, flag string, value **T, disabled *bool) {
+ if enabled, ok := boolFrom(inputs, flag); ok {
+ *disabled = !enabled
+ }
+ if *disabled {
+ *value = nil
+ }
+}
+
// floatFrom extracts a float64 from inputs[name], also accepting int.
func floatFrom(inputs map[string]any, name string) (float64, bool) {
v, ok := inputs[name]
@@ -1484,14 +1512,17 @@ func init() {
f := v
p.Temperature = &f
}
+ gateSampler(params, "temperatureEnabled", &p.Temperature, &p.TemperatureDisabled)
if v, ok := floatFrom(params, "top_p"); ok {
f := v
p.TopP = &f
}
+ gateSampler(params, "topPEnabled", &p.TopP, &p.TopPDisabled)
if v, ok := intFrom(params, "max_tokens"); ok {
i := v
p.MaxTokens = &i
}
+ gateSampler(params, "maxTokensEnabled", &p.MaxTokens, &p.MaxTokensDisabled)
if v, ok := boolFrom(params, "json_output"); ok {
p.JSONOutput = v
}
@@ -1502,10 +1533,12 @@ func init() {
f := v
p.PresencePenalty = &f
}
+ gateSampler(params, "presencePenaltyEnabled", &p.PresencePenalty, &p.PresencePenaltyDisabled)
if v, ok := floatFrom(params, "frequency_penalty"); ok {
f := v
p.FrequencyPenalty = &f
}
+ gateSampler(params, "frequencyPenaltyEnabled", &p.FrequencyPenalty, &p.FrequencyPenaltyDisabled)
// cite defaults to true (matches Python) when neither LLMParam
// nor inputs set it.
p.Cite = true
diff --git a/internal/agent/component/sampler_params_test.go b/internal/agent/component/sampler_params_test.go
index c407155480..dfc1423c29 100644
--- a/internal/agent/component/sampler_params_test.go
+++ b/internal/agent/component/sampler_params_test.go
@@ -18,10 +18,17 @@ package component
import (
"context"
+ "encoding/json"
+ "maps"
"math"
+ "net/http"
+ "net/http/httptest"
+ "sync"
"testing"
"github.com/cloudwego/eino/schema"
+
+ "ragflow/internal/entity/models"
)
// TestLLM_ForwardsTopP verifies that a TopP value on LLMParam reaches
@@ -118,6 +125,161 @@ func TestLLMFactory_ParsesTopP(t *testing.T) {
}
}
+// TestLLMFactory_DisabledSamplerParams verifies that the LLM factory drops
+// sampler values whose *Enabled flag is false, matching Python's
+// LLMParam.gen_conf, and keeps them when the flag is true.
+func TestLLMFactory_DisabledSamplerParams(t *testing.T) {
+ params := map[string]any{
+ "model_id": "echo",
+ "temperature": 0.2,
+ "top_p": 0.75,
+ "max_tokens": 256,
+ "presence_penalty": 0.4,
+ "frequency_penalty": 0.7,
+ }
+ flags := []string{"temperatureEnabled", "topPEnabled", "maxTokensEnabled", "presencePenaltyEnabled", "frequencyPenaltyEnabled"}
+
+ build := func(enabled bool) LLMParam {
+ t.Helper()
+ conf := maps.Clone(params)
+ for _, flag := range flags {
+ conf[flag] = enabled
+ }
+ c, err := New("LLM", conf)
+ if err != nil {
+ t.Fatalf("New(LLM): %v", err)
+ }
+ return c.(*LLMComponent).param
+ }
+
+ p := build(false)
+ if p.Temperature != nil {
+ t.Errorf("disabled temperature still applied: %v", *p.Temperature)
+ }
+ if p.TopP != nil {
+ t.Errorf("disabled top_p still applied: %v", *p.TopP)
+ }
+ if p.MaxTokens != nil {
+ t.Errorf("disabled max_tokens still applied: %v", *p.MaxTokens)
+ }
+ if p.PresencePenalty != nil {
+ t.Errorf("disabled presence_penalty still applied: %v", *p.PresencePenalty)
+ }
+ if p.FrequencyPenalty != nil {
+ t.Errorf("disabled frequency_penalty still applied: %v", *p.FrequencyPenalty)
+ }
+
+ p = build(true)
+ if p.Temperature == nil || p.TopP == nil || p.MaxTokens == nil || p.PresencePenalty == nil || p.FrequencyPenalty == nil {
+ t.Errorf("enabled sampler params lost: temperature=%v top_p=%v max_tokens=%v presence_penalty=%v frequency_penalty=%v",
+ p.Temperature != nil, p.TopP != nil, p.MaxTokens != nil, p.PresencePenalty != nil, p.FrequencyPenalty != nil)
+ }
+}
+
+// TestLLM_DisabledSamplersStayOffAtRuntime verifies that runtime inputs
+// carrying a sampler value without its *Enabled flag do not bring back a value
+// the DSL switched off, checked on the request sent to the ChatInvoker.
+func TestLLM_DisabledSamplersStayOffAtRuntime(t *testing.T) {
+ stub := &stubInvoker{resp: &ChatInvokeResponse{Content: "ok", Model: "echo"}}
+ withStubInvoker(t, stub)
+
+ c, err := New("LLM", map[string]any{
+ "model_id": "echo",
+ "temperature": 0.2,
+ "temperatureEnabled": false,
+ "top_p": 0.75,
+ "topPEnabled": false,
+ "max_tokens": 256,
+ "maxTokensEnabled": false,
+ "presence_penalty": 0.4,
+ "presencePenaltyEnabled": false,
+ "frequency_penalty": 0.7,
+ "frequencyPenaltyEnabled": false,
+ })
+ if err != nil {
+ t.Fatalf("New(LLM): %v", err)
+ }
+ if _, err := c.Invoke(t.Context(), nil, map[string]any{
+ "user_prompt": "hi",
+ "temperature": 0.9,
+ "top_p": 0.5,
+ "max_tokens": 128,
+ "presence_penalty": 0.3,
+ "frequency_penalty": 0.3,
+ }); err != nil {
+ t.Fatalf("Invoke: %v", err)
+ }
+ req := stub.captured
+ if req == nil {
+ t.Fatalf("invoker captured no request")
+ }
+ if req.Temperature != nil || req.TopP != nil || req.MaxTokens != nil || req.PresencePenalty != nil || req.FrequencyPenalty != nil {
+ t.Errorf("disabled sampler params sent: temperature=%v top_p=%v max_tokens=%v presence_penalty=%v frequency_penalty=%v",
+ req.Temperature != nil, req.TopP != nil, req.MaxTokens != nil, req.PresencePenalty != nil, req.FrequencyPenalty != nil)
+ }
+}
+
+// TestAgent_DisabledSamplersStayOffAtRuntime verifies that runtime inputs
+// carrying a sampler value without its *Enabled flag do not bring back a value
+// the DSL switched off, checked on the request body sent to the provider.
+func TestAgent_DisabledSamplersStayOffAtRuntime(t *testing.T) {
+ setupAllowAnyHost(t, true)
+ if err := models.InitProviderManager("../../../conf/models"); err != nil {
+ t.Fatalf("InitProviderManager: %v", err)
+ }
+
+ var mu sync.Mutex
+ var bodies []map[string]any
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ var body map[string]any
+ _ = json.NewDecoder(r.Body).Decode(&body)
+ mu.Lock()
+ bodies = append(bodies, body)
+ mu.Unlock()
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+ }))
+ defer server.Close()
+
+ c, err := New("Agent", map[string]any{
+ "llm_id": "qwen-flash",
+ "driver": "Tongyi-Qianwen",
+ "api_key": "test-key",
+ "base_url": server.URL,
+ "max_rounds": 1,
+ "temperature": 0.2,
+ "temperatureEnabled": false,
+ "top_p": 0.75,
+ "topPEnabled": false,
+ "max_tokens": 256,
+ "maxTokensEnabled": false,
+ })
+ if err != nil {
+ t.Fatalf("New(Agent): %v", err)
+ }
+ if _, err := c.Invoke(t.Context(), nil, map[string]any{
+ "user_prompt": "hi",
+ "temperature": 0.9,
+ "top_p": 0.5,
+ "max_tokens": 128,
+ }); err != nil {
+ t.Fatalf("Invoke: %v", err)
+ }
+
+ mu.Lock()
+ defer mu.Unlock()
+ if len(bodies) == 0 {
+ t.Fatalf("provider received no request")
+ }
+ for _, body := range bodies {
+ for _, key := range []string{"temperature", "top_p", "max_tokens"} {
+ if v, ok := body[key]; ok {
+ t.Errorf("disabled %s sent to provider: %v", key, v)
+ }
+ }
+ }
+}
+
// TestAgentParam_ForwardsTopP verifies AgentParam.TopP reaches
// buildAgentChatModel and produces a ChatConfig with the value set.
//