Byted Viking Search Knowledgebase

Byted Viking Search Knowledgebase

该 Skill 用于通过 APIG 网关调用火山引擎 Viking 知识库的 API：

• /api/knowledge/collection/info：查看知识库详情，获取 collection_name 和 description。仅在路由/连接检查场景使用，不是知识问答的默认入口。
• /api/knowledge/collection/search_knowledge：语义检索，根据 query 从知识库中获取相关切片，返回切片列表、相关度分数、文档信息等。

---

输入前提（必读）

你接收到的不是用户原话，而是上级 Agent 分配给你的任务描述。这类描述通常具有以下特征，必须在拆分阶段处理掉，不能整段塞进 `--query`：

• 篇幅长（动辄数十到上百字）
• 分点（"1、…2、…3、…" 或 "首先…其次…最后…"）
• 多子意图叠加（同一段话里夹了"原因 + 步骤 + 流程 + 案例"等多个独立检索目标）
• 含大量过渡词、修饰语、上下文铺垫

直接把任务原文当 query 必然召回失配（向量被多个语义稀释，分数全部偏低）。正确做法是：先拆，再并行检索。

---

默认策略（最重要）

对于"基于知识库回答问题"类需求，默认走 `auto` 多库并行检索，且 query 必须经过【拆分 + 关键词化】处理。 不要在没有充分理由的情况下走 info → 推理 → search 的两步路由。

只有在以下少数场景才偏离默认策略：

经验法则：当你不确定走哪个动作时，默认选 `auto`。它本身就是为"未知目标 + 有具体语义"设计的。

---

Query 构造规则（拆分 + 关键词化 + 并行）

search / auto 的 --query 是语义检索向量入口。面对上级 Agent 的长任务描述，必须执行三步处理：

第 1 步：拆分子意图

逐句通读任务描述，识别其中独立的检索目标。每个分点、每个"和/与/以及/同时"连接的并列项，通常都是一个独立子意图。

示例：上级任务 = "排查网络连接失败的问题，需要：1、常见故障原因分类；2、对应的排查解决步骤；3、从易到难的标准化处理流程" → 识别出 3 个子意图：① 故障原因分类 ② 排查解决步骤 ③ 标准化处理流程

第 2 步：每个子意图压缩为关键词 query

对每个子意图，提炼成由 2~5 个核心关键词 构成的短 query，剔除连接词、修饰语、铺垫语。

形态要求：

• 长度：每个 query 控制在 5~15 个汉字 / 10~30 个英文词以内
• 由名词性关键词为主，允许少量动词，避免完整句式和疑问语气
• 保留专有名词、术语、产品名、错误码原文

示例（接上文）：

• query₁ = "网络连接失败 故障原因 分类"
• query₂ = "网络故障 排查步骤 解决方法"
• query₃ = "网络故障 标准化处理流程"

第 3 步：并行检索（关键约束）

将拆出的多个 query 分别独立调用 auto，禁止拼接成一个长 query。多次调用应在同一轮内并行发起。

多个 query 之间必须满足：

硬禁止清单

• ❌ 把任务原文（含"1、2、3、"分点或"首先…其次…"）整段塞进 --query
• ❌ 把多个子意图用顿号/逗号拼成一个长 query（如"原因分类、排查步骤、处理流程"——这是 R2 失败的根本原因）
• ❌ 用完整问句作为 query（如"网络连接失败时应该如何排查和处理？"——疑问句式会引入大量无关向量噪声）
• ❌ 串行检索（一个查完再查下一个）；多个独立 query 应在同一轮并行发起

---

召回不足时的正确处置（避免无效重试）

如果一次检索的 top 切片明显与意图无关，不要简单放大 `--limit` 重跑同一个 query——top10 已经是相关度排序的前 10 名，把 limit 提到 20/30 只会拿到更不相关的切片，不会让答案变好。

正确做法按优先级：

1. 重写关键词组合：替换同义关键词、调整词序、增删一个核心名词，重试一次。 2. 进一步拆分：如果某个 query 仍承载了过多语义，按"Query 构造规则"再拆出 2 个更窄的子 query 并行检索。 3. 合并过窄 query：如果多个 query 都返回空，可能是拆得过细，尝试合并相邻子意图（仍保持关键词形态）。 4. 换知识库：如果命中库与主题不符，换 resource_id 重新 search，或回到 auto 让多库竞争。 5. 如实回报上级：上述都失败后，向上级 Agent 回报"当前知识库内未检索到与 {子意图} 相关的内容"，不要继续盲目放大 limit 或编造来源。

