Docs
Contents

Search Testing and Q&A Debugging (Search)

Search testing (Search) is a Console page for validating retrieval results, tuning retrieval strategies, and verifying sources. Hybrid, vector, and full-text modes, as well as the available rerank, GraphRAG, and Wiki options, are operated on this page; answer synthesis, anchor tag filtering, and cross-library retrieval are accessed via API / SDK. This document describes these entry points separately and does not treat API parameters as page controls.


Feature overview and core scenarios

In an enterprise-grade RAG system, merely completing document chunking and vector storage does not equal a high-quality Q&A experience. Different business questions place very different demands on retrieval strategy: for example, querying a specific error code (such as OB_ALLOCATE_MEMORY_FAILED or support ticket number TK-20261022-001) relies on precise full-text keyword matching, while asking about conceptual troubleshooting approaches (such as “how to tune when vector building runs out of memory”) relies on high-dimensional semantic vector matching.

Agentbase retrieval capabilities include the following categories. Among them, item 3 (answer synthesis) and the explicit filtering parameters of item 4 are accessed via API / SDK; Console Search has no corresponding input controls:

  1. Three retrieval modes (searchMode) and dynamic weight fusion:

    • Supports hybrid (default hybrid retrieval), vector (semantic vector retrieval), and fulltext (full-text keyword retrieval).

    • In hybrid mode, the fusion ratio between vector similarity scores and full-text retrieval scores can be dynamically adjusted via vectorWeight (0.0 to 1.0).

  2. Optional semantic rerank (Rerank) and enhanced retrieval degradation:

    • The first stage uses coarse retrieval (recallLimit, defaulting to min(100, max(limit * 4, 20)) when reranking is enabled) to quickly screen candidate chunks from a large volume of chunks;

    • The second stage calls the project's available rerank models (for example qwen3.7-text-rerank) to reorder candidates. Rerank is disabled by default; the model name is an example and must be replaced with the project's actual configuration;

    • Rerank failure is handled according to the model selection method: when rerankModel or rerankProviderRef is explicitly passed in, upstream exceptions are returned to the caller; automatic rerank with neither specified can fall back to the original ordering and return reranked: false. allowDegraded independently controls degradable errors in GraphRAG / RAPTOR / Wiki enhanced retrieval; single-library responses report status via capabilities and degradedCapabilities.

  3. Grounded answer synthesis (answer=true) and citation evidence tracing:

    • When answer=true is enabled, the system automatically calls the knowledge base's configured Chat model (such as qwen-plus) to generate a structured answer of no more than 1024 Tokens based on the reranked top evidence chunks (up to 12 evidence items), along with answer status, generation time, model used, and source text preview (View Source).

  4. Lexicon query rewriting and multi-dimensional metadata filtering:

    • Direct search can use synonyms and expansion terms from enabled bindings to rewrite the query; it does not clean the query using stop terms.

    • Supports precise scope narrowing via documentTag (multiple tags and segment-aligned matching), subProductId (sub-product AND filtering), and cross-library retrieval's metadataFilter.


Core Concepts and Architecture

Multi-path hybrid retrieval, rerank, and answer synthesis pipeline

Search Testing and Q&A Debugging (Search): workflow diagram, not a runtime screenshot

Flow diagram, not a runtime screenshot; read the relationships between steps or states along the arrows.

View the flow diagram in full size

allowDegraded controls the enhanced retrieval stage; rerank failures are handled separately depending on whether a model or Provider is explicitly selected. This diagram illustrates the single-library API flow; the Console does not provide answer synthesis controls.

Complete retrieval parameter reference

Parameter nameField identifierTypeDefault valueValue range and behavior
Query textquerystringRequiredNatural-language question or combination of keywords entered by the user.
Retrieval modesearchModestringhybridOptions: hybrid (vector + full-text hybrid), vector (pure vector retrieval), fulltext (pure full-text retrieval).
Number of returned resultslimitintegerConsole 10 / API 10Number of items finally returned, range 1 to 100.
Pagination offsetoffsetinteger0Cross-library retrieval range 0–5000.
Similarity thresholdsimilarityThresholdfloatConsole 0; API can use the knowledge base defaultRange 0.0 to 1.0. Only applies to vector retrieval and the vector retrieval branch of hybrid; not used for the full-text branch, and it cannot guarantee answer correctness.
Vector weightvectorWeightfloatConsole 0.5; API can use the knowledge base defaultOnly effective under searchMode=hybrid (range 0.0 to 1.0). Controls the vector score proportion; the full-text score proportion is automatically 1 - vectorWeight.
Enable semantic rerankrerankbooleanfalseWhen enabled, uses a rerank model to reorder the coarse retrieval candidate set.
Rerank modelrerankModelstringAuto-selectYou can also explicitly select a model with rerank capability enabled; explicit model or Provider call failures return an error.
Coarse retrieval candidate limitrecallLimitintegerWhen omitted in the API, min(100, max(limit * 4, 20)); the Console initial value is 50Only used when rerank is enabled; explicit values are 1–100 and must not be less than limit. When rerank is enabled, the Console value must be at least limit and at most the API limit of 100.
Allow enhanced retrieval degradationallowDegradedbooleanConsole false / API trueWhen GraphRAG / RAPTOR / Wiki encounters a degradable error, normal results are preserved; check capabilities / degradedCapabilities; it does not control rerank model failures.
Synthesize grounded answeranswerbooleanfalse (can be enabled as needed)Single-library API only: uses indexingDefaults.chatModel and optional chatProviderRef to synthesize an answer based on up to 12 evidence items, capped at 1024 Tokens.
Document anchor tag filterdocumentTagstringOptionalAccepts multiple non-empty comma-separated tags with any-match semantics. Structured values support segment-aligned matching, for example ob_12 matches ob_12_<fileKey>.
Sub-product code filtersubProductIdstringOptionalNon-empty values are limited to 1–64 letters or digits; when passed together with documentTag, the AND (intersection) semantics apply.
Metadata filter conditionsmetadataFilterobjectOptionalFor a single knowledge base, use logic / conditions; for cross-knowledge-base search, key by knowledge base ID, and "*" only serves as the fallback for knowledge bases without dedicated configuration.

