Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Streaming für LLM-Antworten und anderen Traffic konfigurieren

In diesem Dokument wird beschrieben, wie Sie Streaming in API Gateway konfigurieren.

API Gateway unterstützt Streaming. Mit Streaming können Gateways langlebige Verbindungen bedienen und Daten in Blöcken sowohl für das Anfrage- als auch für das Antwort-Streaming übertragen.

Eine häufige Verwendung von Streaming ist die Bereitstellung eines Large Language Models (LLM). Das Modell sendet seine Antwort Token für Token, sodass ein Client den Text anzeigen kann, während das Modell ihn noch generiert. Ein vollständiges Beispiel, in dem Antworten von einem Gemma-Modell gestreamt werden, das von vLLM in Cloud Run bereitgestellt wird, finden Sie unter Antworten von einem LLM streamen.

Unterstützte Streamingprotokolle

Wenn aktiviert, unterstützt API Gateway die folgenden Streamingmethoden:

Inkrementelle Antwortbereitstellung: HTTP/2-DATA-Frames oder HTTP/1.1-Chunked-Transfer-Codierung, je nachdem, was der Client aushandelt.
Server-Sent Events (SSE): Unidirektionales Streaming vom Server zum Client.
WebSockets: Vollduplex-Kommunikationskanäle über eine einzelne TCP-Verbindung.
Bidirektionales gRPC-Streaming: Vollduplex-Streaming mit gRPC.

Vorbereitung

Bevor Sie Streaming verwenden können, müssen Sie prüfen, ob Ihr Backend-Dienst das erforderliche Protokoll (z. B. HTTP/2 oder WebSockets) unterstützt und ob Ihre API-Konfiguration korrekt eingerichtet ist.

Backend-Protokoll konfigurieren

Damit Streaming-Traffic unterstützt wird, müssen Sie das Protokoll für Ihr Backend basierend auf dem Streaming-Typ konfigurieren:

gRPC: Sie müssen Ihr Backend für die Verwendung von HTTP/2 (h2) konfigurieren.
WebSockets: Sie müssen http/1.1 verwenden. WebSockets erfordern den HTTP/1.1-Connection: Upgrade-Handshake.
Server-Sent Events (SSE) und inkrementelle Antwortbereitstellung: Ihr Backend kann entweder HTTP/1.1 oder HTTP/2 (h2) verwenden. Wir empfehlen HTTP/2 (h2) für eine bessere Leistung.

Konfigurieren Sie das Backend-Protokoll in Ihrer OpenAPI-Spezifikation so:

Beispiel (OpenAPI 3.x)

Legen Sie das Feld protocol in der benannten Backend-Definition im Objekt x-google-api-management.backends fest. Sie müssen dieses Backend auch mit x-google-backend auf der Stamm- oder Vorgangsebene referenzieren.

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

Beispiel (OpenAPI 2.0)

Legen Sie das Feld protocol in der Erweiterung x-google-backend fest.

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

Stream-Frist festlegen

Das Feld deadline bestimmt, wie lange eine Anfrage (unär oder Streaming) ausgeführt werden darf.

In der folgenden Tabelle sehen Sie, wie die Zeitlimits für die einzelnen Anfragetypen gelten:

Methode	Zeitüberschreitung bei Inaktivität (maximaler Abstand zwischen Nachrichten)	Zeitüberschreitung bei Anfrage (maximale Gesamtdauer der Anfrage)
Nicht-Streaming	–: Das Zeitlimit für Inaktivität gilt nur für Streams	Standardmäßig 15 Sekunden. Legen Sie `deadline` fest, um den Wert zu ändern,bis zu 3.600 Sekunden für Gateways mit aktiviertem Streaming.
Streaming über HTTP (SSE, Chunked Transfer)	–: praktisch unendlich; nur das Zeitlimit für die Anfrage beendet den Stream	Standardmäßig 15 Sekunden. Legen Sie `deadline` fest, um den Wert zu ändern,bis zu 3.600 Sekunden für Gateways mit aktiviertem Streaming.
Streaming über gRPC oder WebSockets	Der Standardwert beträgt 300 Sekunden. Legen Sie `deadline` fest, um ihn zu ändern,bis zu 3.600 Sekunden für Gateways mit aktiviertem Streaming. Bei WebSockets wird ein `deadline` von weniger als 300 Sekunden ignoriert und es gilt ein Mindestwert von 300 Sekunden.	Immer 3.600 Sekunden für Gateways mit aktiviertem Streaming, nicht konfigurierbar

