FastGPTFastGPT

知识库搜索 API

联合检索一个或多个可读知识库,支持语义、全文与混合召回、重排、查询扩展、集合与标签过滤以及 topk/maxTokens 预算控制。

端点概览

  • HTTP 方法:POST
  • 请求路径:/api/core/dataset/search
  • 所属模块:知识库 / 知识库搜索
  • 鉴权方式:Authorization: Bearer <apiKey>—个人密钥(按归属团队成员资源权限校验)(详见 API 入门:完成首次请求)
  • 在线调试:在云服务 Scalar 调试台打开(自部署实例请将域名替换为 <instance>/apidoc/systemopenapi#tag/%E7%9F%A5%E8%AF%86%E5%BA%93%E6%90%9C%E7%B4%A2/POST/core/dataset/search)

接口说明与注意事项

使用 API Key 或登录态联合检索多个可读知识库。向量召回要求有效 embedding 模型一致;结果按集合权限过滤。result.topk 与 result.maxTokens 二选一;都不传时默认 topk=20,不设置 token 预算。topk 返回排序后的前 1–100 条,不做 token 过滤;maxTokens 按完整数据块 token 预算截断,无业务上限。为兼容同时传入两种预算的请求,HTTP 入口优先保留 topk 并忽略 maxTokens。响应 meta 只包含实际执行信息。

请求参数

Request Body 请求体(application/json)

字段类型必填默认值约束与说明
scopeobject是-搜索范围
scope.datasetIdsstring[]是-目标知识库 ID,最多 100 个;服务端去重,逐个校验读取权限。最少项数:1;最多项数:100
scope.filterobject否-集合与标签筛选,需要服务端提供筛选能力
scope.filter.collectionIdsstring[]否-限制在这些集合或目录内搜索,与其他筛选条件求交集。最少项数:1;最多项数:500
scope.filter.createTimeobject否-集合创建时间范围
scope.filter.createTime.gtestring否-创建时间下界,含边界。正则:^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
scope.filter.createTime.ltestring否-创建时间上界,含边界。正则:^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
scope.filter.tagsobject否-标签条件;and 与 or 两组之间求交集
scope.filter.tags.andobject[]否-全部满足的标签条件。最少项数:1;最多项数:50
scope.filter.tags.orobject[]否-至少满足一项的标签条件。最少项数:1;最多项数:50
queryobject是-搜索内容
query.textstring是-分支:text。查询文本,trim 后最多 10000 字符;与图片至少提供一项。最小长度:1;最大长度:10000
query.imageKeysstring[]否[]分支:text。本团队上传的临时图片对象 key,最多 10 张。最多项数:10
query.imageKeysstring[]是-分支:imageKeys。本团队上传的临时图片对象 key,最多 10 张。最少项数:1;最多项数:10
query.textstring否""分支:imageKeys。查询文本,trim 后最多 10000 字符;与图片至少提供一项。最大长度:10000
retrievalobject否{}召回配置
retrieval.modestring (enum)否"embedding"embedding、fullTextRecall 或 mixedRecall。可选值:embedding , fullTextRecall , mixedRecall
retrieval.embeddingWeightnumber否0.5混合检索中向量结果的融合权重。最小值:0;最大值:1
rerankobject否{"enabled":false}重排配置;关闭时不能传模型或权重
rerank.enabledfalse是-分支:enabled=false。关闭重排。固定值:false
rerank.enabledtrue是-分支:enabled=true。启用重排。固定值:true
rerank.modelIdstring否-分支:enabled=true。模型 ID;省略时使用有权调用的默认模型。最小长度:1
rerank.candidateNuminteger否-分支:enabled=true。重排候选数,范围 10–100;省略时使用默认值 100。最小值:10;最大值:100
rerank.weightnumber否0.5分支:enabled=true。重排结果的融合权重。最小值:0;最大值:1
queryExtensionobject否{"enabled":false}查询扩展配置
queryExtension.enabledfalse是-分支:enabled=false。关闭查询扩展。固定值:false
queryExtension.enabledtrue是-分支:enabled=true。启用查询扩展。固定值:true
queryExtension.modelIdstring否-分支:enabled=true。模型 ID;省略时使用有权调用的默认模型。最小长度:1
queryExtension.backgroundstring否""分支:enabled=true。帮助模型理解查询的背景信息。最大长度:100000
resultobject否{}条数和 token 预算二选一;未指定时默认 topk=20,不设置 token 预算
result.similaritynumber否0沿用检索分数阈值语义;是否生效以 usingSimilarityFilter 为准。最小值:0;最大值:1
result.maxTokensinteger是-分支:maxTokens。结果总 token 预算,无业务上限;保留完整数据块,最后一块可能使预算超出。最小值:1;最大值:9007199254740991
result.topkinteger否20分支:anyOf 分支 2。返回排序后的前 k 条,范围 1–100;未传两种预算时默认 20,不做 token 过滤。最小值:1;最大值:100
usageScenestring (enum)否"search"账单用途:search 显示知识库搜索,searchTest 显示搜索测试;不影响检索和权限。可选值:search , searchTest

请求示例

调用前请将 YOUR_API_KEY 与示例 ID 替换为真实值;私有化部署实例请将基础域名替换为 <instance>/api。

cURL 请求示例

curl --fail-with-body -X POST "https://cloud.fastgpt.cn/api/core/dataset/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "scope": {
    "datasetIds": [
      "507f1f77bcf86cd799439011"
    ]
  },
  "query": {
    "text": "如何创建知识库?"
  }
}'

