Skip to content

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

Fix: porting #18300 to go (#18690)

Wang Qicc7d99e28865
diff --git a/internal/agent/runtime/retrieval.go b/internal/agent/runtime/retrieval.go
new file mode 100644
index 0000000000..b9e343bb54
--- /dev/null
+++ b/internal/agent/runtime/retrieval.go
@@ -0,0 +1,287 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+// Retrieval contracts shared by the canvas agent runtime (internal/agent/tool)
+// and the smart-reasoning agent (internal/agentic_rag). Keeping these here —
+// in the engine-agnostic runtime package — means neither agent layer depends on
+// the other: both depend on this shared contract.
+package runtime
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "sync"
+
+ "gorm.io/gorm"
+)
+
+// RetrievalChunk is the minimal shape a RetrievalService returns. The full
+// Chunk type (with document_id, docnm_kwd, position, etc.) lives in
+// internal/entity and is wired in by the retrieval adapters.
+type RetrievalChunk struct {
+ ID string
+ Content string
+ DocumentID string
+ DocumentName string
+ DatasetID string
+ ImageID string
+ URL string
+ Positions any
+ // ChunkIndex is the chunk's 0-based reading-order index within its document
+ // (ES `chunk_order_int`). Deep-read tools sort chunks by it so the model reads
+ // a document sequentially rather than in arbitrary match order.
+ ChunkIndex int
+ // PageNum is the chunk's page number within its document (ES `page_num_int`).
+ PageNum int
+ Score float64
+ TermSimilarity float64
+ VectorSimilarity float64
+}
+
+// RetrievalRequest is the input to RetrievalService.Search.
+type RetrievalRequest struct {
+ Query string
+ DatasetIDs []string
+ MemoryIDs []string
+ TopN int
+ PrefetchSize int
+ TopK int
+ KeywordsSimilarityWeight *float64
+ UseKG bool
+ SimilarityThreshold *float64
+ RerankID string
+ CrossLanguages []string
+ TOCEnhance bool
+ MetaDataFilter map[string]any
+ RetrievalFrom string
+ // DocScope restricts retrieval to a set of document ids. Empty = no doc filter.
+ DocScope []string
+ // TenantID is the calling tenant (== user_id in RAGFlow's data model).
+ TenantID string
+ // OnlyOriginalText, when true, restricts retrieval to ordinary document
+ // text chunks (available_int=1 and no compile_kwd), excluding
+ // knowledge-compiled products.
+ OnlyOriginalText bool
+ // SelectFields limits the ES _source fields returned per hit.
+ SelectFields []string
+}
+
+// RetrievalService is the knowledge-base search interface. The server installs
+// an adapter during boot.
+type RetrievalService interface {
+ Search(ctx context.Context, db *gorm.DB, req RetrievalRequest) ([]RetrievalChunk, error)
+}
+
+// MemoryRetrievalService is the memory-message retrieval surface used when
+// retrieval_from=memory.
+type MemoryRetrievalService interface {
+ Search(ctx context.Context, db *gorm.DB, req RetrievalRequest) ([]RetrievalChunk, error)
+}
+
+// KGRetrievalService is the GraphRAG retrieval surface.
+type KGRetrievalService interface {
+ Search(ctx context.Context, db *gorm.DB, req RetrievalRequest) ([]RetrievalChunk, error)
+}
+
+// GrepService is the regex-search surface used by grep_chunks. It is separate
+// from RetrievalService because regex matching over chunk content is a distinct
+// retrieval mode.
+type GrepService interface {
+ Grep(ctx context.Context, req GrepRequest) ([]RetrievalChunk, error)
+}
+
+// GrepRequest is the input to GrepService.Grep.
+type GrepRequest struct {
+ Pattern string // The regex to match against chunk content (case-insensitive).
+ DatasetIDs []string // Knowledge base IDs to restrict to.
+ DocScope []string // Document IDs to restrict to (empty = no doc filter).
+ Limit int // Max number of chunks to return.
+ Offset int // Number of chunks to skip (0-based), for pagination.
+ // Sort is an ordered list of field names to order results by ascending
+ // (e.g. a document's reading order: chunk_order_int, page_num_int, top_int).
+ Sort []string // Ordered ascending sort fields.
+ // SelectFields limits the ES _source fields returned per hit.
+ SelectFields []string
+ TenantID string // Calling tenant (== user_id in RAGFlow's data model).
+}
+
+// ErrRetrievalServiceMissing is returned when no RetrievalService is registered.
+var ErrRetrievalServiceMissing = errors.New(
+ "Retrieval service not yet implemented (service not registered) — " +
+ "use Python Canvas or implement internal/service/nlp/retrieval.go",
+)
+
+// ErrMemoryRetrievalServiceMissing is returned when no MemoryRetrievalService is registered.
+var ErrMemoryRetrievalServiceMissing = errors.New("memory retrieval service not registered")
+
+// ErrKGRetrievalServiceMissing is returned when no KGRetrievalService is registered.
+var ErrKGRetrievalServiceMissing = errors.New(
+ "GraphRAG (kg) retrieval service not yet wired",
+)
+
+// ErrGrepServiceMissing is returned when no GrepService has been registered.
+var ErrGrepServiceMissing = errors.New(
+ "grep service not registered — call runtime.SetGrepService(...) at boot",
+)
+
+// ErrRegexpNotSupported is returned when the underlying doc engine does not
+// implement regex matching on chunk content (e.g. Infinity).
+var ErrRegexpNotSupported = errors.New(
+ "grep_chunks: regex matching is not supported by this document engine",
+)
+
+var (
+ retrievalServiceMu sync.RWMutex
+ retrievalServiceImpl RetrievalService = stubRetrievalService{}
+)
+
+func SetRetrievalService(svc RetrievalService) {
+ retrievalServiceMu.Lock()
+ defer retrievalServiceMu.Unlock()
+ if svc == nil {
+ retrievalServiceImpl = stubRetrievalService{}
+ return
+ }
+ retrievalServiceImpl = svc
+}
+
+func GetRetrievalService() RetrievalService {
+ retrievalServiceMu.RLock()
+ defer retrievalServiceMu.RUnlock()
+ return retrievalServiceImpl
+}
+
+var (
+ memoryRetrievalServiceMu sync.RWMutex
+ memoryRetrievalServiceImpl MemoryRetrievalService = stubMemoryRetrievalService{}
+)
+
+func SetMemoryRetrievalService(svc MemoryRetrievalService) {
+ memoryRetrievalServiceMu.Lock()
+ defer memoryRetrievalServiceMu.Unlock()
+ if svc == nil {
+ memoryRetrievalServiceImpl = stubMemoryRetrievalService{}
+ return
+ }
+ memoryRetrievalServiceImpl = svc
+}
+
+func GetMemoryRetrievalService() MemoryRetrievalService {
+ memoryRetrievalServiceMu.RLock()
+ defer memoryRetrievalServiceMu.RUnlock()
+ return memoryRetrievalServiceImpl
+}
+
+var (
+ kgRetrievalServiceMu sync.RWMutex
+ kgRetrievalServiceImpl KGRetrievalService = stubKGRetrievalService{}
+)
+
+func SetKGRetrievalService(svc KGRetrievalService) {
+ kgRetrievalServiceMu.Lock()
+ defer kgRetrievalServiceMu.Unlock()
+ if svc == nil {
+ kgRetrievalServiceImpl = stubKGRetrievalService{}
+ return
+ }
+ kgRetrievalServiceImpl = svc
+}
+
+func GetKGRetrievalService() KGRetrievalService {
+ kgRetrievalServiceMu.RLock()
+ defer kgRetrievalServiceMu.RUnlock()
+ return kgRetrievalServiceImpl
+}
+
+var (
+ grepServiceMu sync.RWMutex
+ grepServiceImpl GrepService = stubGrepService{}
+)
+
+func SetGrepService(svc GrepService) {
+ grepServiceMu.Lock()
+ defer grepServiceMu.Unlock()
+ if svc == nil {
+ grepServiceImpl = stubGrepService{}
+ return
+ }
+ grepServiceImpl = svc
+}
+
+func GetGrepService() GrepService {
+ grepServiceMu.RLock()
+ defer grepServiceMu.RUnlock()
+ return grepServiceImpl
+}
+
+type stubRetrievalService struct{}
+
+func (stubRetrievalService) Search(_ context.Context, _ *gorm.DB, _ RetrievalRequest) ([]RetrievalChunk, error) {
+ return nil, ErrRetrievalServiceMissing
+}
+
+type stubMemoryRetrievalService struct{}
+
+func (stubMemoryRetrievalService) Search(_ context.Context, _ *gorm.DB, _ RetrievalRequest) ([]RetrievalChunk, error) {
+ return nil, ErrMemoryRetrievalServiceMissing
+}
+
+type stubKGRetrievalService struct{}
+
+func (stubKGRetrievalService) Search(_ context.Context, _ *gorm.DB, _ RetrievalRequest) ([]RetrievalChunk, error) {
+ return nil, ErrKGRetrievalServiceMissing
+}
+
+type stubGrepService struct{}
+
+func (stubGrepService) Grep(_ context.Context, _ GrepRequest) ([]RetrievalChunk, error) {
+ return nil, ErrGrepServiceMissing
+}
+
+// simpleRetrievalService is a deterministic test implementation that returns
+// synthetic chunks based on the query.
+type simpleRetrievalService struct{}
+
+func (simpleRetrievalService) Search(_ context.Context, _ *gorm.DB, req RetrievalRequest) ([]RetrievalChunk, error) {
+ if req.Query == "" {
+ return nil, nil
+ }
+ topN := req.TopN
+ if topN <= 0 {
+ topN = 8
+ }
+ const maxSimpleTopN = 1024
+ if topN > maxSimpleTopN {
+ topN = maxSimpleTopN
+ }
+ chunks := make([]RetrievalChunk, 0, topN)
+ for i := 0; i < topN && i < 3; i++ {
+ chunks = append(chunks, RetrievalChunk{
+ ID: fmt.Sprintf("simple-%d", i),
+ Content: fmt.Sprintf("Chunk %d matching %q", i, req.Query),
+ DocumentID: "simple-doc",
+ Score: 0.9 - float64(i)*0.1,
+ })
+ }
+ return chunks, nil
+}
+
+// SetSimpleRetrievalService installs deterministic synthetic retrieval for
+// tests and local demos.
+func SetSimpleRetrievalService() {
+ SetRetrievalService(simpleRetrievalService{})
+}
diff --git a/internal/agent/tool/registry.go b/internal/agent/tool/registry.go
index 4f8eb71d75..dea39254c9 100644
--- a/internal/agent/tool/registry.go
+++ b/internal/agent/tool/registry.go
@@ -395,7 +395,7 @@ func buildRetrievalTool(params map[string]any) (einotool.BaseTool, error) {
defaults := retrievalArgs{}
for key := range params {
switch key {
- case "dataset_ids", "kb_ids", "top_n", "top_k", "similarity_threshold",
+ case "dataset_ids", "kb_ids", "top_n", "prefetch_size", "top_k", "similarity_threshold",
"keywords_similarity_weight", "use_kg", "rerank_id", "empty_response",
"toc_enhance", "meta_data_filter", "retrieval_from", "memory_ids",
"kb_vars", "cross_languages", "function_name", "description", "meta",
@@ -426,6 +426,13 @@ func buildRetrievalTool(params map[string]any) (einotool.BaseTool, error) {
if v, ok := intParam(params, "top_n"); ok {
defaults.TopN = v
}
+ if raw, exists := params["prefetch_size"]; exists {
+ value, ok := strictInt(raw)
+ if !ok || value <= 0 {
+ return nil, fmt.Errorf("agent tool: retrieval tool requires positive integer node-level param prefetch_size")
+ }
+ defaults.PrefetchSize = value
+ }
if raw, exists := params["top_k"]; exists {
value, ok := strictInt(raw)
if !ok || value <= 0 {
diff --git a/internal/agent/tool/retrieval.go b/internal/agent/tool/retrieval.go
index 7f9dc34993..3446cd0593 100644
--- a/internal/agent/tool/retrieval.go
+++ b/internal/agent/tool/retrieval.go
@@ -61,6 +61,7 @@ type retrievalArgs struct {
KBIDs []string `json:"kb_ids,omitempty"`
MemoryIDs []string `json:"memory_ids,omitempty"`
TopN int `json:"top_n,omitempty"`
+ PrefetchSize int `json:"prefetch_size,omitempty"`
TopK int `json:"top_k,omitempty"`
KeywordsSimilarityWeight *float64 `json:"keywords_similarity_weight,omitempty"`
UseKG bool `json:"use_kg,omitempty"`
@@ -200,6 +201,7 @@ func (r *RetrievalTool) InvokableRun(ctx context.Context, argumentsInJSON string
DatasetIDs: args.DatasetIDs,
MemoryIDs: args.MemoryIDs,
TopN: args.TopN,
+ PrefetchSize: args.PrefetchSize,
TopK: args.TopK,
KeywordsSimilarityWeight: args.KeywordsSimilarityWeight,
UseKG: args.UseKG,
@@ -274,6 +276,9 @@ func (r *RetrievalTool) mergeDefaults(args retrievalArgs) retrievalArgs {
if args.TopN <= 0 {
args.TopN = r.defaults.TopN
}
+ if args.PrefetchSize <= 0 {
+ args.PrefetchSize = r.defaults.PrefetchSize
+ }
if args.TopK <= 0 {
args.TopK = r.defaults.TopK
}
diff --git a/internal/agent/tool/retrieval_nlp.go b/internal/agent/tool/retrieval_nlp.go
index dc4976cc7d..95281d3e3a 100644
--- a/internal/agent/tool/retrieval_nlp.go
+++ b/internal/agent/tool/retrieval_nlp.go
@@ -325,6 +325,9 @@ func nlpRequestFromRetrieval(
Aggs: boolPtr(false),
Highlight: boolPtr(false),
}
+ if req.PrefetchSize != 0 {
+ nlpReq.PrefetchSize = &req.PrefetchSize
+ }
if req.TopK > 0 {
nlpReq.Top = &req.TopK
} else if topN > 0 {
diff --git a/internal/agent/tool/retrieval_service.go b/internal/agent/tool/retrieval_service.go
index 0ca0ae2c84..6308b1cd9d 100644
--- a/internal/agent/tool/retrieval_service.go
+++ b/internal/agent/tool/retrieval_service.go
@@ -52,6 +52,7 @@ type RetrievalRequest struct {
DatasetIDs []string
MemoryIDs []string
TopN int
+ PrefetchSize int
TopK int
KeywordsSimilarityWeight *float64
UseKG bool
diff --git a/internal/entity/chat.go b/internal/entity/chat.go
index 5ccebbb7eb..1dca67d514 100644
--- a/internal/entity/chat.go
+++ b/internal/entity/chat.go
@@ -33,7 +33,7 @@ type Chat struct {
PromptConfig JSONMap `gorm:"column:prompt_config;type:longtext;not null" json:"prompt_config"`
MetaDataFilter *JSONMap `gorm:"column:meta_data_filter;type:longtext" json:"meta_data_filter,omitempty"`
// NOTE: No `default:` GORM tags here. The service layer (chat.go Create)
- // supplies sensible defaults (0.1 / 0.3 / 6 / 1024 / "1") when a field is
+ // supplies sensible defaults (0.1 / 0.3 / 6 / 64 / 1024 / "1") when a field is
// omitted, and honors an explicitly provided zero value. A GORM `default:`
// tag would force GORM to overwrite an explicit zero (e.g.
// similarity_threshold=0) with the column default during Create, breaking
@@ -41,6 +41,7 @@ type Chat struct {
SimilarityThreshold float64 `gorm:"column:similarity_threshold" json:"similarity_threshold"`
VectorSimilarityWeight float64 `gorm:"column:vector_similarity_weight" json:"vector_similarity_weight"`
TopN int64 `gorm:"column:top_n" json:"top_n"`
+ PrefetchSize int64 `gorm:"column:prefetch_size" json:"prefetch_size"`
TopK int64 `gorm:"column:top_k" json:"top_k"`
DoRefer string `gorm:"column:do_refer;size:1;not null" json:"do_refer"`
RerankID string `gorm:"column:rerank_id;size:128;not null;default:''" json:"rerank_id"`
diff --git a/internal/handler/chat.go b/internal/handler/chat.go
index 2b55455368..6eced41eae 100644
--- a/internal/handler/chat.go
+++ b/internal/handler/chat.go
@@ -369,6 +369,7 @@ func (h *ChatHandler) GetChat(c *gin.Context) {
"similarity_threshold": chat.SimilarityThreshold,
"vector_similarity_weight": chat.VectorSimilarityWeight,
"top_n": chat.TopN,
+ "prefetch_size": chat.PrefetchSize,
"top_k": chat.TopK,
"do_refer": chat.DoRefer,
"rerank_id": chat.RerankID,
diff --git a/internal/handler/mindmap.go b/internal/handler/mindmap.go
index 05b20bf297..710651d497 100644
--- a/internal/handler/mindmap.go
+++ b/internal/handler/mindmap.go
@@ -106,6 +106,7 @@ func mindMapRetrievalRequest(question string, kbIDs common.StringSlice, searchID
page := 1
size := 12
topK := intFromConfig(searchConfig, "top_k", 1024)
+ prefetchSize := intFromConfig(searchConfig, "prefetch_size", 100)
similarityThreshold := floatFromConfig(searchConfig, "similarity_threshold", 0.2)
vectorSimilarityWeight := floatFromConfig(searchConfig, "vector_similarity_weight", 0.3)
req := &service.RetrievalTestRequest{
@@ -114,6 +115,7 @@ func mindMapRetrievalRequest(question string, kbIDs common.StringSlice, searchID
Page: &page,
Size: &size,
TopK: &topK,
+ PrefetchSize: &prefetchSize,
SimilarityThreshold: &similarityThreshold,
VectorSimilarityWeight: &vectorSimilarityWeight,
DocIDs: stringSliceFromConfig(searchConfig, "doc_ids"),
diff --git a/internal/handler/searchbot.go b/internal/handler/searchbot.go
index d37f8eadd4..f5c8251c1e 100644
--- a/internal/handler/searchbot.go
+++ b/internal/handler/searchbot.go
@@ -52,6 +52,7 @@ type SearchBotRetrievalTestRequest struct {
Question string `json:"question" binding:"required"`
Page *int `json:"page,omitempty"`
Size *int `json:"size,omitempty"`
+ PrefetchSize *int `json:"prefetch_size,omitempty"`
DocIDs []string `json:"doc_ids,omitempty"`
UseKG *bool `json:"use_kg,omitempty"`
TopK *int `json:"top_k,omitempty"`
@@ -509,6 +510,7 @@ func toRetrievalServiceRequest(h *SearchBotRetrievalTestRequest) *service.Retrie
Question: h.Question,
Page: h.Page,
Size: h.Size,
+ PrefetchSize: h.PrefetchSize,
DocIDs: h.DocIDs,
UseKG: h.UseKG,
TopK: h.TopK,
diff --git a/internal/service/ask_service.go b/internal/service/ask_service.go
index 46234df9ee..2a2c4a338f 100644
--- a/internal/service/ask_service.go
+++ b/internal/service/ask_service.go
@@ -30,6 +30,7 @@ import (
const (
DefaultAskPage = 1
DefaultAskPageSize = 12
+ DefaultAskPrefetchSize = 100
DefaultAskTopK = 1024
DefaultAskSimilarityThreshold = 0.1
DefaultAskVectorSimilarityWeight = 0.3
@@ -65,6 +66,7 @@ type AskStreamOptions struct {
DocIDs []string
UseKG *bool
TopK *int
+ PrefetchSize *int
CrossLanguages []string
Filter map[string]interface{}
TenantRerankID *string
@@ -159,6 +161,10 @@ func (s *AskService) run(ctx context.Context, llm StreamingLLM, userID, question
if opts.VectorSimilarityWeight != nil {
vectorSimilarityWeight = *opts.VectorSimilarityWeight
}
+ prefetchSize := DefaultAskPrefetchSize
+ if opts.PrefetchSize != nil {
+ prefetchSize = *opts.PrefetchSize
+ }
req := &RetrievalTestRequest{
Datasets: common.StringSlice(datasetIDs),
@@ -166,6 +172,7 @@ func (s *AskService) run(ctx context.Context, llm StreamingLLM, userID, question
DocIDs: opts.DocIDs,
UseKG: opts.UseKG,
TopK: ptrInt(topK),
+ PrefetchSize: ptrInt(prefetchSize),
CrossLanguages: opts.CrossLanguages,
Filter: opts.Filter,
TenantRerankID: opts.TenantRerankID,
diff --git a/internal/service/chat.go b/internal/service/chat.go
index 13e2970bf4..d4858f2ef5 100644
--- a/internal/service/chat.go
+++ b/internal/service/chat.go
@@ -200,6 +200,7 @@ type CreateChatRequest struct {
PromptConfig map[string]interface{} `json:"prompt_config"`
Description *string
TopN *int
+ PrefetchSize *int
TopK *int
SimilarityThreshold *float64
VectorSimilarityWeight *float64
@@ -299,6 +300,9 @@ func (s *ChatService) Create(ctx context.Context, userID string, req map[string]
if _, ok := req["top_n"]; !ok {
req["top_n"] = 6
}
+ if _, ok := req["prefetch_size"]; !ok {
+ req["prefetch_size"] = 64
+ }
if _, ok := req["top_k"]; !ok {
req["top_k"] = 1024
}
@@ -501,7 +505,7 @@ func filterCreateChatPersistedFields(req map[string]interface{}) {
persisted := map[string]struct{}{
"name": {}, "description": {}, "icon": {}, "language": {}, "llm_id": {}, "tenant_llm_id": {},
"llm_setting": {}, "prompt_type": {}, "prompt_config": {}, "meta_data_filter": {},
- "similarity_threshold": {}, "vector_similarity_weight": {}, "top_n": {}, "top_k": {},
+ "similarity_threshold": {}, "vector_similarity_weight": {}, "top_n": {}, "prefetch_size": {}, "top_k": {},
"do_refer": {}, "rerank_id": {}, "tenant_rerank_id": {}, "kb_ids": {}, "status": {},
}
for key := range req {
@@ -549,6 +553,7 @@ func buildCreateChatEntity(req map[string]interface{}, tenantID string) *entity.
SimilarityThreshold: floatFromValue(req["similarity_threshold"]),
VectorSimilarityWeight: floatFromValue(req["vector_similarity_weight"]),
TopN: int64FromValue(req["top_n"]),
+ PrefetchSize: int64FromValue(req["prefetch_size"]),
TopK: int64FromValue(req["top_k"]),
DoRefer: stringFromValue(req["do_refer"]),
RerankID: rerankID,
@@ -799,6 +804,7 @@ var chatPersistedFields = map[string]struct{}{
"similarity_threshold": {},
"vector_similarity_weight": {},
"top_n": {},
+ "prefetch_size": {},
"top_k": {},
"do_refer": {},
"rerank_id": {},
@@ -1156,6 +1162,7 @@ func (s *ChatService) buildRESTChatResponse(ctx context.Context, chat *entity.Ch
"similarity_threshold": chat.SimilarityThreshold,
"vector_similarity_weight": chat.VectorSimilarityWeight,
"top_n": chat.TopN,
+ "prefetch_size": chat.PrefetchSize,
"top_k": chat.TopK,
"do_refer": chat.DoRefer,
"rerank_id": chat.RerankID,
diff --git a/internal/service/chat_pipeline.go b/internal/service/chat_pipeline.go
index 19d81c6b63..faa595c114 100644
--- a/internal/service/chat_pipeline.go
+++ b/internal/service/chat_pipeline.go
@@ -613,6 +613,7 @@ func (s *ChatPipelineService) AsyncChat(
"doc_aggs": []interface{}{},
}
var knowledges []string
+ prefetchSize := int(chat.PrefetchSize)
// When hasKnowledgeParam is true, runs (mutually exclusive):
// a) If reasoning is enabled: DeepResearcher replaces vector retrieval.
@@ -642,6 +643,7 @@ func (s *ChatPipelineService) AsyncChat(
DocIDs: docIDs,
Page: 1,
PageSize: int(chat.TopN),
+ PrefetchSize: &prefetchSize,
EmbeddingModel: embModel,
})
}
@@ -697,6 +699,7 @@ func (s *ChatPipelineService) AsyncChat(
DocIDs: docIDs,
Page: 1,
PageSize: topN,
+ PrefetchSize: &prefetchSize,
Top: &top,
SimilarityThreshold: &threshold,
VectorSimilarityWeight: &vsw,
diff --git a/internal/service/chat_session.go b/internal/service/chat_session.go
index dd4ba6c740..5fbe68f4a7 100644
--- a/internal/service/chat_session.go
+++ b/internal/service/chat_session.go
@@ -1818,6 +1818,7 @@ func (s *ChatSessionService) buildDefaultCompletionDialog(tenantID string) *enti
PromptConfig: entity.JSONMap{},
KBIDs: entity.JSONSlice{},
TopN: 6,
+ PrefetchSize: 64,
TopK: 1024,
RerankID: "",
SimilarityThreshold: 0.1,
diff --git a/internal/service/chunk/chunk.go b/internal/service/chunk/chunk.go
index 07567891cb..326a5a7c99 100644
--- a/internal/service/chunk/chunk.go
+++ b/internal/service/chunk/chunk.go
@@ -208,6 +208,10 @@ func (s *ChunkService) RetrievalTest(ctx context.Context, req *service.Retrieval
var chatID string
var chatModelForFilter *models.ChatModel
filter := req.Filter
+ prefetchSize := 64
+ if req.PrefetchSize != nil {
+ prefetchSize = *req.PrefetchSize
+ }
if req.SearchID != nil && *req.SearchID != "" {
// If search_id is set, get meta_data_filter and chat_id from search_config
@@ -215,6 +219,12 @@ func (s *ChunkService) RetrievalTest(ctx context.Context, req *service.Retrieval
if err != nil {
common.Warn("Failed to get search detail for search_id, proceeding without it", zap.String("searchID", *req.SearchID), zap.Error(err))
} else if searchConfig, ok := searchConfigMap(searchDetail["search_config"]); ok && searchConfig != nil {
+ if req.PrefetchSize == nil || *req.PrefetchSize == 0 {
+ prefetchSize = 100
+ if configuredPrefetchSize, ok := common.GetInt(searchConfig["prefetch_size"]); ok {
+ prefetchSize = configuredPrefetchSize
+ }
+ }
if searchMetaFilter, ok := searchConfigMap(searchConfig["meta_data_filter"]); ok {
filter = searchMetaFilter
}
@@ -407,6 +417,7 @@ func (s *ChunkService) RetrievalTest(ctx context.Context, req *service.Retrieval
DocIDs: docIDs,
Page: common.CoalesceInt(req.Page, 1),
PageSize: common.CoalesceInt(req.Size, 30),
+ PrefetchSize: &prefetchSize,
Top: req.TopK,
SimilarityThreshold: req.SimilarityThreshold,
VectorSimilarityWeight: req.VectorSimilarityWeight,
diff --git a/internal/service/chunk_types.go b/internal/service/chunk_types.go
index 7566187763..3cd143a008 100644
--- a/internal/service/chunk_types.go
+++ b/internal/service/chunk_types.go
@@ -64,6 +64,7 @@ type RetrievalTestRequest struct {
Question string `json:"question"`
Page *int `json:"page,omitempty"`
Size *int `json:"size,omitempty"`
+ PrefetchSize *int `json:"prefetch_size,omitempty"`
DocIDs []string `json:"doc_ids,omitempty"`
UseKG *bool `json:"use_kg,omitempty"`
TopK *int `json:"top_k,omitempty"`
diff --git a/internal/service/dataset/search.go b/internal/service/dataset/search.go
index 5549365d5a..fa040ca663 100644
--- a/internal/service/dataset/search.go
+++ b/internal/service/dataset/search.go
@@ -38,6 +38,10 @@ func (d *DatasetService) SearchDatasets(ctx context.Context, req *service.Search
if req.Size != nil {
pageSize = *req.Size
}
+ prefetchSize := 64
+ if req.PrefetchSize != nil {
+ prefetchSize = *req.PrefetchSize
+ }
useKG := false
if req.UseKG != nil {
useKG = *req.UseKG
@@ -127,6 +131,7 @@ func (d *DatasetService) SearchDatasets(ctx context.Context, req *service.Search
}
if searchConfig, ok := searchDetail["search_config"].(map[string]interface{}); ok && searchConfig != nil {
+ prefetchSize = 100
if scMetadataFilter, ok := searchConfig["meta_data_filter"].(map[string]interface{}); ok {
metadataFilter = scMetadataFilter
}
@@ -144,6 +149,9 @@ func (d *DatasetService) SearchDatasets(ctx context.Context, req *service.Search
topK = 2048
}
}
+ if scPrefetchSize, ok := common.GetInt(searchConfig["prefetch_size"]); ok {
+ prefetchSize = scPrefetchSize
+ }
if scUseKG, ok := searchConfig["use_kg"].(bool); ok {
useKG = scUseKG
}
@@ -263,6 +271,7 @@ func (d *DatasetService) SearchDatasets(ctx context.Context, req *service.Search
DocIDs: docIDs,
Page: page,
PageSize: pageSize,
+ PrefetchSize: &prefetchSize,
Top: &topK,
SimilarityThreshold: &similarityThreshold,
VectorSimilarityWeight: &vectorSimilarityWeight,
diff --git a/internal/service/dataset_types.go b/internal/service/dataset_types.go
index a1be4a7280..ef3e9e63a6 100644
--- a/internal/service/dataset_types.go
+++ b/internal/service/dataset_types.go
@@ -41,6 +41,7 @@ type SearchDatasetsRequest struct {
Question string `json:"question" binding:"required"`
Page *int `json:"page,omitempty"`
Size *int `json:"size,omitempty"`
+ PrefetchSize *int `json:"prefetch_size,omitempty"`
DocIDs []string `json:"doc_ids,omitempty"`
UseKG *bool `json:"use_kg,omitempty"`
TopK *int `json:"top_k,omitempty"`
@@ -68,6 +69,7 @@ type SearchDatasetRequest struct {
Question string `json:"question"`
Page *int `json:"page,omitempty"`
Size *int `json:"size,omitempty"`
+ PrefetchSize *int `json:"prefetch_size,omitempty"`
DocIDs []string `json:"doc_ids,omitempty"`
UseKG *bool `json:"use_kg,omitempty"`
TopK *int `json:"top_k,omitempty"`
@@ -91,6 +93,7 @@ func (req *SearchDatasetRequest) ToSearchDatasetsRequest(datasetID string) *Sear
Question: req.Question,
Page: req.Page,
Size: req.Size,
+ PrefetchSize: req.PrefetchSize,
DocIDs: req.DocIDs,
UseKG: req.UseKG,
TopK: req.TopK,
diff --git a/internal/service/nlp/retrieval.go b/internal/service/nlp/retrieval.go
index 33c956e195..b2b45a3979 100644
--- a/internal/service/nlp/retrieval.go
+++ b/internal/service/nlp/retrieval.go
@@ -53,6 +53,7 @@ type RetrievalRequest struct {
DocIDs []string
Page int
PageSize int
+ PrefetchSize *int
Top *int
SimilarityThreshold *float64
VectorSimilarityWeight *float64
@@ -72,7 +73,7 @@ type RetrievalResult struct {
}
// Retrieval performs hybrid search + reranking + pagination
-// - Calculate rerank limit and call Search() to fetch rerankLimit candidates for reranking
+// - Prefetch candidates for reranking
// - Perform reranking via Rerank()
// - Sort indices by score descending and filter by threshold
// - Calculate pagination to extract actual page returned from reranked results
@@ -107,33 +108,23 @@ func (s *RetrievalService) Retrieval(ctx context.Context, req *RetrievalRequest)
if req.PageSize <= 0 {
req.PageSize = 1
}
+ if req.PrefetchSize == nil {
+ req.PrefetchSize = func() *int { v := 64; return &v }()
+ }
- // Calculate rerank limit to ensure we get enough results for proper pagination
pageSize := req.PageSize
- rerankLimit := pageSize
- if pageSize > 1 {
- rerankLimit = int(math.Ceil(64.0/float64(pageSize))) * pageSize
- } else {
- rerankLimit = 1
- }
- if rerankLimit < 30 {
- rerankLimit = 30
- }
- // Cap rerank limit when external rerank model is used
- if req.RerankModel != nil && *req.Top > 0 {
- if rerankLimit > *req.Top {
- rerankLimit = *req.Top
- }
- if rerankLimit > 64 {
- rerankLimit = 64
+ prefetchSize := *req.PrefetchSize
+ if prefetchSize <= 0 || req.Page > prefetchSize/pageSize {
+ requiredSize := "overflow"
+ if req.Page <= int(^uint(0)>>1)/pageSize {
+ requiredSize = strconv.Itoa(req.Page * pageSize)
}
+ return nil, fmt.Errorf("prefetch_size(%d) must be greater than page * page_size(%s) to ensure correct pagination", prefetchSize, requiredSize)
}
-
- page := req.Page
- globalOffset := (page - 1) * pageSize
- searchPage := globalOffset/rerankLimit + 1
- common.Debug("Retrieval rerank params", zap.Int("page", req.Page), zap.Int("pageSize", pageSize),
- zap.Int("searchPage", searchPage), zap.Int("rerankLimit", rerankLimit), zap.Int("globalOffset", globalOffset))
+ if req.RerankModel != nil && req.Page != 1 {
+ return nil, fmt.Errorf("Pagination is not supported when rerank_mdl is specified. Please set page=1 to retrieve the top %d results.", pageSize)
+ }
+ common.Info("Retrieval prefetch params", zap.Int("page", req.Page), zap.Int("pageSize", pageSize), zap.Int("prefetchSize", prefetchSize))
// Execute search via Search()
searchReq := &RetrievalSearchRequest{
@@ -141,8 +132,8 @@ func (s *RetrievalService) Retrieval(ctx context.Context, req *RetrievalRequest)
Question: req.Question,
KbIDs: req.KbIDs,
DocIDs: req.DocIDs,
- Page: searchPage,
- PageSize: rerankLimit,
+ Page: 1,
+ PageSize: prefetchSize,
Top: *req.Top,
RankFeature: *req.RankFeature,
EmbeddingModel: req.EmbeddingModel,
@@ -153,8 +144,6 @@ func (s *RetrievalService) Retrieval(ctx context.Context, req *RetrievalRequest)
if err != nil {
return nil, fmt.Errorf("search failed: %w", err)
}
- searchTotal := searchResult.Total
-
// Prune deleted chunks
searchResult, err = s.PruneDeletedChunks(ctx, searchResult)
if err != nil {
@@ -203,7 +192,7 @@ func (s *RetrievalService) Retrieval(ctx context.Context, req *RetrievalRequest)
// Calculate pagination
// begin and end define which of validIdx to return as the page
- begin := globalOffset % rerankLimit
+ begin := (req.Page - 1) * pageSize
end := begin + pageSize
// Get page indices
@@ -217,17 +206,7 @@ func (s *RetrievalService) Retrieval(ctx context.Context, req *RetrievalRequest)
common.Info("Pagination result info", zap.Int("totalValid", len(validIdx)), zap.Int("begin", begin),
zap.Int("end", end), zap.Int("chunkCount", len(pageIdx)), zap.Float64("postThreshold", postThreshold))
- //searchTotal > len(searchResult.IDs): The total number reported by the engine exceeds the number actually retrieved this time,
- //indicating that there are still unretrieved chunks in the candidate set; the current count may be an underestimate
- //*req.Top > rerankLimit: The Top value requested by the caller exceeds the re-ranking limit, indicating that we have indeed
- //‘only examined a portion’ rather than having covered all target results
total := int64(len(validIdx))
- if searchTotal > int64(len(searchResult.IDs)) && *req.Top > rerankLimit {
- total, err = s.countThresholdValidMatches(ctx, req, *req.Top, postThreshold)
- if err != nil {
- return nil, err
- }
- }
// Build chunks for pageIdx, transforms raw search results into the API response format
var filteredChunks []map[string]interface{}
@@ -426,41 +405,6 @@ func (s *RetrievalService) Retrieval(ctx context.Context, req *RetrievalRequest)
}, nil
}
-func (s *RetrievalService) countThresholdValidMatches(ctx context.Context, req *RetrievalRequest, limit int, postThreshold float64) (int64, error) {
- searchReq := &RetrievalSearchRequest{
- TenantIDs: req.TenantIDs,
- Question: req.Question,
- KbIDs: req.KbIDs,
- DocIDs: req.DocIDs,
- Page: 1,
- PageSize: limit,
- Top: *req.Top,
- RankFeature: *req.RankFeature,
- EmbeddingModel: req.EmbeddingModel,
- Filter: req.Filter,
- }
- searchResult, err := s.Search(ctx, searchReq)
- if err != nil {
- return 0, fmt.Errorf("search count failed: %w", err)
- }
- searchResult, err = s.PruneDeletedChunks(ctx, searchResult)
- if err != nil {
- return 0, fmt.Errorf("PruneDeletedChunks count failed: %w", err)
- }
- if searchResult.Total == 0 {
- return 0, nil
- }
-
- sim, _, _ := s.scoreSearchResult(ctx, req, searchResult)
- var total int64
- for _, score := range sim {
- if score >= postThreshold {
- total++
- }
- }
- return total, nil
-}
-
func (s *RetrievalService) scoreSearchResult(ctx context.Context, req *RetrievalRequest, searchResult *RetrievalSearchResult) ([]float64, []float64, []float64) {
// sim = tkWeight*tsim + vtWeight*vsim
vtWeight := *req.VectorSimilarityWeight
diff --git a/internal/service/nlp/retrieval_test.go b/internal/service/nlp/retrieval_test.go
index 1db4372c9f..75f31e1126 100644
--- a/internal/service/nlp/retrieval_test.go
+++ b/internal/service/nlp/retrieval_test.go
@@ -14,7 +14,7 @@ import (
"gorm.io/gorm"
)
-func TestRetrievalTotalCountsThresholdValidMatchesBeyondRerankWindow(t *testing.T) {
+func TestRetrievalUsesPrefetchSizeAsCandidateSet(t *testing.T) {
oldQueryBuilder := globalQueryBuilder
globalQueryBuilder = NewQueryBuilder()
defer func() { globalQueryBuilder = oldQueryBuilder }()
@@ -34,6 +34,7 @@ func TestRetrievalTotalCountsThresholdValidMatchesBeyondRerankWindow(t *testing.
threshold := 0.5
vectorWeight := 1.0
aggs := false
+ prefetchSize := 70
result, err := service.Retrieval(context.Background(), &RetrievalRequest{
Question: "alpha",
@@ -45,6 +46,7 @@ func TestRetrievalTotalCountsThresholdValidMatchesBeyondRerankWindow(t *testing.
VectorSimilarityWeight: &vectorWeight,
Aggs: &aggs,
Filter: map[string]interface{}{"must_not": map[string]interface{}{"exists": "compile_kwd"}},
+ PrefetchSize: &prefetchSize,
})
if err != nil {
t.Fatalf("Retrieval failed: %v", err)
@@ -52,11 +54,11 @@ func TestRetrievalTotalCountsThresholdValidMatchesBeyondRerankWindow(t *testing.
if len(result.Chunks) != 10 {
t.Fatalf("page chunk count = %d, want 10", len(result.Chunks))
}
- if result.Total != 75 {
- t.Fatalf("total = %d, want 75", result.Total)
+ if result.Total != 70 {
+ t.Fatalf("total = %d, want 70", result.Total)
}
- if len(engine.searchLimits) != 2 || engine.searchLimits[0] != 70 || engine.searchLimits[1] != 100 {
- t.Fatalf("search limits = %v, want [70 100]", engine.searchLimits)
+ if len(engine.searchLimits) != 1 || engine.searchLimits[0] != prefetchSize {
+ t.Fatalf("search limits = %v, want [%d]", engine.searchLimits, prefetchSize)
}
for _, filters := range engine.searchFilters {
mustNot, ok := filters["must_not"].(map[string]interface{})
diff --git a/internal/service/search.go b/internal/service/search.go
index 6f450495e3..4da8ce1b84 100644
--- a/internal/service/search.go
+++ b/internal/service/search.go
@@ -435,6 +435,9 @@ func askOptionsFromSearchConfig(searchID string, searchConfig map[string]interfa
if value, ok := intFromSearchConfig(searchConfig["top_k"]); ok {
opts.TopK = &value
}
+ if value, ok := intFromSearchConfig(searchConfig["prefetch_size"]); ok {
+ opts.PrefetchSize = &value
+ }
if value, ok := searchConfigMapValue(searchConfig["meta_data_filter"]); ok {
opts.Filter = value
}