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(knowledge): configurable question-generation token budget (#4690)

LuckVd4f6e6af18360
diff --git a/.env.example b/.env.example
index 7d060002e..6a5af46b4 100644
--- a/.env.example
+++ b/.env.example
@@ -360,6 +360,11 @@ OLLAMA_BASE_URL=http://host.docker.internal:11434
# 知识库描述生成的补全 token 预算(留空走代码默认 2048)。推理型模型即使关闭思考
# 也可能耗尽小预算导致描述生成失败(报 no gist),遇到时可调大此值。
# KNOWLEDGE_BASE_PROFILE_MAX_TOKENS=
+# KNOWLEDGE_BASE_PROFILE_MAX_TOKENS=
+# 分块问题生成(Doc2Query)单次模型调用的补全 token 预算(留空走代码默认 2048)。
+# 推理型模型即使关闭思考也可能耗尽小预算,导致问题生成为空(仅日志告警可见),
+# 遇到时可调大此值。
+# GENERATE_QUESTIONS_MAX_TOKENS=
# VLM 单次 HTTP 请求超时(秒,默认 180;慢端点超时报 context deadline 时调大)。
# VLM_HTTP_TIMEOUT_SECONDS=180
# LLM 流原始转储(排查上下文问题;1 启用,默认目录 ~/.weknora/investigate/llm-stream)。
diff --git a/internal/application/service/knowledge_process.go b/internal/application/service/knowledge_process.go
index 1e2b81714..f8d26796b 100644
--- a/internal/application/service/knowledge_process.go
+++ b/internal/application/service/knowledge_process.go
@@ -6,7 +6,9 @@ import (
"errors"
"fmt"
"io"
+ "os"
"sort"
+ "strconv"
"strings"
"time"
@@ -1903,6 +1905,18 @@ func (s *knowledgeService) processQuestionGenerationForKnowledge(ctx context.Con
indexBatchAttempted,
indexBatchSucceeded,
)
+ if llmCallEmpty > 0 {
+ // Empty completions are counted, not logged, at the call site; a
+ // run where every chunk came back empty is indistinguishable from
+ // a healthy run in the application log. Reasoning-style models
+ // burning the whole budget on thinking are the known cause —
+ // point operators at the knob instead of leaving them to guess.
+ logger.Warnf(ctx,
+ "Question generation: %d of %d model calls returned empty completions "+
+ "(reasoning-style models can spend the completion budget on thinking even when disabled; "+
+ "raise %s to give the reply room)",
+ llmCallEmpty, llmCallAttempts, generateQuestionsMaxTokensEnv)
+ }
if qSpan != nil {
out := types.JSONMap{
"status": exitStatus,
@@ -2224,6 +2238,7 @@ func (s *knowledgeService) processQuestionGenerationForChunks(ctx context.Contex
chunksInBatch := len(batchIDs)
chunksProcessed := 0
emptyChunks := 0
+ llmCallEmpty := 0
llmCallFailed := 0
generatedQuestionsTotal := 0
indexEntriesPrepared := 0
@@ -2252,11 +2267,23 @@ func (s *knowledgeService) processQuestionGenerationForChunks(ctx context.Contex
}()
defer func() {
logger.Infof(ctx,
- "Question generation (batch) stats: knowledge=%s batch=%d chunks(in_batch=%d,processed=%d,empty=%d) llm_failed=%d retry=%d/%d status=%s elapsed=%s generated_questions=%d index(entries=%d,succeeded=%v)",
- payload.KnowledgeID, payload.BatchIndex, chunksInBatch, chunksProcessed, emptyChunks, llmCallFailed,
- retryCount, maxRetry, exitStatus, time.Since(taskStartedAt).Round(time.Millisecond),
+ "Question generation (batch) stats: knowledge=%s batch=%d "+
+ "chunks(in_batch=%d,processed=%d,empty=%d,llm_empty=%d) llm_failed=%d retry=%d/%d "+
+ "status=%s elapsed=%s generated_questions=%d index(entries=%d,succeeded=%v)",
+ payload.KnowledgeID, payload.BatchIndex, chunksInBatch, chunksProcessed, emptyChunks,
+ llmCallEmpty, llmCallFailed, retryCount, maxRetry, exitStatus,
+ time.Since(taskStartedAt).Round(time.Millisecond),
generatedQuestionsTotal, indexEntriesPrepared, indexBatchSucceeded,
)
+ if llmCallEmpty > 0 {
+ // See the matching warning in processQuestionGenerationForKnowledge:
+ // empty completions point at a completion budget spent on thinking.
+ logger.Warnf(ctx,
+ "Question generation (batch): %d model calls returned empty completions "+
+ "(reasoning-style models can spend the completion budget on thinking even when disabled; "+
+ "raise %s to give the reply room)",
+ llmCallEmpty, generateQuestionsMaxTokensEnv)
+ }
if qSpan != nil {
out := types.JSONMap{
"status": exitStatus,
@@ -2466,6 +2493,7 @@ func (s *knowledgeService) processQuestionGenerationForChunks(ctx context.Contex
continue
}
if len(questions) == 0 {
+ llmCallEmpty++
continue
}
latestChunk, latestErr := s.chunkRepo.GetChunkByID(ctx, payload.TenantID, chunk.ID)
@@ -2528,6 +2556,29 @@ func (s *knowledgeService) processQuestionGenerationForChunks(ctx context.Contex
return nil
}
+const (
+ // generateQuestionsDefaultMaxTokens is the per-chunk completion budget for
+ // question generation. The reply itself is a handful of short lines, but
+ // reasoning-style models can spend a small budget on thinking even when
+ // thinking is disabled and come back with an empty completion (the same
+ // failure mode the description path grew KNOWLEDGE_BASE_PROFILE_MAX_TOKENS
+ // for, issue #4221) — so the default keeps headroom.
+ generateQuestionsDefaultMaxTokens = 2048
+ // generateQuestionsMaxTokensEnv lets operators raise (or lower) the budget
+ // without a rebuild; invalid or non-positive values fall back to the
+ // default so one bad variable cannot break question generation.
+ generateQuestionsMaxTokensEnv = "GENERATE_QUESTIONS_MAX_TOKENS"
+)
+
+func generateQuestionsMaxTokens() int {
+ if v := strings.TrimSpace(os.Getenv(generateQuestionsMaxTokensEnv)); v != "" {
+ if n, err := strconv.Atoi(v); err == nil && n > 0 {
+ return n
+ }
+ }
+ return generateQuestionsDefaultMaxTokens
+}
+
// generateQuestionsWithContext generates questions for a chunk with surrounding context
func (s *knowledgeService) generateQuestionsWithContext(ctx context.Context,
chatModel chat.Chat, content, prevContent, nextContent, docName string, questionCount int,
@@ -2574,7 +2625,7 @@ func (s *knowledgeService) generateQuestionsWithContext(ctx context.Context,
},
}, &chat.ChatOptions{
Temperature: 0.7,
- MaxTokens: 512,
+ MaxTokens: generateQuestionsMaxTokens(),
Thinking: &thinking,
})
if err != nil {
diff --git a/internal/application/service/knowledge_process_budget_test.go b/internal/application/service/knowledge_process_budget_test.go
new file mode 100644
index 000000000..ccd1b5d9c
--- /dev/null
+++ b/internal/application/service/knowledge_process_budget_test.go
@@ -0,0 +1,88 @@
+package service
+
+import (
+ "context"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/config"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// budgetCaptureChatModel records the options the real call sites pass so the
+// budget plumbing can be asserted end-to-end through generateQuestionsWithContext.
+type budgetCaptureChatModel struct {
+ response string
+ options []*chat.ChatOptions
+}
+
+func (m *budgetCaptureChatModel) Chat(
+ _ context.Context, _ []chat.Message, opts *chat.ChatOptions,
+) (*types.ChatResponse, error) {
+ if opts != nil {
+ copyOpts := *opts
+ m.options = append(m.options, &copyOpts)
+ }
+ return &types.ChatResponse{Content: m.response}, nil
+}
+
+func (m *budgetCaptureChatModel) ChatStream(
+ context.Context, []chat.Message, *chat.ChatOptions,
+) (<-chan types.StreamResponse, error) {
+ return nil, nil
+}
+func (m *budgetCaptureChatModel) GetModelName() string { return "budget" }
+func (m *budgetCaptureChatModel) GetModelID() string { return "budget" }
+
+func newQuestionBudgetService() *knowledgeService {
+ return &knowledgeService{config: &config.Config{Conversation: &config.ConversationConfig{
+ GenerateQuestionsPrompt: "Generate {{question_count}} questions:\n{{content}}",
+ }}}
+}
+
+func TestGenerateQuestionsMaxTokensDefaultAndEnv(t *testing.T) {
+ t.Setenv(generateQuestionsMaxTokensEnv, "")
+ assert.Equal(t, 2048, generateQuestionsMaxTokens(), "default when unset")
+
+ t.Setenv(generateQuestionsMaxTokensEnv, "4096")
+ assert.Equal(t, 4096, generateQuestionsMaxTokens(), "explicit override applied")
+
+ for _, bad := range []string{"abc", "0", "-5", "3.5", " "} {
+ t.Setenv(generateQuestionsMaxTokensEnv, bad)
+ assert.Equal(t, 2048, generateQuestionsMaxTokens(),
+ "invalid value %q must fall back to the default", bad)
+ }
+}
+
+func TestGenerateQuestionsWithContextUsesConfiguredBudget(t *testing.T) {
+ s := newQuestionBudgetService()
+
+ t.Setenv(generateQuestionsMaxTokensEnv, "")
+ model := &budgetCaptureChatModel{response: "1. First question?\n2. Second question?"}
+ _, err := s.generateQuestionsWithContext(context.Background(), model,
+ "chunk body text", "", "", "doc.pdf", 2, "")
+ require.NoError(t, err)
+ require.Len(t, model.options, 1)
+ assert.Equal(t, 2048, model.options[0].MaxTokens, "default budget reaches the model call")
+
+ t.Setenv(generateQuestionsMaxTokensEnv, "8192")
+ model = &budgetCaptureChatModel{response: "1. First question?\n2. Second question?"}
+ _, err = s.generateQuestionsWithContext(context.Background(), model,
+ "chunk body text", "", "", "doc.pdf", 2, "")
+ require.NoError(t, err)
+ require.Len(t, model.options, 1)
+ assert.Equal(t, 8192, model.options[0].MaxTokens, "env override reaches the model call")
+}
+
+// An empty completion must keep returning (no questions, no error): the batch
+// callers count it and surface a warning, they do not fail the task.
+func TestGenerateQuestionsWithContextEmptyCompletionIsCountedNotFailed(t *testing.T) {
+ s := newQuestionBudgetService()
+ model := &budgetCaptureChatModel{response: ""}
+ questions, err := s.generateQuestionsWithContext(context.Background(), model,
+ "chunk body text", "", "", "doc.pdf", 3, "")
+ require.NoError(t, err)
+ assert.Empty(t, questions)
+}