Skip to main content
工具包/架構

OpenAI Responses介面相容

阿里雲百鍊的通義千問模型支援 OpenAI 相容 Responses 介面。作為Chat Completions API的演化版本,Responses API能夠以更簡潔的方式提供智能體原生功能。

相較於OpenAI Chat Completions API 的優勢:
  • 內建工具:內建連網搜尋、網頁抓取、代碼解譯器、文搜圖、圖搜圖等工具,可在處理複雜任務時獲得更佳效果,詳情參考調用內建工具
  • 更靈活的輸入:支援直接傳入字串作為模型輸入,也相容 Chat 格式的訊息數組。
  • 簡化上下文管理:通過傳遞上一輪響應的 previous_response_id,無需手動構建完整的訊息歷史數組。
輸入輸出參數說明請參考OpenAI Responses API參考

前提條件

您需要先擷取與配置 API Key配置API Key到環境變數。若通過 OpenAI SDK 進行調用,需要安裝SDK

支援的模型

qwen3.8-maxqwen3.8-flashqwen3.7-maxqwen3.7-max-2026-05-20qwen3.7-max-2026-06-08qwen3.7-max-2026-05-17qwen3.7-max-previewqwen3-maxqwen3-max-2026-01-23qwen3.7-plusqwen3.7-plus-2026-05-26qwen3.6-plusqwen3.6-plus-2026-04-02qwen3.5-plusqwen3.5-plus-2026-04-20qwen3.5-plus-2026-02-15qwen3.7-flashqwen3.7-flash-2026-07-15qwen3.6-flashqwen3.6-flash-2026-04-16qwen3.5-flashqwen3.5-flash-2026-02-23qwen3.8-2.4t-a95bqwen3.8-27bqwen3.6-35b-a3bqwen3.5-397b-a17bqwen3.5-122b-a10bqwen3.5-27bqwen3.5-35b-a3bdeepseek-v4-prodeepseek-v4-pro-0813deepseek-v4-flashdeepseek-v4-flash-0731glm-5.2kimi-k3
非列表中阿里雲百鍊直供文本生成模型僅支援基礎相容能力,Agent 能力(内建工具等)受限。

服務地址

OpenAI 相容介面 Responses API 的舊版路徑 /api/v2/apps/protocols/compatible-mode/v1/responses 即將停止維護,請儘快遷移至新版路徑 /compatible-mode/v1/responses
阿里雲百鍊為華北2(北京)、新加坡、中國香港地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:
  • 華北2(北京)地區:從 https://dashscope.aliyuncs.com 遷移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區:從 https://dashscope-intl.aliyuncs.com 遷移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
  • 中國香港地區:從 https://cn-hongkong.dashscope.aliyuncs.com 遷移至 https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com
其中 {WorkspaceId} 為您的業務空間 ID,可在阿里雲百鍊控制台的業務空間詳情頁面查看。現有網域名稱仍可正常使用。
  • 新加坡
  • 华北2(北京)
  • 美國(維吉尼亞)
  • 德國(法蘭克福)
  • 中國香港
  • 日本(東京)
SDK 調用配置的base_urlhttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1HTTP 要求地址:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses調用時請將{WorkspaceId}替換為真實的Workspace ID

程式碼範例

基礎調用

最簡單的調用方式,發送一條訊息並擷取模型回複。
Python
import os
from openai import OpenAI

client = OpenAI(
    # If environment variable is not set, replace with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

response = client.responses.create(
    model="qwen3.8-max",
    input="What can you do?"
)

# Get model response
# print(response.model_dump_json())
print(response.output_text)
響應樣本
以下為API返回的完整響應。
{
    "created_at": 1771226624,
    "id": "bf0d5c2e-f14b-9ad7-bc0d-ee0c8c9ee2d8",
    "model": "qwen3-max-2026-01-23",
    "object": "response",
    "output": [
        {
            "content": [
                {
                    "annotations": [],
                    "text": "Hi there!  I'm actually quite ......",
                    "type": "output_text"
                }
            ],
            "id": "msg_1e17fdb2-5fc3-4c78-a9e9-cbd78eb043f0",
            "role": "assistant",
            "status": "completed",
            "type": "message"
        }
    ],
    "parallel_tool_calls": false,
    "status": "completed",
    "tool_choice": "auto",
    "tools": [],
    "usage": {
        "input_tokens": 37,
        "input_tokens_details": {
            "cached_tokens": 0
        },
        "output_tokens": 220,
        "output_tokens_details": {
            "reasoning_tokens": 0
        },
        "total_tokens": 257,
        "x_details": [
            {
                "input_tokens": 37,
                "output_tokens": 220,
                "total_tokens": 257,
                "x_billing_type": "response_api"
            }
        ]
    }
}

多輪對話

通過 previous_response_id 參數自動關聯上下文,無需手動構建訊息歷史,當前響應id有效期間為7天。
previous_response_id 應傳入上一輪響應中的頂層 idresp_xxx,UUID格式),而不是 output 數組內訊息的 idmsg_56c860c4-3ad8-4a96-8553-d2f94c259xxx)。
Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# First round
response1 = client.responses.create(
    model="qwen3.8-max",
    input="My name is John, please remember it."
)
print(f"First response: {response1.output_text}")

