Skip to main content
Mais

Configure connection reuse for DashScope SDK

Sem a reutilização de conexões, cada chamada de API abre uma nova conexão TCP e executa um handshake TLS, o que aumenta a latência. Em cenários de alta concorrência, essa sobrecarga causa timeouts e desperdício de recursos. A reutilização de conexões elimina a configuração repetida, reduzindo a latência e o consumo de recursos.

O DashScope SDK oferece suporte à reutilização de conexões em Java e Python:
  • Java SDK: Um pool de conexões integrado vem ativado por padrão. Configure parâmetros como limite de conexões e tempos limite.
  • Python SDK: Ative a reutilização de conexões passando uma Session personalizada. O SDK suporta chamadas síncronas e assíncronas.

Antes de começar

Antes de executar os exemplos de código:
  1. Exporte a chave da API como variável de ambiente.
  2. Instale o SDK mais recente.

Java SDK

O Java SDK inclui um pool de conexões integrado, ativado por padrão. Ajuste as configurações de limite de conexões e timeout para otimizar sua carga de trabalho.

Parâmetros

Parâmetro

Descrição

Valor padrão

Unidade

connectTimeout

Tempo limite para estabelecimento da conexão.

120

segundos

readTimeout

Tempo limite para leitura de dados.

300

segundos

writeTimeout

Tempo limite para gravação de dados.

60

segundos

connectionIdleTimeout

Tempo limite para conexões ociosas no pool.

300

segundos

connectionPoolSize

Número máximo de conexões no pool.

32

conexões

maximumAsyncRequests

Limite de requisições simultâneas em todos os hosts (limite global).

32

requisições

maximumAsyncRequestsPerHost

Limite de requisições simultâneas por host.

32

requisições

Restrições de parâmetros:
  • maximumAsyncRequests deve ser ≤ connectionPoolSize; caso contrário, as requisições podem sofrer bloqueio.
  • maximumAsyncRequestsPerHost deve ser ≤ maximumAsyncRequests.
Diretrizes de ajuste:
  • connectTimeout: Em cenários de baixa latência, defina um tempo limite menor para reduzir o tempo de espera.
  • connectionIdleTimeout: Para cenários de alta concorrência, aumente o tempo limite de ociosidade para evitar a criação frequente de conexões e reduzir o consumo de recursos.
  • connectionPoolSize: Poucas conexões em ambientes de alta concorrência causam bloqueios, timeouts e reconexões frequentes (maior uso de recursos). Por outro lado, conexões em excesso sobrecarregam o servidor. Equilibre a quantidade de conexões com base na sua carga de trabalho.

Exemplo de código

O exemplo abaixo configura os parâmetros do pool de conexões (timeout e limite de conexões) e chama um serviço de modelo. Ajuste os parâmetros para otimizar a concorrência e o uso de recursos. 
// Recommended DashScope SDK version >= 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.utils.Constants;

public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        Generation gen = new Generation();
        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .content("You are a helpful assistant.")
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content("Who are you?")
                .build();
        GenerationParam param = GenerationParam.builder()
                // API keys for Singapore and Beijing regions differ. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                // If you have not configured the environment variable, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // This example uses qwen-plus. Change the model name as needed. Model list: https://www.alibabacloud.com/help/en/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) {
        // Connection pool configuration
        Constants.connectionConfigurations = ConnectionConfigurations.builder()
                .connectTimeout(Duration.ofSeconds(10))  // Timeout for establishing a connection, default 120s
                .readTimeout(Duration.ofSeconds(300)) // Timeout for reading data, default 300s
                .writeTimeout(Duration.ofSeconds(60)) // Timeout for writing data, default 60s
                .connectionIdleTimeout(Duration.ofSeconds(300)) // Timeout for idle connections in the connection pool, default 300s
                .connectionPoolSize(256) // Maximum connections in the connection pool, default 32
                .maximumAsyncRequests(256)  // Maximum concurrent requests, default 32
                .maximumAsyncRequestsPerHost(256) // Maximum concurrent requests per host, default 32
                .build();

        try {
            GenerationResult result = callWithMessage();
            System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent());
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // Use a logging framework to record exception information
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
        System.exit(0);
    }
}

// Recommended DashScope SDK version >= 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 {
        // This is the Singapore region URL. Replace WorkspaceId with your actual workspace ID. URLs differ by region.
        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("Who are you?")
                .build();
        GenerationParam param = GenerationParam.builder()
                // API keys for Singapore and Beijing regions differ. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                // If you have not configured the environment variable, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // This example uses qwen-plus. Change the model name as needed. Model list: https://www.alibabacloud.com/help/en/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) {
        // Connection pool configuration
        Constants.connectionConfigurations = ConnectionConfigurations.builder()
                .connectTimeout(Duration.ofSeconds(10))  // Timeout for establishing a connection, default 120s
                .readTimeout(Duration.ofSeconds(300)) // Timeout for reading data, default 300s
                .writeTimeout(Duration.ofSeconds(60)) // Timeout for writing data, default 60s
                .connectionIdleTimeout(Duration.ofSeconds(300)) // Timeout for idle connections in the connection pool, default 300s
                .connectionPoolSize(256) // Maximum connections in the connection pool, default 32
                .maximumAsyncRequests(256)  // Maximum concurrent requests, default 32
                .maximumAsyncRequestsPerHost(256) // Maximum concurrent requests per host, default 32
                .build();

        try {
            GenerationResult result = callWithMessage();
            System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent());
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // Use a logging framework to record exception information
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
        System.exit(0);
    }
}

Python SDK

O Python SDK permite a reutilização de conexões ao passar uma Session personalizada. Dois métodos de chamada têm suporte: HTTP assíncrono (baseado em corrotinas) e HTTP síncrono.

