Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(docparser): make PaddleOCR-VL request timeout configurable (#3537)

Leon402729341a44
diff --git a/.env.example b/.env.example
index 52c105c48..9ef0d0616 100644
--- a/.env.example
+++ b/.env.example
@@ -504,6 +504,9 @@ OLLAMA_BASE_URL=http://host.docker.internal:11434
# WEKNORA_DOCUMENT_PROCESS_TIMEOUT=2h
# 单次 DocReader RPC 超时(默认 30m,须小于上一项)。
# WEKNORA_DOCREADER_CALL_TIMEOUT=30m
+# 自建 PaddleOCR-VL HTTP 请求超时(正数 Go duration,默认 1000s;无效值回退默认值)。
+# 大文件示例:本项 90m、DocReader 100m、单文档任务 2h,外层超时需留余量。
+# WEKNORA_PADDLEOCR_VL_TIMEOUT=1000s
# 知识库巡检回收(回收卡在 processing 的脏数据;false 禁用,不建议)。
# WEKNORA_HOUSEKEEPING_ENABLED=true
# 聊天附件解析产物保留时长(小时,默认 24)。
diff --git a/docker-compose.yml b/docker-compose.yml
index 0f15de3c8..ff4ecd0b2 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -327,6 +327,8 @@ services:
- WEKNORA_DOCUMENT_PROCESS_TIMEOUT=${WEKNORA_DOCUMENT_PROCESS_TIMEOUT:-}
# 单次 DocReader RPC 超时(默认 30m,须小于上一项)
- WEKNORA_DOCREADER_CALL_TIMEOUT=${WEKNORA_DOCREADER_CALL_TIMEOUT:-}
+ # 自建 PaddleOCR-VL HTTP 请求超时(Go duration,默认 1000s)
+ - WEKNORA_PADDLEOCR_VL_TIMEOUT=${WEKNORA_PADDLEOCR_VL_TIMEOUT:-}
# 知识库巡检回收(回收卡在 processing 的脏数据;false 禁用,不建议)
- WEKNORA_HOUSEKEEPING_ENABLED=${WEKNORA_HOUSEKEEPING_ENABLED:-}
- WEKNORA_CHAT_ATTACHMENT_TTL_HOURS=${WEKNORA_CHAT_ATTACHMENT_TTL_HOURS:-24}
diff --git a/internal/infrastructure/docparser/paddleocr_vl_converter.go b/internal/infrastructure/docparser/paddleocr_vl_converter.go
index f49e1df58..f16d1020d 100644
--- a/internal/infrastructure/docparser/paddleocr_vl_converter.go
+++ b/internal/infrastructure/docparser/paddleocr_vl_converter.go
@@ -9,6 +9,7 @@ import (
"io"
"mime"
"net/http"
+ "os"
"path/filepath"
"strings"
"time"
@@ -18,7 +19,7 @@ import (
"github.com/Tencent/WeKnora/internal/utils"
)
-const paddleOCRVLTimeout = 1000 * time.Second // large scanned PDFs can take a while
+const defaultPaddleOCRVLTimeout = 1000 * time.Second // large scanned PDFs can take a while
// PaddleOCRVLReader calls a self-hosted PaddleOCR-VL pipeline service
// (the full document-parsing API, not the bare VLM inference server).
@@ -27,6 +28,7 @@ const paddleOCRVLTimeout = 1000 * time.Second // large scanned PDFs can take a w
// response containing per-page markdown + inline base64 images.
type PaddleOCRVLReader struct {
endpoint string
+ timeout time.Duration
useSeal bool
useChart bool
}
@@ -34,12 +36,29 @@ type PaddleOCRVLReader struct {
// NewPaddleOCRVLReader creates a reader from ParserEngineOverrides.
func NewPaddleOCRVLReader(overrides map[string]string) *PaddleOCRVLReader {
return &PaddleOCRVLReader{
+ timeout: paddleOCRVLRequestTimeout(),
endpoint: strings.TrimRight(overrides["paddleocr_vl_endpoint"], "/"),
useSeal: parseBoolOr(overrides["paddleocr_vl_use_seal_recognition"], true),
useChart: parseBoolOr(overrides["paddleocr_vl_use_chart_recognition"], false),
}
}
+// paddleOCRVLRequestTimeout bounds a self-hosted layout-parsing request.
+// The caller's context may impose an earlier deadline.
+func paddleOCRVLRequestTimeout() time.Duration {
+ value := strings.TrimSpace(os.Getenv("WEKNORA_PADDLEOCR_VL_TIMEOUT"))
+ if value == "" {
+ return defaultPaddleOCRVLTimeout
+ }
+ timeout, err := time.ParseDuration(value)
+ if err != nil || timeout <= 0 {
+ logger.Warnf(context.Background(), "Invalid WEKNORA_PADDLEOCR_VL_TIMEOUT %q; using %s",
+ value, defaultPaddleOCRVLTimeout)
+ return defaultPaddleOCRVLTimeout
+ }
+ return timeout
+}
+
func (c *PaddleOCRVLReader) Read(ctx context.Context, req *types.ReadRequest) (*types.ReadResult, error) {
if c.endpoint == "" {
return &types.ReadResult{Error: "PaddleOCR-VL endpoint is not configured"}, nil
@@ -161,7 +180,7 @@ func (c *PaddleOCRVLReader) callLayoutParsing(
httpReq.Header.Set("Content-Type", "application/json")
client := utils.NewSSRFSafeHTTPClient(utils.SSRFSafeHTTPClientConfig{
- Timeout: paddleOCRVLTimeout,
+ Timeout: c.timeout,
MaxRedirects: 5,
})
resp, err := client.Do(httpReq)
diff --git a/internal/infrastructure/docparser/paddleocr_vl_converter_test.go b/internal/infrastructure/docparser/paddleocr_vl_converter_test.go
new file mode 100644
index 000000000..36afcf961
--- /dev/null
+++ b/internal/infrastructure/docparser/paddleocr_vl_converter_test.go
@@ -0,0 +1,119 @@
+package docparser
+
+import (
+ "context"
+ "errors"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/utils"
+)
+
+func TestPaddleOCRVLTimeoutConfig(t *testing.T) {
+ for _, tt := range []struct {
+ name, value string
+ want time.Duration
+ }{
+ {"unset", "", 1000 * time.Second},
+ {"empty", "", 1000 * time.Second},
+ {"whitespace", " ", 1000 * time.Second},
+ {"seconds", "5400s", 90 * time.Minute},
+ {"minutes", "90m", 90 * time.Minute},
+ {"trimmed", " 90m ", 90 * time.Minute},
+ {"invalid", "invalid", 1000 * time.Second},
+ {"unitless", "5400", 1000 * time.Second},
+ {"zero", "0s", 1000 * time.Second},
+ {"negative", "-1s", 1000 * time.Second},
+ {"overflow", "999999999999999999999h", 1000 * time.Second},
+ } {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Setenv("WEKNORA_PADDLEOCR_VL_TIMEOUT", tt.value)
+ if tt.name == "unset" {
+ if err := os.Unsetenv("WEKNORA_PADDLEOCR_VL_TIMEOUT"); err != nil {
+ t.Fatal(err)
+ }
+ }
+ reader := NewPaddleOCRVLReader(nil)
+ if reader.timeout != tt.want {
+ t.Fatalf("timeout = %s, want %s", reader.timeout, tt.want)
+ }
+ })
+ }
+}
+
+func TestPaddleOCRVLReadTimeout(t *testing.T) {
+ // Earlier parser tests may have initialized the runtime whitelist.
+ utils.SetSSRFWhitelistFromRaw("127.0.0.1,localhost")
+ t.Cleanup(func() { utils.SetSSRFWhitelistFromRaw("") })
+ for _, mode := range []string{"success", "http timeout", "parent deadline", "parent cancellation"} {
+ t.Run(mode, func(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1,localhost")
+ t.Setenv("WEKNORA_PADDLEOCR_VL_TIMEOUT", "10s")
+ if mode == "http timeout" {
+ t.Setenv("WEKNORA_PADDLEOCR_VL_TIMEOUT", "100ms")
+ }
+ arrived := make(chan struct{})
+ release := make(chan struct{})
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ _, _ = io.Copy(io.Discard, r.Body)
+ close(arrived)
+ if mode == "success" {
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = io.WriteString(w, `{"errorCode":0,"result":{"layoutParsingResults":[
+ {"markdown":{"text":"parsed document","images":{}}}]}}`)
+ return
+ }
+ select {
+ case <-r.Context().Done():
+ case <-release:
+ }
+ }))
+ defer server.Close()
+ defer close(release)
+ ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+ defer cancel()
+ if mode == "parent deadline" {
+ var stop context.CancelFunc
+ ctx, stop = context.WithTimeout(ctx, 100*time.Millisecond)
+ defer stop()
+ }
+ if mode == "parent cancellation" {
+ go func() {
+ select {
+ case <-arrived:
+ cancel()
+ case <-ctx.Done():
+ }
+ }()
+ }
+ reader := NewPaddleOCRVLReader(map[string]string{"paddleocr_vl_endpoint": server.URL})
+ result, err := reader.Read(ctx, &types.ReadRequest{
+ FileName: "test.pdf", FileType: "pdf", FileContent: []byte("test"),
+ })
+ if mode == "success" {
+ if err != nil {
+ t.Fatal(err)
+ }
+ if result.MarkdownContent != "parsed document" {
+ t.Fatalf("unexpected result: %+v", result)
+ }
+ return
+ }
+ want := context.DeadlineExceeded
+ if mode == "parent cancellation" {
+ want = context.Canceled
+ }
+ if !errors.Is(err, want) {
+ t.Fatalf("error = %v, want %v", err, want)
+ }
+ if mode == "http timeout" && ctx.Err() != nil {
+ t.Fatalf("request only stopped at parent deadline: %v", ctx.Err())
+ }
+ })
+ }
+}
diff --git a/website-docs/01-getting-started/04-configuration.md b/website-docs/01-getting-started/04-configuration.md
index 2ed2a569a..e18d0ac12 100644
--- a/website-docs/01-getting-started/04-configuration.md
+++ b/website-docs/01-getting-started/04-configuration.md
@@ -262,6 +262,7 @@ AWS S3 的 `S3_ACCESS_KEY` / `S3_SECRET_KEY` 可以**同时留空**,此时走
| `WEKNORA_CHAT_ATTACHMENT_TTL_HOURS` / `_WAIT_TIMEOUT_SEC` / `_OCR_CONCURRENCY` / `_OCR_MAX_PAGES` | 24 / 60 / 8 / 8 | 聊天附件解析保留时长、等待超时与 OCR 并发/页数上限 |
| `WEKNORA_HOUSEKEEPING_ENABLED` | 启用 | 回收卡在 processing 的脏数据 |
| `WEKNORA_DOCUMENT_PROCESS_TIMEOUT` / `WEKNORA_DOCREADER_CALL_TIMEOUT` | 2h / 30m | 文档处理任务与单次 RPC 超时 |
+| `WEKNORA_PADDLEOCR_VL_TIMEOUT` | 1000s | 自建 PaddleOCR-VL HTTP 请求超时,支持正数 Go duration(如 `5400s`、`90m`);空值、无效值或非正数使用默认值。外层超时需留余量,例如本项 `90m`、DocReader `100m`、文档任务 `2h` |
沙箱后端、网络策略、脚本开关与个人环境变量使用空间配置/API 管理,见[技能与沙箱](../03-features/22-skills-sandbox.md)。长期记忆与自动标签均默认关闭,分别使用租户 memory_config 和知识库 auto_tag_config,不用全局环境变量替代各空间配置。