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): make the knowledge base description token budget configurable (#4230)

LuckVd7972cdd251ac
diff --git a/.env.example b/.env.example
index 59ae4ddf3..43c196e91 100644
--- a/.env.example
+++ b/.env.example
@@ -356,6 +356,9 @@ OLLAMA_OPTIONAL=true
OLLAMA_BASE_URL=http://host.docker.internal:11434
# 批量 embedding 大小(留空走代码默认)。
# BATCH_EMBED_SIZE=
+# 知识库描述生成的补全 token 预算(留空走代码默认 2048)。推理型模型即使关闭思考
+# 也可能耗尽小预算导致描述生成失败(报 no gist),遇到时可调大此值。
+# KNOWLEDGE_BASE_PROFILE_MAX_TOKENS=
# VLM 单次 HTTP 请求超时(秒,默认 180;慢端点超时报 context deadline 时调大)。
# VLM_HTTP_TIMEOUT_SECONDS=180
# LLM 流原始转储(排查上下文问题;1 启用,默认目录 ~/.weknora/investigate/llm-stream)。
diff --git a/internal/application/service/knowledgebase_profile.go b/internal/application/service/knowledgebase_profile.go
index 538687bbc..fa08ae330 100644
--- a/internal/application/service/knowledgebase_profile.go
+++ b/internal/application/service/knowledgebase_profile.go
@@ -5,7 +5,9 @@ import (
"encoding/json"
"errors"
"fmt"
+ "os"
"sort"
+ "strconv"
"strings"
"time"
@@ -27,12 +29,35 @@ const (
knowledgeBaseProfileDebounce = 30 * time.Second
// knowledgeBaseProfileTaskTimeout bounds one aggregation plus model call.
knowledgeBaseProfileTaskTimeout = 5 * time.Minute
- // knowledgeBaseProfileMaxTokens bounds the JSON reply; the fields are short.
- knowledgeBaseProfileMaxTokens = 800
// knowledgeBaseProfileTagBatch bounds the IN-list of one tag lookup.
knowledgeBaseProfileTagBatch = 500
)
+const (
+ // knowledgeBaseProfileDefaultMaxTokens is the default completion budget
+ // for the description model call. The JSON reply itself is short, but
+ // reasoning-style models can spend a small budget on thinking even when
+ // thinking is disabled, returning an empty completion that fails the
+ // whole description (issue #4221) — so the default keeps headroom.
+ knowledgeBaseProfileDefaultMaxTokens = 2048
+ // knowledgeBaseProfileMaxTokensEnv lets an operator raise (or lower) the
+ // completion budget without a rebuild; see .env.example.
+ knowledgeBaseProfileMaxTokensEnv = "KNOWLEDGE_BASE_PROFILE_MAX_TOKENS"
+)
+
+// knowledgeBaseProfileMaxTokens returns the completion budget for the
+// description model call: the env override when it parses to a positive
+// integer, the built-in default otherwise (invalid or non-positive values
+// fall back silently so one bad variable cannot break generation).
+func knowledgeBaseProfileMaxTokens() int {
+ if raw := strings.TrimSpace(os.Getenv(knowledgeBaseProfileMaxTokensEnv)); raw != "" {
+ if n, err := strconv.Atoi(raw); err == nil && n > 0 {
+ return n
+ }
+ }
+ return knowledgeBaseProfileDefaultMaxTokens
+}
+
var (
// ErrKnowledgeBaseProfileUnsupported aliases the types sentinel.
ErrKnowledgeBaseProfileUnsupported = types.ErrKnowledgeBaseProfileUnsupported
@@ -342,7 +367,7 @@ func (s *KnowledgeBaseProfileService) describeAggregate(
response, err := chatModel.Chat(types.WithLLMCallMetadata(ctx, "knowledge_base_description", ""), []chat.Message{
{Role: "system", Content: systemPrompt},
{Role: "user", Content: userPrompt},
- }, &chat.ChatOptions{Temperature: 0.2, MaxTokens: knowledgeBaseProfileMaxTokens, Thinking: &thinking})
+ }, &chat.ChatOptions{Temperature: 0.2, MaxTokens: knowledgeBaseProfileMaxTokens(), Thinking: &thinking})
if err != nil {
return nil, fmt.Errorf("generate knowledge base description: %w", err)
}
diff --git a/internal/application/service/knowledgebase_profile_test.go b/internal/application/service/knowledgebase_profile_test.go
index 586859868..89ec98a77 100644
--- a/internal/application/service/knowledgebase_profile_test.go
+++ b/internal/application/service/knowledgebase_profile_test.go
@@ -73,13 +73,15 @@ type kbProfileChatModel struct {
err error
calls int
messages []chat.Message
+ lastOpts *chat.ChatOptions
}
func (m *kbProfileChatModel) Chat(
- _ context.Context, messages []chat.Message, _ *chat.ChatOptions,
+ _ context.Context, messages []chat.Message, opts *chat.ChatOptions,
) (*types.ChatResponse, error) {
m.calls++
m.messages = append([]chat.Message(nil), messages...)
+ m.lastOpts = opts
if m.err != nil {
return nil, m.err
}
@@ -250,6 +252,35 @@ func TestKnowledgeBaseProfileGenerateRejectsUnparseableOutput(t *testing.T) {
assert.Equal(t, types.KnowledgeBaseProfileStatusFailed, f.kb.GeneratedProfile.Status)
}
+func TestKnowledgeBaseProfileMaxTokensDefaultAndEnv(t *testing.T) {
+ t.Setenv(knowledgeBaseProfileMaxTokensEnv, "")
+ assert.Equal(t, knowledgeBaseProfileDefaultMaxTokens, knowledgeBaseProfileMaxTokens())
+
+ t.Setenv(knowledgeBaseProfileMaxTokensEnv, "4096")
+ assert.Equal(t, 4096, knowledgeBaseProfileMaxTokens())
+
+ for _, bad := range []string{"abc", "0", "-5", "12.5"} {
+ t.Setenv(knowledgeBaseProfileMaxTokensEnv, bad)
+ assert.Equal(t, knowledgeBaseProfileDefaultMaxTokens, knowledgeBaseProfileMaxTokens(),
+ "invalid value %q must fall back to the default", bad)
+ }
+}
+
+func TestKnowledgeBaseProfileGenerateUsesConfiguredMaxTokens(t *testing.T) {
+ f := newKBProfileFixture(kbProfileResponse)
+ _, err := f.service.GenerateKnowledgeBaseProfile(context.Background(), f.kb, false)
+ require.NoError(t, err)
+ require.NotNil(t, f.chatModel.lastOpts)
+ assert.Equal(t, knowledgeBaseProfileDefaultMaxTokens, f.chatModel.lastOpts.MaxTokens)
+
+ t.Setenv(knowledgeBaseProfileMaxTokensEnv, "3000")
+ f2 := newKBProfileFixture(kbProfileResponse)
+ _, err = f2.service.GenerateKnowledgeBaseProfile(context.Background(), f2.kb, false)
+ require.NoError(t, err)
+ require.NotNil(t, f2.chatModel.lastOpts)
+ assert.Equal(t, 3000, f2.chatModel.lastOpts.MaxTokens)
+}
+
func TestKnowledgeBaseProfileGenerateModelResolution(t *testing.T) {
f := newKBProfileFixture(kbProfileResponse)
f.kb.SummaryModelID = ""