# Second round - use previous_response_id to link context
# The response id expires in 7 days
response2 = client.responses.create(
    model="qwen3.8-max",
    input="Do you remember my name?",
    previous_response_id=response1.id
)
print(f"Second response: {response2.output_text}")
第二輪對話響應樣本
{
  "id": "f0dbb153-117f-9bbf-8176-5284b47f3xxx",
  "created_at": 1769173209.0,
  "model": "qwen3.8-max",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "id": "msg_56c860c4-3ad8-4a96-8553-d2f94c259xxx",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Yes, John! I remember your name. How can I assist you today?",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 78,
    "output_tokens": 16,
    "total_tokens": 94,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}
說明:第二輪對話的 input_tokens 為 78,包含了第一輪的上下文,模型成功記住了名字"John"。

深度思考

通過 reasoning 參數控制模型的推理強度。設定 reasoning.effort 後,模型會在回複前進行思考,思考內容通過 reasoning 類型的輸出項返回。effort 支援以下取值:
  • none:關閉思考,直接回答
  • minimal:最小化思考,最快速響應
  • low:輕度思考,側重快速響應
  • medium(預設值):中度思考,平衡速度與思考深度
  • high:深度思考,側重處理複雜專業問題
不支援 thinking_budget 參數控制最大思維長度。reasoning.effort 的優先順序高於 enable_thinking,建議優先使用 reasoning.effortenable_thinking 後續將不再支援。
Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

response = client.responses.create(
    model="qwen3.8-max",
    input="9.9和9.11誰大?",
    reasoning={"effort": "medium"}
)

# 處理輸出
for item in response.output:
    if item.type == "reasoning":
        print("=== 思考過程 ===")
        for summary in item.summary:
            print(summary.text)
    elif item.type == "message":
        print("\n=== 最終答案 ===")
        print(item.content[0].text)

