Mengonfigurasi streaming untuk respons LLM dan traffic lainnya

Pratinjau — streaming

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Dokumen ini menjelaskan cara mengonfigurasi streaming di Gateway API.

Gateway API mendukung streaming. Streaming memungkinkan gateway menyajikan koneksi yang berjalan lama dan mengirimkan data dalam potongan untuk streaming permintaan dan respons.

Penggunaan streaming yang umum adalah menyajikan model bahasa besar (LLM). Model mengirimkan jawabannya satu token per satu, sehingga klien dapat menampilkan teks saat model masih membuatnya. Untuk contoh lengkap yang men-streaming respons dari model Gemma yang disajikan vLLM di Cloud Run, lihat Men-streaming respons dari LLM.

Protokol streaming yang didukung

Jika diaktifkan, Gateway API mendukung metode streaming berikut:

• Pengiriman respons inkremental: Frame DATA HTTP/2 atau encoding transfer dalam bentuk potongan data HTTP/1.1, bergantung pada apa yang dinegosiasikan klien.
• Server-Sent Events (SSE): Streaming searah dari server ke klien.
• WebSockets: Saluran komunikasi full-duplex melalui satu koneksi TCP.
• Streaming dua arah gRPC: Streaming full-duplex menggunakan gRPC.

Prasyarat

Sebelum dapat menggunakan streaming, pastikan layanan backend Anda mendukung protokol yang diperlukan (misalnya, HTTP/2 atau WebSockets) dan konfigurasi API Anda disiapkan dengan benar.

Mengonfigurasi protokol backend

Untuk mendukung traffic streaming, Anda harus mengonfigurasi protokol untuk backend berdasarkan jenis streaming:

• gRPC: Anda harus mengonfigurasi backend untuk menggunakan HTTP/2 (h2).
• WebSockets: Anda harus menggunakan http/1.1. WebSocket memerlukan handshake Connection: Upgrade HTTP/1.1.
• Server-Sent Events (SSE) dan pengiriman respons inkremental: Backend Anda dapat menggunakan HTTP/1.1 atau HTTP/2 (h2). Sebaiknya gunakan HTTP/2 (h2) untuk meningkatkan performa.

Dalam spesifikasi OpenAPI, konfigurasikan protokol backend sebagai berikut:

Contoh (OpenAPI 3.x)

Tetapkan kolom protocol dalam definisi backend bernama dalam objek x-google-api-management.backends. Anda juga harus mereferensikan backend ini menggunakan x-google-backend di tingkat root atau operasi.

x-google-api-management:
  backends:
    gemma:
      address: https://my-gemma-service.run.app
      protocol: h2 # Use 'http/1.1' for WebSockets
x-google-backend: gemma

Contoh (OpenAPI 2.0)

Tetapkan kolom protocol di ekstensi x-google-backend.

x-google-backend:
  address: https://my-gemma-service.run.app
  protocol: h2 # Use 'http/1.1' for WebSockets

Menetapkan batas waktu streaming

Kolom deadline mengatur durasi permintaan (unary atau streaming) dapat berjalan.

Tabel berikut menunjukkan cara penerapan waktu tunggu untuk setiap jenis permintaan:

Metode	Waktu tunggu tidak ada aktivitas (selisih maksimum antar-pesan)	Waktu tunggu permintaan (durasi total permintaan maksimum)
Non-streaming	T/A: waktu tunggu tidak ada aktivitas hanya berlaku untuk streaming	Default 15 detik; tetapkan deadline untuk mengubahnya, hingga 3.600 detik untuk gateway yang mendukung streaming
Streaming melalui HTTP (SSE, transfer yang dipotong-potong)	T/A: efektif tanpa batas; hanya waktu tunggu permintaan yang mengakhiri streaming	Default 15 detik; tetapkan deadline untuk mengubahnya, hingga 3.600 detik untuk gateway yang mendukung streaming
Streaming melalui gRPC atau WebSocket	Default 300 detik; tetapkan deadline untuk mengubahnya, hingga 3.600 detik untuk gateway yang mendukung streaming. Di WebSockets, deadline yang kurang dari 300 detik akan diabaikan dan berlaku minimum 300 detik	Selalu 3.600 detik untuk gateway yang mendukung streaming, tidak dapat dikonfigurasi

