调用SearchKnowledge搜索文档 - 智能开放搜索 OpenSearch

获取知识库的内容，进行文本问答查询。

前提条件

获取身份鉴权API Key：调用OpenSearch-LLM智能问答版服务时，需要对调用者身份进行鉴权，具体请参见管理API Key。
获取服务调用地址：调用OpenSearch-LLM智能问答版服务时，需要提供服务的调用地址，具体请参见获取服务调用地址。

接口信息

请求方法

POST

请求协议

HTTP

请求URL

{host}/v3/openapi/apps/{app_group_identity}/actions/knowledge-search

{host}：调用服务的地址，支持通过公网和VPC两种方式调用API服务，可参见获取服务调用地址。
{app_group_identity}：应用名称（需要指定应用名访问，主要针对服务中的应用版本）。需要登录OpenSearch-LLM智能问答版控制台，在实例列表中查看对应实例的应用名称。

请求数据格式

JSON

请求参数

Header参数

参数	类型	是否必填	描述	示例值
Content-Type	string	是	请求的数据格式，目前仅支持JSON格式，固定填写"application/json"。	application/json
Authorization	string	是	请求鉴权的API Key，Bearer开头。	Bearer OS-d1**2a

Body参数

参数	类型	是否必填	描述	示例值
question	map	是	输入的问题。	{ "text":"user question" "type": "TEXT", "session" : "" }
question.text	string	是	用户输入的问题文本内容。	user question
question.session	string	否	多轮对话的会话ID，用于标识多轮对话上下文。取值：不设或者为空，则表示不开启多轮对话。如设置非空的值，则表示开启多轮对话，并且系统会将相同的session的对话进行保留，作为多轮对话的上下文。	1725530408586
question.type	string	否	输入问题的类型，这里指定为文本类型`TEXT`。	TEXT
options	map	否	用来设置额外的请求参数，用户控制召回、模型、prompt等。
options.chat	map	否	用来设置访问大模型相关的参数。
options.chat.disable	boolean	否	是否关闭大模型的访问。 false：访问大模型，对结果进行总结生成，默认为false。 true：不访问大模型。	false
options.chat.stream	boolean	否	是否启用流式返回结果。 true：流式返回，默认为true。 false：非流式返回。	true
options.chat.model	string	否	选择的LLM（大语言模型）。可选：	opensearch-llama2-13b
options.chat.model_generation	integer	否	使用产品定制模型时，需要设置对应的模型版本，默认使用最老的版本进行访问。	20
options.chat.prompt_template	string	否	设置用户自定义的prompt模板名称。默认为空，使用系统内置的prompt模板。	user_defined_prompt_name
options.chat.prompt_config	object	否	用户自定义prompt中配置的键值对，参数格式为： `{ "String_key": "value", "Integer_key" : 1 }`	`{ "attitude": "normal", "rule" : "detailed", "noanswer": "sorry", "language": "Chinese", "role": false, "role_name": "AI小助手", }`
options.chat.prompt_config.attitude	string	否	系统内置模板的参数，用来控制对话内容的语气，默认为normal。 normal：无。 polite：使用和蔼和礼貌的语气。 patience：使用委婉和耐心的语气。	normal
options.chat.prompt_config.rule	string	否	对话内容的详细程度，默认为detailed。 detailed：详细和专业。 stepbystep：详细且按步骤。	detailed
options.chat.prompt_config.noanswer	string	否	无法回答问题时的回复，默认为sorry。 sorry：抱歉，根据已知信息无法回答该问题。 uncertain：我不知道。	sorry
options.chat.prompt_config.language	string	否	回答问题使用的语言，默认为Chinese。 Chinese：中文。 English：英语。 Thai：泰语。 Korean：韩语。	Chinese
options.chat.prompt_config.role	boolean	否	是否开启回答角色。开启后，将定制回答的角色。	false
options.chat.prompt_config.role_name	string	否	定制回答的角色，例如：AI Assistant。	AI Assistant
options.chat.prompt_config.out_format	string	否	输出内容的形式，默认为text。 text：文本。 table：表格。 list：列项。 markdown：markdown。	text
options.chat.generate_config.repetition_penalty	float	否	用于控制模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度，1.0表示不做惩罚。没有严格的取值范围。	1.01
options.chat.generate_config.top_k	integer	否	生成时，采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。默认值为0，表示不启用top_k策略，此时，仅有top_p策略生效。	50
options.chat.generate_config.top_p	float	否	生成过程中核采样方法概率阈值，例如，取值为0.8时，仅保留概率加起来大于等于0.8的最可能token的最小集合作为候选集。取值范围为（0,1.0)，取值越大，生成的随机性越高；取值越低，生成的确定性越高。	0.5
options.chat.generate_config.temperature	float	否	用于控制随机性和多样性的程度。具体来说，temperature值控制了生成文本时对每个候选词的概率分布进行平滑的程度。较高的temperature值会降低概率分布的峰值，使得更多的低概率词被选择，生成结果更加多样化；而较低的temperature值则会增强概率分布的峰值，使得高概率词更容易被选择，生成结果更加确定。取值范围：[0, 2)，不建议取值为0，无意义。 python version >=1.10.1 java version >= 2.5.1	0.7
options.chat.history_max	integer	否	多轮对话历史最大轮数，最大20轮，默认是1。	20
options.chat.link	boolean	否	是否返回链接。控制模型生成的内容是否标识内容引用的来源。取值： true: 内容包含来源。 false: 不包含。默认为false。包含内容的返回信息实例如下： `可以通过在线扩容和离线扩容两种方式扩容ECS云盘容量[^1^]。在线扩容无需重启实例，离线扩容需要重启实例[^1^]。具体操作步骤为：在ECS控制台上选择待扩容的云盘，在操作列选择扩容，然后根据需要选择扩容方式[^1^]。如果需要扩容分区和文件系统，可以通过控制台获取或者通过控制台获取[^2^]。扩容云盘容量后，新容量生效后无法再缩小，建议合理规划存储空间[^3^]。` 其中被`[^`和`^]`包起来的数字表示引用结果中reference里的第几个文档。例如`[^1^]`表示应用reference中的第一个文档。	false
options.chat.agent	map	否	设置RAG工具能力的选项，当开启时，模型会根据已有的内容，输出决定是否要执行对应的工具。目前支持该功能大模型有： qwen-plus qwen-max qwen2-72b-instruct
options.chat.agent.tools	list of string	否	设置使用的RAG工具名字，目前可用的工具： knowledge_search：知识库检索	["knowledge_search"]
options.retrieve	map	否	用来设置额外的请求参数，用户控制召回、模型、prompt等。
options.retrieve.doc	map	否	用来设置控制召回相关的参数。
options.retrieve.doc.disable	boolean	否	是否关闭知识库召回。 false：不关闭，默认为fasle。 true：关闭。	false
options.retrieve.doc.filter	string	否	从知识库中召回筛选条件的数据时，需要明确指定相应的字段及满足的条件。默认为空。filter使用示例可参考：filter参数。支持的字段： table：文档所在表。 raw_pk：文档主键。 category：文档分类。 score：文档分数。 timestamp：文档时间。示例格式： `"filter" : "raw_pk=\"123\"" # 只从id为123的doc中获取数据 "filter" : "category=\"value1\"" # 只从category为value1的doc中获取数据 "filter" : "category=\"value1\" OR category=\"value2\"" #只从category为value1和value2的doc中获取数据 "filter" : "score>1.0" # 只从score大于1.0的doc中获取数据 "filter" : "timestamp>1356969600" # 只从timestamp大于2013-1-1的doc中获取数据`	category=\"value1\"
options.retrieve.doc.sf	float	否	控制向量召回的向量分的阈值。当没有开启稀疏向量时，取值范围为[0, 2.0]，默认值是1.3，该值越小，结果越相关，但结果数会越少；反之，可能会召回不太相关的结果。但开启了稀疏向量时，默认值是0.35。其值越大，召回的结果越相关，结果数会越少；反之，结果可能会不太相关。	1.3
options.retrieve.doc.top_n	integer	否	召回的文档数量，默认为5个，取值范围：(0, 50]。	5
options.retrieve.doc.formula	string	否	指定召回时，文档排序的排序公式。说明语法请参考业务排序函数，其中的算法相关性和地理位置相关性的特征不支持。	-timestamp: 按文档的timestamp字段降序
options.retrieve.doc.rerank_size	integer	否	开启rerank重排功能时，参与重排的文档数。默认值为30，取值范围：(0,100]。	30
options.retrieve.doc.operator	string	否	在知识库召回时，question.text分词后的term的关系。该参数只有在没有启用稀疏向量时生效。 AND：表示所有term都需要出现才能被召回。默认为AND。 OR：表示只要有一个term出现就可以召回。	AND
options.retrieve.doc.dense_weight	float	否	开启稀疏向量后，控制文档召回时，稠密向量的权重。取值范围：(0.0, 1.0)，默认值为0.7。	0.7
options.retrieve.entry	map	否	用来控制从人工干预数据中召回结果的相关参数
options.retrieve.entry.disable	boolean	否	是否关闭人工干预数据的召回。 false：不关闭，默认为false。 true：关闭。	false
options.retrieve.entry.sf	float	否	控制召回人工干预的向量分阈值。取值范围：[0, 2.0]，默认值是0.3，该值越小，结果越相关，但结果数会越少；反之，可能会召回不太相关的结果。	0.3
options.retrieve.image	map	否	用来控制从知识库中召回图片结果的相关参数。
options.retrieve.image.disable	boolean	否	是否需要关闭图片数据的召回，默认为false。 false：不关闭，默认为false。 true：关闭。	false
options.retrieve.image.sf	float	否	控制向量召回的向量分的阈值。当没有开启稀疏向量时，取值范围：[0, 2.0]，默认值为1.0，该值越小，结果越相关，但结果数会越少；反之，可能会召回不太相关的结果。但开启了稀疏向量时，默认值为0.5。其值越大，召回的结果越相关，结果数会越少；反之，结果可能会不太相关。	1.0
options.retrieve.image.dense_weight	float	否	开启稀疏向量后，控制图片召回时，稠密向量的权重。取值范围：(0.0, 1.0)，默认值为0.7。	0.7
options.retrieve.qp	map	否	用户query改写的选项。
options.retrieve.qp.query_extend	boolean	否	是否对用户query进行扩展，扩展query会用来在引擎中召回文档切片。默认为false。默认为false，和原来逻辑保持一致，即表示不进行query扩展。如果设置为true，则会多一次与大模型的交互，所以回复速度会变慢。对耗时敏感的应用请勿开启。	false
options.retrieve.qp.query_extend_num	integer	否	开启相似query扩展时，最多扩展几个query，默认值为5。	5
options.retrieve.rerank	map	否	用户设置文档召回时重排的选项。
options.retrieve.rerank.enable	boolean	否	是否对召回的结果用模型进行相关性的重排。取值： true：用模型对召回结果进行重排。 false：不用模型对召回结果进行重排。当options.retrieve.doc.formula不为空时，默认为false，其他情况默认为true。	true
options.retrieve.rerank.model	string	否	用于重排的大模型名称。 ops-bge-reranker-larger：bge-reranker模型（默认） ops-text-reranker-001：自研的reranker模型	ops-bge-reranker-larger
options.retrieve.return_hits	boolean	否	是否在结果中返回文档召回的结果，即response中的search_hits。	false