# 查看思考 Token 數
print(f"\n思考 Token 數: {response.usage.output_tokens_details.reasoning_tokens}")
響應樣本
{
    "created_at": 1774498317,
    "id": "resp_xxx",
    "model": "qwen3.8-max",
    "object": "response",
    "output": [
        {
            "id": "msg_xxx",
            "summary": [
                {
                    "text": "Thinking Process:\n\n1.  **Analyze the Request:**\n    *   Question: \"9.9 和 9.11 誰大?\" (Which is larger, 9.9 or 9.11?)\n    *   Context: The user is asking a simple mathematical comparison question.\n    *   Current Date: Thursday, March 26, 2026 (provided in the system prompt).\n    *   Knowledge Cutoff: 2026 (provided in the system prompt).\n\n2.  **Evaluate the Numbers:**\n    *   Number A: 9.9\n    *   Number B: 9.11\n    *   These are decimal numbers.\n    *   Compare the integer part: Both are 9.\n    *   Compare the tenths place (first decimal digit):\n        *   9.9 has 9 in the tenths place.\n        *   9.11 has 1 in the tenths place.\n    *   Since 9 > 1, 9.9 is greater than 9.11.\n\n3.  **Consider Potential Ambiguities:**\n    *   Could this be version numbering? (e.g., software versions). In versioning, 9.11 is often \"newer\" or \"higher\" than 9.9. However, mathematically, 9.9 > 9.11.\n    *   Could this be dates? (September 9th vs September 11th). 11th is later.\n    *   Standard interpretation: Without context, decimal numbers are assumed to be mathematical values.\n    *   Common pitfall: Some people mistakenly treat decimals like whole numbers (where 11 > 9), leading them to think 9.11 > 9.9. This is a known cognitive bias or misconception in elementary math.\n    *   Decision: Provide the mathematical answer clearly, but perhaps acknowledge the versioning context if relevant (though usually, for this specific question, it's a math test). Given the simplicity, stick to the mathematical truth first.\n\n4.  **Formulate the Answer:**\n    *   Direct answer: 9.9 is larger.\n    *   Explanation: Compare place values. 9.9 = 9.90, 9.11 = 9.11. 90 hundredths > 11 hundredths.\n    *   Tone: Helpful, clear.\n\n5.  **Drafting the Response (Internal Monologue/Draft):**\n    *   Okay, mathematically 9.9 is bigger. 9.9 is 9 and 9 tenths. 9.11 is 9 and 11 hundredths (or 1 tenth and 1 hundredth). 9 tenths is more than 1 tenth.\n    *   So, 9.9 > 9.11.\n    *   I should answer in Chinese since the question is in Chinese.\n    *   \"9.9 更大。\" (9.9 is larger.)\n    *   Add a brief explanation to avoid confusion. \"因為 9.9 等於 9.90,而 9.90 大於 9.11。\" (Because 9.9 equals 9.90, and 9.90 is greater than 9.11.)\n\n6.  **Refining based on \"Version Number\" possibility:**\n    *   Sometimes this is a trick question about software versions. In semver, 9.11 > 9.9.\n    *   However, usually, when asked plainly \"which is larger\", it refers to numerical value.\n    *   I will provide the numerical answer as primary, maybe add a note about versions if it feels necessary. But keeping it simple is better. Most likely, this is testing the decimal comparison logic.\n    *   Let's stick to the mathematical value as the default.\n\n7.  **Final Polish:**\n    *   Answer: 9.9 大。\n    *   Reasoning: 比較小數時,先看整數部分,再看十分位。9.9 的十分位是 9,9.11 的十分位是 1。9 > 1,所以 9.9 > 9.11。\n\n8.  **Output Generation:** (Matching the thought process)\n    *   State clearly which is larger.\n    *   Explain why.\n\n    *Self-Correction on Date/Time:* The system prompt mentions the current date is 2026. This doesn't affect the math question, but I should ensure I don't reference anything post-2026 if I were adding context (not needed here).\n\n    *Final Decision:* Just answer the math question directly.\n\n    \"從數值上看,9.9 更大。\" (Numerically, 9.9 is larger.)\n    Explain: 9.9 = 9.90, 9.11 = 9.11. 90 > 11.\n\n    Wait, is there any other interpretation?\n    - Dates? 9/9 vs 9/11. 11th is later.\n    - Versions? 9.11 is newer.\n    - But \"誰大\" (who is big/larger) usually implies magnitude.\n    - I will answer based on numerical magnitude but briefly mention the version context if it adds value without confusing. Actually, better to be decisive. Numerical value is the standard interpretation for \"who is larger\" with numbers.\n\n    Let's go with the numerical answer.\n\n    **Plan:**\n    1. State 9.9 is larger numerically.\n    2. Explain the decimal comparison.\n    3. (Optional but helpful) Mention that if it's version numbers, 9.11 might be considered \"higher\". But prioritize the math.\n    Actually, for a simple query like this, over-explaining versions might be confusing. I'll stick to the math but acknowledge the common confusion.\n\n    *Revised Plan:*\n    1. Direct answer: 9.9 is larger (mathematically).\n    2. Explanation: Place value.\n    3. Note: Unless it's a version number.\n\n    Let's keep it concise.\n\n    \"在數學數值上,9.9 更大。\"\n    \"因為 9.9 等於 9.90,比 9.11 大。\"\n    \"如果是版本號碼,則 9.11 版本通常高於 9.9 版本。\"\n    This covers both bases.\n\n    Wait, looking at common AI training, this is often a \"trap\" question to see if the AI treats decimals like integers. The correct mathematical answer is crucial.\n\n    Okay, final output structure:\n    1. Mathematical answer.\n    2. Brief explanation.\n    3. Contextual note (versions).\n\n    Let's write it.\n    \"從數學數值上看,9.9 更大。\"\n    \"比較小數時,先看整數部分(都是 9),再看十分位:9.9 的十分位是 9,而 9.11 的十分位是 1。因為 9 > 1,所以 9.9 > 9.11。\"\n    \"不過,如果是軟體版本號碼,通常 9.11 版會比 9.9 版更新。\"\n\n    This is balanced.\n\n    Wait, I need to check the instruction again. \"Please remember the current actual time...\". This is just system context. I don't need to mention the date in the answer unless relevant. It's not relevant here.\n\n    Okay, ready to generate.\n\n    Wait, one more check. Is there any cultural context? In some contexts, people might say 9.11 is bigger because 11 > 9. This is the misconception I need to correct.\n    So, emphasizing the mathematical rule is key.\n\n    Final check:\n    9.9 = 9 + 9/10 = 9.90\n    9.11 = 9 + 1/10 + 1/100 = 9.11\n    9.90 > 9.11. Correct.\n\n    Response will be in Chinese.\n    \"從數值大小來看,9.9 更大。\"\n    Explain why.\n    Mention version exception.\n    Done.\n",
                    "type": "summary_text"
                }
            ],
            "type": "reasoning"
        },
        {
            "content": [
                {
                    "annotations": [],
                    "text": "從**數學數值**上看,**9.9 更大**。\n\n原因如下:\n比較小數時,先看整數部分,都是 9;再看十分位(小數點後第一位):\n*   9.9 的十分位是 **9**\n*   9.11 的十分位是 **1**\n\n因為 9 大於 1,所以 **9.9 > 9.11**(可以把 9.9 看作 9.90 來比較)。\n\n**注意**:如果是**軟體版本號碼**,通常 9.11 版會比 9.9 版更新(更高),但在純數字大小比較中,9.9 更大。",
                    "type": "output_text"
                }
            ],
            "id": "msg_xxx",
            "role": "assistant",
            "status": "completed",
            "type": "message"
        }
    ],
    "parallel_tool_calls": false,
    "status": "completed",
    "tool_choice": "auto",
    "tools": [],
    "usage": {
        "input_tokens": 57,
        "input_tokens_details": {
            "cached_tokens": 0
        },
        "output_tokens": 2018,
        "output_tokens_details": {
            "reasoning_tokens": 1861
        },
        "total_tokens": 2075,
        "x_details": [
            {
                "input_tokens": 57,
                "output_tokens": 2018,
                "output_tokens_details": {
                    "reasoning_tokens": 1861
                },
                "total_tokens": 2075,
                "x_billing_type": "response_api"
            }
        ]
    }
}

