Skip to main content
應用調用

應用調用

您可以通過DashScope SDK或HTTP的方式來整合百鍊應用(智能體、工作流程或智能體編排)到您的業務系統中。

前提條件

您可以使用DashScope SDK或HTTP介面調用百鍊的應用,請您根據您的需求,準備您的計算環境。
無論使用哪種調用方式,建議您配置API Key到環境變數。如果通過DashScope SDK進行調用,還需要安裝DashScope SDK

如何使用

快速開始

  • Python
  • Java
  • HTTP
請求樣本
import os
from http import HTTPStatus
from dashscope import Application
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.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://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code')
else:
    print(response.output.text)
響應樣本
我是阿里雲開發的一款超大規模語言模型,我叫千問。我被設計用來協助使用者產生各種類型的文本,如文章、故事、詩歌、故事等,並能根據不同的情境和需求進行調整和最佳化。此外,我還能夠回答各種問題,提供資訊和解釋,輔助學習和研究。如果您有任何需要,歡迎隨時向我提問!

多輪對話

相比於單輪對話,多輪對話可以讓大模型參考歷史對話資訊,更符合日常交流的情境。
  • Python
  • Java
  • HTTP
請求樣本
import os
from http import HTTPStatus
from dashscope import Application
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

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://www.alibabacloud.com/help/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://www.alibabacloud.com/help/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

傳遞自訂參數

為使同一智能體或工作流程適應不同業務情境,可藉助自訂提示詞變數、自訂節點參數,外掛程式參數及使用者級鑒權參數進行配置。在應用調用過程中,通過biz_params傳遞所需參數以實現靈活適配。
  1. 自訂變數參數:在控制台的智能体应用內添加自訂變數,並在提示詞中引用,发布應用後,API調用時通過 user_prompt_params 傳遞;
    確保應用內添加的自訂變數名和API調用時傳遞的調用名一致。
  2. 自訂外掛程式的參數:通過關聯的智能体应用傳遞。 支援傳遞自訂外掛程式的參數資訊和使用者級鑒權資訊:
    • 自訂外掛程式的參數資訊通過user_defined_params傳遞。
    • 自訂外掛程式的使用者級鑒權資訊通過user_defined_tokens傳遞,其中user_token傳遞的值為該外掛程式需要的鑒權資訊,如實際DASHSCOPE_API_KEY的值。
    外掛程式的參數配置方法,請參考應用的參數傳遞 外掛程式工具只能與位於相同業務空間裡的智能体应用關聯。
參考下面在智能体应用中的調用樣本。
  • 自訂外掛程式參數傳遞
  • 自訂外掛程式使用者級鑒權
下面為傳遞關聯外掛程式的“索引”參數資訊和使用者級鑒權資訊,查詢寢室公約內容的例子。
<YOUR_TOOL_ID>替換為關聯的外掛程式工具ID(可在外掛程式卡片中擷取),並傳遞外掛程式中配置的輸入參數索引值對。本樣本中傳遞的參數為article_index,值為2。
  • Python
  • Java
  • HTTP
請求樣本
import os
from http import HTTPStatus
# 建議dashscope SDK 的版本 >= 1.14.0
from dashscope import Application
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
biz_params = {
    # 智能體應用的自訂外掛程式輸入參數傳遞,自訂的外掛程式ID替換<YOUR_TOOL_ID>
    "user_defined_params": {
        "<YOUR_TOOL_ID>": {
            "article_index": 2}}}
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',
        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://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code')
else:
    print('%s\n' % (response.output.text))  # 處理只輸出文本text
    # print('%s\n' % (response.usage))
響應樣本
寢室公約的第二條規定如下:

"寢室成員應當互幫互助、互相關心、互相學習、共同提高;寬容謙讓、相互尊重、以誠相待。"

