byted-viking-search-knowledgebase

Byted Viking Search Knowledgebase

This Skill is used to call the API of the Volcano Engine Viking knowledge base through the APIG gateway:

/api/knowledge/collection/info: View knowledge base details, get collection_name and description。Only used in routing/connection check scenarios, and is not the default entry point for knowledge Q&A.
/api/knowledge/collection/search_knowledge: Semantic retrieval, obtain relevant chunks from the knowledge base according to the query, and return the chunk list, relevance scores, document information, etc.

Version consolidation notes:byted-viking-search-knowledgebase.tar.gz once included the legacy root directory byted-viking-knowledgebase（scripts/search.py、VIKING_KBSVR_*); that directory remains compatible with the old skill in the repository and is not the update target of this skill. Currently, the APIG authentication,DATABASE_VIKING_* configuration, and scripts/viking_search.py。

Input prerequisites (required reading)

What you receive is not the user's original words, butthe task description assigned to you by the superior Agent. Such descriptions usually have the following characteristics, which must be handled during the splitting stage,and must not be stuffed in whole into --query：

Long length (often dozens to hundreds of characters)
Bullet points ("1, ... 2, ... 3, ..." or "first ... then ... finally ...")
Multiple sub-intents stacked together (the same passage contains multiple independent retrieval targets such as "reason + steps + process + case")
Contains a large number of transitional words, modifiers, and contextual setup

Directly using the original task text as the query will inevitably cause recall mismatch(the vector is diluted by multiple semantics, and all scores are low). The correct approach is: split first, then retrieve in parallel.

Default strategy (most important)

For "answer questions based on the knowledge base" type requirements, by default use auto multi-knowledge-base parallel retrieval, and the query must undergo [splitting + keywordization] processing. Do not use the two-step route of info → reasoning → search without sufficient reason.

Only deviate from the default strategy in the following few scenarios:

Scenario	Choice
Knowledge Q&A (the vast majority)	`auto`, split multiple independent queries for parallel retrieval according to the "Query construction rules"
The task has already specified a concrete `resource_id` or `name`	`search`
When the number of knowledge bases in the configuration is ≤ 2 and the task is routing decision-making	Optional `info` as assistance
The task intent is "connection check" / "see whether this base is connected" / "call this knowledge base" / "list which bases I have"	`info`
The task description has no topic keywords at all (such as "help me look up something")	First `info` list, then report back to the superior Agent and request clarification

Rule of thumb: when you are unsure which action to take,choose autoby default. It is itself designed for "unknown target + concrete semantics".

Query construction rules (splitting + keywordization + parallelization)

search / auto of --query is the semantic retrieval vector entry point. When facing a long task description from a superior Agent, three steps must be carried out:

Step 1: Split sub-intents

Read the task description sentence by sentence and identify the independent retrieval targets within it. Each bullet point, and each parallel item connected by "and/with/as well as/at the same time," is usually an independent sub-intent.

Example: Parent task = "Troubleshoot the network connection failure issue, need: 1. classification of common fault causes; 2. corresponding troubleshooting and resolution steps; 3. standardized handling process from easy to difficult" → Identify 3 sub-intents: ① fault cause classification ② troubleshooting and resolution steps ③ standardized handling process

Step 2: Compress each sub-intent into a keyword query

For each sub-intent, distill it into a short query composed of 2~5 core keywords , removing connectives, modifiers, and filler phrases.

Form requirements：

Length: keep each query within 5~15 Chinese characters / 10~30 English words
Mainly composed of noun keywords, a small number of verbs is allowed,avoid complete sentence patterns and interrogative tone
Preserve proper nouns, terminology, product names, and error codes as-is

Example(continuing from above):

query₁ = "network connection failure fault cause classification"
query₂ = "network fault troubleshooting steps resolution methods"
query₃ = "network fault standardized handling process"

Step 3: Parallel retrieval (key constraint)

Call the multiple split queries independently and separately auto，Concatenating them into one long query is prohibited. Multiple calls should be initiated in parallel within the same round.

Multiple queries must satisfy：

Constraint	Description	Counterexample
Mutually independent	Each query expresses one complete, retrievable sub-intent	"fault cause" (too vague, must carry the topic word "network fault cause")
No overlap	The intersection between keyword sets should be as small as possible; do not let multiple queries retrieve the same slice	query₁="network fault cause classification", query₂="network fault cause type" ← overlap too high
High discriminability	Each query should be able to hit different slice groups in the knowledge base	All three queries contain "network fault steps" ← low discriminability
Moderate quantity	Usually 2~4 queries; more than 5 means the sub-intents are split too finely and need to be merged	—

Hard prohibition list