流式輸出

通過流式輸出即時接收模型產生的內容,適合長文本產生情境。
Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

stream = client.responses.create(
    model="qwen3.8-max",
    input="Please briefly introduce artificial intelligence.",
    stream=True
)

print("Receiving stream output:")
for event in stream:
    # print(event.model_dump_json())  # Uncomment to see raw event response
    if event.type == 'response.output_text.delta':
        print(event.delta, end='', flush=True)
    elif event.type == 'response.completed':
        print("\nStream completed")
        print(f"Total tokens: {event.response.usage.total_tokens}")
響應樣本
{"response":{"id":"47a71e7d-868c-4204-9693-ef8ff9058xxx","created_at":1769417481.0,"error":null,"incomplete_details":null,"instructions":null,"metadata":null,"model":"","object":"response","output":[],"parallel_tool_calls":false,"temperature":null,"tool_choice":"auto","tools":[],"top_p":null,"background":null,"completed_at":null,"conversation":null,"max_output_tokens":null,"max_tool_calls":null,"previous_response_id":null,"prompt":null,"prompt_cache_key":null,"prompt_cache_retention":null,"reasoning":null,"safety_identifier":null,"service_tier":null,"status":"queued","text":null,"top_logprobs":null,"truncation":null,"usage":null,"user":null},"sequence_number":0,"type":"response.created"}
{"response":{"id":"47a71e7d-868c-4204-9693-ef8ff9058xxx","created_at":1769417481.0,"error":null,"incomplete_details":null,"instructions":null,"metadata":null,"model":"","object":"response","output":[],"parallel_tool_calls":false,"temperature":null,"tool_choice":"auto","tools":[],"top_p":null,"background":null,"completed_at":null,"conversation":null,"max_output_tokens":null,"max_tool_calls":null,"previous_response_id":null,"prompt":null,"prompt_cache_key":null,"prompt_cache_retention":null,"reasoning":null,"safety_identifier":null,"service_tier":null,"status":"in_progress","text":null,"top_logprobs":null,"truncation":null,"usage":null,"user":null},"sequence_number":1,"type":"response.in_progress"}
{"item":{"id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","content":[],"role":"assistant","status":"in_progress","type":"message"},"output_index":0,"sequence_number":2,"type":"response.output_item.added"}
{"content_index":0,"item_id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","output_index":0,"part":{"annotations":[],"text":"","type":"output_text","logprobs":null},"sequence_number":3,"type":"response.content_part.added"}
{"content_index":0,"delta":"人工智慧","item_id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","logprobs":[],"output_index":0,"sequence_number":4,"type":"response.output_text.delta"}
{"content_index":0,"delta":"(Art","item_id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","logprobs":[],"output_index":0,"sequence_number":5,"type":"response.output_text.delta"}
{"content_index":0,"delta":"ificial Intelligence,","item_id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","logprobs":[],"output_index":0,"sequence_number":6,"type":"response.output_text.delta"}
{"content_index":0,"delta":"簡稱 AI)","item_id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","logprobs":[],"output_index":0,"sequence_number":7,"type":"response.output_text.delta"}
... (省略中間事件) ...
{"content_index":0,"delta":"領域,正在深刻改變我們的","item_id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","logprobs":[],"output_index":0,"sequence_number":38,"type":"response.output_text.delta"}
{"content_index":0,"delta":"生活和工作方式","item_id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","logprobs":[],"output_index":0,"sequence_number":39,"type":"response.output_text.delta"}
{"content_index":0,"delta":"。","item_id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","logprobs":[],"output_index":0,"sequence_number":40,"type":"response.output_text.delta"}
{"content_index":0,"item_id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","logprobs":[],"output_index":0,"sequence_number":41,"text":"人工智慧(Artificial Intelligence,簡稱 AI)是指由電腦系統類比人類智能行為的技術和科學。xxxx","type":"response.output_text.done"}
{"content_index":0,"item_id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","output_index":0,"part":{"annotations":[],"text":"人工智慧(Artificial Intelligence,簡稱 AI)是指由電腦系統類比人類智能行為的技術和科學。xxx","type":"output_text","logprobs":null},"sequence_number":42,"type":"response.content_part.done"}
{"item":{"id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","content":[{"annotations":[],"text":"人工智慧(Artificial Intelligence,簡稱 AI)是指由電腦系統類比人類智能行為的技術和科學。它旨在讓機器能夠執行通常需要人類智能才能完成的任務,例如:\n\n- **學習**(如通過資料訓練模型)  \n- **推理**(如邏輯判斷和問題求解)  \n- **感知**(如識別映像、語音或文字)  \n- **理解語言**(如自然語言處理)  \n- **決策**(如在複雜環境中做出最優選擇)\n\n人工智慧可分為**弱人工智慧**(專註於特定任務,如語音助手、推薦系統)和**強人工智慧**(具備類似人類的通用智能,目前尚未實現)。\n\n當前,AI 已廣泛應用於醫學、金融、交通、教育、娛樂等多個領域,正在深刻改變我們的生活和工作方式。","type":"output_text","logprobs":null}],"role":"assistant","status":"completed","type":"message"},"output_index":0,"sequence_number":43,"type":"response.output_item.done"}
{"response":{"id":"47a71e7d-868c-4204-9693-ef8ff9058xxx","created_at":1769417481.0,"error":null,"incomplete_details":null,"instructions":null,"metadata":null,"model":"qwen3.8-max","object":"response","output":[{"id":"msg_16db29d6-c1d3-47d7-9177-0fba81964xxx","content":[{"annotations":[],"text":"人工智慧(Artificial Intelligence,簡稱 AI)是xxxxxx","type":"output_text","logprobs":null}],"role":"assistant","status":"completed","type":"message"}],"parallel_tool_calls":false,"temperature":null,"tool_choice":"auto","tools":[],"top_p":null,"background":null,"completed_at":null,"conversation":null,"max_output_tokens":null,"max_tool_calls":null,"previous_response_id":null,"prompt":null,"prompt_cache_key":null,"prompt_cache_retention":null,"reasoning":null,"safety_identifier":null,"service_tier":null,"status":"completed","text":null,"top_logprobs":null,"truncation":null,"usage":{"input_tokens":37,"input_tokens_details":{"cached_tokens":0},"output_tokens":166,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":203},"user":null},"sequence_number":44,"type":"response.completed"}

調用內建工具

開啟內建工具可在處理複雜任務時獲得更佳效果,當前網頁抓取與代碼解譯器工具限時免費,支援的工具請參見工具調用
Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

response = client.responses.create(
    model="qwen3.8-max",
    input="Find the Alibaba Cloud website and extract key information",
    # For best results, enable all the built-in tools
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"},
        {"type": "web_extractor"}
    ],
    reasoning={"effort": "medium"}
)

# Uncomment the line below to see the intermediate output
# print(response.output)
print(response.output_text)
響應樣本
{
    "id": "69258b21-5099-9d09-92e8-8492b1955xxx",
    "object": "response",
    "status": "completed",
    "output": [
        {
            "type": "reasoning",
            "summary": [
                {
                    "type": "summary_text",
                    "text": "使用者要求找阿里雲官網並提取資訊..."
                }
            ]
        },
        {
            "type": "web_search_call",
            "status": "completed",
            "action": {
                "query": "阿里雲官網",
                "type": "search",
                "sources": [
                    {
                        "type": "url",
                        "url": "https://cn.aliyun.com/"
                    },
                    {
                        "type": "url",
                        "url": "https://www.alibabacloud.com/zh"
                    }
                ]
            }
        },
        {
            "type": "reasoning",
            "summary": [
                {
                    "type": "summary_text",
                    "text": "搜尋結果顯示阿里雲官網URL..."
                }
            ]
        },
        {
            "type": "web_extractor_call",
            "status": "completed",
            "goal": "提取阿里雲官網首頁的關鍵資訊",
            "output": "通義大模型、完整產品體系、AI解決方案...",
            "urls": [
                "https://cn.aliyun.com/"
            ]
        },
        {
            "type": "message",
            "role": "assistant",
            "status": "completed",
            "content": [
                {
                    "type": "output_text",
                    "text": "阿里雲官網關鍵資訊:通義大模型,雲端運算服務..."
                }
            ]
        }
    ],
    "usage": {
        "input_tokens": 40836,
        "output_tokens": 2106,
        "total_tokens": 42942,
        "output_tokens_details": {
            "reasoning_tokens": 677
        },
        "x_tools": {
            "web_extractor": {
                "count": 1
            },
            "web_search": {
                "count": 1
            }
        }
    }
}

Session 緩衝

在多輪對話情境中,開啟 Session 緩衝 可讓服務端自動緩衝對話上下文,降低推理延遲與使用成本。您無需手動管理緩衝,只需按正常多輪對話方式調用即可。 使用方式:在請求 Header 中添加 x-dashscope-session-cache: enable 開啟,或設定為 disable 關閉。預設值為 disable 支援的模型:qwen3.8-maxqwen3.8-flashqwen3.8-2.4t-a95bqwen3.8-27bqwen3-maxqwen3.7-maxqwen3.7-max-2026-05-20qwen3.7-max-2026-06-08qwen3.7-plusqwen3.7-plus-2026-05-26qwen3.6-plusqwen3.5-plusqwen3.7-flashqwen3.6-flashqwen3.5-flashqwen-plusqwen-flashqwen3-coder-plusqwen3-coder-flash
Session 緩衝 最小可緩衝提示詞長度為 1024 Token,緩衝有效期間為 5 分鐘。相關約束限制與顯式緩衝一致。
Session 緩衝的緩衝鍵由完整請求內容計算產生,包含 system prompt、user prompt、tools 等所有請求組成部分。僅當兩次請求的完整內容完全一致時,才能命中緩衝;user prompt 中僅修改一個字元,也會導致緩衝鍵不同,無法命中緩衝。 多輪對話中每輪 user prompt 不同,Session 緩衝的命中率會顯著下降。建議使用 previous_response_id 參數關聯歷史響應,複用歷史請求中 system prompt 部分的緩衝,僅新增內容需重新計算。
Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
    # 通過 default_headers 開啟 Session 緩衝
    default_headers={"x-dashscope-session-cache": "enable"}
)

# 構造超過 1024 Token 的長文本,確保能觸發緩衝建立(若未達到1024 Token,後續累積對話上下文超過1024 Token時將觸發緩衝建立)
long_context = "人工智慧是電腦科學的一個重要分支,致力於研究和開發能夠類比、延伸和擴充人類智能的理論、方法、技術及應用系統。" * 50

# 第一輪對話
response1 = client.responses.create(
    model="qwen3.8-max",
    input=long_context + "\n\n基於以上背景知識,請簡短介紹機器學習中的隨機森林演算法。",
)
print(f"第一輪迴複: {response1.output_text}")

# 第二輪對話:通過 previous_response_id 關聯上下文,緩衝由服務端自動處理
response2 = client.responses.create(
    model="qwen3.8-max",
    input="它和 GBDT 有什麼主要區別?",
    previous_response_id=response1.id,
)
print(f"第二輪迴複: {response2.output_text}")

# 查看快取命中情況
usage = response2.usage
print(f"輸入 Token: {usage.input_tokens}")
print(f"快取命中 Token: {usage.input_tokens_details.cached_tokens}")

從 Chat Completions 遷移到 Responses API

如果您當前使用的是 OpenAI Chat Completions API,可以通過以下步驟遷移到 Responses API。Responses API 提供了更簡潔的介面和更強大的功能,同時保持了與 Chat Completions 的相容性。

1. 更新端點地址

/v1/chat/completions 更新為 /v1/responses
Python
# Chat Completions API
completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)
print(completion.choices[0].message.content)

