Skip to content

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

Fix: make the provider response-header timeout configurable (#21434)

CCLUCKYb5500ff7d3e8
diff --git a/docker/.env b/docker/.env
index ace2a8ba3a..fec0b927ba 100644
--- a/docker/.env
+++ b/docker/.env
@@ -401,6 +401,11 @@ RERANK_TOKEN_LIMIT_MODE=${RERANK_TOKEN_LIMIT_MODE:-truncate}
# This may contain sensitive information and generate massive logs. Use with caution.
# LLM_DEBUG=true
+# Bound how long a provider call may wait for response headers before the attempt fails.
+# A hung endpoint otherwise blocks every retry for the full client default (20m).
+# Accepts Go durations such as `45s` or `5m`. Unset keeps the default.
+# LLM_HTTP_RESPONSE_HEADER_TIMEOUT=60s
+
# aliyun OSS configuration
# STORAGE_IMPL=OSS
# ACCESS_KEY=xxx
diff --git a/internal/common/environments.go b/internal/common/environments.go
index 40120f83c9..c5025a0b21 100644
--- a/internal/common/environments.go
+++ b/internal/common/environments.go
@@ -21,6 +21,7 @@ import (
"path/filepath"
"strconv"
"strings"
+ "time"
)
func GetEnv(key string) string {
@@ -47,6 +48,22 @@ func GetEnvSmall(key string) string {
return strings.ToLower(GetEnv(key))
}
+// getEnvDuration reads a duration setting such as "90s" or "5m", falling back to
+// def when the variable is unset, malformed, or non-positive. A zero or
+// negative value would remove the deadline instead of tightening it, so it is
+// treated as a typo rather than as an instruction to disable the guard.
+func getEnvDuration(key string, def time.Duration) time.Duration {
+ raw := strings.TrimSpace(GetEnv(key))
+ if raw == "" {
+ return def
+ }
+ v, err := time.ParseDuration(raw)
+ if err != nil || v <= 0 {
+ return def
+ }
+ return v
+}
+
// SandboxArtifactBucket is the object-storage bucket that holds
// code-exec sandbox artifacts, served back through
// /api/v1/documents/artifact/<name>.
@@ -436,6 +453,17 @@ const (
EnvAgenticTokenBudget = "RAGFLOW_AGENTIC_TOKEN_BUDGET"
)
+// EnvLLMHTTPResponseHeaderTimeout bounds how long an outbound provider call may
+// wait for response headers. An endpoint that accepts the connection and then
+// never answers otherwise blocks each retry attempt for the full client default
+// (20m on both shared clients), so retries consume wall time instead of
+// retrying. One override covers both shared clients because a hung endpoint is
+// indistinguishable to the caller; each client keeps its own default while the
+// override is unset.
+// The value is a Go duration ("45s", "5m"), read once when a client is first
+// built. Unset, malformed, or non-positive keeps the client default.
+const EnvLLMHTTPResponseHeaderTimeout = "LLM_HTTP_RESPONSE_HEADER_TIMEOUT"
+
// DeepDocModelFiles is the single source of truth for the weights the
// in-process (Go) DeepDoc backend requires to serve. The Go backend consumes
// the FlatBuffer (.ort) serialization — the static ONNX Runtime build linked
diff --git a/internal/common/http.go b/internal/common/http.go
index d05c291bd2..2aecde99ea 100644
--- a/internal/common/http.go
+++ b/internal/common/http.go
@@ -47,6 +47,9 @@ const (
DefaultMaxDocumentUploadBytes int64 = 128 << 20
// MaxWebhookRequestBodyBytes is the default and maximum request body size for agent webhooks.
MaxWebhookRequestBodyBytes int64 = 10 * 1_000_000
+
+ ssrfResponseHeaderTimeoutDefault = 20 * time.Minute
+ schemeSafeResponseHeaderTimeoutDefault = 20 * time.Minute
)
// GetMaxJSONRequestBodyBytes returns the configured non-multipart request-body
@@ -87,6 +90,13 @@ func getMaxConfiguredBytes(envName, fallbackEnvName string, defaultBytes int64)
var ssrfHttpClient *http.Client
var schemeSafeHttpClient *http.Client
+// llmHTTPResponseHeaderTimeout lets a deployment shorten the wait for response
+// headers, which is what a hung provider endpoint spends on every retry. Each
+// client keeps its own default while the override is unset.
+func llmHTTPResponseHeaderTimeout(def time.Duration) time.Duration {
+ return getEnvDuration(EnvLLMHTTPResponseHeaderTimeout, def)
+}
+
func GetSSRFHTTPClient() *http.Client {
if ssrfHttpClient == nil {
var t *http.Transport
@@ -99,7 +109,7 @@ func GetSSRFHTTPClient() *http.Client {
t.MaxIdleConnsPerHost = 10
t.IdleConnTimeout = 90 * time.Second
t.DisableCompression = false
- t.ResponseHeaderTimeout = 20 * time.Minute
+ t.ResponseHeaderTimeout = llmHTTPResponseHeaderTimeout(ssrfResponseHeaderTimeoutDefault)
t.TLSHandshakeTimeout = 30 * time.Second
var rt http.RoundTripper = t
@@ -122,7 +132,7 @@ func GetSchemeSafeHTTPClient() *http.Client {
t.MaxIdleConnsPerHost = 500
t.IdleConnTimeout = 90 * time.Second
t.DisableCompression = false
- t.ResponseHeaderTimeout = 20 * time.Minute
+ t.ResponseHeaderTimeout = llmHTTPResponseHeaderTimeout(schemeSafeResponseHeaderTimeoutDefault)
t.TLSHandshakeTimeout = 30 * time.Second
var rt http.RoundTripper = t
diff --git a/internal/common/http_test.go b/internal/common/http_test.go
index b2e1fa9280..de386295ca 100644
--- a/internal/common/http_test.go
+++ b/internal/common/http_test.go
@@ -284,3 +284,78 @@ func TestProviderSlowStreamReportsTimingsWithoutDebug(t *testing.T) {
t.Errorf("timing log must not carry payloads while LLM_DEBUG is disabled: %v", fields)
}
}
+
+// resetSharedHTTPClients drops the process-wide client cache so the next Get*
+// call rebuilds it under the test's environment, and restores the previous
+// cache afterwards. A test that changed the env must not leave a client built
+// from it behind for later tests.
+func resetSharedHTTPClients(t *testing.T) {
+ t.Helper()
+ previousSSRF, previousSchemeSafe := ssrfHttpClient, schemeSafeHttpClient
+ ssrfHttpClient, schemeSafeHttpClient = nil, nil
+ t.Cleanup(func() {
+ ssrfHttpClient, schemeSafeHttpClient = previousSSRF, previousSchemeSafe
+ })
+}
+
+func responseHeaderTimeoutOf(t *testing.T, client *http.Client) time.Duration {
+ t.Helper()
+ logging, ok := client.Transport.(*providerLoggingTransport)
+ if !ok {
+ t.Fatalf("client transport = %T, want *providerLoggingTransport", client.Transport)
+ }
+ var inner http.RoundTripper
+ switch tr := logging.base.(type) {
+ case *schemeSafeTransport:
+ inner = tr.base
+ case *strictSSRFTransport:
+ inner = tr.base
+ default:
+ t.Fatalf("inner transport = %T, want scheme-safe or SSRF transport", logging.base)
+ }
+ transport, ok := inner.(*http.Transport)
+ if !ok {
+ t.Fatalf("inner transport base = %T, want *http.Transport", inner)
+ }
+ return transport.ResponseHeaderTimeout
+}
+
+func TestProviderHTTPClientResponseHeaderTimeoutDefaults(t *testing.T) {
+ t.Setenv(EnvLLMHTTPResponseHeaderTimeout, "")
+ resetSharedHTTPClients(t)
+
+ if got := responseHeaderTimeoutOf(t, GetSchemeSafeHTTPClient()); got != schemeSafeResponseHeaderTimeoutDefault {
+ t.Errorf("scheme-safe response header timeout = %v, want %v", got, schemeSafeResponseHeaderTimeoutDefault)
+ }
+ if got := responseHeaderTimeoutOf(t, GetSSRFHTTPClient()); got != ssrfResponseHeaderTimeoutDefault {
+ t.Errorf("SSRF response header timeout = %v, want %v", got, ssrfResponseHeaderTimeoutDefault)
+ }
+}
+
+func TestProviderHTTPClientResponseHeaderTimeoutOverride(t *testing.T) {
+ t.Setenv(EnvLLMHTTPResponseHeaderTimeout, "15s")
+ resetSharedHTTPClients(t)
+
+ if got := responseHeaderTimeoutOf(t, GetSchemeSafeHTTPClient()); got != 15*time.Second {
+ t.Errorf("scheme-safe response header timeout = %v, want 15s", got)
+ }
+ if got := responseHeaderTimeoutOf(t, GetSSRFHTTPClient()); got != 15*time.Second {
+ t.Errorf("SSRF response header timeout = %v, want 15s", got)
+ }
+}
+
+func TestProviderHTTPClientResponseHeaderTimeoutIgnoresInvalidValues(t *testing.T) {
+ for _, value := range []string{"not-a-duration", "0s", "-5s", "30"} {
+ t.Run(value, func(t *testing.T) {
+ t.Setenv(EnvLLMHTTPResponseHeaderTimeout, value)
+ resetSharedHTTPClients(t)
+
+ if got := responseHeaderTimeoutOf(t, GetSchemeSafeHTTPClient()); got != schemeSafeResponseHeaderTimeoutDefault {
+ t.Errorf("scheme-safe response header timeout = %v, want default %v for %q", got, schemeSafeResponseHeaderTimeoutDefault, value)
+ }
+ if got := responseHeaderTimeoutOf(t, GetSSRFHTTPClient()); got != ssrfResponseHeaderTimeoutDefault {
+ t.Errorf("SSRF response header timeout = %v, want default %v for %q", got, ssrfResponseHeaderTimeoutDefault, value)
+ }
+ })
+ }
+}