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 melayani koneksi yang berjalan lama dan mengirimkan data dalam potongan untuk streaming permintaan dan respons.

Penggunaan streaming yang umum adalah untuk menayangkan model bahasa besar (LLM). Model mengirimkan jawabannya satu token dalam satu waktu, sehingga klien dapat menampilkan teks saat model masih membuatnya. Untuk contoh lengkap yang melakukan streaming respons dari model Gemma yang ditayangkan vLLM di Cloud Run, lihat Melakukan 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 satu arah 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. WebSockets memerlukan handshake Connection: Upgrade HTTP/1.1.
• Peristiwa yang Dikirim Server (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, konfigurasi 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 terkelompok)	T/A: pada dasarnya tidak terbatas; 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 WebSockets	Default 300 detik; tetapkan deadline untuk mengubahnya, hingga 3.600 detik untuk gateway yang mendukung streaming. Di WebSockets, deadline 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 WebSockets, nilai defaultnya hanya 15 detik, yang terlalu singkat untuk sebagian besar streaming. Aliran akan terputus setelah waktu tunggu permintaan berlalu, meskipun 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 mengakhiri koneksi berapa pun traffic yang dibawanya. deadline tidak mengubahnya. Backend Cloud Run yang dibiarkan dalam default 300 detiknya akan menutup aliran data 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 batas lain yang berlaku pada koneksi streaming, lihat Batasan.

Mengaktifkan streaming di gateway

Streaming ditentukan pada saat pembuatan gateway. Perhatikan perilaku berikut:

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

Untuk menentukan streaming di gateway, gunakan tanda --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 di 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 akan mencakup:

effectiveStreamingMode: EFFECTIVE_STREAMING_MODE_ENABLED

Menampilkan respons dari LLM secara bertahap

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 Peristiwa yang Dikirim Server (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 kecepatan download, log layanan akan menampilkan HTTP Error 429, container gagal dalam pemeriksaan startup, dan revisi tidak menjadi siap. Untuk menghindari hal ini, tetapkan token akses Hugging Face di variabel lingkungan HF_TOKEN, seperti yang ditunjukkan dalam tabel setelan deployment di panduan.

Memberi gateway akses 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) untuk 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

Buat 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 570 detik lebih pendek 30 detik daripada --timeout 600 yang ditetapkan panduan Gemma pada layanan. Akibatnya, deadline gateway, bukan waktu tunggu layanan, mengakhiri streaming yang berjalan terlalu lama. x-google-backend tingkat teratas secara default adalah pathTranslation: APPEND_PATH_TO_ADDRESS. Gateway menambahkan jalur permintaan ke alamat backend, sehingga permintaan ke /v1/chat/completions akan 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, selama pemanggil meminta string yang sama saat mereka mencetak token. Untuk mengetahui informasi selengkapnya, lihat Menggunakan token ID Google untuk mengautentikasi pengguna.

Perhatian: Token ID mengidentifikasi pemanggil, tetapi tidak membatasi identitas Google yang digunakan. Identitas apa pun yang dapat membuat token untuk audiens gemma-api dapat mengirim permintaan ke model Anda. Anda membayar instance GPU yang permintaannya dimulai. Untuk mewajibkan kunci API juga, 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.

Buat 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 mencetak token untuk akun layanan yang Anda tiru identitasnya. Untuk pemanggil, gunakan akun layanan yang ada atau buat akun layanan baru. Untuk mengetahui informasi selengkapnya, lihat Membuat akun layanan. Beri diri Anda peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator) 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 tiba 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 sebagai deadline gateway. Untuk menjaga agar instance tetap berjalan, lihat Menetapkan instance minimum untuk layanan. Instance yang terus berjalan dengan cara ini akan ditagih.

Responsnya adalah aliran SSE. Peristiwa pertama memiliki peran assistant, setiap peristiwa berikutnya memiliki 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 ditagih untuk keluar dari jaringan di gateway yang mendukung streaming. Namun, penagihan Service Control tetap berlaku di tingkat 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 agar 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 regional *.gateway.dev tersedia akan mempertahankan nama host ini secara permanen dan tidak dimigrasikan ke pola baru.

  Gateway baru yang mendukung streaming 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 dibandingkan dengan 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 dalam batas tersebut untuk nomor project hingga 13 digit; nomor project yang lebih panjang memerlukan ID gateway yang lebih pendek.

• Terraform: Pengaktifan 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 chunked. Batas waktu tetap terikat pada waktu dinding untuk respons lengkap, sehingga streaming akan dihentikan 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 antar-pesan, dan koneksi akan berakhir setelah 3.600 detik. Lihat Menetapkan batas waktu streaming.

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