# Responses API - can use the same message format
response = client.responses.create(
    model="qwen3.8-max",
    input=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)
print(response.output_text)

# Responses API - or use a more concise format
response = client.responses.create(
    model="qwen3.8-max",
    input="Hello!"
)
print(response.output_text)

2. 更新響應處理

Responses API 的響應結構有所不同。使用 output_text 快捷方法擷取文本輸出,或通過 output 數組訪問詳細資料。 響應對比
# Chat Completions Response
{
  "id": "chatcmpl-416b0ea5-e362-9fec-97c5-0a60b5d7xxx",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "Hello! I'm happy to see you~  How can I help you?",
        "refusal": null,
        "role": "assistant",
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1769416269,
  "model": "qwen3.8-max",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 14,
    "prompt_tokens": 22,
    "total_tokens": 36,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}
# Responses API Response
{
  "id": "d69c735d-0f5e-4b6c-9c2a-8cab5eb14xxx",
  "created_at": 1769416269.0,
  "model": "qwen3.8-max",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "id": "msg_3426d3e5-8da7-4dd8-a6a5-7c2cd866xxx",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! Today is Monday, January 26, 2026. How can I help you? ",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 34,
    "output_tokens": 25,
    "total_tokens": 59,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

3. 簡化多輪對話管理

在 Chat Completions 中需要手動管理訊息歷史數組,而 Responses API 提供了 previous_response_id 參數自動關聯上下文,當前響應id有效期間為7天。
  • Python
  • Node.js
# Chat Completions - manual message history management
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"}
]
res1 = client.chat.completions.create(
    model="qwen3.8-max",
    messages=messages
)

