root/Neo-ZQYY

Fork 0

Files

Neo 6e20987d2f 微信小程序页面迁移校验之前 P5任务处理之前

2026-03-09 01:19:21 +08:00

12 KiB

Raw Permalink Blame History

阿里云百炼 — 应用调用 DashScope API 参考

来源：应用调用-DashScope API 采集日期：2026-02-28

本文介绍 DashScope API 调用阿里云百炼应用（智能体、工作流）的输入与输出参数。

1. 调用方式

HTTP 接口调用
- 请求地址：POST https://dashscope.aliyuncs.com/api/v1/apps/{APP_ID}/completion
- 其中 APP_ID 需替换为您的实际应用 ID。
SDK 调用
- Python/Java SDK：已默认配置正确的 endpoint
- 自定义 endpoint：可通过 base_url 参数配置

2. 前置准备

创建应用：前往应用管理创建百炼应用并获取应用 ID。
获取 API Key：通过密钥管理获取，并配置 API Key 到环境变量。
安装 SDK（可选）：若使用 SDK 调用，请安装相应语言的 DashScope SDK。

3. 请求示例（Python 单轮对话）

import os
from http import HTTPStatus
from dashscope import Application

response = Application.call(
    # 若没有配置环境变量，可用百炼API Key将下行替换为：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='APP_ID',       # 替换为实际的应用 ID
    prompt='你是谁？'
)

if response.status_code != HTTPStatus.OK:
    print(f'request_id={response.request_id}')
    print(f'code={response.status_code}')
    print(f'message={response.message}')
    print(f'请参考文档：https://help.aliyun.com/zh/model-studio/developer-reference/error-code')
else:
    print(response.output.text)

4. 请求体参数（完整）

必选参数

参数	类型	说明
`app_id`	string	应用标识。可在应用管理页面的应用卡片上获取。Java SDK 中为 `appId`。通过 HTTP 调用时，将实际应用 ID 放入 URL 中替换 `APP_ID`。
`prompt`	string	用户的输入指令，用于指导应用生成回复。通过 HTTP 调用时，请将 prompt 放入 `input` 对象中。

可选参数

参数	类型	默认值	说明
`session_id`	string	—	历史对话标识。传入后请求将自动携带云端存储的对话历史。此时必须传递 `prompt`。该 ID 在连续 1 小时内无任何请求后自动失效。
`messages`	array	—	传递给大模型的上下文，按对话顺序排列。使用 `messages` 时无需传递 `prompt` 和 `session_id`。若同时传入 `session_id` 和 `messages`，则优先使用 `messages`。
`workspace`	string	—	业务空间标识。仅调用子业务空间的应用时需传递。HTTP 调用时指定 Header 中的 `X-DashScope-WorkSpace`。
`stream`	boolean	`false`	是否以流式输出方式回复。推荐设置为 `true`，可提升阅读体验并降低超时风险。HTTP 实现流式输出请在 Header 中指定 `X-DashScope-SSE` 为 `enable`。
`incremental_output`	boolean	`false`	流式输出模式下是否开启增量输出。推荐设置为 `true`。`false`：每次输出当前已生成的整个序列；`true`：增量输出，后续内容不包含已输出内容。
`has_thoughts`	boolean	`false`	是否输出插件调用、知识检索的过程，或已开启思考模式的模型思考过程，在 `thoughts` 字段中查看。
`model_id`	string	—	模型名称（仅智能体应用支持）。API 传递的 `model_id` 与控制台配置不同时，以 API 参数值为准。
`memory_id`	string	—	长期记忆体 ID（仅智能体应用支持）。通过 CreateMemory 创建。
`dialog_round`	integer	—	携带的上下文轮数（仅智能体应用支持）。轮数越多，对话相关性越强。API 参数优先于控制台配置。
`enable_thinking`	boolean	`false`	在深度思考模型中切换思考/非思考模式。`true` 时模型先输出思考过程再返回最终答案。要获取思考内容，须同时将 `has_thoughts` 设为 `true`。
`enable_system_time`	boolean	`true`	控制模型是否自动获取当前时间（北京时间）（仅智能体应用支持）。设为 `false` 时需通过自定义变量手动传入时间。
`enable_web_search`	boolean	`false`	模型生成回复时是否使用互联网搜索结果（仅智能体应用支持）。若调用时未设置，以应用内联网搜索开关状态为准。
`image_list`	array	—	图片列表。支持图像 URL 和 Data URL（Base64 编码）。应用内需选择视觉理解模型。
`file_list`	array	—	包含一个或多个文件 URL 的列表（仅智能体应用支持）。