In 2.12.0, matching uses underscore-delimited segment prefixes, including free-form tags: finance can match finance_confidential_notes. Trailing empty segments are removed from ___, which can match documents with tags; avoid all-underscore filters. Tag filtering is not an authorization boundary; validate the inputs and returned results.


Feature Entrypoints and Permission Matrix

Console Entry Points, REST API, SDK Methods, and Permission Matrix

Console entrypoint / feature moduleFrontend route pathCorresponding REST API endpointServer SDK method (Node.js / Python)Required RBAC role / API Key scopeCross-module dependency
Single knowledge base interactive retrieval and Q&A debugging/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/searchPOST /v1/knowledgebases/{kbId}/searchcreateSearch() / create_search()Roles: owner, admin, developer, member
Scope: knowledgebases.read
Uses enabled project-level lexicons for synonym and expansion rewriting; direct search ignores stop terms
Semantic reranking (Rerank)"Semantic Rerank (Rerank)" toggle on the retrieval test pagePOST /v1/knowledgebases/{kbId}/search (rerank: true)createSearch() / create_search()Roles: owner, admin, developer, member
Scope: knowledgebases.read
Requires a rerank model available to the project; model and provider depend on its configuration
Grounded answer synthesis (Grounded Answer, answer=true)In this version, access is via API / SDK; Console Search has no such togglePOST /v1/knowledgebases/{kbId}/search (answer: true)createSearch() / create_search()Roles: owner, admin, developer, member
Scope: knowledgebases.read
Requires indexingDefaults.chatModel in the knowledge base settings and a chat model available to the project
Knowledge-graph-enhanced multi-hop retrieval (useKnowledgeGraph=true)"Enable knowledge graph enhancement" toggle on the retrieval test page (shown when enabled at deployment)POST /v1/knowledgebases/{kbId}/search (useKnowledgeGraph: true)createSearch() / create_search()Roles: owner, admin, developer, member
Scope: knowledgebases.read
Depends on GraphRAG being ready in Advanced index build (see knowledge graph exploration)
Federated search across multiple knowledge bases (Multi-KB Search)Server-side API / agent workbench multi-KB mountingPOST /v1/knowledgebases/searchcreateMultiSearch() / create_multi_search()Roles: owner, admin, developer, member
Scope: knowledgebases.read
Supports unified cross-KB reranking, metadataFilter and offset pagination

Feature Details and Operation Guide

One. Debugging hybrid retrieval and semantic reranking in the Console

  1. Go to the Retrieval Test (Search) tab of kb_enterprise_support.

  2. In the retrieval parameters area of the page, the following example values are for initial reference only; validate them against your project data before adjusting parameters:

    • Search mode: select Hybrid(混合检索).

    • Limit (number of results returned): set to 5.

    • Similarity Threshold: set to 0.35.

    • Vector Weight: enter 0.70 (i.e., 70% semantic vector weight + 30% full-text keyword weight).

    • Semantic reranking (Rerank): turn on the toggle, select a rerank model actually available to the project, and in the advanced options set Recall Limit (number of coarse retrieval candidates) to 20. Once a specific model is selected, a failed call returns an error.

  3. In the query input box at the top, enter a typical compound customer service question: OceanBase 向量索引构建报 4013 内存不足时如何排障?如果一线坐席无法解决,工单升级 SOP 是什么?

  4. Click the Search button and review the result list below the parameters area:

    • Retrieved Chunks (result list): lists the top 5 reranked chunk cards in order; each card shows the score, available source information, and a content excerpt; defer to the actual results returned this time.

    • View source (source preview): when a result includes source.documentId, its card shows a View source button. Whether the panel can load the content also depends on the source status and permissions.