❌ Stuff the entire original task text (including "1, 2, 3," bullet points or "first… then…") into --query
❌ Concatenate multiple sub-intents into one long query with enumeration commas/commas (e.g. "cause classification, troubleshooting steps, handling process" — this is the root cause of R2 failure)
❌ Use a complete question sentence as the query (e.g. "How should a network connection failure be troubleshot and handled?" — interrogative sentence patterns introduce a large amount of irrelevant vector noise)
❌ Serial retrieval (finish one query before the next); multiple independent queries should be initiated in parallel within the same round

Correct handling when recall is insufficient (avoid ineffective retries)

If the top slices from one retrieval are clearly unrelated to the intent,do not simply enlarge --limit and rerun the same query——top10 is already the top 10 ranked by relevance; raising the limit to 20/30 will only retrieve even less relevant chunks and will not improve the answer.

The correct approach, in order of priority:

Rewrite the keyword combination: replace synonymous keywords, adjust word order, add or remove one core noun, and retry once.
Split further: if a query still carries too much semantics, follow the "Query construction rules" to split out 2 narrower sub-queries and retrieve them in parallel.
Merge overly narrow queries: if multiple queries all return empty, it may be split too finely; try merging adjacent sub-intents (still keeping the keyword form).
Switch knowledge base: if the matched knowledge base does not match the topic, switch to resource_id and re- search, or go back to auto to let multiple knowledge bases compete.
Report truthfully to the superior: after all of the above fail, report to the superior Agent that "no content related to {sub-intent} was retrieved in the current knowledge base,"do notcontinue blindly increasing the limit or fabricating sources.

Only when a single recall is clearly truncated (top-N are all highly relevant and scores are all high) should you consider increasing --limit。

info interface usage rules (anti-hallucination)

info is used to view knowledge base metadata,not an entry point for knowledge Q&A. Before calling, the following must be satisfied:

✅ There is a reliable resource_id, and that ID is in the DATABASE_VIKING_COLLECTION list (from configuration or explicitly specified by the superior and belonging to that list),or
✅ There is a reliable name(from configuration / the user's exact words, and confirmed to be a knowledge base collection name, not a Feishu Wiki name)

Strictly prohibited：

❌ --name "" passing an empty value
❌ Guessing a Chinese name from intuition/context (such as "网络知识库", "网络") as the --name. Viking knowledge base collection_name is generally English/pinyin/ID,does not support Chinese; using a Chinese name will almost certainly fail.
❌ Treating a Feishu Wiki directory name (such as [网络知识库]) as a Viking collection name. Feishu Wiki is a data source synchronized to Viking, and it and Viking collection are two separate naming systems; do not confuse them.
❌ When the task is simply "answer questions based on the knowledge base," first querying info and going in circles. Directly split + auto is sufficient.

When to use info：

User intent	Whether to call info
"Connect this knowledge base" / "See whether the XXX knowledge base is connected"	✅ Yes, perform a connection check
"What knowledge bases do I have" / "List the knowledge bases"	✅ Yes, list metadata
The task description has no topic at all (such as "help me look something up")	✅ Yes, after listing, report to the superior and request clarification
Answer a specific question based on the knowledge base (the vast majority)	❌ No, directly split + `auto`
The number of knowledge bases in the configuration is ≥ 3	❌ No,`auto` 's concurrent filtering is more reliable than info reasoning

Usage

Script:scripts/viking_search.py

info - view knowledge base details

Get the specified knowledge base's collection_name and description, used for connection checks or routing decisions.

# 方式一：通过 resource_id 查询（推荐，唯一标识，不会歧义）
python scripts/viking_search.py --action info --resource-id <collection_resource_id>

# 方式二：通过 name + project 查询（name 必须来自配置或上级 Agent 指定，不要猜）
python scripts/viking_search.py --action info --name "XXX" --project "default"

search - single-database retrieval

Perform semantic retrieval on thealready determinedknowledge base. The query must be a keyword combination processed according to the "Query construction rules".

# 方式一：通过 resource_id（推荐）
python scripts/viking_search.py --action search --resource-id <resource_id> --query "关键词1 关键词2 关键词3" --limit 10

# 方式二：通过 name + project
python scripts/viking_search.py --action search --name "XXX" --project "default" --query "关键词1 关键词2 关键词3"

auto - multi-database parallel retrieval (the default entry point for knowledge Q&A)

Concurrently perform lightweight retrieval on all knowledge bases for which you have permissions,this is the preferred choice for knowledge Q&A。 For tasks containing multiple sub-intents, call automultiple times in parallel, passing a keyword query for one independent sub-intent each time.

export DATABASE_VIKING_COLLECTION="rid1,rid2,rid3"

# 单一子意图
python scripts/viking_search.py --action auto --query "网络故障 原因 分类"

# 多子意图（在同一轮内并行发起，不要拼接进同一个 query）
python scripts/viking_search.py --action auto --query "网络故障 原因 分类"
python scripts/viking_search.py --action auto --query "网络故障 排查步骤 解决方法"
python scripts/viking_search.py --action auto --query "网络故障 标准化处理流程"

Emphasize again: each --query is a keyword combination, not the original task text; multiple sub-intents must be split + parallelized,concatenation is prohibited。

Return Description

info return example

{
  "code": 0,
  "message": "success",
  "data": {
    "resource_id": "rid_xxx",
    "collection_name": "xxx",
    "description": "包含商品信息、订单数据、用户评价等电商相关文档。",
    "project": "default"
  }
}

search return example

{
  "code": 0,
  "message": "success",
  "data": {
    "result_list": [
      {
        "score": 0.892,
        "rerank_score": 0.912,
        "content": "Mac 配置 Python 开发环境的步骤：首先安装 Homebrew，然后通过 brew install pyenv 来管理 Python 版本...",
        "chunk_title": "Python 环境配置",
        "chunk_id": "chunk_101",
        "doc_info": {
          "doc_id": "doc_001",
          "doc_name": "Mac 开发环境配置大全.md",
          "doc_type": "markdown"
        }
      }
    ]
  }
}

auto return example

{
  "mode": "multi",
  "query": "Mac 上怎么配 Python 环境？",
  "collections": [
    {
      "resource_id": "rid1_mac_guide",
      "search": {
        "code": 0,
        "data": {
          "result_list": [
            {
              "score": 0.892,
              "rerank_score": 0.912,
              "content": "Mac 配置 Python 开发环境的步骤：首先安装 Homebrew，然后通过 brew install pyenv...",
              "chunk_title": "Python 环境配置",
              "chunk_id": "chunk_101",
              "doc_info": { "doc_id": "doc_001", "doc_name": "Mac 开发环境配置大全.md", "doc_type": "markdown" }
            }
          ]
        }
      },
      "top_chunks": [
        {
          "score": 0.892,
          "rerank_score": 0.912,
          "content": "Mac 配置 Python 开发环境的步骤：首先安装 Homebrew，然后通过 brew install pyenv...",
          "chunk_title": "Python 环境配置",
          "chunk_id": "chunk_101",
          "doc_id": "doc_001",
          "doc_name": "Mac 开发环境配置大全.md",
          "doc_type": "markdown"
        }
      ]
    },
    {
      "resource_id": "rid2_hr_policy",
      "search": { "code": 0, "data": { "result_list": [] } },
      "top_chunks": []
    }
  ]
}

Configuration

Environment Requirements

Python 3.7+
requests library (used for HTTP requests)

Environment Configuration Instructions

The API addresses and authentication Keys required for this Skill's execution have been pre-configured in the execution environment. The script will automatically read the necessary credentials from environment variables without user intervention,no sensitive configuration should be directly exposed to the user。

Optional Environment Variables

DATABASE_VIKING_PROJECT: the name of the project to which the knowledge base belongs, default default. Used to assist in locating when querying/retrieving by name.
DATABASE_VIKING_COLLECTION: comma-separated knowledge collection resource_id list, as the auto / info / search accessible scope; it is also the only trusted source of valid resource_id / name —do not guess IDs or names not in this list。info / search If a database outside the list is specified, the script will report an error:没有权限访问当前知识库数据源。

Notes

Exception handling: if the script returns an error related to "detected missing environment configuration", you shouldreport back to the superior Agent: the current knowledge base query service is not yet fully configured; it is recommended to prompt the user to contact the administrator to supplement the necessary environment parameters.
Permission control: if info / search returns 没有权限访问当前知识库数据源, it means the requested resource_id or name is not within DATABASE_VIKING_COLLECTION . Do not guess other IDs/names and retry; only use databases in the allowed list, or switch to auto。
Security: properly safeguard API credentials and authentication information; it is strictly prohibited to leak any sensitive environment variables or Keys in the output.
Concurrency：auto mode defaults to concurrency 8, adjustable via --max-workers . When calling in parallel for multiple sub-intents, multiple auto should be initiated within the same round.
Performance：auto mode's lightweight retrieval defaults to limit=5; if the top-N are all highly relevant but truncated, then consider increasing --limit，do not treat increasing limit as a fallback for inaccurate recall。
Feishu Wiki ≠ Viking collection: the customer may have synced Feishu Wiki in Viking, but the Wiki directory name (Chinese) ≠ Viking collection name. When seeing a Feishu Wiki directory name, do not use it as the Viking knowledge base's --name to query.

Resources

scripts/

viking_search.py - Viking knowledge base retrieval script (supports three actions: info / search / auto)

references/

search_knowledge_api.md - Volcano Engine Viking Knowledge Base Search API Documentation (Original API Description)
collection_info_api.md - Volcano Engine Viking Knowledge Base View Knowledge Base Details API Documentation (Original API Description)