Beispiel (OpenAPI 3.x)

Legen Sie das Feld deadline in der benannten Backend-Definition fest.

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

Beispiel (OpenAPI 2.0)

Legen Sie das Feld deadline in der Erweiterung x-google-backend fest.

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

Weitere Limits für Streamingverbindungen finden Sie unter Einschränkungen.

Streaming auf einem Gateway aktivieren

Streaming wird beim Erstellen des Gateways angegeben. Beachten Sie Folgendes:

Keine explizite Deaktivierung: Es gibt kein Flag, um das Streaming explizit zu deaktivieren. Wenn Sie das Flag --enable-streaming weglassen, löst API Gateway den Modus bei der Erstellung anhand der API-Konfiguration und des Plattformstandards auf: Eine API-Konfiguration, die einen Modellrouter konfiguriert, erzeugt immer ein Streaming-Gateway. Lesen Sie das Nur-Ausgabe-Feld effectiveStreamingMode des Gateways, um den Modus zu sehen, mit dem es erstellt wurde.
Unveränderlichkeit: Der Streamingmodus wird bei der Erstellung festgelegt und kann später nicht mehr geändert werden.

Wenn Sie Streaming auf einem Gateway angeben möchten, verwenden Sie das Flag --enable-streaming mit dem Befehl gcloud api-gateway gateways create:

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

Weitere Informationen zu den Bereitstellungsoptionen für Gateways finden Sie unter API auf einem Gateway bereitstellen.

Gateway-Streaming-Eigenschaften

Die folgenden Felder in der Gateway-Ressource steuern das Streamingverhalten:

Feld	Attribute	Werte
`streamingMode`	String (UNVERÄNDERLICH, OPTIONAL)	`STREAMING_MODE_UNSPECIFIED` (Standard: Dienst wählt Modus aus) `STREAMING_MODE_ENABLED`
`effectiveStreamingMode`	String (OUTPUT_ONLY)	`EFFECTIVE_STREAMING_MODE_DISABLED` `EFFECTIVE_STREAMING_MODE_ENABLED`

Wenn Sie die REST API zum Erstellen eines Gateways verwenden, können Sie das Streaming im Anfragetext angeben:

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

Prüfen, ob Streaming aktiviert ist

Wenn Sie prüfen möchten, ob Streaming auf Ihrem Gateway aktiv ist, beschreiben Sie das Gateway mit der gcloud CLI:

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

Suchen Sie in der Ausgabe nach dem Feld effectiveStreamingMode. Wenn Streaming aktiviert ist, enthält die Ausgabe Folgendes:

effectiveStreamingMode: EFFECTIVE_STREAMING_MODE_ENABLED

Google Cloud -APIs aufrufen

Ein Streaming-Gateway kann Google Cloud -APIs wie aiplatform.googleapis.com aufrufen, sodass Sie Antworten von einem Gemini-Modell auf der Agent Platform über das Gateway streamen können. Das Gateway authentifiziert sich bei diesen Back-Ends mit einem Zugriffstoken anstelle eines ID-Tokens. Weitere Informationen finden Sie unter Backend-Dienste sichern.

Antworten von einem LLM streamen

In diesem Beispiel wird ein Streaming-Gateway vor einem Gemma-Modell platziert, das von vLLM in Cloud Run bereitgestellt wird. Anschließend wird eine Chat-Vervollständigung über das Gateway gestreamt. vLLM stellt eine OpenAI-kompatible API bereit, die Antworten als Server-Sent Events (SSE) streamt.

Bevor Sie beginnen, müssen Sie die Entwicklungsumgebung konfigurieren, einschließlich der Konfiguration des Dienstkontos, das zum Erstellen von API-Konfigurationen verwendet wird. Das Gateway verwendet dieses Dienstkonto, um den Cloud Run-Dienst aufzurufen.

Modell bereitstellen

Stellen Sie ein Gemma-Modell bereit, indem Sie der Anleitung unter Gemma 4-Modell mit einem vLLM-Container bereitstellen folgen. Notieren Sie sich den Dienstnamen, die Dienst-URL, die Region und den Namen des Modells, das Sie bereitstellen, z. B. google/gemma-4-E4B-it.

Gateway Zugriff auf den Dienst gewähren

