本文主要介绍如何使用API调用旧版的阿里云百炼RAG检索增强应用。
迁移方案
企业知识库目前已停止维护,我们建议您尽快将您的私有知识迁移至新版知识库(阿里云暂无提供官方的迁移工具或服务)。新版知识库的功能更加丰富,并支持更多文档格式。
企业知识类型 | 迁移方案 |
|---|---|
文档 | 建议您创建非结构化知识库来管理文档类知识。文档导入方式可选择本地上传或从对象存储OSS导入。 若选择本地上传,后续您需要手动更新知识库;若选择从对象存储OSS导入,后续您可以通过整合对象存储OSS、函数计算FC与阿里云百炼的知识库API,实现知识库的自动更新。 本地上传支持通过控制台和API操作;从对象存储OSS导入目前仅支持通过控制台操作。 更多说明,请参见知识库:步骤一导入数据。 |
FAQ | 建议您创建结构化知识库来管理FAQ类知识。您可以通过本地上传文档或基于云数据库RDS构建结构化知识库。 若选择本地上传,后续您需要手动更新知识库;若选择基于云数据库RDS构建,RDS数据表中的数据更新将自动同步至知识库。 目前这两种方式都只能通过控制台进行操作。 更多说明,请参见知识库:步骤一导入数据。 |
SDK使用
前提条件
- 已获取并完成API-KEY配置:您需要获取与配置 API Key并配置API Key到环境变量。
- 已安装SDK:DashScope SDK提供了Python和Java两个版本,安装最新版SDK。
- 已创建RAG检索增强应用(不再支持新建),并上传企业知识:上传企业知识。
- 已获取APP_ID:可在我的应用页面目标应用卡片上查看。
调用示例
标签检索
如果您的企业知识数据量较大,可以采用标签检索的方式提高召回的准确率。
首先,需要参考上传企业知识对文档添加知识标签。
其次,获取到“标签ID”,并通过doc_tag_codes参数传入对应的标签ID,可以同时传入多个标签。
多轮会话
云端托管多轮会话
阿里云百炼应用提供云端托管多轮对话功能,通过session_id进行多轮会话,阿里云百炼云端将自动托管多轮会话,调用侧无需自行维护多轮会话。
下面的例子中,第一次调用后返回session_id,在第二次调用时,可以传入第一次返回的session_id,那么第二次调用模型服务时,将携带第一次调用的会话信息。
调用侧传入多轮会话
调用侧自行维护多轮会话时,可以通过history传入多轮会话信息。
流式输出
流式输出需要添加对应参数。其中,Python SDK中需要添加stream=True,Java SDK中需要使用streamCall接口调用。
业务空间
上述调用示例调用的是默认业务空间的应用,如果需要调用其他业务空间,需要传入指定的业务空间标识。
输入参数
参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
app_id | string | - | 应用标识。 |
prompt | string | - | 用户当前输入的期望模型执行指令,用于指导模型生成回复。 |
session_id | string | - | 对话历史会话唯一标识,传入session_id后,将在云端进行对话历史记录,调用大模型将自动携带存储的对话历史。请确保session_id不重复,并且session_id和history二选一即可。 |
history(可选) | list[dict] | [] | 用户与模型的对话历史,list中的每个元素是形式为{"user":"用户输入","bot":"模型输出"}的一轮对话,多轮对话按时间顺序排列。 |
workspace(可选) | string | - | 业务空间标识。 |
seed(可选) | int | 1234 | 生成时使用的随机数种子,用户控制模型生成内容的随机性。seed支持无符号64位整数,默认值为1234。在使用seed时,模型将尽可能生成相同或相似的结果,但目前不保证每次生成的结果完全相同。 |
top_p(可选) | float | 0.2 | 生成过程中核采样方法的概率阈值,例如,取值为0.2时,仅保留概率加起来大于等于0.2的最可能token的最小集合作为候选集。取值范围为(0,1.0),取值越大,生成的随机性越高;取值越低,生成的确定性越高。 |
top_k(可选) | int | None | 生成时,采样候选集的大小。例如,取值为50时,仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大,生成的随机性越高;取值越小,生成的确定性越高。默认不传递该参数,取值为None或当top_k大于100时,表示不启用top_k策略,此时,仅有top_p策略生效。 |
temperature(可选) | float | 1.0 | 用于控制随机性和多样性的程度。具体来说,temperature值控制了生成文本时对每个候选词的概率分布进行平滑的程度。较高的temperature值会降低概率分布的峰值,使得更多的低概率词被选择,生成结果更加多样化;而较低的temperature值则会增强概率分布的峰值,使得高概率词更容易被选择,生成结果更加确定。 取值范围: [0, 2),不建议取值为0,无意义。 python version >=1.10.1 java version >= 2.5.1 |
stream(可选) | bool | False | 是否使用流式输出。当以stream模式输出结果时,接口返回结果为generator,需要通过迭代获取结果,默认每次输出为当前生成的整个序列,最后一次输出为最终全部生成结果,可以通过参数incremental_output为False改变输出模式为非增量输出。 |
doc_tag_codes(可选) | list[str] | - | 文档标签code列表。传入文档标签code列表后,在检索召回过程中,会从指定的标签code关联的文档中进行检索召回。 |
doc_reference_type | str | - | 返回文档检索后的引用类型,取值为:simple。 传simple则返回的结果中不包含角标信息。 |
has_thoughts | bool | False | 是否输出检索召回处理过程信息。开启后,将返回文档检索召回和模型推理的过程信息。 |
输出参数
返回参数 | 类型 | 说明 | 备注 |
|---|---|---|---|
status_code | int | 200(HTTPStatus.OK)表示请求成功,否则表示请求失败,可以通过code获取错误码,通过message字段获取错误详细信息。 说明 Python才有这个字段,Java失败会抛出异常,异常信息为code,message内容。 | |
request_Id | string | 系统生成的标志本次调用的id。 | |
code | string | 表示请求失败,表示错误码,成功忽略。 python only | |
message | string | 失败,表示失败详细信息,成功忽略。 python only | |
output | dict | 调用结果信息,对于千问模型,包含输出text。 | |
usage | dict | 计量信息,表示本次请求的计量数据。 | |
output.text | string | 模型生成回复。 | |
output.finish_reason | string | 正在生成时为null,生成结束时如果由于停止token导致则为stop。 | |
output.session_id | string | 对话历史会话的唯一标识. | 在多轮会话时,可以使用此标识进行多轮会话保持。 |
usage.models[].model_id | string | 本次应用调用到的模型。 | |
usage.models[].input_tokens | int | 用户输入文本转换成Token后的长度。 | |
usage.models[].output_tokens | int | 模型生成回复转换为Token后的长度。 | |
output.thoughts[].throught | string | 模型的思考结果。 | |
output.thoughts[].action_type | string | 大模型返回的执行步骤类型 api:执行API插件,response:返回最终结果。 | |
output.thoughts[].action_name | string | 执行的action名称,如文档检索、API插件。 | |
output.thoughts[].action | string | 执行的步骤。 | |
output.thoughts[].action_input_stream | string | 入参的流式结果。 | |
output.thoughts[].action_input | string | 插件的输入参数。 | |
output.thoughts[].response | string | 模型调用返回的结果。 | |
output.thoughts[].observation | string | 检索或插件的返回结果。 |
HTTP调用接口
功能描述
应用调用同时支持 HTTP 调用来完成客户的响应,目前提供普通 HTTP 和 HTTP SSE 两种协议,您可根据自己的需求自行选择。
前提条件
- 已开通阿里云百炼服务: 产品开通。
- 已创建API-KEY:获取与配置 API Key。
- 已创建RAG检索增强应用:0代码构建问答应用,并上传企业知识:上传企业知识。
提交接口调用
入参描述
传参方式 | 字段 | 类型 | 必选 | 描述 | 示例值 |
|---|---|---|---|---|---|
Header | Content-Type | String | 是 | 请求类型:application/json | application/json |
Accept | String | 否 | */*,选择text/event-stream则会开启 SSE 响应,默认无设置 | text/event-stream | |
Authorization | String | 是 | API-Key,例如:Bearer d1**2a | Bearer d1**2a | |
X-DashScope-SSE | String | 否 | 跟Accept: text/event-stream 二选一即可启用SSE响应 | enable | |
X-DashScope-WorkSpace | String | 否 | 业务空间标识。 | ws_ik******RVYCKzt | |
Body | input.prompt | String | 是 | 用户当前输入的期望模型执行指令,支持中英文。 | 哪个公园距离我更近 |
input.history | List | 否 | 用户与模型的对话历史,list中的每个元素是形式为{"user":"用户输入","bot":"模型输出"}的一轮对话,多轮对话按时间正序排列。 | "history": [ { "user":"今天天气好吗?", "bot":"今天天气不错,要出去玩玩嘛?" }, { "user":"那你有什么地方推荐?", "bot":"我建议你去公园,春天来了,花朵开了,很美丽。" } ] | |
input.session_id | String | 否 | 对话历史会话唯一标识, 传入session_id后,将在云端进行对话历史进行记录,调用大模型将自动携带存储的对话历史。请确保session_id不重复,并且session_id和history二选一即可。 | ||
input.doc_tag_codes | String | 否 | 文档标签code列表。传入文档标签code列表后,在检索召回过程中,会从指定的标签code关联的文档中进行检索召回。 | ["471d*******3427", "881f*****0c232"] | |
parameters.seed | Integer | 否 | 生成时使用的随机数种子,用户控制模型生成内容的随机性。seed支持无符号64位整数,默认值为1234。在使用seed时,模型将尽可能生成相同或相似的结果,但目前不保证每次生成的结果完全相同。 | 65535 | |
parameters.top_p | Float | 否 | 生成时,核采样方法的概率阈值。例如,取值为0.2时,仅保留累计概率之和大于等于0.2的概率分布中的token,作为随机采样的候选集。取值范围为(0,1.0),取值越大,生成的随机性越高;取值越低,生成的随机性越低。默认值为0.2。注意,取值不要大于等于1。 | 0.2 | |
parameters.top_k | Integer | 否 | 生成时,采样候选集的大小。例如,取值为50时,仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大,生成的随机性越高;取值越小,生成的确定性越高。注意:如果top_k参数为空或者top_k的值大于100,表示不启用top_k策略,此时仅有top_p策略生效,默认是空。 | 50 | |
parameters.temperature | Float | 否 | 用于控制随机性和多样性的程度。具体来说,temperature值控制了生成文本时对每个候选词的概率分布进行平滑的程度。较高的temperature值会降低概率分布的峰值,使得更多的低概率词被选择,生成结果更加多样化;而较低的temperature值则会增强概率分布的峰值,使得高概率词更容易被选择,生成结果更加确定。 取值范围:[0, 2),系统默认值为1.0。不建议将值为0,因为这没有意义。 | 1.0 | |
parameters.has_thoughts | Bool | 否 | 是否输出检索召回处理过程信息。开启后,将返回文档检索召回和模型推理的过程信息。 |
出参描述
字段 | 类型 | 描述 | 示例值 |
|---|---|---|---|
status_code | int | 200(HTTPStatus.OK)表示请求成功,否则表示请求失败,可以通过code获取错误码,通过message字段获取错误详细信息。 说明 Python才有这个字段,Java失败会抛出异常,异常信息为code,message内容。 | 200 |
request_Id | string | 系统生成的标识本次调用的id。 | 33dcf25a-******-8b711f15614e |
code | string | 表示请求失败,表示错误码,成功忽略。 | |
message | string | 失败,表示失败详细信息,成功忽略。 | |
output.text | string | 模型生成回复。 | |
output.finish_reason | string | 正在生成时为null,生成结束时如果由于停止token导致则为stop。 | |
output.session_id | string | 对话历史会话的唯一标识。 | 在多轮会话时,可以使用此标识进行多轮会话保持。 |
usage.models[].model_id | string | 本次应用调用到的模型。 | |
usage.models[].input_tokens | int | 用户输入文本转换成Token后的长度。 | |
usage.models[].output_tokens | int | 模型生成回复转换为Token后的长度。 | |
output.thoughts[].throught | string | 模型的思考结果。 | |
output.thoughts[].action_type | string | 大模型返回的执行步骤类型 api:执行API插件,response:返回最终结果。 | |
output.thoughts[].action_name | string | 执行的action名称,如文档检索、API插件。 | |
output.thoughts[].action | string | 执行的步骤。 | |
output.thoughts[].action_input_stream | string | 入参的流式结果。 | |
output.thoughts[].action_input | string | 插件的输入参数。 | |
output.thoughts[].response | string | 模型调用返回的结果。 | |
output.thoughts[].observation | string | 检索或插件的返回结果。 |