Todos os produtos
Search
Central de documentação

Platform For AI:Apêndice: Configure timeouts de gateway dedicado

Última atualização: Jul 16, 2026

Configure timeouts de conexão ociosa e de requisição para gateways dedicados em clientes Java, Go e EAS SDK e solucione problemas comuns relacionados a timeout.

Contexto

Por que os timeouts são importantes

Em sistemas distribuídos, as cadeias de chamadas entre services podem ser extensas. Atrasos ou falhas em qualquer ponto podem deixar requisições pendentes. Uma configuração adequada de timeout ajuda a:

  • Evitar exaustão de recursos: impede que clientes ou gateways mantenham conexões e threads ocupadas enquanto aguardam resposta de um service de backend.

  • Melhorar a experiência do usuário: retorna falhas rapidamente para que os chamadores tentem novamente ou usem alternativas conforme necessário.

  • Manter a estabilidade do sistema: libera recursos antecipadamente para evitar que services lentos ou instáveis afetem toda a cadeia de chamadas.

Configure o timeout de conexão ociosa

O timeout de conexão ociosa encerra uma conexão após um período sem transferência de dados. Esse mecanismo gerencia pools de conexões e libera recursos inativos.

Configuração recomendada

O gateway totalmente gerenciado utiliza valores fixos para o timeout de conexão ociosa. Não é possível modificar esses valores.

  • Gateway como servidor (voltado para clientes): fixo em 600 seconds. Se uma conexão entre cliente e gateway ficar ociosa por mais tempo que esse período, o gateway a encerrará.

  • Gateway como cliente (voltado para services de inferência de backend): fixo em 30 seconds. Se uma conexão entre o gateway e o backend ficar ociosa por mais tempo que esse período, o gateway a encerrará.

O diagrama a seguir ilustra o fluxo de conexão:

image

Para garantir que o cliente gerencie e encerre as conexões, configure cada enlace da seguinte forma:

Enlace

Configuração recomendada

Objetivo

Cliente → Gateway

Timeout de ociosidade do cliente < timeout de ociosidade do servidor no gateway

Evita que o cliente reutilize uma conexão já encerrada pelo gateway

Gateway → Service de inferência de backend

Timeout de ociosidade do cliente no gateway < timeout de ociosidade do servidor no service de inferência de backend

Evita que o gateway reutilize uma conexão já encerrada pelo service de inferência de backend

Mantenha uma margem de segurança entre os valores upstream e downstream. Evite definir timeouts relacionados com o mesmo valor.

Importante

O timeout de conexão ociosa não é um timeout de execução de requisição. O vLLM e o SGLang utilizam HTTP/1.1 Keep-Alive. Com esse mecanismo, o timeout de ociosidade do servidor da engine só começa a contar após a conclusão de uma resposta, enquanto aguarda a próxima requisição na mesma conexão. Definir esse valor como 60 segundos não interrompe uma requisição de inferência longa ou em streaming.

Valores padrão por método de acesso

A tabela a seguir lista o timeout padrão de conexão ociosa para cada método de acesso, juntamente com as configurações recomendadas para o cliente e para o service de inferência de backend.

Nota

Não é possível modificar os valores de timeout de conexão ociosa do gateway. Para solicitar uma alteração, envie um ticket.

Método de acesso

Timeout de ociosidade do servidor no gateway

Timeout de ociosidade do cliente no gateway

Timeout de ociosidade recomendado para o cliente

Timeout de ociosidade recomendado para o servidor de backend

Gateway totalmente gerenciado (gateway MSE)

600 segundos

30 segundos

Menor que 600 segundos

Maior que 30 segundos

Gateway dedicado ALB

600 segundos

15 segundos

Menor que 600 segundos

Maior que 15 segundos

Balanceamento de carga NLB

900 segundos

900 segundos

Menor que 900 segundos

Maior que 900 segundos, com margem de segurança

Padrões do modelo Model Gallery e considerações sobre NLB

O timeout de ociosidade do servidor no service de inferência de backend deve ser maior que o timeout de ociosidade do cliente no gateway.

Ao implantar um service de inferência vLLM ou SGLang com um modelo do Model Gallery, o modelo define o HTTP Keep-Alive da engine como 60 segundos por padrão.

Framework de inferência

Variável de ambiente

Padrão do modelo Model Gallery

vLLM

