Files
Enterprise-Knowledge-Base/docs/AGENT_KB_RETRIEVAL_ARCHITECTURE.md
T
wizardchen 28deb8282f feat: Add comprehensive documentation for WeKnora knowledge base and wiki features
- Introduced multiple new documentation files, including a complete documentation index, quick reference guides, and comprehensive analyses of the knowledge base and wiki settings.
- The new files provide detailed insights into the architecture, data models, API endpoints, and implementation strategies for the knowledge base and wiki functionalities.
- Enhanced navigation and usability for developers and team members by summarizing key components, configurations, and data flows related to the knowledge base system.

These additions significantly improve the clarity and accessibility of documentation, supporting better onboarding and reference for current and future team members.
2026-04-22 21:18:10 +08:00

20 KiB

Agent/Bot Knowledge Base Integration Architecture

Overview

This document maps how agents/bots in WeKnora use knowledge bases, reference datasets, configure retrieval strategies, and execute the retrieval pipeline.


1. AGENT/BOT MODEL DEFINITIONS

Primary Models

CustomAgent (internal/types/custom_agent.go)

  • Role: User-configurable AI agent (similar to GPTs)
  • Key Fields:
    • ID: Agent identifier (UUID for custom, or builtin-* prefix for built-in)
    • TenantID: Owner tenant (composite primary key with ID)
    • Config: CustomAgentConfig struct containing full configuration
    • IsBuiltin: Boolean flag (built-in vs. custom)

Built-in Agent IDs:

  • builtin-quick-answer: RAG mode for Q&A
  • builtin-smart-reasoning: ReAct mode for multi-step reasoning
  • builtin-deep-researcher, builtin-data-analyst, etc.

AgentConfig (internal/types/agent.go)

  • Role: Runtime agent configuration (resolved from CustomAgent + Tenant config)
  • Key Fields:
    KnowledgeBases      []string      // Accessible KB IDs
    KnowledgeIDs        []string      // Individual document IDs (within KBs)
    SearchTargets       SearchTargets // Pre-computed unified search targets (runtime only)
    AllowedTools        []string      // List of tool names agent can use
    WebSearchEnabled    bool          // Whether web search is available
    MultiTurnEnabled    bool          // Multi-turn conversation support
    RetrieveKBOnlyWhenMentioned bool // Only retrieve KB when explicitly mentioned with @
    Thinking            *bool         // Extended thinking mode support
    LLMCallTimeout      int           // Single LLM call timeout in seconds
    

SessionAgentConfig (internal/types/agent.go)

  • Role: Session-level agent override
  • Immutable fields only: AgentModeEnabled, WebSearchEnabled, KnowledgeBases, KnowledgeIDs
  • Other configs read from Tenant at runtime

2. KNOWLEDGE BASE BINDING

How Agents Reference Knowledge Bases

Path: internal/types/agent.go → AgentConfig.KnowledgeBases[]

  1. Agent Config Level:

    • CustomAgentConfig.AvailableKnowledgeBases contains KB IDs agent can access
    • These are stored in the agent definition
  2. Session Override Level:

    • SessionAgentConfig.KnowledgeBases can override/restrict agent's KB access
    • Resolved at request entry point
  3. Runtime Resolution (session_agent_qa.go:242):

    agentConfig.KnowledgeBases, agentConfig.KnowledgeIDs = 
        s.resolveKnowledgeBases(ctx, req)
    

Knowledge Base Model (internal/types/knowledgebase.go)

type KnowledgeBase struct {
    ID                    string              // Unique identifier
    Type                  string              // "document", "faq", "wiki"
    TenantID              uint64              // Owner tenant
    EmbeddingModelID      string              // Embedding model for vectors
    ChunkingConfig        ChunkingConfig      // Document splitting strategy
    FAQConfig            *FAQConfig           // FAQ-specific indexing options
    WikiConfig           *WikiConfig          // Wiki-specific configuration
    VLMConfig            VLMConfig            // Vision model for image processing
    QuestionGenerationConfig *QuestionGenerationConfig // Auto-generate questions
    // ... other metadata
}

Knowledge Base Types:

  • "document": Standard document-based KB
  • "faq": FAQ pairs (question-answer)
  • "wiki": Wiki pages with structured content

