知识库检索-知识库问答-API参考-API

接口描述

检索知识库内容，支持丰富的检索策略。

请求方法

POST

接口要求

无

URI

/openapi/v1/index/retrieve

请求参数

请求头header参数

参数	是否必填	参数类型	说明	示例	下级对象
Content-Type	是	String	json格式	application/json
tenantId	是	String	租户ID	562b89493b1a40e1b97ea05e50dd8170
ctyun-eop-request-id	是	String	用户请求 id，由用户构造，用户可以通过 uuid 等方法自行生成唯一字符串，用于日志请求追踪	33dfa732-b27b-464f-b15a-21ed6845afd5
eop-date	是	String	请求时间，由用户构造，形如 yyyymmddTHHMMSSZ。	20211221T163014Z
host	是	String	终端节点域名，固定字段	kqa-global.ctapi.ctyun.cn
Eop-Authorization	是	String	由天翼云官网 accessKey 和 securityKey 经签名后生成，参与签名生成的字段包括天翼云官网 accessKey 、securityKey、平台应用的appkey（非必须），用户请求id（非必须），请求时间，终端节点域名（非必须）以及请求体内容。

请求体Body参数

参数	是否必填	参数类型	说明	示例	下级对象
origin	是	Array[Object]	对话历史内容注意：当前仅支持传入两轮对话上下文	[ { "role": "user", "content": "deepseek什么时候发布的" }, { "role": "assistant", "content": "2025年1月份" }, { "role": "user", "content": "它是由哪家公司研发的？" } ]	Chat对象
searchType	是	String	搜索策略设置，有以下三种取值： - HYBRID_SEARCH：混合检索； - DENSE_SEARCH: 向量检索； - SPARSE_SEARCH：稀疏/关键字检索；注意：当指定某一检索模式后，下方`params`参数中仅该模式对应的配置项会生效，其余模式的参数将被忽略。	"DENSE_SEARCH"
hybridParams	否	Object	混合检索专属配置参数，仅当 searchType 取值为 HYBRID_SEARCH 时生效；若未传入该参数，系统将使用混合检索的默认配置	{ "hybridTopK": 15, "denseWeight": 0.7, "sparseWeight": 0.3 }	HybridParams对象
denseParams	否	Object	向量检索专属配置参数，仅当 searchType 取值为 DENSE_SEARCH 时生效；若未传入该参数，系统将使用向量检索的默认配置	{ "denseSimilarityTopK": 25 }	DenseParams对象
sparseParams	否	Object	稀疏/关键词检索参数，仅当 searchType 取值为 SPARSE_SEARCH 时生效；若未传入该参数，系统将使用稀疏 / 关键字检索的默认配置数	{ "sparseSimilarityTopK":15 }	SparseParams对象
searchScope	是	Array[Object]	指定检索的知识库范围，系统仅在该范围內执行检索操作	[ { "infoBaseId": "302", "fileIds": [ 1107， 1108 ] } ]	SearchScope对象
enableRewrite	是	Boolean	是否开启历史对话补全改写。开启后，系统会基于 origin 中的完整对话历史，将最后一轮用户问题补全为语义完整、可独立检索的查询语句，并使用改写后的 query 执行检索	true
rerankParams	否	Object	检索结果重排等特殊策略的配置参数；若未传入，系统将使用结果重排的默认规则		RerankParams对象

Chat对象

参数	是否必填	参数类型	说明	示例	下级对象
role	是	String	角色	user/assistant/system
content	是	String	内容	你是谁

HybridParams对象

参数	是否必填	参数类型	说明	示例	下级对象
hybridTopK	否	Int	混合检索阶段召回结果的 TopK 数量；当 NeedReRank=false（未开启重排）时，该值即为最终返回给用户的结果数量取值范围：[1,100] 默认值：15	30
denseWeight	否	float	混合检索中，向量检索结果在最终评分计算时的权重占比。取值范围：[0,1] 默认值：0.8 注意：denseWeight和sparseWeight之和必须为1	0.8
sparseWeight	否	float	混合检索中，关键字检索结果在最终评分计算时的权重占比。取值范围：[0,1] 默认值：0.2 注意：denseWeight和sparseWeight之和必须为1	0.2

DenseParams对象

参数

是否必填

参数类型

说明

示例

下级对象

denseSimilarityTopK

否

Int

向量检索阶段召回结果的 TopK 数量；

当 NeedReRank=false（未开启重排）时，该值即为最终返回给用户的结果数量

取值范围：[1, 100]

默认值：30

SparseParams对象

参数

是否必填

参数类型

说明

示例

下级对象

sparseSimilarityTopK

否

Int

关键词检索阶段召回结果的 TopK 数量；

当 NeedReRank=false（未开启重排）时，该值即为最终返回给用户的结果数量

取值范围：[1,100]

默认值：30

SearchScope对象

参数

是否必填

参数类型

说明

示例

下级对象

infobaseId

是

String

知识库ID

600

fileIds

否

Array[Int]

文档ID列表。

fileIds为空时默认检索知识库ID下所有文档

[11,71]

RerankParams对象

参数	是否必填	参数类型	说明	示例	下级对象
enableReranking	是	boolean	是否开启检索结果重排功能，开启后系统将对召回的文本切片执行重排策略	true
rerankMinScore	否	float	重排阶段文本切片的相似度筛选阈值；仅 Rank 模型返回的相似度分数大于等于该值的文本切片会被保留召回；取值范围： [0.01, 1.00] 默认值：0.1	0.5
rerankTopN	否	integer	重排完成后最终返回的文本切片数量（Top N）。取值范围：[1-20] 默认值为：5	30