VLLM_HTTP_TIMEOUT_KEEP_ALIVE

60 segundos

SGLang

SGLANG_TIMEOUT_KEEP_ALIVE

60 segundos

Para o gateway totalmente gerenciado e o gateway dedicado ALB, a configuração padrão funciona da seguinte maneira:

  • Timeout de ociosidade do servidor da engine no Model Gallery (60 segundos) > Timeout de ociosidade do cliente no gateway ALB (15 segundos)

  • Timeout de ociosidade do servidor da engine no Model Gallery (60 segundos) > Timeout de ociosidade do cliente no gateway totalmente gerenciado (30 segundos)

O valor padrão de 60 segundos do modelo Model Gallery atende aos requisitos tanto do gateway dedicado ALB quanto do gateway totalmente gerenciado.

O NLB requer atenção especial:

Timeout de ociosidade do servidor da engine no Model Gallery (60 segundos) < Timeout de ociosidade do cliente no NLB (900 segundos)

Nessa configuração, o service de inferência de backend pode encerrar primeiro as conexões ociosas, enquanto o NLB ou o gerenciamento de conexões upstream ainda considera a conexão disponível. Requisições subsequentes que reutilizarem essa conexão podem encontrar erros EOF, RST, redefinição de conexão ou falhas intermitentes 502/503.

Ao usar NLB com services vLLM ou SGLang implantados via Model Gallery, defina o timeout de ociosidade do servidor no service de inferência de backend com um valor maior que 900 segundos, incluindo uma margem de segurança. Por exemplo:

# vLLM, example value
VLLM_HTTP_TIMEOUT_KEEP_ALIVE=1000

# SGLang, example value
SGLANG_TIMEOUT_KEEP_ALIVE=1000
Importante

Modificar variáveis de ambiente do service EAS aciona uma recompilação ou atualização contínua do service. Realize alterações fora dos horários de pico e confirme previamente a capacidade das réplicas, o desligamento graceful e os procedimentos de rollback. Imagens personalizadas e versões mais antigas da engine podem não suportar essas variáveis de ambiente. Consulte a documentação da imagem para obter detalhes.

Exemplos de configuração do cliente

O timeout de ociosidade do cliente deve ser menor que o timeout de ociosidade do servidor no gateway. Os exemplos a seguir mostram como gerenciar ou definir o timeout de conexão ociosa do cliente em diferentes linguagens de programação.

Importante

Estes exemplos servem apenas como referência de parâmetros e não se destinam ao uso direto em sistemas de produção. Os valores reais dependem dos padrões de tráfego, condições de carga e características da versão do cliente.

Java

O gerenciador de conexões Apache HttpClient 4.x limpa conexões ociosas chamando periodicamente closeIdleConnections(). O exemplo a seguir define o timeout de conexão ociosa do cliente como 500 segundos, valor inferior ao timeout de ociosidade do servidor de 600 segundos do gateway totalmente gerenciado e do gateway dedicado ALB, e também inferior ao timeout de 900 segundos do NLB.

import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
import org.apache.http.client.config.RequestConfig;
import java.util.concurrent.TimeUnit;