请求体示例

{
    "question" : {
        "text" : "user question",
        "session" : "对话的session，设置了之后，会有多轮对话的功能",
        "type" : "TEXT"
    },
    "options": {
        "chat": {
            "disable" : false, # 是否不走chat模型，仅作文档召回，默认为false。
            "stream" : false, # 是否流式返回，默认false。
            "model" : "Qwen", # 选择的LLM模型
            "prompt_template" : "user_defined_prompt_name", # 用户自定的prompt名称
            "prompt_config" : { # 自定义prompt配置，可选
                "key" : "value" # key和value在实际使用时应替换为具体的键值对
            },
            "generate_config" : {
                "repetition_penalty": 1.01,
                "top_k": 50,
                "top_p": 0.5,
                "temperature": 0.7
            },
            "history_max": 20, # 多轮对话历史最大轮数,
            "link": false, # 返回链接,
            "agent":{
                "tools":["knowledge_search"]
            }
        },
        "retrieve": {
            "doc": {
                "disable": false, # 是否需要关闭文档召回，默认false。
                "filter": "category=\"type\"", # 召回时根据category字段做过滤，默认为空
                "sf": 1.3,    # 向量召回阈值，默认1.3；阈值越大，文档可能约不相关
                "top_n": 5,    # 文档召回多少个文档，默认是5个，取值返回(0, 50],
                "formula" : "", #默认为向量相似度
                "rerank_size" : 5,  #精排文档数，默认不用设置，系统自己决定
                "operator":"OR"  # 表示文本召回时，文本token之间的关系是OR，默认是AND
            },
            "entry": {
                "disable": false, # 是否需要关闭人工干预数据的召回，默认false。
                "sf": 0.3 # 干预数据召回的向量相关性，默认0.3
            },
            "image": {
                "disable": false,  # 是否需要关闭图片数据的召回，默认false。
                "sf": 1.0          # 图片数据召回的向量相关性，默认1.0
            },
            "qp": {
                "query_extend": false, # 是否需要对用户query进行query扩展
                "query_extend_num": 5 # 表示扩展query的数量，默认值为5
            },
            "rerank" : {
                "enable": true  # 召回后是否使用大模型进行重排，默认为true,
                "model":"model_name" # 实际使用时应替换为具体的模型名称
            },
            "return_hits": false   # 是否在结果中返回文档召回的结果, 即response里面的search_hits
        }
    }
}