请求代码示例


Curl -X POST "https://kqa-global.ctapi.ctyun.cn/openapi/v1/index/retrieve"
-H "Content-Type: application/json"
-H "ctyun-eop-request-id:33dfa732-b27b-464f-b15a-21ed6845afd5"
-H "tenantId:XXX"
-H "Eop-Authorization:XXX"
-H "eop-date:20211109T104641Z"
-H "host:kqa-global.ctapi.ctyun.cn"
--data '{
    "origin": [
        {
            "role": "user",
            "content": "deepseek什么时候发布的"
        },
        {
            "role": "assistant",
            "content": "2025年1月份"
        },
        {
            "role": "user",
            "content": "它是由哪家公司研发的？"
        }
    ],
    "searchType": "SPARSE_SEARCH",
    "hybridParams": {
        "hybridTopK": 15,
        "denseWeight": 0.7,
        "sparseWeight": 0.3
    },
    "denseParams": {
        "denseSimilarityTopK": 25
    },
    "sparseParams": {
        "sparseSimilarityTopK": 15
    },
    "searchScope": [
        {
            "infoBaseId": "302",
            "fileIds": [
                1107,
                1108
            ]
        },
        {
            "infoBaseId": "304",
            "fileIds": []
        }
    ],
    "enableRewrite": true,
    "rerankParams": {
        "enableReranking": true,
        "rerankMinScore": 0.5,
        "rerankTopN": 5
    }
}

返回值说明

1.请求成功返回响应参数

参数	参数类型	说明	示例	下级对象
statusCode	String	返回状态，返回200表示成功	200
message	String	返回Success	Success
returnObj	Object	接口返回结果		returnObj表

returnObj表

参数	参数类型	说明	示例	下级对象
matchList	Array[Object]	检索到的匹配文本片段列表		MatchListObject对象
count	Integer	列表长度	3

MatchListObject表

参数	是否必填	参数类型	说明	示例	下级对象
FileID	是	Long	文件id
FileName	是	String	文件名
KnowledgeID	是	Long	知识ID
ChunkID	是	Long	文档片段ID
ChunkText	是	String	文档片段文本
ContentID	是	Long	内容ID
ContentText	是	String	内容文本
SubTitle	是	String	文档摘要
DocTitle	是	String	内容摘要
Score	是	Float	匹配得分
UserName	是	String	用户名
DbName	是	String	知识库名
From	是	String	来源，可以取值（Knowledge/PPT/~~Image/Excel~~）
QAID	否	Long	问答对id
Question	否	String	问题文本
Answer	否	String	答案文本
ScreenShot	是	String	PPT截图
ImageShot	是	String	图片截图
HostLogo	否	String	联网搜索的logo地址
Order	否	Long	顺序
Url	否	String	联网搜索的地址
FileType	是	String	文档类型
FileID	是	Long	文件id
FileName	是	String	文件名
KnowledgeID	是	Long	知识ID

2.请求失败返回响应参数

参数	参数类型	说明	示例	下级对象
statusCode	String	错误码，放置API对应的错误码	40001
message	String	失败信息	缺少鉴权信息
error	String	返回对应的错误码	KQA_40001

返回值示例

1.请求成功返回值示例

 {
    "statusCode": 200,
    "error": null,
    "message": "Success",
    "returnObj": {
        "count": 2,
        "matchList": [
            {
                "FileID": 1108,
                "FileName": "知识库API.docx",
                "KnowledgeID": 461419421572632289,
                "ChunkID": 1,
                "ChunkText": "知识库API.docx...",
                "ContentID": 14,
                "ContentText": "1.请求成功返回值示例...",
                "SubTitle": "三、 API",
                "DocTitle": "知识库API.docx\n天翼云StateCloud",
                "Score": 0.064522564,
                "UserName": "155535",
                "DbName": "302",
                "From": "Knowledge",
                "QAID": null,
                "Question": null,
                "Answer": null,
                "ScreenShot": null,
                "ImageShot": null,
                "HostLogo": null,
                "Order": null,
                "Url": null,
                "FileType": "doc"
            },
            {
                "FileID": 1108,
                "FileName": "知识库API.docx",
                "KnowledgeID": 461419421572632275,
                "ChunkID": 1,
                "ChunkText": "知识库API.docx\n...",
                "ContentID": 7,
                "ContentText": "需要在http_client 的请求头部中加上...",
                "SubTitle": "二、 如何调用API\n3.拿kAk 作为密钥，eop-date 的年月日值作为数据，算出kdate。",
                "DocTitle": "知识库API.docx\n天翼云StateCloud",
                "Score": 0.014622092,
                "UserName": "155535",
                "DbName": "302",
                "From": "Knowledge",
                "QAID": null,
                "Question": null,
                "Answer": null,
                "ScreenShot": null,
                "ImageShot": null,
                "HostLogo": null,
                "Order": null,
                "Url": null,
                "FileType": "doc"
            }
        ]
    }
}

2.请求失败返回值示例

  {
      "statusCode": "40004",
      "error": "KQA_40004",
      "message": "接口执行异常"
}

状态码

http状态码	描述
200	表示请求成功

错误码说明

错误码	错误信息	错误描述
40004	业务异常	业务异常，详情见message
40005	知识库不存在

息壤智算

应用商城

定价

合作伙伴

开发者

支持与服务

了解天翼云

知识库问答

知识库问答

活动

息壤智算

应用商城

定价

合作伙伴

开发者

支持与服务

了解天翼云

知识库问答

知识库问答