public class HttpClientIdleTimeout {
    public static void main(String[] args) throws InterruptedException {
        PoolingHttpClientConnectionManager cm = new PoolingHttpClientConnectionManager();
        // Example value: max connections per route
        cm.setDefaultMaxPerRoute(20);
         // Example value: max total connections
        cm.setMaxTotal(100);

        RequestConfig requestConfig = RequestConfig.custom()
                // Example value: connect timeout 5 seconds
                .setConnectTimeout(5000)
                // Example value: read timeout 10 seconds
                .setSocketTimeout(10000)
                .build();

        try (CloseableHttpClient httpClient = HttpClients.custom()
                .setConnectionManager(cm)
                .setDefaultRequestConfig(requestConfig)
                .build()) {

            // Start a background thread to clean up idle connections periodically
            Thread cleanerThread = new Thread(() -> {
                try {
                    while (!Thread.currentThread().isInterrupted()) {
                        // Example value: check every 5 seconds
                        Thread.sleep(5000);
                        // Close connections idle for more than 500 seconds (less than gateway idle timeout of 600 seconds)
                        cm.closeIdleConnections(500, TimeUnit.SECONDS);
                        // Close expired connections (e.g., connections closed by the server)
                        cm.closeExpiredConnections();
                    }
                } catch (InterruptedException e) {
                    // Restore interrupted status
                    Thread.currentThread().interrupt();
                }
            });
            // Set as daemon thread so it exits when the main thread exits
            cleanerThread.setDaemon(true);
            cleanerThread.start();

            // Execute HTTP requests...
            // Example: httpClient.execute(new HttpGet("http://your-gateway-url"));

            // Simulate the program running for a period. Example value: run for 1 minute
            Thread.sleep(60000);

            // Stop the cleaner thread (in production, gracefully shut it down during application shutdown)
            cleanerThread.interrupt();

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Go

A biblioteca net/http do Go permite definir o timeout de ociosidade do pool de conexões do cliente por meio de Transport.IdleConnTimeout.

package main

import (
    "net/http"
    "time"
)

func main() {
    // Create a custom Transport
    tr := &http.Transport{
        MaxIdleConns:        100,              // Maximum number of idle connections
        IdleConnTimeout:     500 * time.Second, // Idle connection timeout, e.g. 500 seconds (less than 600 seconds)
        DisableKeepAlives:   false,            // Enable Keep-Alive
    }
}

EAS SDK (Java)

O EAS SDK suporta a configuração do intervalo de limpeza de conexões ociosas e do timeout de conexão ociosa do cliente.

import com.aliyun.openservices.eas.predict.http.HttpConfig;

public class EasSdkTimeoutJava {
    public static void main(String[] args) {
        // 1. Global client configuration
        HttpConfig httpConfig = new HttpConfig();
        // Enable idle connection cleanup, in milliseconds. Set based on your client requirements.
        httpConfig.setConnectionCleanupInterval(5000);
        // Set the idle connection timeout to 500 seconds, less than the fully managed gateway idle timeout of 600 seconds
        httpConfig.setIdleConnectionTimeout(500000);
        ...
    }
}
Nota

O código anterior configura apenas a conexão entre o cliente e o gateway. Ele não modifica o timeout de conexão ociosa do cliente entre o gateway e o service de modelo, nem o timeout de ociosidade do servidor vLLM/SGLang.

Configure o timeout de requisição

O timeout de requisição é o tempo máximo permitido desde o estabelecimento da conexão TCP e o envio da requisição até o recebimento completo da resposta. Trata-se do timeout de cliente configurado com mais frequência.

Configuração recomendada

Ajuste o timeout de requisição de acordo com seus requisitos de negócio. Em produção, equilibre tolerância a falhas, tempo de resposta, tempo de processamento do modelo e instabilidade da rede.

Para evitar que o cliente atinja o timeout enquanto o servidor ainda processa a requisição, defina o timeout de requisição do cliente ligeiramente acima do timeout de requisição do gateway.

  • Uma fórmula comum: client timeout = server request timeout + 1–5 seconds.

  • Para cenários de falha rápida, defina um timeout de cliente mais curto e dependa de idempotência e estratégia de nova tentativa para lidar com falhas.

Para cenários de longa duração que excedam 10 minutos, utilize uma destas abordagens:

  • Streaming, como geração de conteúdo de IA e downloads de arquivos grandes.

  • WebSocket, para comunicação bidirecional persistente.

  • Inferência assíncrona ou polling de tarefas.

O gateway totalmente gerenciado possui um timeout de requisição padrão de 10 minutos (600 segundos). O diagrama a seguir ilustra o fluxo do timeout de requisição:

image

Timeout de requisição por método de acesso

Método de acesso

Descrição do timeout de requisição

Gateway totalmente gerenciado (gateway MSE)

Timeout de requisição padrão: 600 segundos. É possível personalizar o timeout de requisição do gateway para services específicos através do campo metadata.rpc.keepalive no arquivo de configuração do service. Para mais detalhes, consulte Parâmetros de metadados.

Gateway dedicado ALB

Não pode ser modificado via metadata.rpc.keepalive. O timeout real de requisição segue a configuração do gateway dedicado ALB.

Balanceamento de carga NLB

O NLB é um balanceador de carga de Camada 4 que não analisa requisições HTTP, portanto, não fornece timeout no nível de requisição HTTP. As requisições ainda estão sujeitas aos timeouts do cliente, do proxy upstream e do service de backend, além do timeout de ociosidade TCP do NLB.

Importante

O timeout de requisição e o timeout de ociosidade HTTP Keep-Alive são parâmetros diferentes. Um timeout de ociosidade do servidor da engine de 60 segundos não significa que uma única inferência esteja limitada a 60 segundos. No entanto, para requisições sem streaming que não apresentem dados de rede por um período prolongado, o timeout de ociosidade TCP do NLB ainda pode ser aplicado. Valide o timeout em relação ao tempo máximo até o primeiro token (TTFT) e ao padrão real de resposta.

Exemplos de configuração do cliente

Os exemplos a seguir mostram como configurar o timeout de requisição do cliente em diferentes linguagens de programação.

Importante

Estes exemplos servem apenas como referência de parâmetros e não se destinam ao uso direto em sistemas de produção. Os valores reais dependem dos padrões de tráfego, condições de carga e características da versão do cliente.

Java

O exemplo a seguir mostra como configurar o timeout de requisição do cliente. Ajuste o valor real com base no tipo de gateway e no tempo de processamento do modelo.

import org.apache.http.client.config.RequestConfig;

public class ApacheHttpClientTimeout {
    public static void main(String[] args) {
        // Set the client request timeout slightly above the gateway request timeout.
        // If the gateway default is 600 seconds, use 610 seconds here.
        RequestConfig requestConfig = RequestConfig.custom()
                // Example value: connection timeout in milliseconds
                .setConnectTimeout(5000)
                // Data transfer timeout (read timeout) in milliseconds (610 seconds)
                .setSocketTimeout(610000)
                .build();
    }
}

Go

A biblioteca net/http do Go oferece várias formas de definir timeouts de requisição. A abordagem mais comum é definir Timeout em http.Client, ou usar context.WithTimeout para timeouts por requisição individual.

package main

import (
    "context"
    "fmt"
    "io"
    "net/http"
    "time"
)

func main() {
    // Recommended: set client request timeout slightly greater than or equal to the gateway request timeout (default 600 seconds). Use 610 seconds here.
    client := &http.Client{
        Timeout: 610 * time.Second, // Timeout for the entire request
    }

    req, err := http.NewRequest("GET", "http://your-gateway-url", nil)
    if err != nil {
        fmt.Println("Error creating request:", err)
        return
    }

    // You can also set a shorter timeout for individual requests
    ctx, cancel := context.WithTimeout(req.Context(), 610*time.Second) // 610 seconds
    defer cancel()
    req = req.WithContext(ctx)

    resp, err := client.Do(req)
    if err != nil {
            fmt.Println("Error sending request:", err)
            // Check if it is a timeout error
            if t, ok := err.(interface{ Timeout() bool }); ok && t.Timeout() {
                    fmt.Println("Request timed out!")
            }
            return
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Error reading response body:", err)
        return
    }
    fmt.Printf("Response Status: %s\n", resp.Status)
    fmt.Printf("Response Body: %s\n", body)
}

EAS SDK (Java)

O EAS SDK da Alibaba Cloud suporta a definição de timeout de conexão e timeout de leitura tanto no nível global do cliente quanto no nível de cada requisição.

import com.aliyun.openservices.eas.predict.http.HttpConfig;

public class EasSdkTimeoutJava {
    public static void main(String[] args) {
        // 1. Global client configuration
        HttpConfig httpConfig = new HttpConfig();
        // Connection timeout
        httpConfig.setConnectTimeout(5);
        // Read timeout. Set the client request timeout slightly above the gateway request timeout.
        // If the gateway default is 600 seconds, use 610 seconds here.
        httpConfig.setReadTimeout(610);

    }
}

Problemas comuns

Configuração incorreta do timeout de conexão ociosa

Cenário 1: Timeout de ociosidade do cliente excede o timeout de ociosidade do servidor no gateway

Sintoma: o pool de conexões do cliente considera uma conexão válida, mas o gateway já a encerrou. Requisições subsequentes que reutilizam essa conexão falham.

Erros comuns incluem:

  • Connection reset by peer

  • Broken pipe

  • java.net.SocketException: Connection reset

  • requests.exceptions.ConnectionError

  • read: connection reset by peer

O cliente também pode receber um HTTP 503, dependendo de quando a conexão foi encerrada e da lógica de processamento do gateway.

Solução de problemas: identifique o tipo de gateway e defina o timeout de ociosidade do cliente abaixo do timeout de ociosidade do servidor correspondente no gateway. Por padrão, o gateway totalmente gerenciado e o gateway dedicado ALB usam 600 segundos, e o NLB usa 900 segundos.

Cenário 2: Timeout de ociosidade do cliente no gateway excede o timeout de ociosidade do servidor no service de inferência de backend

Sintoma: o gateway considera a conexão com o backend reutilizável, mas o service de inferência de backend já a encerrou devido ao timeout de ociosidade. Quando o gateway tenta reutilizar a conexão, percebe que ela foi descartada.

O cliente pode receber HTTP 502, 503 ou uma redefinição de conexão. Esse problema costuma ser intermitente, pois o gateway consegue estabelecer uma nova conexão se detectar o encerramento a tempo.

Solução de problemas:

  1. Identifique o tipo de gateway e seu timeout de ociosidade do cliente: gateway totalmente gerenciado (30 segundos), gateway dedicado ALB (15 segundos), NLB (900 segundos).

  2. Verifique o timeout de ociosidade do servidor na engine de inferência de backend.

  3. Certifique-se de que o timeout de ociosidade do servidor no service de inferência de backend seja maior que o timeout de ociosidade do cliente no gateway.

  4. Para NLB, verifique o valor padrão de 60 segundos do modelo Model Gallery e aumente-o para mais de 900 segundos.

  5. Se necessário, utilize captura de pacotes para determinar a ordem dos pacotes FIN e RST após a conclusão da resposta anterior. Isso identifica qual camada iniciou o encerramento da conexão.

Configuração incorreta do timeout de requisição

Cenário 1: Timeout de requisição do cliente definido como muito curto

O cliente pode se desconectar antes que o gateway ou o service de inferência de backend termine o processamento, gerando um falso timeout. Erros comuns incluem:

  • java.net.http.HttpTimeoutException

  • java.net.SocketTimeoutException: Read timed out

  • requests.exceptions.ReadTimeout

  • context deadline exceeded

É possível ajustar o timeout de requisição do cliente com base na sua estratégia de falha rápida. Nem todo cenário exige que o timeout do cliente exceda o timeout de requisição do servidor.

Cenário 2: Timeout de requisição do gateway menor que o tempo real de processamento do modelo

O gateway para de aguardar antes que o service de inferência de backend termine. O cliente geralmente recebe HTTP 504, mas também pode obter 502 ou 500, dependendo de onde a conexão for interrompida. O service de inferência de backend pode continuar processando ou detectar o cancelamento da requisição após o gateway encerrar a conexão.

Reúna as seguintes informações para solucionar o problema:

  1. Tipo de erro do cliente, duração da requisição e histórico de novas tentativas.

  2. Códigos de status, duração da requisição e tempo de resposta do backend nos logs de acesso do gateway.

  3. Status da requisição, tempo de processamento do modelo e detalhes da interrupção de conexão nos logs do service de inferência de backend.

  4. Para requisições sem streaming: tempo até o primeiro token (TTFT), tempo total de resposta e timeout de ociosidade TCP do enlace.

Diretrizes de alteração e verificação

  1. Confirme o método de acesso: gateway totalmente gerenciado, gateway dedicado ALB ou NLB.

  2. Registre o timeout de ociosidade do cliente, timeout de ociosidade do servidor no gateway, timeout de ociosidade do cliente no gateway, timeout de ociosidade do servidor no service de inferência de backend e timeout de requisição.

  3. Diferencie timeout de conexão ociosa, timeout de requisição, timeout de leitura e intervalo de sondagem TCP Keep-Alive.

  4. Modificar variáveis de ambiente da engine de inferência EAS aciona uma recompilação do service. Realize alterações fora dos horários de pico.

  5. Após as alterações, verifique se as variáveis de ambiente e a configuração real do servidor HTTP entraram em vigor nas novas instâncias.

  6. Teste conexões em intervalos abaixo e acima do timeout de ociosidade alvo para observar como as conexões são encerradas e restabelecidas.

  7. Use logs do cliente, logs do gateway e captura de pacotes para identificar qual camada gera erros FIN, RST e 502/503/504.

  8. Monitore a contagem de conexões, descritores de arquivos, proporção de erros 5xx, taxa de sucesso e latência de requisição. Prepare um plano de rollback.