Skip to main content
应用调用

调用智能体应用

可通过 DashScope SDK(阿里云模型服务的统一API)或 HTTP 请求方式,将阿里云百炼的智能体应用集成至业务系统。

前提条件

在开始之前,请完成以下三个步骤以配置您的开发环境。
  1. 获取凭证
  2. 安装DashScope SDK
    HTTP接口调用跳过此步骤。
    请根据您使用的编程语言选择并执行相应的安装命令。
    • Python
    • Java
    运行以下命令安装或升级DashScope Python SDK:
    # 使用此命令,将SDK安装到您的Python 3环境中
    python3 -m pip install -U dashscope
    
  3. 配置环境变量(推荐) 为保障密钥安全并避免在代码中硬编码,建议配置 API Key 到环境变量。SDK将自动从此变量读取。

快速开始

  • Python
  • Java
  • HTTP
请求示例
import os
from http import HTTPStatus
from dashscope import Application
response = Application.call(
    # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
    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)
响应示例
我是阿里云开发的一款超大规模语言模型,我叫千问。我被设计用来帮助用户生成各种类型的文本,如文章、故事、诗歌、故事等,并能根据不同的场景和需求进行调整和优化。此外,我还能够回答各种问题,提供信息和解释,辅助学习和研究。如果您有任何需要,欢迎随时向我提问!

核心功能

多轮对话

相比于单轮对话,多轮对话可以让大模型参考历史对话信息,更符合日常交流的场景。
云端存储自行管理
通过传入 session_id,系统会自动从云端加载存储的对话历史,并结合新的指令生成上下文。需要维护一个 messages 数组,手动记录和传递每一轮的对话历史及新指令。
必传参数
  • session_id:会话ID。
  • prompt:提示词。
必传参数:messages 数组可选参数:prompt(可选)
  • 若传入promptprompt 会被转换为一条 {"role": "user", "content": "prompt"},自动追加到 messages 末尾,生成最终上下文。
  • 示例:
// 原始传入
{
  "messages": [{"role": "user", "content": "你好"}],
  "prompt": "推荐一部电影"
}
// 实际生效的messages
[
  {"role": "user", "content": "你好"},
  {"role": "user", "content": "推荐一部电影"}
]
优先级规则:若同时传入 session_id 和 messages,则优先使用 messages,忽略 session_id
  • 云端存储
  • 自行管理
  • Python
  • Java
  • HTTP