messages 消息类型

消息类型	说明
System Message (`object`, 可选)	系统消息，用于设定大模型的角色、语气、任务目标或约束条件等。一般放在 `messages` 数组的第一位。
User Message (`object`, 必选)	用户消息，用于向模型传递问题、指令或上下文等。
Assistant Message (`object`, 可选)	模型的回复。通常用于在多轮对话中作为上下文回传给模型。

biz_params 参数传递

biz_params 用于应用通过自定义变量、节点或插件传递参数。

工作流应用开始节点的自定义变量直接传递：
```
biz_params = {"city": "杭州"}
```
智能体应用通过以下字段传递：
- user_prompt_params (object, 可选)：自定义提示词变量参数。一个应用内变量名不可重复，上限 10 个。
```
biz_params = {
    "user_prompt_params": {
        "date": "2025年03月03日",
        "city": "杭州"
    }
}
```
- user_defined_params (object, 可选)：自定义插件参数。每个键为插件的 TOOL_ID，值为该插件所需的参数对象。
- user_defined_tokens (object, 可选)：自定义插件的用户级鉴权信息。

rag_options 知识库检索参数（仅智能体应用）

参数	类型	说明
`pipeline_ids`	array (必选)	包含一个或多个知识库 ID 的列表，上限 5 个。
`file_ids`	array (可选)	包含一个或多个非结构化文档 ID 的列表，上限 5 个。须同时传入文档所属的知识库 ID。
`metadata_filter`	object (可选)	非结构化文档的元数据，检索具备该元数据的文档。
`tags`	array (可选)	包含一个或多个非结构化文档标签的列表。
`structured_filter`	object (可选)	结构化文档的列名和值，键值对形式。
`session_file_ids`	array (可选)	包含一个或多个文件 ID 的列表，上限 10 个。文件 ID 必须以 `file_session_` 开头且状态为 `FILE_IS_READY`。

flow_stream_mode 工作流流式输出模式

值	说明
`message_format` (推荐)	在 `message` 字段输出指定节点（流程输出节点或结束节点）的结果。需在控制台开启目标节点的流式输出开关。
`full_thoughts` (默认)	在 `thoughts` 字段输出所有节点的结果。使用此模式时须同时将 `has_thoughts` 设为 `true`。
`agent_format`	在 `text` 字段输出指定节点（大模型节点或结束节点）的结果。请勿在并行节点上使用此模式。

5. 响应对象

响应示例（单轮对话）

{
  "output": {
    "finish_reason": "stop",
    "session_id": "6105c965c31b40958a43dc93c28c7a59",
    "text": "我是通义千问，由阿里云开发的AI助手。我被设计用来回答各种问题、提供信息和与用户进行对话。有什么我可以帮助你的吗？"
  },
  "usage": {
    "models": [
      {
        "output_tokens": 36,
        "model_id": "qwen-plus",
        "input_tokens": 74
      }
    ]
  },
  "request_id": "f97ee37d-0f9c-9b93-b6bf-bd263a232bf9"
}

响应示例（知识库检索，含引用来源）

需在百炼控制台的智能体应用内，单击检索配置，打开"展示回答来源"开关并发布应用。

{
  "text": "根据您的预算，我推荐您考虑百炼 Zephyr Z9...<ref>[1]</ref>。",
  "finish_reason": "stop",
  "session_id": "6c1d47fa5eca46b2ad0668c04ccfbf13",
  "thoughts": null,
  "doc_references": [
    {
      "index_id": "1",
      "title": "百炼手机产品介绍",
      "doc_id": "file_7c0e9abee4f142f386e488c9baa9cf38_10317360",
      "doc_name": "百炼系列手机产品介绍",
      "doc_url": null,
      "text": "【文档名】:百炼系列手机产品介绍\n【标题】:百炼手机产品介绍\n【正文】:...",
      "biz_id": null,
      "images": [],
      "page_number": [0]
    }
  ]
}

