Skip to main content

Konfigurasikan penggunaan kembali koneksi untuk DashScope SDK

Tanpa penggunaan kembali koneksi, setiap panggilan API membuka koneksi TCP baru dan menjalankan proses jabat tangan TLS, yang menambah latensi. Dalam skenario konkurensi tinggi, overhead ini dapat menyebabkan timeout dan pemborosan sumber daya. Penggunaan kembali koneksi menghilangkan penyiapan berulang, sehingga mengurangi latensi dan konsumsi sumber daya.

DashScope SDK mendukung penggunaan kembali koneksi baik di Java maupun Python:
  • Java SDK: Kolam koneksi bawaan diaktifkan secara default. Konfigurasikan parameter seperti jumlah koneksi maksimum dan durasi timeout.
  • Python SDK: Aktifkan penggunaan kembali koneksi dengan meneruskan Session kustom. SDK ini mendukung panggilan sinkron maupun asinkron.

Sebelum memulai

Sebelum menjalankan contoh kode berikut:
  1. Ekspor kunci API sebagai variabel lingkungan.
  2. Instal SDK versi terbaru.

Java SDK

Java SDK menyertakan kolam koneksi bawaan yang diaktifkan secara default. Sesuaikan jumlah koneksi maksimum dan pengaturan timeout untuk mengoptimalkan sesuai beban kerja Anda.

Parameter

ParameterDescriptionDefault valueUnit
connectTimeoutTimeout pembentukan koneksi.120seconds
readTimeoutTimeout pembacaan data.300seconds
writeTimeoutTimeout penulisan data.60seconds
connectionIdleTimeoutTimeout koneksi idle dalam kolam.300seconds
connectionPoolSizeJumlah koneksi maksimum dalam kolam.32connections
maximumAsyncRequestsJumlah maksimum permintaan konkuren di semua host (batas global).32requests
maximumAsyncRequestsPerHostJumlah maksimum permintaan konkuren per host.32requests
Batasan parameter:
  • maximumAsyncRequests harus ≤ connectionPoolSize; jika tidak, permintaan dapat hang.
  • maximumAsyncRequestsPerHost harus ≤ maximumAsyncRequests.
Panduan penyetelan:
  • connectTimeout: Dalam skenario latensi rendah, atur timeout lebih pendek untuk mengurangi waktu tunggu.
  • connectionIdleTimeout: Dalam skenario konkurensi tinggi, perpanjang timeout idle untuk menghindari pembuatan koneksi berulang dan mengurangi penggunaan sumber daya.
  • connectionPoolSize: Dalam skenario konkurensi tinggi, jumlah koneksi yang terlalu sedikit menyebabkan blocking, timeout, dan koneksi ulang berulang (penggunaan sumber daya lebih tinggi). Sebaliknya, jumlah koneksi yang terlalu banyak membebani server. Seimbangkan jumlah koneksi berdasarkan beban kerja Anda.

Contoh kode

Contoh berikut mengonfigurasi parameter kolam koneksi (timeout, jumlah koneksi maksimum) dan memanggil layanan model. Sesuaikan parameter tersebut untuk mengoptimalkan konkurensi dan penggunaan sumber daya.
// Disarankan versi 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 {
        // Ini adalah URL wilayah Singapura. Ganti WorkspaceId dengan ID ruang kerja aktual Anda. URL berbeda tiap wilayah.
        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()
                // Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // Contoh ini menggunakan qwen-plus. Ubah nama model sesuai kebutuhan. Daftar model: 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) {
        // Konfigurasi kolam koneksi
        Constants.connectionConfigurations = ConnectionConfigurations.builder()
                .connectTimeout(Duration.ofSeconds(10))  // Timeout untuk membentuk koneksi, default 120s
                .readTimeout(Duration.ofSeconds(300)) // Timeout untuk membaca data, default 300s
                .writeTimeout(Duration.ofSeconds(60)) // Timeout untuk menulis data, default 60s
                .connectionIdleTimeout(Duration.ofSeconds(300)) // Timeout untuk koneksi idle dalam kolam koneksi, default 300s
                .connectionPoolSize(256) // Jumlah koneksi maksimum dalam kolam koneksi, default 32
                .maximumAsyncRequests(256)  // Jumlah maksimum permintaan konkuren, default 32
                .maximumAsyncRequestsPerHost(256) // Jumlah maksimum permintaan konkuren per host, default 32
                .build();

        try {
            GenerationResult result = callWithMessage();
            System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent());
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // Gunakan framework logging untuk mencatat informasi exception
            System.err.println("Terjadi kesalahan saat memanggil layanan generasi: " + e.getMessage());
        }
        System.exit(0);
    }
}

Python SDK

Python SDK DashScope mendukung penggunaan kembali koneksi dengan meneruskan HTTP client kustom (httpx.Client / httpx.AsyncClient). SDK ini mendukung dua metode pemanggilan: HTTP asinkron (berbasis korutin) dan HTTP sinkron.