3. RETRIEVAL STRATEGY CONFIGURATION

Global Retrieval Configuration (internal/types/retrieval_config.go)

Stored at: Tenant level (JSONB column in tenants table) Managed via: Settings UI at /tenants/kv/retrieval-config

type RetrievalConfig struct {
    EmbeddingTopK       int     // Vector search result limit (default: 50)
    VectorThreshold     float64 // Min similarity score 0-1 (default: 0.15)
    KeywordThreshold    float64 // Min keyword match score 0-1 (default: 0.3)
    RerankTopK          int     // Results after reranking (default: 10)
    RerankThreshold     float64 // Min rerank score (default: 0.2)
    RerankModelID       string  // Rerank model to use
}

Application: Used by all chat/search operations in the tenant

Retriever Types (internal/types/retriever.go)

type RetrieverType string

const (
    KeywordsRetrieverType  RetrieverType = "keywords"   // Exact/keyword matching
    VectorRetrieverType    RetrieverType = "vector"     // Semantic/embedding search
    WebSearchRetrieverType RetrieverType = "websearch"  // Web search
)

Retriever Engine Types (internal/types/retriever.go)

type RetrieverEngineType string

const (
    PostgresRetrieverEngineType      RetrieverEngineType = "postgres"       // Native SQL
    ElasticsearchRetrieverEngineType RetrieverEngineType = "elasticsearch"  // ES
    InfinityRetrieverEngineType      RetrieverEngineType = "infinity"       // Vector DB
    ElasticFaissRetrieverEngineType  RetrieverEngineType = "elasticfaiss"   // FAISS
    QdrantRetrieverEngineType        RetrieverEngineType = "qdrant"         // Qdrant
    MilvusRetrieverEngineType        RetrieverEngineType = "milvus"         // Milvus
    WeaviateRetrieverEngineType      RetrieverEngineType = "weaviate"       // Weaviate
    SQLiteRetrieverEngineType        RetrieverEngineType = "sqlite"         // SQLite
)

Retriever Engine Configuration (Tenant-level)

Field: Tenant.EffectiveEngines → []RetrieverEngineParams

type RetrieverEngineParams struct {
    RetrieverEngineType RetrieverEngineType  // e.g., "elasticsearch"
    RetrieverType       RetrieverType        // e.g., "vector" or "keywords"
}

Determines: Which physical backend (ES, Postgres, etc.) handles which retrieval type


4. THE RETRIEVAL PIPELINE

Entry Point: Agent Execution

File: internal/application/service/session_agent_qa.go

Flow:

  1. Request arrives with QARequest containing user query and agent ID
  2. Resolve Tenant: Determine retrieval tenant (own tenant or shared agent tenant)
  3. Build AgentConfig (line 210-298):
    func (s *sessionService) buildAgentConfig(ctx context.Context, ...) {
        // ... resolve KnowledgeBases and KnowledgeIDs
        agentConfig.KnowledgeBases, agentConfig.KnowledgeIDs = 
            s.resolveKnowledgeBases(ctx, req)
    
        // Build SearchTargets (next step)
        searchTargets, _ := s.buildSearchTargets(ctx, agentTenantID, 
            agentConfig.KnowledgeBases, agentConfig.KnowledgeIDs)
        agentConfig.SearchTargets = searchTargets
    }
    

Stage 1: Build Search Targets (session_knowledge_qa.go:393-486)

Function: buildSearchTargets(ctx, tenantID, knowledgeBaseIDs, knowledgeIDs)

Purpose: Convert KnowledgeBase IDs and Knowledge IDs into unified SearchTargets

Output: SearchTargets = []*SearchTarget

type SearchTarget struct {
    Type            SearchTargetType  // "knowledge_base" or "knowledge"
    KnowledgeBaseID string            // KB to search
    TenantID        uint64            // KB's tenant (for cross-tenant shared KBs)
    KnowledgeIDs    []string          // Specific file IDs (only for "knowledge" type)
}

Logic:

For each KnowledgeBaseID:
  → Create SearchTarget(Type=knowledge_base, KnowledgeBaseID=id, TenantID=resolved)

For each KnowledgeID:
  → Find its parent KnowledgeBase
  → If KB not already fully searched, create SearchTarget(Type=knowledge, 
     KnowledgeBaseID=parent, KnowledgeIDs=[kid1, kid2, ...])