Two. Using documentTag and subProductId for precise scope filtering

When the knowledge base contains multiple sub-product lines or multiple types of specification documents, and the business frontend clearly knows which specific sub-product (e.g., subProductId = "ob") or specific manual the user is asking about, you can pass scoping filter conditions with the retrieval request:

Filter values must correspond to actual documents; model, project, and knowledge base names must also be replaced according to the actual configuration.

In this version, Console Search has no documentTag / subProductId input controls. To limit scope, pass these fields via the API / SDK and check the sources in the returned results; when both fields are specified, filtering is by intersection.


Three. Calling single-KB retrieval and multi-KB cross-KB retrieval via the REST API

Business backends can integrate knowledge base retrieval capabilities through the following two standard endpoints:

1. Single knowledge base hybrid retrieval and answer synthesis (POST /v1/knowledgebases/{knowledgeBaseId}/search)

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/search" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI 网关的工具接入与限流是如何工作的?",
    "searchMode": "hybrid",
    "vectorWeight": 0.7,
    "similarityThreshold": 0.35,
    "limit": 5,
    "rerank": true,
    "rerankModel": "qwen3.7-text-rerank",
    "recallLimit": 20,
    "allowDegraded": true,
    "answer": true,
    "subProductId": "aigw"
  }'
)

2. Federated retrieval across multiple knowledge bases (POST /v1/knowledgebases/search)

When an organization has split knowledge bases by department and needs to retrieve across knowledge bases in a single request with unified reranking, call the multi-KB retrieval endpoint (supports metadataFilter and offset pagination). This endpoint does not provide the single-KB enhanced retrieval toggles or answer synthesis. Filter objects are keyed by knowledge base ID; "*" only serves as the fallback for knowledge bases without dedicated configuration, and a specific knowledge base's configuration overrides the fallback rather than merging with it. The example requires the documents to have the corresponding metadata fields extracted:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/search" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseIds": ["kb_enterprise_support"],
    "query": "分布式事务两阶段提交与工单流转规范",
    "searchMode": "hybrid",
    "vectorWeight": 0.65,
    "limit": 10,
    "offset": 0,
    "rerank": true,
    "rerankModel": "qwen3.7-text-rerank",
    "metadataFilter": {
      "*": {"logic": "and", "conditions": [{"name": "category", "comparison": "is", "value": "sop"}]}
    }
  }'
)

Completing a retrieval

  1. In the Query field, enter a specific question, keeping the default Limit (10) and hybrid mode to establish a baseline.

  2. Check the relevance scores, available source information, and content excerpts in the result cards.

  3. When the result includes source.documentId, click View source; the panel reports when the source is unavailable. PDF sources can also be previewed. After confirming that the excerpt genuinely supports the question, decide whether the result is usable. When there is no source entry, go back to Documents to locate the document and check whether the source is still accessible.

  4. When comparing retrieval strategies, change only one option at a time and repeat the same question; with multiple knowledge base versions, first confirm which version is currently selected.

Search results in a test knowledge base

Figure: Default search options retrieve a synthetic Chinese document in a 2.12.0 test knowledge base.

Retrieval scores are for ranking, not answer accuracy. If a high-score result cannot support the question, defer to the source's original text; if the expected source is missing, first go back to Documents to check ingestion status, chunks, and the selected knowledge base version.

Adjustable retrieval options

For how to integrate filtering by document tags, cross-KB retrieval, and answer synthesis, see the knowledge base topics under the site's API / SDK navigation; this version of the Console Search page provides no corresponding controls.

Result troubleshooting

SymptomNext checks
Expected document not foundGo back to Documents to confirm document status and chunks, then check the selected version and similarity threshold
Relevant document hit but excerpt incompleteVerify the original text in the source preview and check the document's parsing and chunk results
High score but content does not support the questionDefer to the source's original text; adjust the Query or retrieval options and compare again; do not interpret scores as answer accuracy

FAQ (Frequently Asked Questions and Troubleshooting)

Q1: When should vectorWeight (vector weight) be raised or lowered?

Q2: Why is no answer produced after enabling answer=true?

First read answer.status, then check the configuration and evidence:

StatusMeaning and handling
not_configuredNot configured indexingDefaults.chatModel; first configure an available Chat model and the chatProviderRef as needed.
no_evidenceModel is configured, but no evidence is available for synthesis; check document ingestion, versions, and filter conditions.
failedModel call failed or returned an empty answer; troubleshoot together with answer.error, model availability, and rate limiting.
succeededText has been generated; you still need to verify whether the sources in results support the answer.

The answer object contains status, text, model, latencyMs, and error. Sources come from the source / locator of the retrieval results; do not assume the answer object has a separate structured reference array. The answer model is taken from indexingDefaults; retrievalDefaults provides retrieval defaults such as vector weight and similarity threshold.

Q3: Why do some paragraphs that clearly contain the keywords not appear in the final Top 5 results?