# Manually add response to history
messages.append(res1.choices[0].message)
messages.append({"role": "user", "content": "What is its population?"})

res2 = client.chat.completions.create(
    model="qwen3.8-max",
    messages=messages
)
# Responses API - automatic linking with previous_response_id
res1 = client.responses.create(
    model="qwen3.8-max",
    input="What is the capital of France?"
)

# Just pass the previous response ID
res2 = client.responses.create(
    model="qwen3.8-max",
    input="What is its population?",
    previous_response_id=res1.id
)

4. 使用內建工具

Responses API 內建了多種工具,無需自行實現。只需在 tools 參數中指定即可,當前代碼解譯器與網頁抓取工具限時免費,詳情請參見工具調用
  • Python
  • Node.js
  • curl
# Chat Completions - need to implement tool functions yourself
def web_search(query):
    # Need to implement web search logic yourself
    import requests
    r = requests.get(f"https://api.example.com/search?q={query}")
    return r.json().get("results", [])

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "Who is the current president of France?"}],
    functions=[{
        "name": "web_search",
        "description": "Search the web for information",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"]
        }
    }]
)
# Responses API - use built-in tools directly
response = client.responses.create(
    model="qwen3.8-max",
    input="Who is the current president of France?",
    tools=[{"type": "web_search"}]  # Enable web search directly
)
print(response.output_text)

常見問題

Q:如何傳遞多輪對話的上下文?

A:在發起新一輪對話請求時,請將上一輪模型響應成功返回的id作為 previous_response_id 參數傳入。

Q:為何無法列印 output_text?

A:OpenAI Python SDK 在某些版本(如1.99.2)錯誤移除了該屬性,請更新 SDK 為最新版以避免該報錯。

相關文檔