Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
fix(knowledge): configurable question-generation token budget (#4690)
LuckVd4f6e6af18360
diff --git a/.env.example b/.env.exampleindex 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.goindex 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.ConindexBatchAttempted,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.ContexchunksInBatch := len(batchIDs)chunksProcessed := 0emptyChunks := 0+ llmCallEmpty := 0llmCallFailed := 0generatedQuestionsTotal := 0indexEntriesPrepared := 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.Contexcontinue}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.Contexreturn 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 contextfunc (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.gonew file mode 100644index 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, ©Opts)+ }+ 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)+}