请求示例
import os
from http import HTTPStatus
from dashscope import Application
def call_with_session():
    response = Application.call(
        # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='YOUR_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')
        return response

    responseNext = Application.call(
                # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
                api_key=os.getenv("DASHSCOPE_API_KEY"),
                app_id='YOUR_APP_ID',  # 替换为实际的应用 ID
                prompt='你有什么技能?',
                session_id=response.output.session_id)  # 上一轮response的session_id

    if responseNext.status_code != HTTPStatus.OK:
        print(f'request_id={responseNext.request_id}')
        print(f'code={responseNext.status_code}')
        print(f'message={responseNext.message}')
        print(f'请参考文档:https://help.aliyun.com/zh/model-studio/developer-reference/error-code')
    else:
        print('%s\n session_id=%s\n' % (responseNext.output.text, responseNext.output.session_id))
        # print('%s\n' % (response.usage))

if __name__ == '__main__':
    call_with_session()
响应示例
我具备多种技能,可以协助你完成各种任务。以下是一些主要的技能:

1. **信息查询**:提供天气、新闻、历史事实、科学知识等各种信息。
2. **语言处理**:翻译文本、纠正语法错误、生成文章和故事。
3. **技术问题解答**:解答编程、软件使用、技术故障排除等问题。
4. **学习辅导**:帮助解答数学、物理、化学等学科的问题。
5. **生活建议**:提供健康、饮食、旅行、购物等方面的建议。
6. **娱乐互动**:讲笑话、玩文字游戏、进行简单的聊天互动。
7. **日程管理**:提醒重要日期、安排日程、设置提醒。
8. **数据分析**:解释数据图表、提供数据分析建议。
9. **情感支持**:倾听你的感受、提供安慰和支持。

如果你有具体的需求或问题,可以直接告诉我,我会尽力帮助你!
 session_id=98ceb3ca0c4e4b05a20a00f913050b42

流式输出

大模型接收输入后,逐步生成中间结果并实时输出。这种方式称为流式输出,在模型生成过程中即时查看内容,减少等待时间。 流式输出的实现方式 根据调用方式的不同,设置相应参数即可启用流式输出:
  • Python SDK方式:设置stream参数为True
  • Java SDK方式:使用streamCall方法。
  • HTTP方式:在Header中指定X-DashScope-SSEenable
流式输出的内容默认是非增量式(即每次返回的内容都包含之前生成的内容),如需增量输出,请设置相应参数:
  • Python SDK方式:设置 incremental_output参数为True
  • Java SDK方式:使用 incrementalOutput 方法并设置为 true
  • HTTP方式:在 parameters 中使用 incremental_output参数并设置为true
调用示例 如果智能体应用内使用了深度思考模型(例如 Qwen3),输出顺序为“先思考、后答案”。调用时设置has_thoughts参数为True,即可在thoughts字段中返回思考过程。
  • 其中Qwen3模型开启思考模式有两种方式:一是在应用内打开思考模式开关并发布应用;二是API调用时设置 enable_thinkingtrue 。若同时设置,则以API参数为准。
  • 其他思考模型默认开启思考模式,且无法关闭。
  • Python
  • Java
  • HTTP
请求示例
import os
from http import HTTPStatus
from dashscope import Application
responses = Application.call(
            # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
            api_key=os.getenv("DASHSCOPE_API_KEY"),
            app_id='YOUR_APP_ID',
            prompt='你是谁?',
            stream=True,  # 流式输出
            incremental_output=True)  # 增量输出

for response in responses:
    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(f'{response.output.text}\n')  # 处理只输出文本text
响应示例
我是来自

阿里



的大规模语言模型

,我叫通

义千问。

传递自定义参数

通过自定义提示词变量(引导输出方向)、插件参数(扩展能力)及用户级鉴权参数(权限控制),智能体可适配多种业务场景。调用时使用biz_params传递参数,实现灵活响应。
描述说明
user_prompt_params类型:object传递自定义提示词变量。用于传递在提示词中插入配置的变量。在控制台定义变量,API调用时传具体值。示例:prompt:请给出{{city}}的三种美食推荐,只显示美食名称,逗号隔开。参数:
biz_params = {
    "user_prompt_params":{
        "city": "北京"}}
实际生效prompt:请给出北京的三种美食推荐,只显示美食名称,逗号隔开。
控制台需要按如下步骤操作:
  1. 智能体应用内添加自定义变量;
  2. 在提示词中引用;
  3. 发布应用。
确保应用内添加的自定义变量名和API调用时传递的变量名一致。
user_defined_params类型:object传递自定义插件参数。用于传递插件执行任务所需的业务数据(如城市、日期)。控制台需要按如下步骤操作:
  1. 在控制台配置插件工具的业务透传参数;
    自定义插件工具参数的配置方法,请参考自定义插件
  2. 测试并发布插件工具;
  3. 关联智能体应用,并发布应用。
    插件工具只能与位于相同业务空间里的智能体应用关联。
user_defined_tokens类型:object传递自定义插件用户级鉴权参数。插件调用时的用户身份验证(如DASHSCOPE_API_KEY)。
biz_params = {
    "user_defined_params": {
        "<YOUR_TOOL_ID>": {
            "city": "北京"}},
    "user_defined_tokens": {
        "<YOUR_TOOL_ID>": {
            "user_token": "sk-xxx"}}}
API调用示例如下:
  • 提示词变量
  • 插件业务参数
  • 插件用户级鉴权参数
使用步骤
  1. 在控制台的智能体应用内添加自定义变量,并在提示词中引用,然后发布应用。示例:
    1. 单击+ 自定义变量按钮添加变量。
    2. 配置变量信息:变量名为 city,描述为城市名,默认值为杭州。
    3. 在提示词编辑区输入引用变量的提示词,例如:根据城市名 ${city},给出该城市的三种美食推荐,只显示美食名称,逗号隔开。
  2. API调用,示例如下:
    • Python
    • Java
    • HTTP
    请求示例
    from http import HTTPStatus
    import os
    # 建议dashscope SDK 的版本 >= 1.14.0
    from dashscope import Application
    biz_params = {
        # 智能体应用的自定义变量参数,可替换为实际参数,支持传入多个变量键值对,英文逗号隔开
        "user_prompt_params":{
            "city": "北京"}}
    response = Application.call(
                # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
                api_key=os.getenv("DASHSCOPE_API_KEY"),
                app_id='YOUR_APP_ID', # 替换为实际的应用ID,应用卡片获取
                prompt='美食推荐',
                biz_params=biz_params)
    
    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('%s\n' % (response.output.text))  # 处理只输出文本text
        # print('%s\n' % (response.usage))
    
    响应示例
    北京烤鸭,炸酱面,豆汁儿
    

进阶功能

检索知识库

知识库功能作为百炼的RAG能力,能有效地为大模型补充私有知识、提供最新信息。调用智能体应用时指定检索范围,可提高大模型的回答准确性。更多知识库功能请参考:创建和使用知识库

前提条件

在百炼控制台的智能体应用中,打开知识库开关,并发布应用。

指定检索范围

  1. 检索指定的创建和使用知识库,有以下三种方式:
    1. 在应用内单击配置知识库以关联指定知识库,并发布应用;
    2. 在应用内不关联指定知识库,API调用时通过rag_options传入知识库ID;
    3. 既在应用内关联指定知识库,又在API调用时通过rag_options传入知识库ID。
      这种情况只会检索调用时传入的知识库。例如,网页端的智能体应用里关联了知识库A,而API调用时只指定了知识库B,那么不会检索知识库A,只会检索知识库B。
    获取知识库ID(pipeline_ids):可以在知识库页面获取,也可以使用CreateIndex接口(仅支持非结构化知识库)返回的Data.Id 可以是智能体应用已经关联的知识库,也可以是没有关联的知识库。 调用示例:此处选择百炼系列手机产品介绍.docx作为一个非结构化数据知识库的文件。
    • Python
    • Java
    • HTTP
    请求示例
    import os
    from http import HTTPStatus
    # 建议dashscope SDK 的版本 >= 1.20.11
    from dashscope import Application
    response = Application.call(
        # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='YOUR_APP_ID',  # 应用ID替换YOUR_APP_ID
        prompt='请帮我推荐一款3000元以下的手机',
        rag_options={
            "pipeline_ids": ["YOUR_PIPELINE_ID1","YOUR_PIPELINE_ID2"],  # 替换为实际的知识库ID,逗号隔开多个
        }
    )
    
    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('%s\n' % (response.output.text))  # 处理只输出文本text
        # print('%s\n' % (response.usage))
    
    响应示例
    根据您的预算,我推荐您选择**百炼 Zephyr Z9**。这款手机的参考售价在2499-2799元之间,符合您的预算需求。它拥有轻巧的6.4英寸1080 x 2340像素屏幕设计,搭配128GB存储与6GB RAM,适合日常使用。此外,它还配备了4000mAh电池以及支持30倍数字变焦的镜头,能够很好地满足拍照及续航的需求。如果您追求的是轻薄便携且功能全面的手机,那么百炼 Zephyr Z9会是一个不错的选择。
    
  2. 检索指定的非结构化数据文档:在rag_options中传入知识库ID、文档ID、文档标签tags或文档元数据metadata(键值对)。
    文档ID、文档标签tags和文档元数据metadata仅对非结构化数据文档检索生效。
    • 获取方式:
      • 文档ID(file_ids):可以在应用数据页面的文档列表中获取,也可以使用AddFile接口导入文档返回的ID。
      • 文档标签(tags):可以在应用数据页面查看非结构化文档的标签。也可以通过DescribeFile接口获取。
      • 文档元数据(metadata):在知识库页面,进入某个知识库后可以查看非结构化文档的元数据(Meta信息)。
    • 可以传入多个文档ID,仅支持已建立知识索引的文档。
    • 传入文档ID时,需要同时传入文档所属的知识库ID,检索才会生效。
    • 只会在指定的文档里检索。例如:网页端的智能体应用里引用了知识库A,而API调用时指定了文档ID和其所属的知识库B的ID,那么不会检索知识库A的文档,只会检索知识库B的文档 此处示例选择百炼系列手机产品介绍.docx作为非结构化数据知识库文件。
      • Python
      • Java
      • HTTP
      请求示例
      import os
      from http import HTTPStatus
      # 建议dashscope SDK 的版本 >= 1.20.11
      from dashscope import Application
      response = Application.call(
          # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
          api_key=os.getenv("DASHSCOPE_API_KEY"),
          app_id='YOUR_APP_ID',  # 应用ID替换YOUR_APP_ID
          prompt='请帮我推荐一款3000元以下的手机',
          rag_options={
              "pipeline_ids": ["YOUR_PIPELINE_ID1", "YOUR_PIPELINE_ID2"],  # 替换为实际的知识库ID,逗号隔开多个
              "file_ids": ["YOUR_FILE_ID1", "YOUR_FILE_ID2"],  # 替换为实际的非结构化文档 ID,逗号隔开多个
              "metadata_filter": {  # 文档元数据键值对,逗号隔开多个
                  "key1": "value1",
                  "key2": "value2"
              },
              "tags": ["tag1", "tag2"]  # 文档标签,逗号隔开多个
          }
      )
      
      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('%s\n' % (response.output))
      
      响应示例
      {
          "text": "在3000元以下的预算范围内,我推荐您考虑**百炼 Zephyr Z9**。这款手机的特点如下:
      
      - **屏幕**:6.4英寸 1080 x 2340像素,适合日常使用和娱乐。
      - **内存与存储**:6GB RAM + 128GB 存储空间,能够满足大部分用户对于流畅度以及存储的需求。
      - **电池容量**:4000mAh,提供了一整天的使用保障。
      - **摄像头功能**:配备了一个支持30倍数字变焦的镜头,可以捕捉到更远距离的细节。
      - **其他特性**:设计轻薄便携,易于携带。
      
      参考售价为2499至2799元之间,正好符合您的预算要求,并且提供了不错的性价比。希望这些建议对您有所帮助!",
          "finish_reason": "stop",
          "session_id": "10bdea3d1435406aad8750538b701bee",
          "thoughts": null,
          "doc_references": null
      }
      
  3. 检索结构化数据文档里的指定数据:在rag_options中传入知识库ID、结构化数据文档的“结构化数据表头+值”的键值对。 获取结构化数据键值对(structured_filter):在知识库页面,进入某个知识库后可以单击查看索引查看结构化文档的索引信息。
    • Python
    • Java
    • HTTP
    请求示例
    import os
    from http import HTTPStatus
    # 建议dashscope SDK 的版本 >= 1.20.11
    from dashscope import Application
    
    response = Application.call(
        # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='YOUR_APP_ID',  # 应用ID替换YOUR_APP_ID
        prompt='请帮我推荐一款3000元以下的手机',
        rag_options={
            "pipeline_ids": ["YOUR_PIPELINE_ID1", "YOUR_PIPELINE_ID2"],  # 替换为实际的知识库ID,逗号隔开多个
             "structured_filter": {  # 结构化数据键值对,对应结构化数据,逗号隔开多个
                "key1": "value1",
                "key2": "value2"
             }
        }
    )
    
    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('%s\n' % (response.output))
    
    响应示例
    {
        "text": "我为您推荐"百炼"这款手机,它的价格是2999元,符合您的预算要求。如果您需要了解更多信息,比如性能、外观等,请告诉我。",
        "finish_reason": "stop",
        "session_id": "80a3b868b5ce42c8a12f01dccf8651e2",
        "thoughts": null,
        "doc_references": null
    }
    

查看信息

查看检索过程信息:调用时在代码中添加has_thoughts并设置为True,则检索的过程信息会在outputthoughts字段中返回。

查看回答来源信息:单击知识库开关旁的配置,在页面中打开展示回答来源开关,然后发布应用,可在调用的返回结果中查看回答来源。

深度思考

如果您在智能体应用内选择了深度思考模型,并成功发布应用,则: 开启思考模式 要开启思考模式并接收其输出,您可通过以下两种方式进行相应设置。
  1. 控制台设置 对于 Qwen3 模型:在控制台应用内,确保思考模式开关已打开,然后重新发布应用。 对于其他模型:默认开启思考模式,无需额外操作。
  2. API 调用参数设置 对于 Qwen3 模型:将enable_thinking参数设置为 true。 对于其他模型:enable_thinking参数无效。
优先级:若两种方式同时设置,则以API参数为准。
获取思考过程:
  • 将has_thoughts参数设置为 true。
处理返回结果
  • 思考过程:将在响应的 thought 字段中返回。
  • 最终回复:将在响应的 text 字段中返回。
深度思考模型可能会输出较长的思考过程,为了降低超时风险,建议您使用流式输出方式调用应用,参考下方示例。
  • Python
  • Java
  • curl
请求示例
import os
from http import HTTPStatus
from dashscope import Application

try:
    response = Application.call(
        # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
        api_key=os.getenv('DASHSCOPE_API_KEY'),
        app_id='YOUR_APP_ID',# 替换为实际的应用 ID
        prompt='你是谁?',# 替换为实际的应用输入
        stream=True,  # 是否流式输出,True:流式输出;False(默认值): 非流式输出
        incremental_output=True,  # 是否增量输出,True:增量输出;False(默认值): 非增量输出
        has_thoughts=True  # 是否返回思考过程,True:返回;False(默认值): 不返回
    )

except Exception as e:
    print(f"API请求异常: {str(e)}")
    exit(1)

# 定义完整思考过程
reasoning_content = []
# 定义完整回复
answer_content = ""
# 判断是否结束思考过程并开始回复
is_answering = False

def print_section(title):
    """打印带装饰的分段标题"""
    print(f"\n{'=' * 20} {title} {'=' * 20}\n", flush=True)

print_section("思考过程")

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

    # 跳过空数据块
    if not chunk.output or (not chunk.output.thoughts and not chunk.output.text):
        continue

    # 处理思考过程
    if chunk.output.thoughts:
        for it in chunk.output.thoughts:
            if it.action_type == 'reasoning':# deepseek-r1类模型的思考过程action_type为reasoning,输出在thought
                content = str(it.thought) if not isinstance(it.thought, str) else it.thought
                reasoning_content.append(content)
                print(content, end="", flush=True)

    # 处理回答内容
    if chunk.output.text:
        if not is_answering:
            print_section("完整回复")
            is_answering = True

        answer_content += str(chunk.output.text)
        print(chunk.output.text, end="", flush=True)

# 最终结果整合
final_reasoning = "".join(reasoning_content)
final_answer = "".join(answer_content)

# 如果您需要打印完整思考过程与完整回复,请将以下代码解除注释后运行
#print_section("完整思考过程")
#print(final_reasoning)

#print_section("完整回复")
#print(final_answer)
响应示例
==================== 思考过程 ====================

嗯,用户问我“你是谁?”,我需要用中文回答。首先,我得介绍自己是一个AI助手,由DeepSeek公司开发。然后要说明我的功能,比如回答问题、提供信息、帮助学习等。要记得保持口语化,不用太正式。还要注意用户可能想了解我的背景,所以可以提到基于大语言模型,但不用太技术化。另外,用户可能在测试我的回答能力,所以需要简洁明了,同时友好自然。可能需要检查有没有遗漏的关键点,比如公司的正确名称,以及是否强调帮助性质。最后确保回答符合格式要求,不使用markdown,保持段落结构清晰。
==================== 完整回复 ====================

您好!我是DeepSeek-R1,一个由深度求索(DeepSeek)公司开发的智能助手,我会尽我所能为您提供帮助,包括回答问题、信息查询以及学习辅助等。

检索知识库

  • 模型思考过程在thoughtsthought中返回,模型思考的action_typereasoning
  • 检索过程在thoughtsobservation中返回,检索的action_typeagentRag
可通过action_type区分不同过程,处理输出内容。

长期记忆

阿里云百炼的智能体应用在和您进行对话时,能够记住一定长度的对话记录,但由于大模型注意力机制的限制,可能会忘记某些信息。为了解决这个问题,您可以将对话过程中的特定信息存储到长期记忆中,应用将在后续对话中持续引用这些信息。 使用步骤 步骤 1: 激活长期记忆功能 访问应用管理页面,找到您的智能体应用,打开长期记忆功能开关,并发布应用。 步骤 2: 创建长期记忆体 调用CreateMemory接口,创建一个长期记忆体,从响应中获得一个唯一的memoryId 步骤 3: 保存对话信息 调用时传入之前获得的memoryId,系统会自动分析并提取您对话中的关键信息,这些信息将被保存为与该memoryId关联的记忆内容。 步骤 4: 使用长期记忆进行对话 每次与智能体交流时提供相同的memoryId,系统会根据提供的memoryId召回相应的记忆内容,并将其与当前提问一起传递给模型生成答案。 调用示例
  • Python
  • Java
  • HTTP
请求示例(生成记忆体内容)
# DashScope SDK版本不低于1.22.1
from http import HTTPStatus
import os
from dashscope import Application
response = Application.call(
           # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
            api_key=os.getenv("DASHSCOPE_API_KEY"),
            app_id='YOUR_APP_ID',  # 请输入实际的应用 ID
            prompt='用户饮食偏好:面食',
            memory_id='YOUR_MEMORY_ID')  # 请输入实际的记忆体 ID

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('%s\n' % (response.output.text))  # 处理只输出text
    # print('%s\n' % (response.usage))
响应示例
了解了,您对面食情有独钟。如果想要推荐或者寻找面食相关的食谱、餐厅等信息,请告诉我更多细节,比如是想吃哪种类型的面条(如拉面、意大利面等),还是有什么特别的口味偏好?这样我能更好地为您提供帮助。
请求示例(再次调用)
# DashScope SDK版本不低于1.22.1
from http import HTTPStatus
import os
from dashscope import Application
response = Application.call(
           # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
            api_key=os.getenv("DASHSCOPE_API_KEY"),
            app_id='YOUR_APP_ID',  # 请输入实际的应用 ID
            prompt='美食推荐',
            memory_id='YOUR_MEMORY_ID')  # 请输入实际的记忆体 ID

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('%s\n' % (response.output.text))  # 处理只输出text
    # print('%s\n' % (response.usage))
响应示例
既然您偏好面食,我推荐您可以尝试一下几种美食:

1. **炸酱面**:经典的北京风味,面条搭配特制的黄豆酱和肉末,口感丰富。
2. **担担面**:四川特色,辣中带麻,非常开胃。如果您喜欢尝试一些稍微刺激一点的味道,这会是个不错的选择。
3. **刀削面**:山西的传统名吃之一,以其独特的制作方法——用刀将面团直接削入锅中煮熟而得名,口感劲道。
4. **意大利面**:如果想要换换口味的话,不妨试试西式的意面,比如番茄肉酱意面或是奶油培根意面等,都是不错的选择。

希望这些建议对您有所帮助!如果有更具体的口味偏好或其他需求,请随时告诉我哦~

上传文件(文档、图片、视频或音频)

智能体应用内,您可上传文件(文档、图片、视频或音频),并基于文件内容进行问答。

使用场景

  • 文本解析:解析文档、图片、视频或音频中的文字内容,结合大模型回答问题。
  • 视觉理解:通过通义千问VL系列模型分析图片中的图像内容(如物体、场景、动作等),无需依赖文字信息。
如需在控制台操作上传文件并与大模型进行问答请参阅上传文件 API方式操作请参阅以下内容。
  • 文本解析
  • 视觉理解
步骤一:准备文件待上传的文件需满足以下要求。支持上传的文件上限10个。支持上传本地的文档、图片、视频或音频,格式要求为:
  • 文档(单文件不超过100MB):.doc,.docx,.wps,.ppt,.pptx,.xls,.xlsx,.md,.txt,.pdf;
  • 图片(单文件不超过20MB):.png,.jpg,.jpeg,.bmp,.gif; 目前仅支持上传包含文字内容的本地图片。
  • 视频(单文件不超过512MB):.mp4,.mkv,.avi,.mov,.wmv;
  • 音频(单文件不超过512MB):.aac,.amr,.flac,.flv,.m4a,.mp3,.mpeg,.ogg,.opus,.wav,.webm,.wma。
步骤二:获取会话文件ID
  1. 通过本文的通过API接口获取会话文件ID获取以“file_session”开头的会话文件ID;
  2. 验证文件状态为FILE_IS_READY。
image
步骤三:API调用应用
  1. 在控制台智能体应用内选择任一模型,开启动态文件解析开关,并发布应用。
    您的智能体应用与步骤二中上传的文件需位于同一业务空间内。
  2. API调用时,通过参数 session_file_ids 传递步骤二中获取的会话文件ID,调用示例如下:
    Java SDK中为sessionFileIds。通过HTTP调用时,请将 session_file_ids 放入 parameters 对象中。
    获取的会话文件ID必须以“file_session_”开头,且文件状态为 FILE_IS_READY。如果未满足条件,调用将会失败。
    • Python
    • Java
    • HTTP
    请求示例
    import os
    from http import HTTPStatus
    # 建议dashscope SDK 的版本 >= 1.20.14
    from dashscope import Application
    response = Application.call(
        # 若没有配置环境变量,可用百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='YOUR_APP_ID',  # 应用ID替换YOUR_APP_ID
        prompt='请根据以下文件帮我推荐一款3000元以下的手机',
        rag_options={
            "session_file_ids": ["FILE_ID1"],  # FILE_ID1 替换为实际的临时文件ID,逗号隔开多个
        }
    )
    
    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('%s\n' % (response.output.text))  # 处理只输出文本text
        # print('%s\n' % (response.usage))
    
    响应示例
    根据您的预算,我推荐您选择**通义 Vivid 7**这款手机。以下是它的主要特点:
    
    - **屏幕**:6.5英寸,1080 x 2400像素
    - **存储与内存**:128GB存储,8GB RAM
    - **电池**:4500mAh
    - **特色功能**:AI智能摄影,侧面指纹解锁
    - **参考售价**:2999-3299
    
    通义Vivid 7不仅价格适中,而且具有良好的性能和实用的功能,特别适合喜欢拍照的用户。希望这个建议对您有所帮助!
    
通过API接口获取会话文件ID

操作步骤

  1. 申请文件上传租约 在线调试ApplyFileUploadLease接口。
    操作说明重要参数说明
    CategoryType 设置为 SESSION_FILE,完成参数配置后单击发起调用CategoryId: 务必填写default。
    FileName:文件名称+后缀。
    Md5:可运行此处示例代码获取该文件的Md5值。

    生成MD5示例代码

    Python
    # 示例代码仅供参考,请勿在生产环境中直接使用
    import hashlib
    def calculate_md5(file_path):
        """计算文档的 MD5 值。
    
        Args:
            file_path (str): 文档的路径。
    
        Returns:
            str: 文档的 MD5 值。
        """
        md5_hash = hashlib.md5()
    
        # 以二进制形式读取文件
        with open(file_path, "rb") as f:
            # 按块读取文件,避免大文件占用过多内存
            for chunk in iter(lambda: f.read(4096), b""):
                md5_hash.update(chunk)
    
        return md5_hash.hexdigest()
    
    # 使用示例
    file_path = "请替换为您需要上传文档的实际本地路径,例如/Users/<username>/Desktop/阿里云百炼系列手机产品介绍.docx"
    md5_value = calculate_md5(file_path)
    print(f"文档的MD5值为: {md5_value}")
    
    SizeInBytes:文件大小,单位为字节。例如:6 KB = 6 * 1024 字节 = 6144 字节。
    CategoryType: 务必填写SESSION_FILE。
    调用成功响应调用成功后,返回如下 JSON 响应(敏感字段已脱敏):
    {
        "Status": "200",
        "Message": "",
        "RequestId": "519DD942-4701-xxx",
        "Data": {
            "FileUploadLeaseId": "ed76eb4xxx",
            "Type": "OSS.PreSignedUrl",
            "Param": {
                "Headers": {
                    "X-bailian-extra": "MTY3MzAyNxxx==",
                    "Content-Type": "application/msword"
                },
                "Method": "PUT",
                "Url": "https://dashscope-file-datacenter-xxx"
            }
        }
    }
    
    说明
    1. 此接口响应中的Data.FileUploadLeaseIdData.Param.MethodData.Param.Url、Data.Param.Headers.X-bailian-extra和Data.Param.Headers.Content-Type字段的值请妥善保存,它们将用于后续的上传步骤。
    2. 此接口响应中的Data.Param.Url字段的值(即租约)有效期为分钟级,请尽快上传文档,以免租约过期导致无法上传。
  2. 上传文件至阿里云百炼的临时存储 示例代码如下,请根据代码提示替换上一步获取的实际字段值,然后运行代码。若响应为“File uploaded successfully.”,则表示上传成功。
    多语言示例请自行编写。
    Python
    # 示例代码仅供参考,请勿在生产环境中直接使用
    import requests
    from urllib.parse import urlparse
    
    def upload_file(pre_signed_url, file_path):
        try:
            # 设置请求头
            headers = {
                "X-bailian-extra": "请替换为您在上一步中调用ApplyFileUploadLease接口实际返回的Data.Param.Headers中X-bailian-extra字段的值",
                "Content-Type": "请替换为您在上一步中调用ApplyFileUploadLease接口实际返回的Data.Param.Headers中Content-Type字段的值"
            }
    
            # 读取文档并上传
            with open(file_path, 'rb') as file:
                # 下方设置请求方法用于文档上传,需与您在上一步中调用ApplyFileUploadLease接口实际返回的Data.Param中Method字段的值一致
                response = requests.put(pre_signed_url, data=file, headers=headers)
    
            # 检查响应状态码
            if response.status_code == 200:
                print("File uploaded successfully.")
            else:
                print(f"Failed to upload the file. ResponseCode: {response.status_code}")
    
        except Exception as e:
            print(f"An error occurred: {str(e)}")
    
    def upload_file_link(pre_signed_url, source_url_string):
        try:
            # 设置请求头
            headers = {
                "X-bailian-extra": "请替换为您在上一步中调用ApplyFileUploadLease接口实际返回的Data.Param.Headers中X-bailian-extra字段的值",
                "Content-Type": "请替换为您在上一步中调用ApplyFileUploadLease接口实际返回的Data.Param.Headers中Content-Type字段的值"
            }
    
            # 设置访问OSS的请求方法为GET
            source_response = requests.get(source_url_string)
            if source_response.status_code != 200:
                raise RuntimeError("Failed to get source file.")
    
            # 下方设置请求方法用于文档上传,需与您在上一步中调用ApplyFileUploadLease接口实际返回的Data.Param中Method字段的值一致
            response = requests.put(pre_signed_url, data=source_response.content, headers=headers)
    
            # 检查响应状态码
            if response.status_code == 200:
                print("File uploaded successfully.")
            else:
                print(f"Failed to upload the file. ResponseCode: {response.status_code}")
    
        except Exception as e:
            print(f"An error occurred: {str(e)}")
    
    if __name__ == "__main__":
    
        pre_signed_url_or_http_url = "请替换为您在上一步中调用ApplyFileUploadLease接口实际返回的Data.Param中Url字段的值"
    
        # 文档来源可以是本地,上传本地文档至百炼临时存储
        file_path = "请替换为您需要上传文档的实际本地路径"
        upload_file(pre_signed_url_or_http_url, file_path)
    
        # 文档来源还可以是阿里云对象存储OSS
        # file_path = "请替换为您需要上传文档的实际阿里云对象存储OSS可公网访问地址"
        # upload_file_link(pre_signed_url_or_http_url, file_path)
    
  3. 将文件添加至阿里云百炼的数据管理 上一步操作成功后,文档将暂存于阿里云百炼的临时存储空间内 12 小时,通过在线调试AddFile接口获取会话文件ID。

    配置图示

    重要参数说明

    image

    LeaseId:第一步接口响应中的Data.FileUploadLeaseId字段值。

    CategoryId: 务必填写default

    CategoryType: 务必填写SESSION_FILE

    调用成功响应调用成功后返回如下 JSON 响应,其中 FileId 为会话文件 ID,将用于后续所有与此文档相关的 API 操作。
    {
      "Status": 200,
      "Message": "",
      "RequestId": "AD2FB14B-8A0E-5DCB-xxx",
      "Data": {
        "FileId": "file_session_6c6bb333395xxx",
        "Parser": "DASHSCOPE_DOCMIND"
      },
      "Code": "Success",
      "Success": true
    }
    
    说明
    • 获取会话文件ID。示例:"file_session_6c6bb33339524b7xxx"。
      仅以“file_session_”开头的ID才能用于下一步的API调用。如未满足,请核实步骤中的重要参数CategoryId和CategoryType是否填写正确。
    • AddFile接口调用成功后,LeaseId(租约 ID)随即失效,请勿再使用相同的租约 ID 重复提交。
  4. 查看文档解析状态 通过在线调试DescribeFile接口查看文档解析状态。

    状态码

    说明

    INIT

    文件已上传,等待解析。

    PARSING

    正在解析文件内容。

    PARSE_SUCCESS

    文件解析成功。

    PARSE_FAILED

    文件解析失败,需重新上传。

    SAFE_CHECKING

    正在进行文件安全检测。

    SAFE_CHECK_FAILED

    文件未通过安全检测,需重新上传或更换文件。

    INDEX_BUILDING

    正在为文件构建索引。

    INDEX_BUILD_SUCCESS

    文件索引构建完成。

    INDEX_BUILDING_FAILED

    索引构建失败,需重新上传文件。

    INDEX_DELETED

    文件索引已删除。

    FILE_IS_READY

    文件准备完毕:文件解析、安全检测、索引构建均已完成。

    FILE_EXPIRED

    文件过期。 文件仅在当前会话有效(最长7天),关闭会话后自动过期,需重新上传文件。

    必须等到Status字段值显示为FILE_IS_READY才能开始后续的API调用。
    在 DescribeFile 接口调试页面,填写 WorkspaceIdFileId 参数后单击发起调用,确认返回结果中 StatusFILE_IS_READYParserDASHSCOPE_DOCMIND
  5. 完成有效的会话文件ID获取后,可进入上述步骤三:API调用应用。
如需查看上述获取ID步骤中的接口参数详细说明请参阅API上传文件

私网调用

为提高数据传输的安全性和效率,您可通过私网调用阿里云百炼平台的应用。
  1. 创建终端节点:在阿里云控制台为您的VPC创建一个私网终端节点。
  2. 替换域名:将API请求URL中的公网域名dashscope.aliyuncs.com替换为您获取到的私网终端节点服务域名。例如: https://ep-2zei6917b47eed******.dashscope.cn-beijing.privatelink.aliyuncs.com/api/v1/
  3. 发起请求:示例代码如下。
    • Python
    • Java
    • HTTP
    import os
    from http import HTTPStatus
    from dashscope import Application
    # 配置私网终端节点
    os.environ['DASHSCOPE_HTTP_BASE_URL'] = 'https://ep-2zei6917b47eed******.dashscope.cn-beijing.privatelink.aliyuncs.com/api/v1/'
    response = Application.call(
        # 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
        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)
    

API参考

通过工作流与旧版智能体应用 API应用 DashScope API 参考查看完整的参数列表。

错误码

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

相关文档

常见问题

  1. 检查导入语句中的类名和包名是否正确。
  2. 添加依赖库:如果使用Maven或Gradle进行项目管理,确保DashScope Java SDK依赖库已经添加到pom.xmlbuild.gradle文件中,且为最新版本。访问Maven获取DashScope Java SDK的最新版本号。
<!-- https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>在此处填写最新版本号,例如2.16.4</version>
</dependency>
// https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
implementation group: 'com.alibaba', name: 'dashscope-sdk-java', version: '在此处填写最新版本号,例如2.16.4'
  1. 升级SDK:旧版本的DashScope Java SDK可能不包含您尝试使用的功能或类。如果您已经添加过依赖库DashScope Java SDK,请确认您所使用的DashScope Java SDK是否为最新版。如果当前版本较低,请将其升级至最新版本。可在pom.xmlbuild.gradle文件中修改DashScope Java SDK的版本为最新版本。
<!-- https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>请将此处的版本号修改为最新版本</version>
</dependency>
// https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
implementation group: 'com.alibaba', name: 'dashscope-sdk-java', version: '请将此处的版本号修改为最新版本'
  1. 重新加载项目使更改生效。
  2. 重新运行代码示例。
  • session_id: 用于云端托管的多轮对话,自动维护对话上下文。 有效期1小时,最大历史轮数50。 无需调用者自行维护上下文,但需在下一轮对话中传入上一轮对话的session_id
  • memory_id: 用于创建长期记忆体,存储特定信息。 需调用CreateMemory接口创建,获取memoryId。 在后续对话中引用特定信息,需传入memoryId
两者分别服务于短期对话和长期信息存储。
Managed Agents
数据连接
Skill
应用评测
应用广场
权限管理
调用智能体应用 - 阿里云百炼