工具调用

私域知识库搜索 Knowledge Search

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

说明

测试期间调用此工具需要增加 header 'ark-beta-knowledge-search: true'，调用方式请参见快速开始。

核心功能

精准私域检索：仅检索企业已授权私域知识库，保障数据安全性，适用于内部敏感信息查询场景。

灵活参数配置：支持设置搜索结果数量、关键词并行数、结果重排、获取切片中图片等参数，适配不同查询需求（如精准查询需减少结果数量，全面查询需增加关键词并行数）。

注意事项

【重要】计费与 Tokens 说明：一轮搜索可能发起多个关键词并行查询，可通过返回参数usage.tool_usage和usage.tool_usage_details查看具体消耗情况。

Function 命名冲突：若用户自定义 Function 与knowledge_search重名，无需特殊配置，由模型根据问题场景自动判断调用哪个工具。

搜索改写限制：当前暂不支持通过参数设置改写后问题的个数，需通过system prompt或instructions控制（例如要求“每次仅生成 1 个核心搜索关键词”）。

知识库版本限制：仅支持旗舰版知识库，标准版知识库暂不支持。

错误信息：暂不支持caching参数，使用该参数会返回 400 错误信息。

准备工作

说明

方舟平台的新用户？获取 API Key 及开通模型等准备工作，请参见快速入门。

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

1. 完成服务授权

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

方式 1：项目授权（推荐）

方式 2：IAM 授权

当前支持项目维度的快捷授权，为项目授权后，方舟服务即可访问该项目下的所有知识库。

打开控制台的项目授权页面，并为需要授权的项目点击授权。

说明

控制台默认显示default项目。如需为其他项目授权，请先在控制台左下角切换项目。

2. 准备知识库

需提前开通旗舰版知识库（暂不支持标准版知识库），并完成知识库构建与数据上传，操作指南详见创建知识库。

计费说明：私域知识库搜索的收费标准详见知识库计费。

配额限制：知识库使用配额详见知识库配额说明，需确保配额充足以避免调用失败。

快速开始

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

说明

cURL 示例中的关键字段：thinking.type: "disabled" 关闭模型思考，直接调用知识库搜索；tools.limit 控制最多返回的搜索结果数量；tools.ranking_options.get_attachment_link 是否获取图片临时下载链接；max_tool_calls 限制调用知识库搜索的轮次。

cURL

OpenAI SDK

参数说明

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

支持模型列表

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

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

最近更新时间：2026.08.21 11:18:08

这个页面对您有帮助吗？

有用

无用

火山方舟