只有当一次召回明显被截断（top-N 都高度相关、分数都很高）时，才考虑加大 --limit。

---

info 接口使用规约（防幻觉）

info 用于查看知识库元数据，不是知识问答的入口。调用前必须满足：

• ✅ 有可靠的 resource_id，且该 ID 在 DATABASE_VIKING_COLLECTION 列表内（来自配置或上级已明确指定且属于该列表），或
• ✅ 有可靠的 name（来自配置 / 用户原话，且确认为知识库 collection name，不是飞书 Wiki 名）

严格禁止：

• ❌ --name "" 传空值
• ❌ 凭直觉/上下文猜一个中文名（如"网络知识库"、"网络"）作为 --name。Viking 知识库的 collection_name 一般是英文/拼音/ID，不支持中文；用中文名几乎必然失败。
• ❌ 把飞书 Wiki 目录名（如 [网络知识库]）当作 Viking collection name。飞书 Wiki 是被同步到 Viking 的数据源，与 Viking collection 是两套命名体系，不要混淆。
• ❌ 在任务只是想"基于知识库回答问题"时，先去查 info 兜圈子。直接拆分 + auto 即可。

何时该用 info：

---

使用方式

脚本：scripts/viking_search.py

info - 查看知识库详情

获取指定知识库的 collection_name 和 description，用于连接检查或路由决策。

# 方式一：通过 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 - 单库检索

对已确定的知识库执行语义检索。query 必须是经过"Query 构造规则"处理的关键词组合。

# 方式一：通过 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 - 多库并行检索（知识问答的默认入口）

对所有有权限的知识库并发执行轻量级检索，这是知识问答的首选。 对于含多个子意图的任务，应分多次并行调用 `auto`，每次传一个独立子意图的关键词 query。

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 "网络故障 标准化处理流程"

再次强调：每个 --query 是关键词组合，不是任务原文；多子意图必须拆分 + 并行，禁止拼接。

---

返回说明

info 返回示例

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

search 返回示例