Perhatian: Di luar streaming gRPC dan WebSocket, defaultnya hanya 15 detik, yang terlalu singkat untuk sebagian besar streaming. Streaming akan dipotong setelah waktu tunggu permintaan berlalu, bahkan saat masih mengirim data, jadi tetapkan deadline secara eksplisit di setiap endpoint streaming.

Catatan: Backend Anda menerapkan waktu tunggu permintaannya sendiri, dan waktu tunggu tersebut akan mengakhiri koneksi, berapa pun traffic yang dibawanya. deadline tidak mengubahnya. Backend Cloud Run yang dibiarkan pada setelan default 300 detik akan menutup streaming lima menit setelah dibuka. Panduan Gemma men-deploy layanannya dengan --timeout 600, sehingga streaming-nya berakhir setelah 10 menit. Untuk menggunakan deadline 3.600 detik dalam dua contoh berikut, deploy layanan dengan --timeout 3600. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi waktu tunggu permintaan untuk layanan.

Contoh (OpenAPI 3.x)

Tetapkan kolom deadline dalam definisi backend bernama.

x-google-api-management:
  backends:
    gemma:
      address: https://my-gemma-service.run.app
      protocol: h2
      deadline: 3600.0
x-google-backend: gemma

Contoh (OpenAPI 2.0)

Tetapkan kolom deadline di ekstensi x-google-backend.

x-google-backend:
  address: https://my-gemma-service.run.app
  protocol: h2
  deadline: 3600.0

Untuk batasan lain yang berlaku pada koneksi streaming, lihat Batasan.

Mengaktifkan streaming di gateway

Streaming ditentukan pada waktu pembuatan gateway. Perhatikan perilaku berikut:

• Tidak ada penonaktifan eksplisit: Tidak ada flag untuk menonaktifkan streaming secara eksplisit. Jika Anda menghilangkan flag --enable-streaming, Gateway API akan me-resolve mode saat pembuatan dari konfigurasi API dan default platform: konfigurasi API yang mengonfigurasi Router Model selalu menghasilkan gateway streaming. Baca kolom effectiveStreamingMode khusus output gateway untuk melihat mode pembuatannya.
• Immutability: Mode streaming ditetapkan saat pembuatan dan tidak dapat diubah nanti.

Untuk menentukan streaming di gateway, gunakan flag --enable-streaming dengan perintah gcloud api-gateway gateways create:

gcloud api-gateway gateways create GATEWAY_ID \
    --api=API_ID \
    --api-config=CONFIG_ID \
    --location=GCP_REGION \
    --enable-streaming

Untuk mengetahui informasi selengkapnya tentang opsi deployment gateway, lihat Men-deploy API ke gateway.

Catatan: Gateway Router Model otomatis mengaktifkan streaming.

Properti streaming gateway

Kolom berikut pada resource Gateway mengontrol perilaku streaming:

Kolom	Atribut	Nilai
streamingMode	String (IMMUTABLE, OPTIONAL)	STREAMING_MODE_UNSPECIFIED (Default: Layanan memilih mode) STREAMING_MODE_ENABLED
effectiveStreamingMode	String (OUTPUT_ONLY)	EFFECTIVE_STREAMING_MODE_DISABLED EFFECTIVE_STREAMING_MODE_ENABLED

Saat menggunakan REST API untuk membuat gateway, Anda dapat menentukan streaming dalam isi permintaan:

{
  "apiConfig": "projects/...",
  "streamingMode": "STREAMING_MODE_ENABLED"
}

Memastikan streaming diaktifkan

Untuk mengonfirmasi apakah streaming aktif di gateway Anda, deskripsikan gateway menggunakan gcloud CLI:

gcloud api-gateway gateways describe GATEWAY_ID \
    --location=GCP_REGION

Cari kolom effectiveStreamingMode di output. Jika streaming diaktifkan, output-nya akan mencakup:

effectiveStreamingMode: EFFECTIVE_STREAMING_MODE_ENABLED

Memanggil API Google Cloud

Gateway streaming dapat memanggil API Google Cloud seperti aiplatform.googleapis.com, sehingga Anda dapat men-streaming respons dari model Gemini di Agent Platform melalui gateway. Gateway melakukan autentikasi ke backend ini dengan token akses, bukan token ID. Untuk mengetahui detailnya, lihat Mengamankan layanan backend.

Men-streaming respons dari LLM