异常响应示例

request_id=1d14958f-0498-91a3-9e15-be477971967b, code=401, message=Invalid API-key provided.

响应参数说明

参数	类型	说明
`status_code`	string	返回的状态码。`200` 表示请求成功，否则表示请求失败。Java SDK 不返回该参数，调用失败会抛出异常。
`request_id`	string	本次调用的唯一标识符。
`code`	string	错误码，调用成功时为空值（仅 Python SDK 返回）。
`message`	string	错误详细信息，请求成功则忽略（仅 Python SDK 返回）。

output 对象

字段	类型	说明
`text`	string	模型生成的回复内容。
`finish_reason`	string	完成原因。`stop` 为自然结束，`null` 为强制中断（如达到最大长度限制或手动停止）。
`session_id`	string	当前对话的唯一标识。在后续请求中传入，可携带历史对话记录。
`thoughts`	array	将 `has_thoughts` 设为 `true` 时，可查看插件调用、知识检索的过程，或深度思考模型的思考过程。
`doc_references`	array	检索的召回文档中被模型引用的文档信息。需在控制台打开"展示回答来源"开关。
`workflow_message`	object	包含工作流节点状态和消息的对象（工作流应用）。

usage 对象

字段	类型	说明
`models`	array	本次调用的模型信息。
`models[].model_id`	string	模型名称。
`models[].input_tokens`	integer	输入 Token 数量。
`models[].output_tokens`	integer	输出 Token 数量。

6. HTTP 请求结构

通过 HTTP 直接调用时，请求体结构如下：

{
  "input": {
    "prompt": "你是谁？",
    "session_id": "可选",
    "messages": [],
    "biz_params": {},
    "image_list": [],
    "file_list": [],
    "memory_id": "可选"
  },
  "parameters": {
    "has_thoughts": false,
    "incremental_output": false,
    "rag_options": {},
    "flow_stream_mode": "full_thoughts",
    "model_id": "可选",
    "dialog_round": 3,
    "enable_thinking": false,
    "enable_system_time": true,
    "enable_web_search": false
  }
}

HTTP Header：

Authorization: Bearer {DASHSCOPE_API_KEY}
Content-Type: application/json
X-DashScope-SSE: enable（流式输出时）
X-DashScope-WorkSpace: {workspace_id}（子业务空间时）

7. 错误码

如果调用失败并返回报错信息，请参阅错误信息进行解决。

8. 获取 APP ID 和 Workspace ID

APP ID：访问应用管理界面，在应用列表中找到目标应用，复制应用的 APP ID。
Workspace ID：业务空间的唯一标识。仅在调用子业务空间下的应用时，API 请求中才必须包含 Workspace ID。
- 获取当前业务空间 ID：前往百炼控制台首页，单击左下角设置图标 → 业务空间详情。
- 查询所有业务空间 ID：需超级管理员权限，前往业务空间管理界面查看。

9. SDK 版本要求

功能	Python SDK 最低版本	Java SDK 最低版本
messages 参数	1.20.14	2.17.0
flow_stream_mode	1.24.0	2.21.0
file_list	1.24.7	2.21.13
session_file_ids	1.20.14	2.17.0
model_id	—	2.19.3
enable_thinking	—	2.20.0
enable_system_time	—	2.19.3
enable_web_search	—	2.19.3
dialog_round	—	2.19.3

12 KiB Raw Permalink Blame History Unescape Escape

阿里云百炼 — 应用调用 DashScope API 参考

1. 调用方式

2. 前置准备

3. 请求示例（Python 单轮对话）

4. 请求体参数（完整）

必选参数

可选参数

messages 消息类型

biz_params 参数传递

rag_options 知识库检索参数（仅智能体应用）

flow_stream_mode 工作流流式输出模式

5. 响应对象

响应示例（单轮对话）

响应示例（知识库检索，含引用来源）

异常响应示例

响应参数说明

output 对象

usage 对象

6. HTTP 请求结构

7. 错误码

8. 获取 APP ID 和 Workspace ID

9. SDK 版本要求

12 KiB

Raw Permalink Blame History