Knowledge Search（私域知识库搜索工具）

私域知识库搜索工具 Knowledge Search 支持通过 Responses API 调用直接获取企业私域知识库中的信息（如内部文档、产品手册、行业资料等），适用于需基于企业专属数据解答问题的场景（如内部培训问答、产品功能咨询、行业方案查询等）。工具通过模型自动判断是否需要调用私域知识库，支持与自定义 Function、MCP 等工具混合使用，当前仅支持旗舰版知识库。

核心功能#

精准私域检索：仅检索企业已授权私域知识库，保障数据安全性，适用于内部敏感信息查询场景。
灵活参数配置：支持设置搜索结果数量、关键词并行数、结果重排、获取切片中图片等参数，适配不同查询需求（如精准查询需减少结果数量，全面查询需增加关键词并行数）。

注意事项#

【重要】计费与 Tokens 说明：一轮搜索可能发起多个关键词并行查询，可通过返回参数usage.tool_usage和usage.tool_usage_details查看具体消耗情况。
Function 命名冲突：若用户自定义 Function 与knowledge_search重名，无需特殊配置，由模型根据问题场景自动判断调用哪个工具。
搜索改写限制：当前暂不支持通过参数设置改写后问题的个数，需通过system prompt或instructions控制（例如要求“每次仅生成 1 个核心搜索关键词”）。
知识库版本限制：仅支持旗舰版知识库，标准版知识库暂不支持。
错误信息：暂不支持caching参数，使用该参数会返回 400 错误信息。

准备工作#

使用 Knowledge Search 私域知识库搜索工具前，必须完成以下准备工作。

1. 完成服务授权#

需先为工具授予访问知识库的权限，支持两种授权方式：

当前支持项目维度的快捷授权，为项目授权后，方舟服务即可访问该项目下的所有知识库。
打开控制台的项目授权页面，并为需要授权的项目点击授权。

打开新建自定义策略页面，输入策略名称，并点击 JSON 编辑器标签页。

将以下代码中的<YourAccountID>替换为您的真实账号 ID，并将这段代码粘贴至 JSON 编辑器标签页的文本框中。

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "vikingdb:*"
      ],
      "Resource": [
        "trn:ark:*:<YourAccountID>:knowledgebase/*"
      ]
    }
  ]
}

在页面底部点击提交。
打开角色管理页面，新增角色，可以命名为ArkAccessRole_项目名称，并为该角色授予上一步创建的自定义策略。

2. 准备知识库#

需提前开通旗舰版知识库（暂不支持标准版知识库），并完成知识库构建与数据上传，操作指南详见创建知识库。
计费说明：私域知识库搜索的收费标准详见知识库计费。
配额限制：知识库使用配额详见知识库配额说明，需确保配额充足以避免调用失败。

快速开始#

以下示例代码中，均需将<ARK_API_KEY>替换为实际 API Key，将<knowledge_resource_id>替换为授权的知识库 ID。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ARK_API_KEY>' \
--header 'ark-beta-knowledge-search: true' \
--data '{
    "model": "doubao-seed-2-1-pro-260915",
    "stream": true,
    "thinking": {
        "type": "disabled"
    },
    "tools": [
        {
            "type": "knowledge_search",
            "knowledge_resource_id": "<knowledge_resource_id>",
            "limit": 2,
            "ranking_options": {
                "get_attachment_link": true
            }
        }
    ],
    "input": [
        {
            "role": "user",
            "content": "机票选择页面中，如何选择该航班不同价格的机票？"
        }
    ],
    "max_tool_calls": 1
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42import os
from openai import OpenAI

# 从环境变量获取API密钥，配置方法见：https://ark.volcengine.com/region:cn-beijing/docs/quick-start
api_key = os.getenv('ARK_API_KEY')

# 初始化客户端
client = OpenAI(
    base_url='https://ark.cn-beijing.volces.com/api/v3',
    api_key=api_key,
    default_headers={"ark-beta-knowledge-search": "true"}  # 启用私域知识库搜索
)

# 发起知识库搜索请求
response = client.responses.create(
    model="doubao-seed-2-1-pro-260915",  # 替换为支持的模型
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "应用实验室里有类似实时视频理解的agent demo么？"  # 用户问题
                }
            ]
        }
    ],
    tools=[
        {
            "type": "knowledge_search",
            "knowledge_resource_id": "<knowledge_resource_id>",  # 替换为实际知识库ID
            "limit": 10,  # 最多返回10条搜索结果
        }
    ],
    stream=True,  # 启用流式响应，实时获取结果
    extra_body={"thinking": {"type": "auto"}}  # 模型自动判断是否需要搜索
)

# 处理流式响应
for chunk in response:
    if hasattr(chunk, 'delta'):
        print(chunk.delta, end="", flush=True)

参数说明#

详情请参见创建 Responses 模型请求。

支持模型列表#

Knowledge Search 工具支持的模型请参考私域知识库搜索工具。

附录：搜索模式系统提示词样例#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20# 定义系统提示词
system_prompt = """
你是豆包个人助手，负责解答用户的各种问题。你的主要职责是：
1. **信息准确性守护者**：确保提供的信息准确无误。
2. **搜索成本优化师**：在信息准确性和搜索成本之间找到最佳平衡。
# 任务说明
## 1. 知识库意图判断
当用户提出的问题涉及以下情况时，需使用 `knowledge_search` 进行私域知识搜索：
- **企业知识**：问题有关于火山方舟、大模型、responses API
## 2. 知识库搜索后回答
- 在回答中，优先使用已搜索到的资料。
- 回复结构应清晰，使用序号、分段等方式帮助用户理解。
## 3. 引用已搜索资料
- 当使用知识库搜索的资料时，在正文中明确引用来源，引用格式为：
`[1]  (URL地址)`。
## 4. 总结与参考资料
- 在回复的最后，列出所有已参考的资料。格式为：
1. [资料标题](URL地址1)
2. [资料标题](URL地址2)
"""