這表明在寢室內,成員之間應該培養一種積極正面的生活和學習氛圍,彼此協助和支援,同時也要學會理解和尊重他人。如果您需要瞭解公約的其他條款,請告訴我!
  1. 自訂節點參數:在工作流应用智能体编排应用开始节点添加,通過biz_params傳遞。 參考下面在工作流应用中傳遞城市名參數的例子,在开始节点設定String類型變數city,同時在Prompt中插入變數city和變數query,最後发布應用。
    image
    調用時通過biz_params傳遞city,通過prompt傳遞query。
    • Python
    • Java
    • HTTP
    請求樣本
    import os
    from http import HTTPStatus
    from dashscope import Application
    import dashscope
    dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
    # 工作流程和智能體編排應用自訂參數傳遞
    biz_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://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code')
    else:
        print(f'{response.output.text}')  # 處理只輸出文本text
    
    響應樣本
    杭州市,作為浙江省的省會城市,其行政地區劃分包括10個市轄區:上城區、拱墅區、西湖區、濱江區、蕭山區、餘杭區、臨平區、錢塘區、富陽區、臨安區。每個區都有其獨特的特色和發展重點。
    
    - 上城區:位於杭州市中心地帶,是杭州的政治、經濟、文化中心之一。
    - 拱墅區:以運河文化為特色,擁有眾多歷史文化遺產。
    - 西湖區:著名的西湖風景區就位於此區,是旅遊觀光的重要目的地。
    - 濱江區:高新技術產業聚集地,阿里巴巴等知名企業坐落於此。
    - 蕭山區:東南部的一個行政區,經濟發展迅速,特別是製造業方面。
    - 餘杭區:近年來發展快速,尤其是互連網經濟領域,阿里巴巴總部也設在這裡(註:阿里巴巴總部實際位於濱江區)。
    - 臨平區:新成立的行政區,旨在促進該地區經濟社會全面發展。
    - 錢塘區:同樣是一個較新的行政區劃調整結果,強調創新發展和生態保護相結合。
    - 富陽區:位於杭州西南方向,以其豐富的自然景觀和悠久的歷史文化著稱。
    - 臨安區:地處杭州西部,以生態優美聞名,並且有著深厚的文化底蘊。
    
    請注意,隨著時間推移,具體的城市規劃可能會有所變化,請參考最新的官方資訊。
    

流式輸出

大模型接收到輸入後,會逐步產生中間結果,最終結果由這些中間結果拼接而成。這種一邊產生一邊輸出中間結果的方式稱為流式輸出。採用流式輸出時,您可以在模型進行輸出的同時閱讀,減少等待模型回複的時間。根據不同的調用方式,您可以設定相應的參數來實現流式輸出:
  • Python SDK方式:設定stream參數為True則開啟流式輸出。
  • Java SDK方式:需要通過streamCall介面調用。
  • HTTP方式:需要在Header中指定X-DashScope-SSEenable
流式輸出的內容預設是非增量式(即每次返回的內容都包含之前產生的內容),如果您需要使用增量式流式輸出,請設定incremental_output(Java 為incrementalOutput介面)參數為 true ,通過HTTP調用時設定incremental_output為true,並將其放入parameters對象中。
參考下方樣本:
  • 智能体应用流式輸出調用樣本如下:
    • Python
    • Java
    • HTTP
    請求樣本
    import os
    from http import HTTPStatus
    from dashscope import Application
    import dashscope
    dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
    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://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code')
        else:
            print(f'{response.output.text}\n')  # 處理只輸出文本text
    
    響應樣本
    我是來自
    
    阿里
    
    
    
    的大規模語言模型
    
    ,我叫通
    
    義千問。
    
工作流应用流式輸出調用樣本如下: 如圖所示發行工作流应用配置,對杭州的美食和景點進行流式輸出。
image
通過API調用。
  • Python
  • Java
  • HTTP
請求樣本
import os
from http import HTTPStatus
from dashscope import Application
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
biz_params = {
    "city": "杭州"}