Stored in: AgentConfig.SearchTargets (runtime only, not persisted)

Stage 2: Agent Initialization

File: internal/application/service/agent_service.go:81-179

Creates: AgentEngine with:

  • AgentConfig (with SearchTargets)
  • Chat model
  • Rerank model
  • Event bus
  • Context manager

File: internal/agent/tools/knowledge_search.go

Tool Definition:

  • Name: "knowledge_search"
  • Type: BaseTool
  • Description: Semantic/vector search for retrieving knowledge by meaning
  • Input: 1-5 semantic queries (not raw text)
  • Retrieval Strategy: Uses vector/semantic matching

Execution Flow (Execute method):

  1. Parse input queries
  2. Get embedding model from KB
  3. Compute query embeddings
  4. Call HybridSearch with SearchTargets
  5. Return ranked results

Stage 4: Hybrid Search (knowledgebase_search.go:77-120)

Function: HybridSearch(ctx, kbID, params)

Parameters:

  • kbID: Primary KB (or first of multiple)
  • params.KnowledgeBaseIDs: Override IDs (for multi-KB search with same embedding model)
  • params.QueryText: Query string
  • params.VectorThreshold: Min vector similarity
  • params.KeywordThreshold: Min keyword score
  • params.MatchCount: Desired results
  • params.DisableVectorMatch / DisableKeywordsMatch: Optional disable flags

Process:

1. Determine search KBs (use params.KnowledgeBaseIDs if provided, else [kbID])
2. Create CompositeRetrieveEngine with tenant's configured engines
3. For each KB:
   a. Get embedding model
   b. Compute query embedding (if vector search enabled)
   c. Create vector + keyword retrieve jobs
4. Execute parallel retrieval across all engines
5. Deduplicate and merge results
6. Apply RRF (Reciprocal Rank Fusion) fusion
7. Rerank using rerank model
8. Return top results

Stage 5: Composite Retrieval Engine (internal/application/service/retriever/composite.go)

Role: Routes retrieval requests to correct backend based on RetrieverType

Structure:

type CompositeRetrieveEngine struct {
    engineInfos []*engineInfo  // Each maps RetrieverType to backend engine
}

type engineInfo struct {
    retrieveEngine interfaces.RetrieveEngineService
    retrieverType  []types.RetrieverType  // "vector", "keywords", etc.
}

Dispatch Logic (Retrieve method):

For each RetrieveParams:
    Find first engineInfo that supports params.RetrieverType
    Delegate to that engine's Retrieve method

Created from Tenant config:

retrieveEngine, err := retriever.NewCompositeRetrieveEngine(
    registry,
    tenantInfo.GetEffectiveEngines()  // []RetrieverEngineParams
)

5. SEARCH/RETRIEVAL TARGETS AT REQUEST LEVEL

ChatManage (Pipeline State)

File: internal/types/chat_manage.go

type ChatManage struct {
    // Immutable config (set at entry point)
    PipelineRequest struct {
        KnowledgeBaseIDs []string      // User-selected KBs
        KnowledgeIDs     []string      // User-selected specific files
        SearchTargets    SearchTargets // Pre-computed unified targets
        VectorThreshold  float64       // From tenant RetrievalConfig
        KeywordThreshold float64       // From tenant RetrievalConfig
        EmbeddingTopK    int           // From tenant RetrievalConfig
        VectorDatabase   string        // Primary vector DB selection
    }
    // Mutable state
    PipelineState struct {
        SearchResult []*SearchResult     // Raw search results
        RerankResult []*SearchResult     // After reranking
        MergeResult  []*SearchResult     // After context merging
    }
}

SearchTargets Usage

Used by: Chat pipeline plugins

File: internal/application/service/chat_pipeline/search.go

