插件和流程编排应用_大模型服务平台百炼(Model Studio)-阿里云帮助中心

重要

历史文档仅适用于百炼1.0版本的API和SDK调用，鉴于旧版功能已停止迭代更新，强烈建议您升级至最新版API和SDK，具体详情请参考新版本升级说明。

功能描述

本文主要介绍如何使用API调用阿里云百炼的插件和流程编排应用，包括从应用广场中创建的插件应用（如插件调用、插件调度应用、检索&插件调度增强）、流程编排中创建的应用和自然语言转SQL应用。

说明

首先，请参考文档AccessKey、AppID及AgentKey获取方式获取AK/SK、Agent Key和AppId。如果是RAM账号，请参考文档RAM子账号使用方式和授权操作进行授权操作。

其次，调用API需要获取到临时Token，请参照创建Token。

API详情

请求地址： https://bailian.aliyuncs.com/v2/app/completions

请求方式：POST

请求数据格式：JSON

请求参数

参数名	参数类型	是否必填	说明	示例值
请求头
Content-Type	string	是	请求类型	application/json; charset=utf-8
Accept	string	否	流式响应时，需要携带此请求头，非流式响应不需要携带。	text/event-stream
Authorization	string	是	API临时Token。	Bearer cc*******m3
请求Body
RequestId	string	是	请求唯一标识，请确保RequestId不重复。	30**********869
SessionId	string	否	对话历史的会话唯一标识, 传入sessionId后，将在云端进行对话历史进行记录，调用大模型将自动携带存储的对话历史。请确保SessionId不重复，并且SessionId和History二选一即可。	40**********213
AppId	string	是	阿里云百炼应用唯一标识。	ea*****541
Stream	boolean	否	是否流式输出, 默认为否。	false
Prompt	string	否	提示词	中国封建王朝经历多少年？
History		否	对话历史。SessionId和History二选一即可，如果同时传入SessionId和History，则只有History会生效。	[{"User": "太阳是恒星吗？", "Bot": "是的"}]
History[x].User	string	是	对话历史的用户消息。	太阳是恒星吗？
History[x].Bot	string	是	对话历史大的模型消息。	是的
TopP	float	否	生成时，核采样方法的概率阈值。例如，取值为0.8时，仅保留累计概率之和大于等于0.8的概率分布中的token，作为随机采样的候选集。取值范围为（0,1.0)，取值越大，生成的随机性越高；取值越低，生成的随机性越低。默认值为0.8。注意，取值不要大于等于1	0.8
Parameters	Parameter	否	模型参数设置。
Parameters.TopK	int	否	生成时，采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。注意：如果top_k参数为空或者top_k的值大于100，表示不启用top_k策略，此时仅有top_p策略生效，默认是空。	50
Parameters.Seed	int	否	生成时使用的随机数种子，用户控制模型生成内容的随机性。seed支持无符号64位整数，默认值为1234。在使用seed时，模型将尽可能生成相同或相似的结果，但目前不保证每次生成的结果完全相同。	65535
Parameters.Temperature	float	否	用于控制随机性和多样性的程度。具体来说，temperature值控制了生成文本时对每个候选词的概率分布进行平滑的程度。较高的temperature值会降低概率分布的峰值，使得更多的低概率词被选择，生成结果更加多样化；而较低的temperature值则会增强概率分布的峰值，使得高概率词更容易被选择，生成结果更加确定。取值范围： [0, 2)，系统默认值1.0。不建议取值为0，无意义。	1.0
HasThoughts	boolean	否	是否输出插件或流程编排调用和模型推理过程相关信息。	true或false
BizParams	object	否	业务api使用的参数，可以直接进行透传。当调用侧在调用插件或者流程编排应用时，需要将业务参数传递给业务方的api时，可以使用此参数，比如userId、token等。	{"userId": "123"}

响应参数