最小合法 JSON 请求体示例

{
  "scope": {
    "datasetIds": ["507f1f77bcf86cd799439011"]
  },
  "query": {
    "text": "如何创建知识库?"
  }
}

响应结构与示例

除兼容 OpenAI 协议的对话补全或二进制下载接口外,成功响应统一包裹在 { "code": 200, "statusText": "", "message": "", "data": ... } 标准结构中;下方 200 字段表对应 data 载荷结构(若契约未声明具体载荷结构,请以上方状态描述及实际响应为准)。

HTTP 200

命中片段和实际检索配置

Content-Type : application/json

字段类型必填默认值约束与说明
listobject[]是-合并排序后的知识库数据块
list[].qstring是-问题/主文本
list[].astring否-回答/补充文本
list[].imageIdstring否-图片 ID
list[].idstring是-数据 ID。正则:^[0-9a-fA-F]{24}$
list[].datasetIdstring是-数据集 ID。正则:^[0-9a-fA-F]{24}$
list[].collectionIdstring是-集合 ID。正则:^[0-9a-fA-F]{24}$
list[].imagePreivewUrlstring否-图片预览 URL
list[].updateTimestring是-更新时间
list[].sourceNamestring是-来源名称
list[].sourceIdstring否-来源 ID
list[].chunkIndexnumber是-块索引
list[].indexStatusstring (enum)否-索引状态,字段缺失表示已索引的历史数据。可选值:indexing , indexed , error , rebuildIndexPending , rebuildIndexRunning , rebuildIndexFailed , rebuildSynonymPending , rebuildSynonymRunning , rebuildSynonymFailed
list[].indexErrorMsgstring否-索引错误信息
list[].imageDescMapobject否-图片描述映射
list[].scoreobject[]是-评分列表
list[].score[].typestring (enum)是-评分类型。可选值:embedding , fullText , reRank , rrf
list[].score[].valuenumber是-评分值
list[].score[].indexnumber是-索引
list[].metadataobject否-自定义元数据
list[].retrievalRanknumber否-检索排名
list[].synonymMappingsobject否-分块或用户问题中出现的原词到标准词映射
metaobject是--
meta.durationMsnumber是-搜索耗时,毫秒。最小值:0
meta.usingSimilarityFilterboolean是-本次是否实际启用相似度过滤
meta.usingReRankboolean是-本次是否实际执行重排
meta.queryExtensionModelIdstring否-实际执行查询扩展的模型 ID
在 GitHub 上编辑

文件更新时间

本页导航

准备好开始了吗?

让你的企业知识真正被 AI 用起来