func (p *PluginSearch) OnEvent(ctx, event, chatManage, next) error {
    // Check if targets exist
    if len(chatManage.SearchTargets) == 0 {
        // No targets, skip KB search (unless web search enabled)
        return nil
    }
    
    // Execute KB search using SearchTargets
    kbResults := p.searchByTargets(ctx, chatManage)
    
    // searchByTargets iterates SearchTargets and queries each
    for _, target := range chatManage.SearchTargets {
        // Determine which index to query based on target
        results := p.knowledgeBaseService.HybridSearch(
            ctx, target.KnowledgeBaseID,
            types.SearchParams{
                KnowledgeBaseIDs: []string{target.KnowledgeBaseID},
                KnowledgeIDs:     target.KnowledgeIDs,  // Scoped if present
                QueryText:        chatManage.RewriteQuery,
                // ... thresholds, top K from RetrievalConfig
            }
        )
    }
}

6. AGENT-LEVEL RETRIEVAL PREFERENCES

AgentConfig: Retrieval Preferences

Stored in CustomAgentConfig:

type CustomAgentConfig struct {
    // Tool selection
    AllowedTools []string  // e.g., ["knowledge_search", "web_search", ...]
    
    // Retrieval triggers
    RetrieveKBOnlyWhenMentioned bool  // @mention required for KB search
    
    // Search strategy
    WebSearchEnabled     bool     // Enable web search tool
    WebSearchMaxResults  int      // Max web results to return
    WebSearchProviderID  string   // Which web search provider
    
    // Model selection for retrieval
    RerankModelID string  // Rerank model for search results
    
    // History management
    MultiTurnEnabled bool  // Use conversation history
    HistoryTurns    int    // How many previous turns to keep
    
    // Context management
    RetainRetrievalHistory bool  // Keep wiki_read_page results across turns
}

Agent Tool Definitions

File: internal/agent/tools/definitions.go

Key Tools for Knowledge Retrieval:

  1. knowledge_search (Semantic Search)

    • Purpose: Vector/embedding-based semantic search
    • Input: 1-5 semantic queries (not raw text)
    • Backends: Vector retrieval engines
    • RetrievalType: VectorRetrieverType
  2. grep_chunks (Keyword Search)

    • Purpose: Exact keyword/literal matching
    • Input: Keywords to find
    • Backends: Keyword retrieval engines (ES, SQL)
    • RetrievalType: KeywordsRetrieverType
  3. list_knowledge_chunks (List Chunks)

    • Purpose: Browse document chunks
    • Input: KB ID, document ID
    • Backends: Direct document lookup
  4. wiki_search (Wiki Search)

    • Purpose: Search within wiki pages
    • Input: Query
    • Backends: Wiki-specific retrieval
  5. web_search (Web Search)

    • Purpose: Search the internet
    • Input: Query
    • Backends: External web search provider
    • RetrievalType: WebSearchRetrieverType

Default Allowed Tools:

[]string{
    ToolThinking,
    ToolTodoWrite,
    ToolKnowledgeSearch,      // Vector search
    ToolGrepChunks,           // Keyword search
    ToolListKnowledgeChunks,
    ToolWebSearch,
    ToolWebFetch,
    ToolFinalAnswer,
}

7. KEY DECISION FLOWS

  1. Agent has AgentConfig.SearchTargets
  2. When agent calls tool, it optionally specifies knowledge_base_ids
  3. If not specified, uses all SearchTargets
  4. Explicit KB param overrides agent defaults

Decision 2: Which Retrieval Strategy?

  1. Agent decides: calls knowledge_search (vector) or grep_chunks (keyword)
  2. Or both sequentially with different queries
  3. Or combines with query_knowledge_graph (graph search)
  4. Tool makes the strategic choice, not the system

Decision 3: Which Backend?

  1. RetrieveParams.RetrieverType set by tool
  2. CompositeRetrieveEngine looks up configured engines
  3. Finds engine that supports that RetrieverType
  4. Delegates to that backend

Decision 4: Result Quality (Reranking)?

  1. RetrievalConfig.RerankModelID specifies reranker
  2. HybridSearch uses it to rerank combined results
  3. Threshold applied: RetrievalConfig.RerankThreshold
  4. Top-K applied: RetrievalConfig.RerankTopK

8. DATA FLOW DIAGRAM

Request
  ↓
QARequest (agent ID, query, KB IDs)
  ↓
BuildAgentConfig
  ├→ Resolve KnowledgeBases from agent + session override
  ├→ Resolve KnowledgeIDs (individual documents)
  ├→ BuildSearchTargets (converts KB IDs → SearchTargets)
  └→ AgentConfig.SearchTargets = [SearchTarget{...}, ...]
  ↓