Contoh ini menempatkan gateway streaming di depan model Gemma yang disajikan vLLM di Cloud Run, dan melakukan streaming penyelesaian chat melalui gateway. vLLM menyajikan API yang kompatibel dengan OpenAI yang melakukan streaming respons sebagai Server-Sent Events (SSE).

Sebelum memulai, selesaikan Mengonfigurasi lingkungan pengembangan, termasuk Mengonfigurasi akun layanan yang digunakan untuk membuat konfigurasi API. Gateway menggunakan akun layanan tersebut untuk memanggil layanan Cloud Run.

Men-deploy model

Deploy model Gemma dengan mengikuti Men-deploy model Gemma 4 dengan container vLLM. Catat nama layanan, URL layanan, region, dan nama model yang Anda deploy, seperti google/gemma-4-E4B-it.

Catatan: Perintah deployment panduan ini mendownload bobot model dari Hugging Face tanpa autentikasi. Jika Hugging Face membatasi kapasitas download, log layanan akan menampilkan HTTP Error 429, container gagal dalam pemeriksaan startup, dan revisi tidak siap. Untuk menghindari hal ini, tetapkan token akses Hugging Face di variabel lingkungan HF_TOKEN, seperti yang ditunjukkan dalam tabel setelan deployment di panduan.

Memberikan akses gateway ke layanan

Panduan ini men-deploy layanan dengan --no-allow-unauthenticated. Gateway memanggil layanan dengan token ID untuk akun layanannya, yang Anda teruskan sebagai --backend-auth-service-account saat membuat konfigurasi API. Berikan peran Cloud Run Invoker (roles/run.invoker) ke akun layanan tersebut di layanan:

gcloud run services add-iam-policy-binding SERVICE_NAME \
    --region=REGION \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
    --role=roles/run.invoker

Ganti kode berikut:

• SERVICE_NAME: nama layanan Cloud Run
• REGION: region tempat Anda men-deploy layanan
• SERVICE_ACCOUNT_EMAIL: alamat email akun layanan gateway

Membuat konfigurasi API

Simpan spesifikasi OpenAPI berikut sebagai gemma-api.yaml, dengan mengganti https://my-gemma-service.run.app dengan URL layanan Anda:

openapi: 3.0.3
info:
  title: Gemma API
  version: 1.0.0
x-google-api-management:
  backends:
    gemma:
      address: https://my-gemma-service.run.app
      protocol: h2
      deadline: 570.0
x-google-backend: gemma
components:
  securitySchemes:
    google_id_token:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: ""
          scopes: {}
      x-google-auth:
        issuer: https://accounts.google.com
        jwksUri: https://www.googleapis.com/oauth2/v3/certs
        audiences:
          - gemma-api
security:
  - google_id_token: []
paths:
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      responses:
        '200':
          description: A chat completion, streamed as SSE when the request sets "stream" to true.

deadline selama 570 detik adalah 30 detik lebih singkat daripada --timeout 600 yang ditetapkan panduan Gemma pada layanan. Akibatnya, deadline gateway, bukan waktu tunggu layanan, akan mengakhiri streaming yang berjalan terlalu lama. x-google-backend level teratas ditetapkan secara default ke pathTranslation: APPEND_PATH_TO_ADDRESS. Gateway menambahkan jalur permintaan ke alamat backend, sehingga permintaan ke /v1/chat/completions mencapai endpoint penyelesaian chat vLLM.

Persyaratan security membuat gateway menolak permintaan apa pun yang tidak membawa token ID yang ditandatangani Google dengan audiens gemma-api. Anda dapat memilih string audiens yang berbeda, asalkan pemanggil meminta string yang sama saat mereka membuat token. Untuk mengetahui informasi selengkapnya, lihat Menggunakan token ID Google untuk mengautentikasi pengguna.

Perhatian: Token ID mengidentifikasi pemanggil, tetapi tidak membatasi identitas Google yang dimaksud. Identitas apa pun yang dapat membuat token untuk audiens gemma-api dapat mengirim permintaan ke model Anda. Anda membayar untuk instance GPU yang dimulai oleh permintaan mereka. Untuk juga mewajibkan kunci API, lihat Menggunakan kunci API. Untuk membatasi jumlah permintaan yang dapat dikirim setiap project konsumen per menit, lihat Tentang kuota.

Buat konfigurasi API:

gcloud api-gateway api-configs create CONFIG_ID \
    --api=API_ID \
    --openapi-spec=gemma-api.yaml \
    --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