In der Anleitung wird der Dienst mit --no-allow-unauthenticated bereitgestellt. Das Gateway ruft den Dienst mit einem ID-Token für sein Dienstkonto auf, das Sie beim Erstellen der API-Konfiguration als --backend-auth-service-account übergeben. Weisen Sie dem Dienstkonto die Rolle „Cloud Run-Aufrufer“ (roles/run.invoker) für den Dienst zu:

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

Ersetzen Sie Folgendes:

SERVICE_NAME: Der Name des Cloud Run-Dienstes
REGION: die Region, in der Sie den Dienst bereitgestellt haben
SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos des Gateways

API-Konfiguration erstellen

Speichern Sie die folgende OpenAPI-Spezifikation als gemma-api.yaml und ersetzen Sie https://my-gemma-service.run.app durch Ihre Dienst-URL:

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.

Der deadline von 570 Sekunden ist 30 Sekunden kürzer als der --timeout 600, der im Gemma-Leitfaden für den Dienst festgelegt ist. Daher wird ein zu lange laufender Stream durch das deadline des Gateways und nicht durch das Dienstzeitlimit beendet. Ein x-google-backend auf oberster Ebene ist standardmäßig pathTranslation: APPEND_PATH_TO_ADDRESS. Das Gateway hängt den Anfragepfad an die Backend-Adresse an, sodass eine Anfrage an /v1/chat/completions den vLLM-Chat-Vervollständigungsendpunkt erreicht.

Die Anforderung security bewirkt, dass das Gateway alle Anfragen ablehnt, die kein von Google signiertes ID-Token mit der Zielgruppe gemma-api enthalten. Sie können einen anderen Zielgruppenstring auswählen, solange Aufrufer denselben String anfordern, wenn sie ein Token erstellen. Weitere Informationen finden Sie unter Google-ID-Tokens zur Authentifizierung von Nutzern verwenden.

Erstellen Sie die API-Konfiguration:

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

Ersetzen Sie Folgendes:

CONFIG_ID: eine ID für die API-Konfiguration
API_ID: die ID der API. Wenn die API nicht vorhanden ist, wird sie mit dem Befehl erstellt.

Gateway erstellen

Erstellen Sie ein Streaming-Gateway aus der API-Konfiguration:

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

Ersetzen Sie Folgendes:

GATEWAY_ID: eine ID für das Gateway
GCP_REGION: die Region für das Gateway, die sich von REGION unterscheiden kann. Informationen zu zulässigen Werten finden Sie unter API auf einem Gateway bereitstellen.

Wenn das Gateway bereit ist, rufen Sie seinen Hostnamen ab:

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

ID-Token für den Aufrufer abrufen

Für ein Nutzerkonto kann die Zielgruppe des ID-Tokens nicht ausgewählt werden. Daher wird im Beispiel das Token für ein Dienstkonto erstellt, dessen Identität Sie übernehmen. Verwenden Sie für den Aufrufer ein vorhandenes Dienstkonto oder erstellen Sie eines. Weitere Informationen finden Sie unter Dienstkonten erstellen. Weisen Sie sich selbst die Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.serviceAccountTokenCreator) für dieses Dienstkonto zu, die die gcloud CLI benötigt, um die Identität des Dienstkontos zu übernehmen:

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

Ersetzen Sie Folgendes:

CALLER_SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos, das das Gateway aufruft
USER_EMAIL: Ihre E-Mail-Adresse.

Streaming-Anfrage senden

Senden Sie eine Anfrage zur Chatvervollständigung, in der "stream": true festgelegt ist, mit einem ID-Token für das Dienstkonto des Aufrufers im Authorization-Header. Mit dem Flag -N wird die Ausgabepufferung in curl deaktiviert, sodass jedes Ereignis ausgegeben wird, wenn es eintrifft:

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
    }'

Ersetzen Sie Folgendes:

DEFAULT_HOSTNAME: der Hostname des Gateways
CALLER_SERVICE_ACCOUNT_EMAIL: das Dienstkonto aus dem vorherigen Schritt
MODEL_NAME: das von Ihnen bereitgestellte Modell, z. B. google/gemma-4-E4B-it

Die Antwort ist ein SSE-Stream. Das erste Ereignis hat die Rolle assistant, jedes nachfolgende Ereignis enthält den nächsten Teil der Antwort und das letzte Ereignis vor data: [DONE] legt finish_reason fest. Die Ausgabe sieht etwa so aus:

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]

Bereinigen

Damit Ihrem Google Cloud -Konto die in diesem Beispiel verwendeten Ressourcen nicht in Rechnung gestellt werden, löschen Sie das Gateway und die API-Konfiguration:

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

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

