Todos os produtos
Search

Este produto

    Alibaba Cloud Model Studio:Configure connection reuse for DashScope SDK

    Central de documentação

    Alibaba Cloud Model Studio:Configure connection reuse for DashScope SDK

    Última atualização: Oct 27, 2026

    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 httpx
import os
import dashscope

async def main():
    # Configure os parâmetros de conexão
    limits = httpx.Limits(
        max_connections=100,           # Limite total de conexões
        max_keepalive_connections=30,  # Número máximo de conexões keep-alive
    )

    # Crie um cliente HTTP personalizado e passe-o para o construtor do Client
    async with httpx.AsyncClient(limits=limits) as http_client:
        # Esta é a configuração da região China (Pequim). A configuração varia conforme a região.
        # As API Keys das regiões Singapura e Pequim são diferentes. Obtenha uma API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
        # Se a variável de ambiente não estiver configurada, defina sua API Key diretamente: api_key = "sk-xxx"
        aclient = dashscope.AsyncClient(
            api_key=os.getenv("DASHSCOPE_API_KEY"),
            base_url="https://dashscope.aliyuncs.com/api/v1",
            http_client=http_client,  # Passe o cliente HTTP personalizado
        )
        response = await aclient.chat.completions.create(
            model='qwen-plus',
            messages=[{"role": "user", "content": 'Hello, please introduce yourself'}],
        )
        print(response)

asyncio.run(main())

    import asyncio
import httpx
import os
import dashscope

async def main():
    # Configure os parâmetros de conexão
    limits = httpx.Limits(
        max_connections=100,           # Limite total de conexões
        max_keepalive_connections=30,  # Número máximo de conexões keep-alive
    )

    # Crie um cliente HTTP personalizado e passe-o para o construtor do Client
    async with httpx.AsyncClient(limits=limits) as http_client:
        # A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
        # A API Key da região Singapura é diferente da da região Pequim. Obtenha uma API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
        # Se a variável de ambiente não estiver configurada, defina sua API Key diretamente: api_key = "sk-xxx"
        aclient = dashscope.AsyncClient(
            api_key=os.getenv("DASHSCOPE_API_KEY"),
            workspace="{WorkspaceId}",
            region="ap-southeast-1",
            http_client=http_client,  # Passe o cliente HTTP personalizado
        )
        response = await aclient.chat.completions.create(
            model='qwen-plus',
            messages=[{"role": "user", "content": 'Hello, please introduce yourself'}],
        )
        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 httpx
import os
import dashscope

# Use a instrução with para garantir que o cliente HTTP seja fechado corretamente
with httpx.Client() as http_client:
    # Esta é a configuração da região China (Pequim). A configuração varia conforme a região.
    # As API Keys das regiões Singapura e Pequim são diferentes. Obtenha uma API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
    # Se a variável de ambiente não estiver configurada, defina sua API Key diretamente: api_key = "sk-xxx"
    client = dashscope.Client(
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        base_url="https://dashscope.aliyuncs.com/api/v1",
        http_client=http_client,  # Passe o cliente HTTP personalizado
    )
    response = client.chat.completions.create(
        model='qwen-plus',
        messages=[{"role": "user", "content": 'Hello'}],
    )
    print(response)

    import httpx
import os
import dashscope

# Use a instrução with para garantir que o cliente HTTP seja fechado corretamente
with httpx.Client() as http_client:
    # A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
    # A API Key da região Singapura é diferente da da região Pequim. Obtenha uma API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
    # Se a variável de ambiente não estiver configurada, defina sua API Key diretamente: api_key = "sk-xxx"
    client = dashscope.Client(
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        workspace="{WorkspaceId}",
        region="ap-southeast-1",
        http_client=http_client,  # Passe o cliente HTTP personalizado
    )
    response = client.chat.completions.create(
        model='qwen-plus',
        messages=[{"role": "user", "content": 'Hello'}],
    )
    print(response)

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

    Para reutilizar uma Session em várias chamadas:

    import httpx
import os
import dashscope

# Crie um objeto de cliente HTTP e configure os parâmetros de reutilização de conexão
http_client = httpx.Client(
    limits=httpx.Limits(
        max_connections=100,          # Limite total de conexões
        max_keepalive_connections=30, # Número máximo de conexões keep-alive
    ),
)

# Esta é a configuração da região China (Pequim). A configuração varia conforme a região.
# As API Keys das regiões Singapura e Pequim são diferentes. Obtenha uma API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, defina sua API Key diretamente: api_key = "sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/api/v1",
    http_client=http_client,  # Passe o cliente HTTP personalizado
)

try:
    # Reutilize o mesmo cliente HTTP em múltiplas chamadas
    response1 = client.chat.completions.create(
        model='qwen-plus',
        messages=[{"role": "user", "content": 'Hello'}],
    )
    print(response1)

    response2 = client.chat.completions.create(
        model='qwen-plus',
        messages=[{"role": "user", "content": 'Introduce yourself'}],
    )
    print(response2)
finally:
    # Garanta que o cliente HTTP seja fechado corretamente
    http_client.close()

    import httpx
import os
import dashscope

# Crie um objeto de cliente HTTP e configure os parâmetros de reutilização de conexão
http_client = httpx.Client(
    limits=httpx.Limits(
        max_connections=100,          # Limite total de conexões
        max_keepalive_connections=30, # Número máximo de conexões keep-alive
    ),
)

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
# A API Key da região Singapura é diferente da da região Pequim. Obtenha uma API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, defina sua API Key diretamente: api_key = "sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
    http_client=http_client,  # Passe o cliente HTTP personalizado
)

try:
    # Reutilize o mesmo cliente HTTP em múltiplas chamadas
    response1 = client.chat.completions.create(
        model='qwen-plus',
        messages=[{"role": "user", "content": 'Hello'}],
    )
    print(response1)

    response2 = client.chat.completions.create(
        model='qwen-plus',
        messages=[{"role": "user", "content": 'Introduce yourself'}],
    )
    print(response2)
finally:
    # Garanta que o cliente HTTP seja fechado corretamente
    http_client.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.