返回参数

参数	类型	描述
request_id	string	请求ID。
status	string	请求的处理状态。 OK：表示请求成功。 FAIL：表示请求失败。
latency	float	请求成功时，服务器处理请求所花费的时间，单位为毫秒。
id	integer	主键ID。
title	string	文档的标题。
category	string	类目名。
url	string	文档链接。
answer	string	问答结果。
type	string	返回结果类型。
scores	array	文档内容分。
code	string	返回的错误码。
message	string	返回的错误信息。

响应体示例

{
  "request_id": "6859E98D-D885-4AEF-B61C-9683A0184744",
  "status": "OK",
  "latency": 6684.410397,
  "result" : {
    "data" : [
      {
        "answer" : "answer text",
        "type" : "TEXT",
        "reference" : [
          {"url" : "http://....","title":"doc title"}
    		]
      },
      {
        "reference": [
          {"id": "16","title": "测试标题","category": "测试类目","url": "测试链接"}
        ],
        "answer": "https://ecmb.bdimg.com/tam-ogel/-xxxx.jpg",
        "type": "IMAGE"
      }
    ],
    "search_hits" : [  // 查询请求中设置了options.retrieve.return_hits才会有
      {
        "fields" : {
          "content" : "...."
          "key1" : "value1"
        },
        "scores" : ["10000.1234"],
        "type" : "doc"
      },
      {
        "fields"{
          "answer" : "...",
          "key1" : "value1"
        },
        "scores" : ["10000.1234"],
        "type" : "entry"
      }
    ]
  }
  "errors" : [
    {
      "code" : "如果有错误，这里填错误码",
      "message" : "如果有错误，这里填错误信息"
    }
  ]
}