Docs
Contents

Retrieval and Source Tracing

Overview and use cases

The Retrieval and Source Tracing module covers the data-plane query loop for knowledge bases: single-KB retrieval (createSearch), cross-KB federated retrieval (createMultiSearch, one query spanning 1–10 knowledge bases with RRF fusion and global reranking returning TopK), grounded answer synthesis (answer: true), enhanced-index cooperative retrieval (joint retrieval over GraphRAG knowledge graph context and LLM Wiki pages), and protected source download for matched chunks (getDocumentSource, supporting HTTP Range range reads of 206 Partial Content).

In enterprise customer service and technical support scenarios (e.g., knowledge base kb_enterprise_support under demo project enterprise-ai-hub-210), server-side applications or agent runtimes use this module to perform hybrid (vector + full-text) hybrid retrieval: if the knowledge base has an enabled lexicon binding (e.g., lex_enterprise_synonyms), the server automatically applies synonym and expansion term rewriting to query before retrieval; after fusing text-embedding-v3 vector retrieval with full-text search, it calls qwen3.7-text-rerank to rerank and locates the source document section offset (locator).

Prerequisites

Usage workflow

  1. Initialize the client and services: construct Client with setEndpoint('https://appbuild-sit.oceanbase.com/v1'), setProject('enterprise-ai-hub-210'), and setKey('<APPBASE_API_KEY>'), then instantiate KnowledgeBases(client).

  2. Single knowledge base hybrid retrieval (createSearch): pass in knowledgeBaseId, query, searchMode: 'hybrid' (note the parameter name is searchMode and must not be written as mode), limit, similarityThreshold, vectorWeight and rerank: true. Optionally add documentTag or subProductId to narrow the document scope, or pass answer: true to obtain a grounded answer synthesized from the retrieved chunks.

  3. Cross-knowledge-base joint retrieval (createMultiSearch): pass in knowledgeBaseIds (an array of 1–10 unique knowledge base IDs), query, searchMode, limit, offset, and a metadataFilter keyed by knowledge base ID (a specific library ID's configuration overrides the "*" fallback; the two are not merged). The server first retrieves candidate sets from each knowledge base and applies RRF (Reciprocal Rank Fusion); when reranking is enabled, a single global Rerank is then performed on the merged pool.

  4. Parse retrieved hits and trace back to read the source (getDocumentSource): iterate over the chunks in the response results[] (including content, score, sourceId, source and locator). For ordinary document chunks, use sourceId as documentId to call getDocumentSource and fetch the original file binary byte stream (supports Range header partial downloads), for front-end citation previews or compliance audit archiving.

Key parameters and returns

Retrieval request parameters (createSearch / createMultiSearch)

ParameterApplicable methodTypeRequiredDefault / constraintDescription
knowledgeBaseIdcreateSearchstringYesNon-empty stringTarget single knowledge base ID (e.g. kb_enterprise_support).
knowledgeBaseIdscreateMultiSearchstring[]Yes1–10 unique IDsList of target knowledge base IDs for cross-knowledge-base retrieval.
queryBothstringYesNon-empty query textThe user's natural language question or retrieval keywords.
searchModeBothstringNoDefault hybrid; enum: vector / fulltext / hybridRetrieval mode (must not be miswritten as mode).
limitBothintegerNoDefault 10 (range 1–100)Maximum number of chunks returned (global TopK).
offsetcreateMultiSearchintegerNoDefault 0 (0–5000)Pagination offset after cross-knowledge-base fusion ranking.
recallLimitBothintegerNoDefault min(100, max(limit * 4, 20)) when reranking is enabled; explicitly 1–100 and not less than limitUpper limit of initial candidate retrieval before reranking.
similarityThresholdBothnumberNo0–1 (defaults to the KB retrievalDefaults)Applies to the vector retrieval branch of vector and hybrid modes; does not filter the full-text branch.
vectorWeightBothnumberNo0–1 (commonly 0.7)Vector score weight in hybrid mode; the full-text weight is 1 - vectorWeight.
rerankBothbooleanNoDefault falseWhether to perform reranking via the LLM Gateway.
rerankModelBothstringNoe.g. qwen3.7-text-rerankExplicitly specify the reranking model; if omitted and rerank=true, the platform selects automatically.
rerankProviderRefBothstringNoproject:<id> / trial:<id>Provider reference that pins the reranking model.
documentTagBothstringNoComma-separated tagsServer 2.12.0 supports any-match across non-empty tags and underscore-delimited segment-prefix filtering for structured and free-form tags; avoid all-underscore filters; SDK field availability depends on the version in use.
subProductIdBothstringNo1–64 letters or digitsAdded in 2.10.0: filter by sub-product identifier (AND relation with documentTag).
metadataFilterBothobjectNoJSON filter objectFor single knowledge base, pass logic and conditions (each item contains name / comparison / value); for cross-knowledge-base, key by knowledge base ID, with "*" as the fallback for libraries without individual configuration.
useKnowledgeGraphcreateSearchbooleanNoDefault falseWhether to jointly retrieve GraphRAG entity, relationship and community report context.
useWikicreateSearchbooleanNoDefault falseWhether to jointly retrieve published LLM Wiki page chunks.
allowDegradedcreateSearchbooleanNoDefault trueControls degradation-eligible errors of augmented retrieval; see capabilities / degradedCapabilities for statuses; does not control reranking model failures.
answercreateSearchbooleanNoDefault falseAdded in 2.9.0: whether to call a Chat model on the retrieved Top evidence (up to 12 items) to generate a grounded answer (≤1024 tokens).

Retrieval response structure

Single knowledge base returns KnowledgeBaseSearchResultList; cross-knowledge-base returns KnowledgeBaseMultiSearchResultList. Do not apply single-knowledge-base augmentation parameters or response fields directly to cross-knowledge-base calls.

FieldApplicable methodDescription
totalBothNumber of results returned this time.
resultsBothResults array; each item uses $id, sourceId, content, score, source, locator, metadata. Cross-knowledge-base items additionally carry knowledgeBaseId, identifying the knowledge base the result belongs to.
rerankedwhether bothcompleted reranking successfully; false when automatic model selection fails and falls back.
resolvedVersionIdcreateSearchKnowledge base version resolved for this request; null on legacy read paths.
capabilitiescreateSearchRAPTOR / GraphRAG / Wiki status, result generation, elapsed time and sanitized errors.
degradedCapabilitiescreateSearchAugmented capabilities where degradation explicitly occurred.
answercreateSearchThe { status, text, model, latencyMs, error } when answer: true was requested; otherwise null.

Single-knowledge-base results also distinguish ordinary chunks from augmented results via indexSource, resultType and resultGeneration. source is the source description object and locator is the location object; fields depend on the respective result type.

The answer model reads indexingDefaults.chatModel / chatProviderRef. answer.status is not_configured (no model configured), no_evidence (no valid evidence), succeeded (generated text) or failed (call error or empty text). Even on a successful answer, verify the sources in results.

Errors and boundaries

SDK Category Differences

SDK categoryCoverageAuthentication methodTypical scenarios
Server SDK (Node.js / Java / Python / Go)Full support createSearch, createMultiSearch, getDocumentSourceProject API Key (knowledgebases.read)Backend RAG services, agent tool retrieval, source-traceability download
Console SDK (Node.js / Java / Python / Go)The Java / Python / Go Console SDKs provide the full KnowledgeBases retrieval surface; the JS Console SDK uses client.call for callsManagement-plane session / short-lived JWT / API KeyConsole retrieval test bench, automated inspection, and evaluation
Client / Web SDK (Web)Does not support knowledge base retrieval and source file download (only includes Yuque OAuth helper methods)User SessionBrowsers must invoke retrieval APIs via the business backend or a Function proxy

Examples by language

Each card allows switching languages (synchronized across the full page).

Retrieval (single knowledge base / cross knowledge base)

createSearch single knowledge base; createMultiSearch spans 1–10 knowledge bases (cross-knowledge-base first merges via RRF, then performs one rerank on the merged pool); result chunks carry content / source / locator. The Web surface has no retrieval capability.

const found = await kb.createSearch({
    knowledgeBaseId: base.$id,
    query: '退款政策是什么?',
    searchMode: 'hybrid',   // Parameter name is searchMode; vector / fulltext / hybrid
    limit: 10,
    rerank: true            // Expand retrieval first, then rerank via the Gateway; automatic selection falls back and returns reranked: false on failure
});
// Cross knowledge base: kb.createMultiSearch({ knowledgeBaseIds: [...], query, limit }) (1–10 knowledge bases, global TopK)

Traceability and reading source files

Retrieved chunks carry content, source (protected source URI) and locator (section / text offsets); getDocumentSource reads back the original file (binary stream, supports Range partial responses 206), requiring only knowledgebases.read and not additionally files.read. The Web surface has no such capability.

// The sourceId of a hit chunk is the original document ID; read back the original for manual verification or archiving
const raw = await kb.getDocumentSource({ knowledgeBaseId: base.$id, documentId: '<documentId>' });

Advanced retrieval (tag filtering, answer synthesis and cross-knowledge-base metadata filtering)

The ob / aigw and document locators in the examples must be replaced with actual document values; subProductId does not accept hyphens, underscores or spaces, and documentTag accepts free-form values; the Console stores both hierarchical labels and locator values in the document’s documentTag list.

Single knowledge base supports answer: true grounded answer synthesis, documentTag / subProductId document scope filtering, and per-library metadataFilter and offset pagination of createMultiSearch.

// 1. Single-library advanced retrieval: filter by subProductId / documentTag + GraphRAG/Wiki enhancement + answer synthesis
const singleResult = await kb.createSearch({
    knowledgeBaseId: 'kb_enterprise_support',
    query: 'OceanBase 分布式事务锁冲突与向量索引构建超时的排障步骤是什么?',
    searchMode: 'hybrid',
    limit: 6,
    similarityThreshold: 0.45,
    vectorWeight: 0.7,
    rerank: true,
    rerankModel: 'qwen3.7-text-rerank',
    subProductId: 'ob',
    documentTag: 'ob_12_4a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d',
    useKnowledgeGraph: true,
    useWiki: true,
    allowDegraded: true,
    answer: true,
});
console.log('合成答案:', singleResult.answer?.text);

// 2. Cross-database joint retrieval: pagination with metadataFilter + offset specified per database
const multiResult = await kb.createMultiSearch({
    knowledgeBaseIds: ['kb_enterprise_support', 'kb_product_docs'],
    query: 'AI 网关的工具接入与限流策略怎么配置?',
    searchMode: 'hybrid',
    limit: 10,
    offset: 0,
    rerank: true,
    subProductId: 'aigw',
    metadataFilter: {
        '*': { logic: 'and', conditions: [{ name: 'env', comparison: 'is', value: 'production' }] },
        kb_enterprise_support: { logic: 'and', conditions: [{ name: 'category', comparison: 'is', value: 'sop' }] },
    },
});

Example Guide

The model names, project IDs and query contents in this document are configuration examples; you still need to complete real model call verification in your own environment.