字段名	字段类型	说明
公共响应参数
Success	boolean	是否成功（true：成功，false：失败）。
Code	string	错误代码。
Message	string	错误消息。
RequestId	string	请求唯一标识。
Data	object	文本生成结果。
响应数据
ResponseId	string	大模型的responseId。
SessionId	string	对话历史的会话唯一标识。
Text	string	本次模型调用的输出内容。
Usage	list	应用级别的token消耗
Usage[x].InputTokens	int	本次请求输入内容的token数。
Usage[x].OutputTokens	int	本次请求输出内容的token数。
Thoughts	list	插件或流程调用处理和模型推理过程信息。
Thoughts[x].Thought	string	大模型思考结果。
Thoughts[x].ActionType	string	大模型返回的执行步骤类型 api：执行API插件，response：返回最终结果。
Thoughts[x].ActionName	string	执行的action名称，比如文档检索、API插件。
Thoughts[x].Action	string	执行的步骤。
Thoughts[x].ActionInputStream	string	入参的流式结果。
Thoughts[x].ActionInput	string	插件的输入参数。
Thoughts[x].Response	string	大模型返回的结果。
Thoughts[x].Observation	string	检索或插件的返回结果。

示例

请求示例

curl -X "POST" "https://bailian.aliyuncs.com/v2/app/completions" \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer <Token>' \
-H 'Accept-charset: utf-8' \
-d '{
  "RequestId": "<RequestId>",
  "AppId": "<AppId>",
  "Prompt": "今天杭州的天气怎么样",
  "HasThoughts": true,
  "BizParams": {"userId": "123"}
}' --verbose

响应示例

{
  "Success": true,
  "Data": {
    "ResponseId": "3c59d91**********37e98135f",
    "Text": "今天杭州晴转多云。",
    "Thoughts": [],
    "Usage": [
      {
        "InputTokens": 10,
        "OutputTokens": 9,
        "ModelId": "bailian-plugin"
      }
    ]
  },
  "RequestId": "f0a953cc-*************-f32e606985d7"
}

请求示例（流式SSE）

curl -X "POST" "https://bailian.aliyuncs.com/v2/app/completions" \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer <Token>' \
-H 'Accept: text/event-stream' \
-H 'Accept-charset: utf-8' \
-d '{
  "RequestId": "<RequestId>",
  "AppId": "<AppId>",
  "Prompt": "今天杭州的天气怎么样",
  "HasThoughts": true,
  "BizParams": {"userId": "123"}
}' --verbose

响应示例（流式SSE）

data: {
  "Success": true,
  "Data": {
    "ResponseId": "3c59d91**********37e98135f",
    "Text": "今天杭州晴转多云。",
    "Thoughts": [],
    "Usage": [
      {
        "InputTokens": 10,
        "OutputTokens": 9,
        "ModelId": "bailian-plugin"
      }
    ]
  },
  "RequestId": "f0a953cc-*************-f32e606985d7"
}

请求示例（自然语言转SQL）

curl -X "POST" "https://bailian.aliyuncs.com/v2/app/completions" \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer <Token>' \
-H 'Accept-charset: utf-8' \
-d '{
  "RequestId": "<RequestId>",
  "AppId": "<AppId>",
  "Prompt": "浙江近五年GNP总和是多少",
  "BizParams": {
    "sqlInput": {
      "synonym_infos": "国民生产总值: GNP|Gross National Product",
      "schema_infos": [
        {
          "columns": [
            {
              "col_caption": "地区",
              "col_name": "region"
            },
            {
              "col_caption": "年份",
              "col_name": "year"
            },
            {
              "col_caption": "国民生产总值",
              "col_name": "gross_national_product"
            }
          ],
          "table_id": "t_gross_national_product_1",
          "table_desc": "国民生产总值表"
        }
      ]
    }
  }
}' --verbose

响应示例（自然语言转SQL）

{
  "Success": true,
  "Data": {
    "ResponseId": "1b595831****************4733ef5d41",
    "Text": "SELECT SUM(gross_national_product) AS 浙江近五年国民生产总值总和 FROM t_gross_national_product_1 WHERE region = '浙江' AND year >= YEAR(CURDATE()) - 5;",
    "Usage": [
      {
        "InputTokens": 194,
        "OutputTokens": 45,
        "ModelId": "bailian_nl2sql"
      }
    ]
  },
  "RequestId": "f0a953cc-*************-f32e606985d7"
}

说明

在调用自然语言转SQL应用时，您可以在百炼控制台测试窗使用“表模式”来编辑数据库Schema信息，然后点击“Code模式”生成JSON格式数据，然后将内容替换到sqlInput中。测试窗生成的JSON格式的Scahema, 在传递到BizParams时，需要添加一层“sqlInput”的JSON数据结构。