{
  "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 返回示例

{
  "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

环境要求

• Python 3.7+
• requests 库（用于 HTTP 请求）

环境配置说明

本 Skill 执行所需的 API 地址及鉴权 Key 已在执行环境中预先配置。脚本会自动从环境变量读取必要凭证，无需用户干预，不应直接向用户暴露任何敏感配置。

可选环境变量

• DATABASE_VIKING_PROJECT：知识库所属项目名称，默认 default。用于按名称查询/检索时辅助定位。
• DATABASE_VIKING_COLLECTION：逗号分隔的 knowledge collection resource_id 列表，作为 auto / info / search 的可访问范围；同时也是合法 resource_id / name 的唯一可信来源——不要猜不在此列表里的 ID 或名称。info / search 若指定了列表外的库，脚本会报错：没有权限访问当前知识库数据源。

---

注意事项

• 异常处理：如果脚本返回"检测到环境配置缺失"相关错误，应向上级 Agent 回报：当前知识库查询服务尚未完全配置，建议提示用户联系管理员补充必要的环境参数。
• 权限管控：若 info / search 返回 没有权限访问当前知识库数据源，说明请求的 resource_id 或 name 不在 DATABASE_VIKING_COLLECTION 内。不要猜测其他 ID/名称重试，应仅使用允许列表中的库，或改走 auto。
• 安全：妥善保管 API 凭证及鉴权信息；严禁在输出中泄露任何敏感环境变量或 Key。
• 并发：auto 模式默认并发 8，可通过 --max-workers 调整。多子意图并行调用时，多次 auto 应在同一轮内发起。
• 性能：auto 模式的轻量检索默认 limit=5；如果 top-N 均高度相关但被截断，再考虑调大 --limit，不要把放大 limit 当作召回不准的兜底手段。
• 飞书 Wiki ≠ Viking collection：客户可能在 Viking 中同步了飞书 Wiki，但 Wiki 目录名（中文）≠ Viking collection name。看到飞书 Wiki 目录名时不要把它当作 Viking 知识库的 --name 去查。

---

Resources

scripts/

• viking_search.py - Viking 知识库检索脚本（支持 info / search / auto 三种动作）

references/

• search_knowledge_api.md - 火山引擎 Viking 知识库 搜索 API 文档（原始接口说明）
• collection_info_api.md - 火山引擎 Viking 知识库 查看知识库详情 API 文档（原始接口说明）

---

本节将说明如何查看一个已创建知识库的信息。 <span id="818f2260"></span>

概述

/api/knowledge/collection/info 接口用于查看知识库详情，根据知识库名称返回知识库的描述，以及知识库配置的实验版本详细信息。 <span id="b2088fbc"></span>

前提条件

完成“签名鉴权方式“页面的注册账号、实名认证、AK/SK 密钥获取和签名获取后，可调用 API 接口实现知识库信息查看的功能。 <span id="5ca54010"></span>

请求接口

| | | | \

<span id="4b10073f"></span>

请求参数（旗舰版、标准版通用）

| | | | | | \

<span id="85fbb85b"></span> # <span id="d47c3787"></span>

响应消息

| | | \

data 返回值

| | | | | \

index_list 返回值

| | | | | \

<span id="af723eb1"></span>

状态码说明

| | | | | \

<span id="f61abe0e"></span>

完整示例

<span id="7f13d566"></span>

请求消息

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-knowledgebase.mlp.cn-beijing.volces.com
/api/knowledge/collection/info \
  -d '{
    "name": "test_collection_name",
    "project": ""
}'

<span id="416e041f"></span>

响应消息

执行成功返回：

{
    "code": 0,
    "data": {
        "collection_name": "apiexample",
        "description": "test",
        "create_time": 1724747158,
        "update_time": 1724747158,
        "creator": "xxx",
        "pipeline_list": [
            {
                "pipeline_type": "user_define",
                "pipeline_stat": {
                    "doc_num": 0,
                    "finish_doc_num": 0,
                    "point_num": 0,
                    "success_doc_num": 0
                },
                "index_list": [
                    {
                        "index_type": "hnsw_hybrid",
                        "index_config": {
                            "vector_field": {
                                "field_name": "_sys_auto_content_vector",
                                "field_type": "vector",
                                "dim": 2048
                            },
                            "sparse_vector_field": {
                                "field_name": "_sys_auto_content_sparse_vector",
                                "field_type": "sparse_vector"
                            },
                            "cpu_quota": 1,
                            "distance": "ip",
                            "quant": "int8",
                            "embedding_model": "doubao-embedding-and-m3",
                            "embedding_dimension": 2048,
                            "need_instruction": true,
                            "fields": [
                                {
                                    "field_name": "_sys_auto_id",
                                    "field_type": "string"
                                },
                                {
                                    "field_name": "_sys_auto_doc_id",
                                    "field_type": "string"
                                },
                                {
                                    "field_name": "_sys_auto_chunk_id",
                                    "field_type": "int64"
                                },
                                {
                                    "field_name": "_sys_auto_doc_type",
                                    "field_type": "string"
                                },
                                {
                                    "field_name": "_sys_auto_add_type",
                                    "field_type": "string"
                                }
                            ]
                        },
                        "primary_key": "",
                        "status": -1
                    }
                ],
                "preprocessing_list": [
                    {
                        "chunking_strategy": "default",
                        "chunking_identifier": null,
                        "chunk_length": 2000
                    }
                ],
                "table_config_list": [
                    {
                        "table_type": "row",
                        "table_pos": 1,
                        "start_pos": 2,
                        "table_fields": [
                            {
                                "field_name": "讲解模块",
                                "field_type": "string",
                                "if_embedding": true,
                                "if_filter": false
                            },
                            {
                                "field_name": "子模块",
                                "field_type": "string",
                                "if_embedding": true,
                                "if_filter": false
                            },
                            {
                                "field_name": "问题示例",
                                "field_type": "string",
                                "if_embedding": true,
                                "if_filter": false
                            },
                            {
                                "field_name": "记忆化 ————讲解要点",
                                "field_type": "string",
                                "if_embedding": true,
                                "if_filter": false
                            }
                        ]
                    }
                ],
                "data_type": "structured_data"
            }
        ],
        "resource_id": "kb-be6833502748aaef",
        "project": "default"
    },
    "message": "success",
    "request_id": "02172474937697900000000000000000000ffff0a00501d3f1d67"
}

执行失败返回：

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000003, "message":"invalid request：%s", "request_id": "021695029757920fd001de6666600000000000000000002569b8f"}

---

本节将说明如何基于一个已创建的知识库或某个实验版本进行语义检索

支持通过指定 pipeline_name 参数，来实现仅检索某个实验版本下的切片

<span id="170e6d2a"></span>

概述

/api/knowledge/collection/search_knowledge 接口用于对知识库进行检索和前后处理，当前会默认对原始文本加工后的知识内容进行检索

<span id="b42b015b"></span>

前提条件

