Skip to main content

Knowledge Retrieval

The Knowledge Retrieval service supports searching a single knowledge base or performing a multi-knowledge-base federated search to help you find relevant content from your private enterprise knowledge bases. You can create and configure retrieval services in the console or integrate them into your applications using the API.

Create a Retrieval Service

  1. Log on to the console and go to Knowledge Services → Knowledge Retrieval.
  2. Click Create Retrieval Service in the upper-right corner. In the dialog box that appears, enter a Service Name (required, up to 40 characters) and a Description (optional, up to 200 characters), then click Confirm.
  3. After the service is created, you are redirected to its configuration page. Click + Add to associate one or more knowledge bases (up to 15). You can set a weight for each knowledge base. A higher weight prioritizes its results in the final ranking.
  4. Configure global retrieval parameters, such as knowledge base routing and the re-ranking model. For details, see Global Retrieval Configuration below. To configure independent parameters for a specific knowledge base, click the Settings icon to the right of the knowledge base to expand its configuration panel. For details, see Per-Knowledge-Base Configuration below.
  5. Enter a query in the chat window on the right to view the returned chunks, including similarity scores, source documents, and retrieval latency.
  6. After you complete the configuration, click Publish in the upper-right corner. After publishing, you can call the retrieval service through the API.
  • At least one knowledge base must exist, and it must contain successfully parsed documents.
  • For multi-knowledge-base federated retrieval, all knowledge bases must reside in the same workspace.

Global Retrieval Configuration

The following parameters apply uniformly to all associated knowledge bases:
ParameterValid RangeDescription
Knowledge Base RoutingOn/OffWhen enabled, the system automatically determines which knowledge bases to query based on retrieval intent, avoiding the need to search all of them. The routing decision relies on a large model and incurs model invocation fees
Re-ranking Modelqwen3-rerank / qwen3-rerank(hybrid) / qwen3-vl-rerank / No modelWhen enabled, a re-ranking model uniformly sorts results from multiple knowledge bases. When disabled, each knowledge base sorts its results independently. For text-only knowledge bases, select the qwen3-rerank series. For multimodal knowledge bases, select qwen3-vl-rerank
Re-ranking ModeQ&A Mode / Similarity Mode / Custom Advanced ModeQ&A Mode: Ranks chunks by Q&A matching score, prioritizing chunks that are likely to answer the query. Similarity Mode: Ranks chunks by semantic similarity. Custom Advanced Mode: Allows custom intervention in the re-ranking model
Max Recall Count1~20The total number of chunks returned after re-ranking

Per-Knowledge-Base Configuration

Click the expand icon next to a knowledge base to configure its independent retrieval parameters: After expanding the panel, you can configure parameters such as query rewriting, recall TopK, re-ranking model, and similarity threshold for the knowledge base.
ParameterValid RangeDescription
Query RewritingOn/OffRewrites and optimizes the user input to improve retrieval performance
Initial Vector Retrieval TopK1~100The number of chunks initially retrieved in the vector search phase
Initial Keyword Retrieval TopK1~100The number of chunks initially retrieved in the keyword search phase
Re-ranking Modelqwen3-rerank, etc. / No modelIndependently sorts the results retrieved from this knowledge base
Re-ranking ModeQ&A Mode / Similarity ModeQ&A Mode ranks chunks by Q&A matching score. Similarity Mode ranks chunks by semantic similarity. Available only when a re-ranking model is selected
Similarity Threshold0.01~1.0Filters out chunks whose scores fall below the threshold after re-ranking. A higher value yields more precise results but may exclude relevant content
Max Recall Count1~20The number of chunks returned from this knowledge base after re-ranking
Tag Filtering—Filters the retrieval scope based on document tags. Enter a tag and press Enter, or select an existing tag from the drop-down list

Retrieval Workflow

After receiving a query request, the Knowledge Retrieval service returns results in the following steps:
  1. Query Rewriting (optional): Rewrites and optimizes the user input to improve retrieval performance.
  2. Vector + Keyword Retrieval: Retrieves relevant chunks based on semantic similarity and keyword matching.
  3. Re-ranking: Uses a re-ranking model to refine the retrieved results and filter out low-scoring chunks.
  4. Result Return: After re-ranking, the original semantic scores are weighted, and the chunks are returned in descending order of weighted score.

API Invocation

Call the service through the Knowledge Retrieval API: 
curl -X POST https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index_id": "<knowledge-base-id>",
    "query": "How do I configure chunking strategies?",
    "top_k": 5
  }'
The returned nodes array contains the matched chunks, including the original content, relevance scores, and source metadata.
You can also call this low-level API through the Alibaba Cloud Bailian CLI: bl knowledge retrieve --index-id <knowledge-base-id> --query "How do I configure chunking strategies?" --top-k 5 (deprecated; use bl knowledge search --agent-id with a published retrieval service instead). For more information, see Use the CLI.
This is the low-level retrieval API for a single knowledge base. It directly returns vector and keyword retrieval results without re-ranking. To enable re-ranking, configure a re-ranking model when you create the retrieval service (see Global Retrieval Configuration above) and call the service through its API.
Agent Development
Agent Context
Agent Governance & Evolution
Store
Application Marketplace
Use Cases
Support