Copy

串連複用

DashScope SDK 支援通過複用已有的串連來減少資源消耗，提高請求處理效率。

Java SDK：內建串連池機制，支援配置串連數、逾時時間等參數，預設啟用。
Python SDK：支援通過傳入自訂 Session 實現串連複用，包括同步和非同步兩種方式。

Java SDK

DashScope Java SDK 內建了串連池機制，預設啟用。建議您根據具體業務合理調整串連池的串連數和逾時時間，最佳化串連複用效果。

配置參數說明

參數	含義	預設值	單位	備忘
connectTimeout	建立串連的逾時時間。	120	秒	在低延遲情境中，通常需要設定較短的連線逾時時間，以減少等待時間，提高響應速度。
readTimeout	讀取資料的逾時時間。	300	秒
writeTimeout	寫入資料的逾時時間。	60	秒
connectionIdleTimeout	串連池中空閑串連的逾時時間。	300	秒	在高並發情境下，適當延長空閑連線逾時時間，有利於避免頻繁建立串連，從而降低資源消耗。
connectionPoolSize	串連池中的最大串連數。	32	個	在高並發情境下：串連數過低時，可能導致請求阻塞或逾時，或者頻繁建立串連，增加資源消耗；串連數過高時，可能導致服務端負載過大。建議根據業務需求調整配置。
maximumAsyncRequests	最大並發請求數。全域的並發請求數限制（包含所有主機）。需要小於或等於最大串連數，否則可能出現請求阻塞的情況。	32	個
maximumAsyncRequestsPerHost	單台主機的最大並發請求數。需要小於或等於最大並發請求數。	32	個

程式碼範例

運行代碼前，請配置API Key到環境變數並安裝最新版SDK。以下程式碼範例展示了如何配置串連池相關參數（如逾時時間、最大串連數等），並調用大模型服務。您可以根據實際需求調整相關參數，以最佳化並發效能和資源使用率。

// 建議DashScope SDK的版本 >= 2.12.0
import java.time.Duration;
import java.util.Arrays;

import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.protocol.ConnectionConfigurations;
import com.alibaba.dashscope.protocol.Protocol;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        // 以下為新加坡地區URL，調用時請將WorkspaceId替換為真實的業務空間ID，各地區的URL不同。
        Generation gen = new Generation(Protocol.HTTP.getValue(), "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1");
        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .content("You are a helpful assistant.")
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content("你是誰？")
                .build();
        GenerationParam param = GenerationParam.builder()
                // 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                // 若沒有配置環境變數，請用百鍊API Key將下行替換為：.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 此處以qwen-plus為例，可按需更換模型名稱。模型列表：https://www.alibabacloud.com/help/zh/model-studio/getting-started/models
                .model("qwen-plus")
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .build();

        System.out.println(userMsg.getContent());
        return gen.call(param);
    }
    public static void main(String[] args) {
        // 串連池配置
        Constants.connectionConfigurations = ConnectionConfigurations.builder()
                .connectTimeout(Duration.ofSeconds(10))  // 建立串連的逾時時間, 預設 120s
                .readTimeout(Duration.ofSeconds(300)) // 讀取資料的逾時時間, 預設 300s
                .writeTimeout(Duration.ofSeconds(60)) // 寫入資料的逾時時間, 預設 60s
                .connectionIdleTimeout(Duration.ofSeconds(300)) // 串連池中空閑串連的逾時時間, 預設 300s
                .connectionPoolSize(256) // 串連池中的最大串連數, 預設 32
                .maximumAsyncRequests(256)  // 最大並發請求數, 預設 32
                .maximumAsyncRequestsPerHost(256) // 單個主機的最大並發請求數, 預設 32
                .build();

        try {
            GenerationResult result = callWithMessage();
            System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent());
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // 使用日誌架構記錄異常資訊
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
        System.exit(0);
    }
}

Python SDK

DashScope Python SDK 支援通過傳入自訂 Session 實現串連複用，提供HTTP非同步（協程）和HTTP同步兩種調用方式。

HTTP非同步呼叫方式