responses = Application.call(
    # 若沒有配置環境變數,可用百鍊API Key將下行替換為:api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 替換為實際的應用 ID
    app_id='YOUR_APP_ID',
    prompt='你好',
    biz_params=biz_params,
    # 開啟流式輸出
    stream=True,
    # incremental_output為true開啟增量輸出,為false關閉增量輸出,不填寫預設false
    incremental_output=True,
    # 需要設定has_thoughts為True
    has_thoughts=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://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code')
    else:
        print(f'{response.output.thoughts}\n')  # 處理輸出只返回thoughts;在output的thoughts欄位中返回過程資訊
響應樣本
[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"LLM_Ilo9","nodeResult":"{\\"result\\":\\"\\"}","nodeType":"LLM","nodeStatus":"executing","nodeId":"LLM_Ilo9"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_Bsvj","nodeResult":"{\\"result\\":\\"西湖醋魚,\\"}","nodeType":"LLM","nodeStatus":"executing","nodeId":"LLM_Ilo9"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_Bsvj","nodeResult":"{\\"result\\":\\"東坡肉,\\"}","nodeType":"LLM","nodeStatus":"executing","nodeId":"LLM_Ilo9"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_Bsvj","nodeResult":"{\\"result\\":\\"知味觀小\\"}","nodeType":"LLM","nodeStatus":"executing","nodeId":"LLM_Ilo9"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_Bsvj","nodeResult":"{\\"result\\":\\"籠包,龍井蝦仁,\\"}","nodeType":"LLM","nodeStatus":"executing","nodeId":"LLM_Ilo9"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_Bsvj","nodeResult":"{\\"result\\":\\"叫化雞\\"}","nodeType":"LLM","nodeStatus":"success","nodeId":"LLM_Ilo9","nodeExecTime":"1332ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_Bsvj","nodeResult":"{\\"result\\":\\"\\"}","nodeType":"LLM","nodeStatus":"success","nodeId":"LLM_Ilo9","nodeExecTime":"1332ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"LLM_vQDv","nodeResult":"{\\"result\\":\\"\\"}","nodeType":"LLM","nodeStatus":"executing","nodeId":"LLM_vQDv"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_Bsvj","nodeResult":"{\\"result\\":\\"\\"}","nodeType":"LLM","nodeStatus":"success","nodeId":"LLM_Ilo9","nodeExecTime":"1332ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_kBgf","nodeResult":"{\\"result\\":\\"西湖,靈隱\\"}","nodeType":"LLM","nodeStatus":"executing","nodeId":"LLM_vQDv"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_Bsvj","nodeResult":"{\\"result\\":\\"\\"}","nodeType":"LLM","nodeStatus":"success","nodeId":"LLM_Ilo9","nodeExecTime":"1332ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_kBgf","nodeResult":"{\\"result\\":\\",宋城\\"}","nodeType":"LLM","nodeStatus":"executing","nodeId":"LLM_vQDv"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_Bsvj","nodeResult":"{\\"result\\":\\"\\"}","nodeType":"LLM","nodeStatus":"success","nodeId":"LLM_Ilo9","nodeExecTime":"1332ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_kBgf","nodeResult":"{\\"result\\":\\",西溪濕地\\"}","nodeType":"LLM","nodeStatus":"executing","nodeId":"LLM_vQDv"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_Bsvj","nodeResult":"{\\"result\\":\\"\\"}","nodeType":"LLM","nodeStatus":"success","nodeId":"LLM_Ilo9","nodeExecTime":"1332ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_kBgf","nodeResult":"{\\"result\\":\\",千島湖\\"}","nodeType":"LLM","nodeStatus":"executing","nodeId":"LLM_vQDv"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

[ApplicationThought(thought=None, action_type=None, response='{"nodeName":"開始","nodeType":"Start","nodeStatus":"success","nodeId":"Start_bYxoRU","nodeExecTime":"0ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_Bsvj","nodeResult":"{\\"result\\":\\"\\"}","nodeType":"LLM","nodeStatus":"success","nodeId":"LLM_Ilo9","nodeExecTime":"1332ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"大模型_kBgf","nodeResult":"{\\"result\\":\\"\\"}","nodeType":"LLM","nodeStatus":"success","nodeId":"LLM_vQDv","nodeExecTime":"948ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None), ApplicationThought(thought=None, action_type=None, response='{"nodeName":"結束","nodeResult":"{\\"result\\":\\"西湖,靈隱寺,宋城,西溪濕地,千島湖\\"}","nodeType":"End","nodeStatus":"success","nodeId":"End_DrQn7F","nodeExecTime":"1ms"}', action_name=None, action=None, action_input_stream=None, action_input=None, observation=None)]

檢索知識庫

知識庫功能作為百鍊的RAG能力,能有效地為大模型補充私人知識、提供最新資訊。您可在調用智能体应用指定檢索範圍,提高大模型的回答準確性。更多知識庫功能請參考:建立和使用知識庫

前提條件

在百鍊控制台的智能体应用中,開啟知识库開關,並发布應用。
其中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
    import dashscope
    dashscope.base_http_api_url = 'https://dashscope-intl.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='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://www.alibabacloud.com/help/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
      import dashscope
      dashscope.base_http_api_url = 'https://dashscope-intl.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='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://www.alibabacloud.com/help/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
    import dashscope
    dashscope.base_http_api_url = 'https://dashscope-intl.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='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://www.alibabacloud.com/help/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欄位中返回。

查看回答來源資訊:智能体应用配置中開啟展示回答来源開關並發布應用,可在調用的返回結果中查看回答來源。
image

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. 重新運行程式碼範例。 如果仍然存在問題,建議查閱開發人員論壇瞭解是否有其他使用者遇到相同的問題及其解決方案,或提交工單以擷取進一步的協助。