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:
Three retrieval modes (
searchMode) and dynamic weight fusion:Supports
hybrid(default hybrid retrieval),vector(semantic vector retrieval), andfulltext(full-text keyword retrieval).In
hybridmode, the fusion ratio between vector similarity scores and full-text retrieval scores can be dynamically adjusted viavectorWeight(0.0to1.0).
Optional semantic rerank (Rerank) and enhanced retrieval degradation:
The first stage uses coarse retrieval (
recallLimit, defaulting tomin(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
rerankModelorrerankProviderRefis explicitly passed in, upstream exceptions are returned to the caller; automatic rerank with neither specified can fall back to the original ordering and returnreranked: false.allowDegradedindependently controls degradable errors in GraphRAG / RAPTOR / Wiki enhanced retrieval; single-library responses report status viacapabilitiesanddegradedCapabilities.
Grounded answer synthesis (
answer=true) and citation evidence tracing:When
answer=trueis enabled, the system automatically calls the knowledge base's configured Chat model (such asqwen-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).
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'smetadataFilter.
Core Concepts and Architecture
Multi-path hybrid retrieval, rerank, and answer synthesis pipeline
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 name | Field identifier | Type | Default value | Value range and behavior |
|---|---|---|---|---|
| Query text | query | string | Required | Natural-language question or combination of keywords entered by the user. |
| Retrieval mode | searchMode | string | hybrid | Options: hybrid (vector + full-text hybrid), vector (pure vector retrieval), fulltext (pure full-text retrieval). |
| Number of returned results | limit | integer | Console 10 / API 10 | Number of items finally returned, range 1 to 100. |
| Pagination offset | offset | integer | 0 | Cross-library retrieval range 0–5000. |
| Similarity threshold | similarityThreshold | float | Console 0; API can use the knowledge base default | Range 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 weight | vectorWeight | float | Console 0.5; API can use the knowledge base default | Only 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 rerank | rerank | boolean | false | When enabled, uses a rerank model to reorder the coarse retrieval candidate set. |
| Rerank model | rerankModel | string | Auto-select | You can also explicitly select a model with rerank capability enabled; explicit model or Provider call failures return an error. |
| Coarse retrieval candidate limit | recallLimit | integer | When omitted in the API, min(100, max(limit * 4, 20)); the Console initial value is 50 | Only 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 degradation | allowDegraded | boolean | Console false / API true | When GraphRAG / RAPTOR / Wiki encounters a degradable error, normal results are preserved; check capabilities / degradedCapabilities; it does not control rerank model failures. |
| Synthesize grounded answer | answer | boolean | false (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 filter | documentTag | string | Optional | Accepts 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 filter | subProductId | string | Optional | Non-empty values are limited to 1–64 letters or digits; when passed together with documentTag, the AND (intersection) semantics apply. |
| Metadata filter conditions | metadataFilter | object | Optional | For 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 module | Frontend route path | Corresponding REST API endpoint | Server SDK method (Node.js / Python) | Required RBAC role / API Key scope | Cross-module dependency |
|---|---|---|---|---|---|
| Single knowledge base interactive retrieval and Q&A debugging | /console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/search | POST /v1/knowledgebases/{kbId}/search | createSearch() / create_search() | Roles: owner, admin, developer, memberScope: 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 page | POST /v1/knowledgebases/{kbId}/search (rerank: true) | createSearch() / create_search() | Roles: owner, admin, developer, memberScope: 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 toggle | POST /v1/knowledgebases/{kbId}/search (answer: true) | createSearch() / create_search() | Roles: owner, admin, developer, memberScope: 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, memberScope: 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 mounting | POST /v1/knowledgebases/search | createMultiSearch() / create_multi_search() | Roles: owner, admin, developer, memberScope: 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
Go to the Retrieval Test (Search) tab of
kb_enterprise_support.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.
In the query input box at the top, enter a typical compound customer service question:
OceanBase 向量索引构建报 4013 内存不足时如何排障?如果一线坐席无法解决,工单升级 SOP 是什么?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
In the Query field, enter a specific question, keeping the default Limit (10) and
hybridmode to establish a baseline.Check the relevance scores, available source information, and content excerpts in the result cards.
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.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.
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
Limit: The Console and API both default to 10, with a range of 1–100.
Search mode:
hybrid(default) /vector/fulltext; the Console starts withsimilarityThresholdat 0 andvectorWeightat 0.5. The API can use knowledge base defaults when omitted.Rerank: off by default; when enabled, select an available model in the Console. Its initial recall limit is 50; the submitted value must be 1–100 and at least the result limit. When the API parameter is omitted, the server computes a default.
GraphRAG / Wiki: toggles appear only when the corresponding capability is enabled at deployment; keep them off for first comparisons; before enabling, confirm the corresponding index has been built and is available.
Allow fallback (
allowDegraded): disabled by default on the page; when enabled and an enhanced capability is unavailable, fallback results can be returned. CheckcapabilitiesanddegradedCapabilitiesto determine whether the expected index was used; when disabled, an unavailable enhanced capability may cause the request to fail.
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
| Symptom | Next checks |
|---|---|
| Expected document not found | Go back to Documents to confirm document status and chunks, then check the selected version and similarity threshold |
| Relevant document hit but excerpt incomplete | Verify the original text in the source preview and check the document's parsing and chunk results |
| High score but content does not support the question | Defer 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?
Root cause analysis:
vectorWeightcontrols the weighting ratio between thetext-embedding-v3cosine similarity score and the full-text BM25 keyword match score in hybrid retrieval (searchMode=hybrid). Different business queries vary in sensitivity to literal precision versus semantic generalization.Resolution:
Raising
vectorWeight(e.g.,0.75–0.85): suitable for scenarios where user questions are highly colloquial, phrased in varied ways, and have low literal overlap with the documents' standard terminology (relying ontext-embedding-v3to capture deeper semantic similarity).Lowering
vectorWeight(e.g.,0.30–0.50, increasing full-text retrieval weight): suitable for scenarios where users often type exact error codes (e.g.,-4013), configuration parameter names (e.g.,chunkTokenNum), support ticket numbers (e.g.,TK-20261022-001), or API paths. In this case, combined with the project-level lexicon (lex_enterprise_synonyms), you can achieve excellent exact hit rates.
Q2: Why is no answer produced after enabling answer=true?
First read answer.status, then check the configuration and evidence:
| Status | Meaning and handling |
|---|---|
not_configured | Not configured indexingDefaults.chatModel; first configure an available Chat model and the chatProviderRef as needed. |
no_evidence | Model is configured, but no evidence is available for synthesis; check document ingestion, versions, and filter conditions. |
failed | Model call failed or returned an empty answer; troubleshoot together with answer.error, model availability, and rate limiting. |
succeeded | Text 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?
Root cause analysis: Candidate chunks may have been truncated by an excessively high similarity threshold (
similarityThreshold), failed to reach the Rerank stage because they fell outside the first-stage coarse retrieval (recallLimit) window, or been excluded by thedocumentTag/subProductIdfilter conditions in the request.Resolution: Troubleshoot in the following three steps:
Check whether
similarityThresholdis too high: if the threshold is set too high (e.g.,0.85), the vector retrieval branch may filter out valid candidates; the full-text branch is not filtered by this threshold, so it is recommended to first lower the threshold to0.25–0.40and observe the raw score distribution;Check whether
recallLimitis too small: if Rerank is enabled, only chunks within the first-stage coarse retrieval toprecallLimitget a chance to participate in reranking; it is recommended to keeprecallLimit >= 20;Check whether excluded by
documentTagorsubProductIdfilters: confirm that no mismatched scoping filter conditions remain in the request.
Related Documentation
External data source integration and incremental sync with Yuque
GraphRAG, RAPTOR, and Advanced Knowledge Index Build Governance
Knowledge Graph Visualization Exploration and Community Reports
Knowledge Base Wiki Compilation, Conflict Adjudication, and Memory Export
Knowledge Base Immutable Version Management and Release Rollback
Project-level lexicons and retrieval/knowledge graph/agent collaborative governance
Knowledge Base Settings Hub, Default Policies, and Multimodal Image Understanding (VLM)