HTTP Assíncrono

Para cenários assíncronos, use aiohttp.ClientSession com aiohttp.TCPConnector para ativar a reutilização de conexões. O TCPConnector permite configurar parâmetros como limites de conexão:

Parâmetro

Descrição

Valor padrão

Observações

limit

Limite total de conexões (todos os hosts).

100

Em cenários de alta concorrência, aumente este valor para melhorar a capacidade de processamento simultâneo.

limit_per_host

Limite de conexões por host.

0 (ilimitado)

Evita sobrecarga excessiva em um único host.

ssl

Configuração do contexto SSL.

None

Validação de certificado SSL para HTTPS.

Exemplo de código

O exemplo a seguir configura a reutilização de conexões e chama um serviço de modelo de forma assíncrona: 
import asyncio
import aiohttp
import ssl
import certifi
from dashscope import AioGeneration
import dashscope
import os

async def main():
    # This is the URL for the China (Beijing) region. URLs differ by region.
    dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

    # API keys for Singapore and Beijing regions differ. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    # If you have not configured the environment variable, replace the following line with your Model Studio API key: dashscope.api_key = "sk-xxx"
    dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

    # Configure connection parameters
    connector = aiohttp.TCPConnector(
        limit=100,           # Total connection limit
        limit_per_host=30,   # Connection limit per host
        ssl=ssl.create_default_context(cafile=certifi.where()),
    )

    # Create a custom Session and pass it to the call method
    async with aiohttp.ClientSession(connector=connector) as session:
        response = await AioGeneration.call(
            model='qwen-plus',
            prompt='Hello, please introduce yourself',
            session=session,  # Pass the custom Session
        )
        print(response)

asyncio.run(main())

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

async def main():
    # This is the Singapore region URL. Replace WorkspaceId with your actual workspace ID. URLs differ by region.
    dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

    # API keys for Singapore and Beijing regions differ. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    # If you have not configured the environment variable, replace the following line with your Model Studio API key: dashscope.api_key = "sk-xxx"
    dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

    # Configure connection parameters
    connector = aiohttp.TCPConnector(
        limit=100,           # Total connection limit
        limit_per_host=30,   # Connection limit per host
        ssl=ssl.create_default_context(cafile=certifi.where()),
    )

    # Create a custom Session and pass it to the call method
    async with aiohttp.ClientSession(connector=connector) as session:
        response = await AioGeneration.call(
            model='qwen-plus',
            prompt='Hello, please introduce yourself',
            session=session,  # Pass the custom Session
        )
        print(response)

asyncio.run(main())

HTTP Síncrono

Em cenários síncronos, use requests.Session para ativar a reutilização de conexões. Múltiplas requisições dentro da mesma Session reaproveitam a conexão TCP subjacente, evitando a sobrecarga de estabelecer conexões repetidamente.

Exemplo de código: chamada única

Este exemplo demonstra a configuração de reutilização de conexões para chamar um serviço de modelo sincronamente: 
import requests
from dashscope import Generation
import dashscope
import os

# This is the URL for the China (Beijing) region. URLs differ by region.
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

# API keys for Singapore and Beijing regions differ. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# Use with statement to ensure Session closes correctly
with requests.Session() as session:
    response = Generation.call(
        model='qwen-plus',
        prompt='Hello',
        session=session  # Pass the custom Session
    )
    print(response)

import requests
from dashscope import Generation
import dashscope
import os

# This is the Singapore region URL. Replace WorkspaceId with your actual workspace ID. URLs differ by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# API keys for Singapore and Beijing regions differ. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# Use with statement to ensure Session closes correctly
with requests.Session() as session:
    response = Generation.call(
        model='qwen-plus',
        prompt='Hello',
        session=session  # Pass the custom Session
    )
    print(response)

Exemplo de código: múltiplas chamadas com uma Session compartilhada

Para reutilizar uma Session em várias chamadas: 
import requests
from dashscope import Generation
import dashscope
import os

# This is the URL for the China (Beijing) region. URLs differ by region.
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

# API keys for Singapore and Beijing regions differ. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# Create a Session object
session = requests.Session()

try:
    # Reuse the same Session for multiple calls
    response1 = Generation.call(
        model='qwen-plus',
        prompt='Hello',
        session=session
    )
    print(response1)

    response2 = Generation.call(
        model='qwen-plus',
        prompt='Introduce yourself',
        session=session
    )
    print(response2)
finally:
    # Ensure Session closes correctly
    session.close()

import requests
from dashscope import Generation
import dashscope
import os

# This is the Singapore region URL. Replace WorkspaceId with your actual workspace ID. URLs differ by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# API keys for Singapore and Beijing regions differ. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# Create a Session object
session = requests.Session()

try:
    # Reuse the same Session for multiple calls
    response1 = Generation.call(
        model='qwen-plus',
        prompt='Hello',
        session=session
    )
    print(response1)

    response2 = Generation.call(
        model='qwen-plus',
        prompt='Introduce yourself',
        session=session
    )
    print(response2)
finally:
    # Ensure Session closes correctly
    session.close()

Melhores práticas

  • Java SDK: Defina connectionPoolSize e maximumAsyncRequests conforme sua carga de trabalho. Encontre o equilíbrio na quantidade de conexões: poucas causam bloqueios, enquanto muitas sobrecarregam o servidor.
  • Python SDK: Utilize a instrução with para gerenciar o ciclo de vida da Session e garantir a limpeza correta dos recursos.
  • Escolha o método adequado: Opte por chamadas assíncronas em aplicações assíncronas (asyncio, FastAPI). Prefira chamadas síncronas para aplicações tradicionais.

Códigos de erro

Se uma chamada de modelo falhar, consulte Mensagens de erro para resolver o problema.
Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais