跳转到主要内容
更多

连接复用配置

在高并发场景下复用 HTTP 连接,减少资源消耗、避免请求超时。

连接复用

DashScope SDK 支持通过复用已有连接来减少资源消耗,提高请求处理效率。
  • Java SDK:内置连接池机制,默认启用,可配置连接数、超时时间等参数。
  • Python SDK:通过传入自定义 HTTP 客户端实现连接复用,支持同步和异步两种方式。

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 {
    Generation gen = new Generation(Protocol.HTTP.getValue(), "https://maas.qianwenaiapi.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:.apiKey("sk-xxx")
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        // 此处以 qwen-plus 为例,可按需更换模型名称
        .model("qwen-plus")
        .messages(Arrays.asList(systemMsg, userMsg))
        .resultFormat(GenerationParam.ResultFormat.MESSAGE)
        .build();

    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("调用模型服务失败:" + e.getMessage());
    }
    System.exit(0);
  }
}

Python SDK

DashScope Python SDK 通过传入自定义 HTTP 客户端(httpx.Client / httpx.AsyncClient)实现连接复用,支持 HTTP 异步和 HTTP 同步两种调用方式。

HTTP 异步调用方式

异步场景下,通过 httpx.AsyncClient 配合 httpx.Limits 实现连接复用。httpx.Limits 支持以下参数:
参数含义默认值备注
max_connections总连接数限制。None(无限制)高并发场景下适当增大可提高并发能力。
max_keepalive_connections保持长连接的最大数量。None(无限制)控制连接池中保持活跃的连接数,避免对单一服务端造成过大压力。
keepalive_expiry长连接保活时间。5.0(秒)空闲长连接超过该时长后自动关闭。

代码示例

运行代码前,请配置 API Key 到环境变量并安装最新版 SDK。
import asyncio
import httpx
import os
import dashscope

async def main():
  # 配置连接参数
  limits = httpx.Limits(
    max_connections=100,           # 总连接数限制
    max_keepalive_connections=30,  # 保持长连接的最大数量
  )

  # 创建自定义 HTTP 客户端并传入 Client 构造
  async with httpx.AsyncClient(limits=limits) as http_client:
    aclient = dashscope.AsyncClient(
      api_key=os.getenv("DASHSCOPE_API_KEY"),
      base_url="https://maas.qianwenaiapi.com/api/v1",
      http_client=http_client,  # 传入自定义 HTTP 客户端
    )
    response = await aclient.chat.completions.create(
      model="qwen-plus",
      messages=[{"role": "user", "content": "你好,请介绍一下你自己"}],
    )
    print(response)

asyncio.run(main())

HTTP 同步调用方式

同步场景下,通过 httpx.Client 实现连接复用。同一个 HTTP 客户端内的多次请求会复用底层 TCP 连接,避免重复建连的开销。

代码示例

运行代码前,请配置 API Key 到环境变量并安装最新版 SDK。
import httpx
import os
import dashscope

# 使用 with 语句确保 HTTP 客户端正确关闭
with httpx.Client() as http_client:
  client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qianwenaiapi.com/api/v1",
    http_client=http_client,  # 传入自定义 HTTP 客户端
  )
  response = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "你好"}],
  )
  print(response)
如果需要在多次调用间复用同一个 HTTP 客户端:
import httpx
import os
import dashscope

# 创建 HTTP 客户端并配置连接复用参数
http_client = httpx.Client(
  limits=httpx.Limits(
    max_connections=100,          # 总连接数限制
    max_keepalive_connections=30, # 保持长连接的最大数量
  ),
)

client = dashscope.Client(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qianwenaiapi.com/api/v1",
  http_client=http_client,  # 传入自定义 HTTP 客户端
)

try:
  # 多次调用复用同一个 HTTP 客户端
  response1 = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "你好"}],
  )
  print(response1)

  response2 = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "介绍一下你自己"}],
  )
  print(response2)
finally:
  # 确保 HTTP 客户端正确关闭
  http_client.close()

最佳实践

  • Java SDK:根据业务并发量合理配置 connectionPoolSize、maximumAsyncRequests 等参数,避免连接数过高或过低。
  • Python SDK:推荐使用 with 语句自动管理 HTTP 客户端的生命周期,确保资源正确释放。
  • 选择合适的调用方式:异步架构(如 asyncio、FastAPI)使用异步调用,传统同步架构使用同步调用。

错误码

如果模型调用失败(Python SDK 会抛出 DashScopeError 异常,HTTP 调用返回报错信息),请参见错误码进行排查。