Ganti kode berikut:

• CONFIG_ID: ID untuk konfigurasi API
• API_ID: ID API. Jika API tidak ada, perintah akan membuatnya.

Membuat gateway

Buat gateway streaming dari konfigurasi API:

gcloud api-gateway gateways create GATEWAY_ID \
    --api=API_ID \
    --api-config=CONFIG_ID \
    --location=GCP_REGION \
    --enable-streaming

Ganti kode berikut:

• GATEWAY_ID: ID untuk gateway
• GCP_REGION: region untuk gateway, yang dapat berbeda dari REGION. Untuk mengetahui nilai yang diizinkan, lihat Men-deploy API ke gateway.

Setelah gateway siap, dapatkan nama host-nya:

gcloud api-gateway gateways describe GATEWAY_ID \
    --location=GCP_REGION \
    --format="value(defaultHostname)"

Mendapatkan token ID untuk pemanggil

Akun pengguna tidak dapat memilih audiens token ID-nya, sehingga contoh ini membuat token untuk akun layanan yang Anda tiru. Untuk pemanggil, gunakan akun layanan yang ada atau buat akun layanan baru. Untuk mengetahui informasi selengkapnya, lihat Membuat akun layanan. Berikan peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator) kepada diri Anda sendiri di akun layanan tersebut, yang diperlukan gcloud CLI untuk meniru identitasnya:

gcloud iam service-accounts add-iam-policy-binding CALLER_SERVICE_ACCOUNT_EMAIL \
    --member=user:USER_EMAIL \
    --role=roles/iam.serviceAccountTokenCreator

Ganti kode berikut:

• CALLER_SERVICE_ACCOUNT_EMAIL: alamat email akun layanan yang memanggil gateway
• USER_EMAIL: alamat email Anda

Mengirim permintaan streaming

Kirim permintaan penyelesaian chat yang menetapkan "stream": true, dengan token ID untuk akun layanan pemanggil di header Authorization. Flag -N menonaktifkan buffering output di curl, sehingga setiap peristiwa dicetak saat tiba:

curl -N https://DEFAULT_HOSTNAME/v1/chat/completions \
    -H "Authorization: Bearer $(gcloud auth print-identity-token \
        --impersonate-service-account=CALLER_SERVICE_ACCOUNT_EMAIL \
        --audiences=gemma-api)" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "MODEL_NAME",
      "messages": [{"role": "user", "content": "Why is the sky blue?"}],
      "stream": true
    }'

Ganti kode berikut:

• DEFAULT_HOSTNAME: nama host gateway
• CALLER_SERVICE_ACCOUNT_EMAIL: akun layanan dari langkah sebelumnya
• MODEL_NAME: model yang Anda deploy, seperti google/gemma-4-E4B-it

Catatan: Panduan Gemma tidak menetapkan instance minimum, sehingga Cloud Run menghapus instance layanan saat tidak ada aktivitas. Permintaan yang masuk saat tidak ada instance yang berjalan akan menunggu saat instance baru dimulai dan memuat model. Proses ini dapat memerlukan waktu beberapa menit, dan waktu tunggu dihitung dalam deadline gateway. Agar instance tetap berjalan, lihat Menetapkan instance minimum untuk layanan. Instance yang terus berjalan dengan cara ini akan ditagih.

Responsnya adalah streaming SSE. Peristiwa pertama membawa peran assistant, setiap peristiwa berikutnya membawa bagian jawaban berikutnya, dan peristiwa terakhir sebelum data: [DONE] menetapkan finish_reason. Outputnya mirip dengan hal berikut ini:

data: {"id":"chatcmpl-7bcd57ad-1c3c-4779-91be-2973b875e517","object":"chat.completion.chunk","created":1790099706,"model":"google/gemma-4-E4B-it","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}],"prompt_token_ids":null}

data: {"id":"chatcmpl-7bcd57ad-1c3c-4779-91be-2973b875e517","object":"chat.completion.chunk","created":1790099706,"model":"google/gemma-4-E4B-it","choices":[{"index":0,"delta":{"content":"The"},"logprobs":null,"finish_reason":null,"token_ids":null}]}

...

data: {"id":"chatcmpl-7bcd57ad-1c3c-4779-91be-2973b875e517","object":"chat.completion.chunk","created":1790099706,"model":"google/gemma-4-E4B-it","choices":[{"index":0,"delta":{"content":""},"logprobs":null,"finish_reason":"stop","stop_reason":106,"token_ids":null}]}

data: [DONE]

Pembersihan

Agar akun Google Cloud Anda tidak dikenai biaya untuk resource yang digunakan dalam contoh ini, hapus gateway dan konfigurasi API:

gcloud api-gateway gateways delete GATEWAY_ID \
    --location=GCP_REGION

gcloud api-gateway api-configs delete CONFIG_ID \
    --api=API_ID

Jika Anda membuat API untuk contoh ini, hapus API tersebut:

gcloud api-gateway apis delete API_ID

Hapus layanan Cloud Run:

gcloud run services delete SERVICE_NAME \
    --region=REGION

Harga

Selama Pratinjau Publik streaming, pelanggan tidak dikenai biaya untuk traffic keluar jaringan di gateway yang mendukung streaming. Namun, penagihan Service Control tetap berlaku di level API, terlepas dari fase rilisnya.

Batasan

Batasan berikut berlaku untuk streaming di Gateway API selama Pratinjau Publik:

• Imutabilitas: Anda tidak dapat memperbarui gateway yang ada untuk mengaktifkan atau menonaktifkan streaming. Anda harus membuat gateway baru. Perhatikan bahwa gateway yang mendukung streaming menerima bentuk nama host yang berbeda, sehingga Anda harus memperbarui klien atau data DNS. Jika Anda ingin kami memperbarui data gateway Anda untuk menggunakan format baru, hubungi dukungan. Gateway API menggunakan pola nama host berikut:

  • Non-streaming: {gateway_id}-{base36_project_number}.{shard_hash}.gateway.dev, misalnya test-gateway-4jcaz8x.uc.gateway.dev
  • Streaming: {gateway_id}-{project_number}.{region}.gateway.dev, misalnya test-gateway-9876654321.us-central1.gateway.dev
  • Streaming (lama): {service}-{tenant_project_number}.{region}.run.app, misalnya test-gateway-834512064953.us-central1.run.app. Gateway yang dibuat sebelum nama host *.gateway.dev regional tersedia akan mempertahankan nama host ini secara permanen dan tidak dimigrasikan ke pola baru.

  Gateway baru yang mendukung streaming akan menerima pola Streaming. Dua contoh pertama adalah gateway yang sama dalam project yang sama: dalam pola Streaming, nomor project muncul dalam desimal, bukan base36, sehingga label pertama memiliki lebih sedikit ruang daripada di gateway non-streaming. Label pertama adalah string {gateway_id}-{project_number} gabungan, yang harus sesuai dengan batas label DNS 63 karakter. Batas ID gateway 49 karakter membuatnya tetap berada dalam batas tersebut untuk nomor project hingga 13 digit; nomor project yang lebih panjang memerlukan ID gateway yang lebih pendek.

• Terraform: Mengaktifkan streaming menggunakan Terraform tidak didukung (direncanakan untuk rilis mendatang).

• Load Balancing dan Domain Kustom: Gateway dengan effectiveStreamingMode EFFECTIVE_STREAMING_MODE_ENABLED tidak kompatibel dengan Load Balancing HTTP(S) untuk Gateway API atau NEG Serverless. Anda tidak dapat menempatkan gateway tersebut di belakang NEG Serverless atau Load Balancer Aplikasi eksternal. Oleh karena itu, domain kustom (yang mengandalkan load balancing) tidak didukung untuk gateway ini selama Pratinjau Publik.

• Perilaku batas waktu: Mengaktifkan streaming di gateway tidak mengubah perilaku kolom deadline di jalur SSE atau transfer yang dipotong-potong. Batas waktu tetap menjadi batas waktu nyata pada respons lengkap, sehingga streaming akan dipotong setelah batas waktu berlalu, terlepas dari seberapa banyak data yang dikirim. Defaultnya adalah 15 detik dan maksimumnya adalah 3.600 detik. Di WebSocket, deadline membatasi jeda antarpesan, dan koneksi akan dihentikan setelah 3.600 detik. Lihat Menetapkan batas waktu streaming.

• Model Context Protocol (MCP): Membuat gateway dengan --enable-streaming tidak akan membuat streaming endpoint MCP. Respons MCP tetap berupa satu isi application/json, terlepas dari mode streaming gateway. Untuk mengetahui detail selengkapnya, lihat Batasan MCP.