Wenn Sie die API für dieses Beispiel erstellt haben, löschen Sie sie:

gcloud api-gateway apis delete API_ID

Löschen Sie den Cloud Run-Dienst:

gcloud run services delete SERVICE_NAME \
    --region=REGION

Preise

Während der öffentlichen Vorschau des Streamings werden Kunden keine Kosten für ausgehenden Netzwerktraffic auf Streaming-fähigen Gateways in Rechnung gestellt. Die Abrechnung für Service Control erfolgt jedoch unabhängig von der Releasephase auf API-Ebene.

Beschränkungen

Für das Streaming in API Gateway gelten während der öffentlichen Vorschau die folgenden Einschränkungen:

Unveränderlichkeit: Sie können ein vorhandenes Gateway nicht aktualisieren, um Streaming zu aktivieren oder zu deaktivieren. Sie müssen ein neues Gateway erstellen. Beachten Sie, dass ein Gateway mit aktiviertem Streaming eine andere Hostnamen-Form erhält. Daher müssen Sie Ihre Clients oder DNS-Einträge aktualisieren. Wenn Sie möchten, dass wir Ihren Gateway-Eintrag auf das neue Format aktualisieren, wenden Sie sich an den Support. API Gateway verwendet die folgenden Hostnamenmuster:
- Nicht-Streaming: {gateway_id}-{base36_project_number}.{shard_hash}.gateway.dev, z. B. test-gateway-4jcaz8x.uc.gateway.dev
- Streaming: {gateway_id}-{project_number}.{region}.gateway.dev, z. B. test-gateway-9876654321.us-central1.gateway.dev
- Streaming (alt): {service}-{tenant_project_number}.{region}.run.app, z. B. test-gateway-834512064953.us-central1.run.app. Gateways, die vor der Verfügbarkeit regionaler *.gateway.dev-Hostnamen erstellt wurden, behalten diesen Hostnamen dauerhaft und werden nicht zum neuen Muster migriert.
Ein neues Gateway mit Streaming-Unterstützung erhält das Muster Streaming. Die ersten beiden Beispiele zeigen dasselbe Gateway im selben Projekt: Im Streaming-Muster wird die Projektnummer im Dezimalformat statt im Base36-Format angezeigt, sodass das erste Label weniger Platz hat als bei einem Nicht-Streaming-Gateway. Das erste Label ist der kombinierte {gateway_id}-{project_number}-String, der das DNS-Label-Limit von 63 Zeichen einhalten muss. Die Gateway-ID-Beschränkung auf 49 Zeichen sorgt dafür, dass die Projektnummern bis zu 13 Ziffern lang sein können. Eine längere Projektnummer erfordert eine kürzere Gateway-ID.
Terraform: Das Aktivieren von Streaming mit Terraform wird nicht unterstützt (geplant für eine zukünftige Version).
Load Balancing und benutzerdefinierte Domains: Gateways mit einem effectiveStreamingMode von EFFECTIVE_STREAMING_MODE_ENABLED sind nicht mit HTTP(S)-Load-Balancing für API Gateway oder serverlosen NEGs kompatibel. Sie können ein solches Gateway nicht hinter einer serverlosen NEG oder einem externen Application Load Balancer platzieren. Daher werden benutzerdefinierte Domains (die auf Load Balancing basieren) für diese Gateways während der öffentlichen Vorschau nicht unterstützt.
Fristverhalten: Wenn Sie Streaming auf einem Gateway aktivieren, ändert sich das Verhalten des Felds deadline auf einem SSE- oder Chunked-Transfer-Pfad nicht. Die Frist bleibt eine zeitliche Begrenzung für die vollständige Antwort. Ein Stream wird also nach Ablauf der Frist beendet, unabhängig davon, wie viele Daten gesendet werden. Der Standardwert beträgt 15 Sekunden und der Höchstwert 3.600 Sekunden. Bei einem WebSocket begrenzt deadline stattdessen die Lücke zwischen Nachrichten und die Verbindung wird nach 3.600 Sekunden beendet. Weitere Informationen finden Sie unter Stream-Frist festlegen.
Model Context Protocol (MCP): Wenn Sie das Gateway mit --enable-streaming erstellen, wird kein MCP-Endpunktstream erstellt. MCP-Antworten bleiben unabhängig vom Streamingmodus des Gateways ein einzelner application/json-Text. Weitere Informationen finden Sie unter MCP-Einschränkungen.