在非同步呼叫情境中，您可以通過 aiohttp.ClientSession 配合 aiohttp.TCPConnector 實現串連複用。TCPConnector 支援配置串連數限制等參數：

參數	含義	預設值	備忘
limit	總串連數限制	100	控制最大串連數。在高並發情境下，適當增加此值可以提高並發能力。
limit_per_host	每個主機的串連數限制	0（無限制）	限制對單個主機的最大串連數，避免對單一服務端造成過大壓力。
ssl	SSL上下文配置	None	用於HTTPS串連的SSL認證驗證配置。

程式碼範例

運行代碼前，請配置API Key到環境變數並安裝最新版SDK。以下程式碼範例展示了如何在非同步情境下配置串連複用，並調用大模型服務：

import asyncio
import aiohttp
import ssl
import certifi
from dashscope import AioGeneration
import dashscope
import os

async def main():
    # 以下為新加坡地區URL，調用時請將WorkspaceId替換為真實的業務空間ID，各地區的URL不同。
    dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

    # 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    # 若沒有配置環境變數，請用百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
    dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

    # 配置串連參數
    connector = aiohttp.TCPConnector(
        limit=100,           # 總串連數限制
        limit_per_host=30,   # 每個主機的串連數限制
        ssl=ssl.create_default_context(cafile=certifi.where()),
    )

    # 建立自訂Session並傳入調用方法
    async with aiohttp.ClientSession(connector=connector) as session:
        response = await AioGeneration.call(
            model='qwen-plus',
            prompt='你好，請介紹一下你自己',
            session=session,  # 傳入自訂 Session
        )
        print(response)

asyncio.run(main())

HTTP同步調用方式

在同步調用情境中，您可以通過 requests.Session 實現串連複用。在同一個 Session 內的多次請求會複用底層 TCP 串連，避免重複建立串連的開銷。

程式碼範例

運行代碼前，請配置API Key到環境變數並安裝最新版SDK。以下程式碼範例展示了如何在同步情境下配置串連複用，並調用大模型服務：

import requests
from dashscope import Generation
import dashscope
import os

# 以下為新加坡地區URL，調用時請將WorkspaceId替換為真實的業務空間ID，各地區的URL不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# 使用 with 語句確保 Session 正確關閉
with requests.Session() as session:
    response = Generation.call(
        model='qwen-plus',
        prompt='你好',
        session=session  # 傳入自訂 Session
    )
    print(response)

如果需要在多次調用中複用同一個 Session，可以採用以下方式：

import requests
from dashscope import Generation
import dashscope
import os

# 以下為新加坡地區URL，調用時請將WorkspaceId替換為真實的業務空間ID，各地區的URL不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# 建立 Session 對象
session = requests.Session()

try:
    # 多次調用複用同一個 Session
    response1 = Generation.call(
        model='qwen-plus',
        prompt='你好',
        session=session
    )
    print(response1)

    response2 = Generation.call(
        model='qwen-plus',
        prompt='介紹一下你自己',
        session=session
    )
    print(response2)
finally:
    # 確保 Session 正確關閉
    session.close()

最佳實務

Java SDK：根據業務並發量合理配置 connectionPoolSize、maximumAsyncRequests 等參數，避免串連數過高或過低。
Python SDK：推薦使用 with 語句自動管理 Session 的生命週期，確保資源正確釋放。
選擇合適的調用方式：如果您的應用是非同步架構（如使用 asyncio、FastAPI 等），建議使用非同步呼叫方式；如果是傳統同步架構，使用同步調用方式即可。

錯誤碼

如果模型調用失敗並返回報錯資訊，請參見錯誤碼進行解決。

​串連複用

​Java SDK

​配置參數說明

​程式碼範例

​Python SDK

​HTTP非同步呼叫方式

​程式碼範例

​HTTP同步調用方式

​程式碼範例

​最佳實務

​錯誤碼

串連複用

Java SDK

配置參數說明

程式碼範例

Python SDK

HTTP非同步呼叫方式

程式碼範例

HTTP同步調用方式

程式碼範例

最佳實務

錯誤碼