HTTP Asinkron

Untuk skenario asinkron, gunakan httpx.AsyncClient dengan httpx.Limits untuk mengaktifkan penggunaan kembali koneksi. httpx.Limits mendukung konfigurasi parameter seperti batas jumlah koneksi:
ParameterDescriptionDefault valueNotes
max_connectionsBatas total koneksi.None (tidak terbatas)Mengontrol jumlah maksimum koneksi. Dalam skenario konkurensi tinggi, tingkatkan nilai ini untuk meningkatkan konkurensi.
max_keepalive_connectionsJumlah maksimum koneksi keep-alive.None (tidak terbatas)Mengontrol jumlah koneksi aktif yang dipertahankan dalam pool, mencegah beban berlebih pada satu server.
keepalive_expiryTimeout keep-alive koneksi.5.0 (detik)Koneksi keep-alive yang menganggur akan ditutup otomatis setelah durasi ini.

Contoh kode

Contoh berikut mengonfigurasi penggunaan kembali koneksi dan memanggil layanan model secara asinkron:
import asyncio
import httpx
import os
import dashscope

async def main():
    # Konfigurasi parameter koneksi
    limits = httpx.Limits(
        max_connections=100,           # Batas total koneksi
        max_keepalive_connections=30,  # Jumlah maksimum koneksi keep-alive
    )

    # Buat HTTP client kustom dan teruskan ke konstruktor Client
    async with httpx.AsyncClient(limits=limits) as http_client:
        # Berikut adalah konfigurasi untuk wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
        # Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
        # Jika variabel lingkungan belum dikonfigurasi, atur API Key Anda secara langsung: api_key = "sk-xxx"
        aclient = dashscope.AsyncClient(
            api_key=os.getenv("DASHSCOPE_API_KEY"),
            workspace="{WorkspaceId}",
            region="ap-southeast-1",
            http_client=http_client,  # Teruskan HTTP client kustom
        )
        response = await aclient.chat.completions.create(
            model='qwen-plus',
            messages=[{"role": "user", "content": 'Hello, please introduce yourself'}],
        )
        print(response)

asyncio.run(main())

HTTP Sinkron

Untuk skenario sinkron, gunakan httpx.Client untuk mengaktifkan penggunaan kembali koneksi. Beberapa permintaan dalam HTTP client yang sama menggunakan kembali koneksi TCP dasar, sehingga menghindari overhead pembentukan koneksi berulang.

Contoh kode: panggilan tunggal

Contoh berikut mengonfigurasi penggunaan kembali koneksi dan memanggil layanan model secara sinkron:
import httpx
import os
import dashscope

# Gunakan pernyataan with untuk memastikan HTTP client ditutup dengan benar
with httpx.Client() as http_client:
    # Berikut adalah konfigurasi untuk wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
    # Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    # Jika variabel lingkungan belum dikonfigurasi, atur API Key Anda secara langsung: api_key = "sk-xxx"
    client = dashscope.Client(
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        workspace="{WorkspaceId}",
        region="ap-southeast-1",
        http_client=http_client,  # Teruskan HTTP client kustom
    )
    response = client.chat.completions.create(
        model='qwen-plus',
        messages=[{"role": "user", "content": 'Hello'}],
    )
    print(response)

Contoh kode: beberapa panggilan dengan HTTP client bersama

Untuk menggunakan kembali HTTP client di beberapa panggilan:
import httpx
import os
import dashscope

# Buat objek HTTP client dan konfigurasikan parameter penggunaan kembali koneksi
http_client = httpx.Client(
    limits=httpx.Limits(
        max_connections=100,          # Batas total koneksi
        max_keepalive_connections=30, # Jumlah maksimum koneksi keep-alive
    ),
)

# Berikut adalah konfigurasi untuk wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika variabel lingkungan belum dikonfigurasi, atur API Key Anda secara langsung: api_key = "sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
    http_client=http_client,  # Teruskan HTTP client kustom
)

try:
    # Gunakan kembali HTTP client yang sama untuk beberapa panggilan
    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:
    # Pastikan HTTP client ditutup dengan benar
    http_client.close()

Praktik terbaik

  • Java SDK: Atur connectionPoolSize dan maximumAsyncRequests sesuai beban kerja Anda. Seimbangkan jumlah koneksi: terlalu sedikit menyebabkan blocking, terlalu banyak membebani server.
  • Python SDK: Gunakan pernyataan with untuk mengelola siklus hidup HTTP client secara otomatis dan memastikan pembersihan sumber daya yang tepat.
  • Pilih metode yang tepat: Gunakan panggilan asinkron untuk aplikasi asinkron (asyncio, FastAPI). Gunakan panggilan sinkron untuk aplikasi sinkron tradisional.

Kode error

Jika pemanggilan model gagal, lihat Pesan error untuk menyelesaikan masalah.