• 知识库创建完成、文档导入且处理完成后，即代表可以进行在线检索
• 调用接口前请先完成 签名鉴权与调用示例 页面的注册账号、实名认证、AK/SK 密钥获取和签名获取
• search 和 search_knowledge 接口的区别：search_knowledge 接口是知识库在线链路升级后的最新接口，在原本 search 接口的基础上支持了多轮改写、文档聚合排序等新功能，与 chat_completions 接口联动，可以完成标准的检索生成链路

<span id="00f93c31"></span>

请求接口

| | | | \

<span id="2a020d4e"></span>

请求参数

| | | | | | | \

<span id="5c1b5386"></span>

响应消息

| | | \

data 返回值

| | | | | \

table_chunk_fields 返回值

| | | | \

chunk_attachment 返回值

| | | | \

<span id="7086e767"></span>

状态码说明

| | | | | \

<span id="a39afcd5"></span>

完整示例

<span id="367f68f4"></span>

请求消息

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-knowledgebase.mlp.cn-beijing.volces.com/api/knowledge/collection/search_knowledge \
  -d '{
        "name": "your_collection",
        "query": "test",
        "limit": 2,
        "query_param": {
            "doc_filter": {
                "op": "must",
                "field": "doc_id",
                "conds": ["tos_doc_id_123", "tos_doc_id_456"]
            }
        },
        "dense_weight": 0.5,
        "pre_processing": {
            "need_instruction": True,
            "rewrite": True,
            "messages": [
                {
                    "role": "system",
                    "content": "prompt template"
                },
                {
                    "role": "user",
                    "content": "history content"
                }
                {
                    "role": "assistant",
                    "content": "history content"
                }，
                {
                    "role": "user",
                    "content": "history content"
                },
                ...
           
                {
                    "role": "assistant",
                    "content": "history content"
                }
                
            ],
            "return_token_usage": True
        },
        "post_processing": {
            "rerank_switch": False,
            "rerank_model": "base-multilingual-rerank",
            "rerank_only_chunk": False,
            "retrieve_count": 25,
            "endpoint_id": "ep",
            "chunk_group": False,
            "get_attachment_link": False
        }
    }
  }
}'

<span id="9ff8b1ec"></span>

响应消息

执行成功返回：

HTTP/1.1 200 OK
Content-Length: 209
Content-Type: application/json
 
{
    "code": 0,
    "data": {
        "collection_name": "example",
        "count": 2,
        "rewrite_query": "xxx"，
        "token_usage": {
            "embedding_token_usage": {
                "prompt_tokens": 16,
                "completion_tokens": 0,
                "total_tokens": 16
            },
            "rerank_token_usage": 0
        },
        "result_list": [
            {
                "id": "_sys_auto_gen_doc_id-13411829101044883689-15",
                "content": "content",
                "score": 0.2639991044998169,
                "point_id": "_sys_auto_gen_doc_id-13411829101044883689-15",
                "chunk_title": "title",
                "chunk_id": 15,
                "process_time": 1727333127,
                "doc_info": {
                    "doc_id": "_sys_auto_gen_doc_id-13411829101044883689",
                    "doc_name": "2404.08817v2.pdf",
                    "create_time": 1727333117,
                    "doc_type": "pdf",
                    "doc_meta": "[{\"field_name\":\"doc_id\",\"field_type\":\"string\",\"field_value\":\"_sys_auto_gen_doc_id-13411829101044883689\"}]",
                    "source": "tos_fe",
                    "title": "title"
                },
                "recall_position": 1,
                "chunk_type": "text"
            },
            {
                "id": "_sys_auto_gen_doc_id-13411829101044883689-7",
                "content": "content",
                "score": 0.2583845257759094,
                "point_id": "_sys_auto_gen_doc_id-13411829101044883689-7",
                "chunk_title": "title",
                "chunk_id": 7,
                "process_time": 1727333127,
                "doc_info": {
                    "doc_id": "_sys_auto_gen_doc_id-13411829101044883689",
                    "doc_name": "2404.08817v2.pdf",
                    "create_time": 1727333117,
                    "doc_type": "pdf",
                    "doc_meta": "[{\"field_name\":\"doc_id\",\"field_type\":\"string\",\"field_value\":\"_sys_auto_gen_doc_id-13411829101044883689\"}]",
                    "source": "tos_fe",
                    "title": "title"
                },
                "recall_position": 2,
                "chunk_type": "text"
            }
        ]
    },
    "message": "success",
    "request_id": "02172740884343900000000000000000000ffff0a00406f8a8861"
}

执行失败返回：

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000003, "message":"invalid request：%s", "request_id": "021695029757920fd001de6666600000000000000000002569b8f"}