268 lines
12 KiB
Markdown
268 lines
12 KiB
Markdown
# 阿里云百炼 — 应用调用 DashScope API 参考
|
||
|
||
> 来源：[应用调用-DashScope API](https://bailian.console.aliyun.com/cn-beijing/?tab=api#/api/?type=app&url=2846133)
|
||
> 采集日期：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. 前置准备
|
||
|
||
1. 创建应用：前往 [应用管理](https://bailian.console.aliyun.com/?tab=app#/app-center) 创建百炼应用并获取应用 ID。
|
||
2. 获取 API Key：通过 [密钥管理](https://bailian.console.aliyun.com/?tab=app#/api-key) 获取，并 [配置 API Key 到环境变量](https://help.aliyun.com/zh/model-studio/configure-api-key-through-environment-variables)。
|
||
3. 安装 SDK（可选）：若使用 SDK 调用，请安装相应语言的 [DashScope SDK](https://help.aliyun.com/zh/model-studio/install-sdk)。
|
||
|
||
## 3. 请求示例（Python 单轮对话）
|
||
|
||
```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](https://help.aliyun.com/zh/model-studio/api-bailian-2023-12-29-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` 用于应用通过自定义变量、节点或插件传递参数。
|
||
|
||
- 工作流应用开始节点的自定义变量直接传递：
|
||
```python
|
||
biz_params = {"city": "杭州"}
|
||
```
|
||
- 智能体应用通过以下字段传递：
|
||
- `user_prompt_params` (object, 可选)：自定义提示词变量参数。一个应用内变量名不可重复，上限 10 个。
|
||
```python
|
||
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. 响应对象
|
||
|
||
### 响应示例（单轮对话）
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
```
|
||
|
||
### 响应示例（知识库检索，含引用来源）
|
||
|
||
> 需在百炼控制台的智能体应用内，单击检索配置，打开"展示回答来源"开关并发布应用。
|
||
|
||
```json
|
||
{
|
||
"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 直接调用时，请求体结构如下：
|
||
|
||
```json
|
||
{
|
||
"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. 错误码
|
||
|
||
如果调用失败并返回报错信息，请参阅 [错误信息](https://help.aliyun.com/zh/model-studio/error-code) 进行解决。
|
||
|
||
## 8. 获取 APP ID 和 Workspace ID
|
||
|
||
- APP ID：访问 [应用管理](https://bailian.console.aliyun.com/#/app-center) 界面，在应用列表中找到目标应用，复制应用的 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 |
|