CreateAgentEngine(AgentConfig, ChatModel, RerankModel)
  ├→ Register tools (knowledge_search, grep_chunks, web_search, ...)
  └→ Tool registry has access to SearchTargets
  ↓
Agent Execution Loop (ReAct)
  ↓
Agent calls tool (e.g., knowledge_search)
  ├→ Tool receives SearchTargets from AgentConfig
  ├→ Optionally filters by knowledge_base_ids param
  └→ Computes query embedding
  ↓
HybridSearch(kb_id, params)
  ├→ Create CompositeRetrieveEngine with tenant engines
  ├→ Parallel: Vector search + Keyword search
  ├→ Both call Retrieve() which dispatches to backends
  └→ Merge + Rerank + Return
  ↓
Backend (ES, Postgres, Qdrant, etc.)
  ├→ Vector search via embedding DB
  ├→ Keyword search via ES/SQL
  └→ Return scored results
  ↓
RRF Fusion (combine vector + keyword)
  ↓
Reranker (optional)
  ↓
Top-K Results
  ↓
Tool Result → Agent Thought/Action Loop

9. CONFIGURATION PRECEDENCE

For any retrieval operation:

  1. Agent-level:

    • CustomAgentConfig.AllowedTools (which tools available)
    • CustomAgentConfig.RetrieveKBOnlyWhenMentioned (when to retrieve)
    • CustomAgentConfig.KnowledgeBases (which KBs)
  2. Session-level override:

    • SessionAgentConfig.KnowledgeBases (restrict agent's KBs)
  3. Request-level:

    • Query string, optional KB filter, images, etc.
  4. Tenant-level:

    • RetrievalConfig (thresholds, top-K, reranker)
    • Tenant.EffectiveEngines (which backends for vector/keyword)
  5. Knowledge Base-level:

    • KnowledgeBase.EmbeddingModelID (which embedding model)
    • KnowledgeBase.Type (document vs FAQ vs wiki)
    • KnowledgeBase.FAQConfig, WikiConfig (type-specific config)

10. KEY FILES SUMMARY

File Purpose
internal/types/agent.go AgentConfig, SessionAgentConfig
internal/types/custom_agent.go CustomAgent, CustomAgentConfig
internal/types/knowledgebase.go KnowledgeBase, KB types (document/faq/wiki)
internal/types/retrieval_config.go RetrievalConfig (tenant-level thresholds)
internal/types/retriever.go RetrieverType, RetrieverEngineType enums
internal/types/search.go SearchTarget, SearchTargets, SearchResult
internal/application/service/session_agent_qa.go Agent QA entry point, buildAgentConfig, buildSearchTargets
internal/application/service/knowledgebase_search.go HybridSearch orchestration
internal/application/service/retriever/composite.go CompositeRetrieveEngine (backend dispatch)
internal/agent/tools/knowledge_search.go Knowledge search tool definition
internal/agent/tools/definitions.go Tool names and available tools list
internal/application/service/chat_pipeline/search.go Chat pipeline search plugin

Summary

Agents bind to KBs via:

  • CustomAgent.Config.AvailableKnowledgeBases + CustomAgent.Config.AvailableKnowledgeIDs
  • Resolved to AgentConfig.KnowledgeBases + AgentConfig.KnowledgeIDs at runtime
  • Converted to AgentConfig.SearchTargets for unified multi-KB querying

Retrieval strategy is determined by:

  • Tool choice: Agent decides to call knowledge_search (vector) vs grep_chunks (keyword)
  • Tenant config: RetrievalConfig sets thresholds, top-K, and rerank model
  • Tenant engines: Tenant.EffectiveEngines specifies which backends handle which retriever types
  • KB model: KnowledgeBase.EmbeddingModelID, type, and type-specific configs

Retrieval pipeline:

  1. Agent executes and calls a retrieval tool
  2. Tool computes embedding or keywords
  3. Tool calls HybridSearch with SearchTargets
  4. HybridSearch creates CompositeRetrieveEngine from tenant engines
  5. CompositeRetrieveEngine dispatches to appropriate backend based on RetrieverType
  6. Results are fused (RRF), reranked, and returned
  7. Agent uses results in reasoning loop