Strukturierte Ausgaben mit Anthropic Claude-Modellen

Vorschau

Diese Funktion unterliegt den Bedingungen für Pre‑GA-Angebote im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen und den Zusatzbedingungen für Vorschauprodukte auf Basis von generativer KI. Sie können personenbezogene Daten für diese Funktion gemäß dem Zusatz zur Verarbeitung von Cloud-Daten verarbeiten, vorbehaltlich der in der Vereinbarung beschriebenen Verpflichtungen und Einschränkungen, gemäß der Sie auf Google Cloud zugreifen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

Mit strukturierten Ausgaben können Sie die generierte Ausgabe eines Claude-Modells so einschränken, dass sie genau einem bestimmten JSON-Schema entspricht. Das ist nützlich, um sicherzustellen, dass die Antworten Ihrer Claude-Modelle immer das genaue Format haben, das für nachgelagerte Anwendungen, Datenbanken und Verarbeitungspipelines erforderlich ist.

Strukturierte Ausgaben bieten zwei ergänzende Funktionen, die Sie unabhängig voneinander oder zusammen in derselben Anfrage verwenden können:

• JSON-Ausgaben (output_config.format): Beschränken Sie die Textantwort des Modells auf ein JSON-Objekt, das einem von Ihnen bereitgestellten Schema entspricht. Verwenden Sie diese Funktion, wenn Sie strukturierte Daten aus Text extrahieren, strukturierte Berichte erstellen oder API-Antworten formatieren müssen.
• Strenge Tool-Nutzung (tools[].strict): Stellen Sie sicher, dass die Argumente, die das Modell an ein Tool übergibt, mit dem input_schema des Tools übereinstimmen. Verwenden Sie diese Funktion, wenn Sie typsichere Funktionsaufrufe in agentischen Workflows benötigen.

Weitere Informationen finden Sie in der Dokumentation von Anthropic unter Building with Claude: Structured Outputs and Strict tool use.

Unterstützte Anthropic Claude-Modelle

Die Gemini Enterprise Agent Platform unterstützt strukturierte Ausgaben für die folgenden Anthropic Claude-Modelle:

• Claude Opus 4.7
• Claude Sonnet 4.6
• Claude Opus 4.6
• (Demnächst verfügbar) Claude Opus 4.5
• (Demnächst verfügbar) Claude Sonnet 4.5
• (Demnächst verfügbar) Claude Haiku 4.5

Zugriff auf strukturierte Ausgaben steuern

Standardmäßig sind strukturierte Ausgaben durch die Einschränkung der Organisationsrichtlinie constraints/vertexai.allowedPartnerModelFeatures deaktiviert. Wenn Sie strukturierte Ausgaben aktivieren möchten, müssen Sie diese Einschränkung so konfigurieren, dass die Funktion structured_outputs explizit zugelassen wird.

Außerdem können Sie die Einschränkung der Organisationsrichtlinie constraints/vertexai.allowedModels konfigurieren, um den Zugriff auf Claude-Modelle einzuschränken.

Eine detaillierte Anleitung zum Konfigurieren von Einschränkungen für Organisationsrichtlinien finden Sie unter Zugriff auf Model Garden-Modelle steuern.

Anfrage für strukturierte Ausgabe senden

Wenn Sie eine JSON-Ausgabe anfordern möchten, senden Sie eine POST-Anfrage an den Endpunkt des Publisher-Modells und fügen Sie den Parameter output_config in den Anfragetext ein. Der Parameter output_config gibt das JSON-Schema an, dem die Antwort des Modells entsprechen muss.

REST

Im folgenden Beispiel wird gezeigt, wie Sie eine Anfrage an die Agent Platform API senden, um strukturierte Kontaktinformationen aus einer unstrukturierten E‑Mail zu extrahieren. Die Antwort ist auf ein JSON-Objekt mit den Feldern name, email, plan_interest und demo_requested beschränkt.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

• LOCATION: Eine Region, die Anthropic Claude-Modelle unterstützt. Informationen zum Verwenden des globalen Endpunkts finden Sie unter Globalen Endpunkt angeben.
• MODEL: Ein unterstütztes Claude-Modell, z. B. claude-opus-4-7.
• ROLE: Die einer Nachricht zugeordnete Rolle. Sie können user oder assistant angeben. Die erste Nachricht muss die Rolle user verwenden. Claude-Modelle arbeiten mit abwechselnden user und assistant Runden. Wenn die endgültige Nachricht die assistant Rolle verwendet, wird der Antwort inhalt direkt vom Inhalt dieser Nachricht aus fortgesetzt. So können Sie einen Teil der Antwort des Modells einschränken.
• CONTENT: Der Inhalt, z. B. Text der user oder assistant Nachricht. Beispiel: Extract the key information from this email: John Smith ([e-mail]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.
• MAX_TOKENS: Maximale Anzahl an Tokens, die in der Antwort generiert werden können. Ein Token entspricht ungefähr 3,5 Zeichen. 100 Tokens entsprechen etwa 60–80 Wörtern.

  Geben Sie kürzere Werte für kürzere Antworten und höhere Werte für längere Antworten an.

• STREAM: Ein boolescher Wert, mit dem angegeben wird, ob die Antwort gestreamt wird oder nicht. Legen Sie true fest, um die Antwort zu streamen, und false fest, um die Antwort auf einmal zurückzugeben. Strukturierte Ausgaben werden in der Regel mit false zurückgegeben.

Im Beispiel werden die folgenden Felder für strukturierte Ausgaben verwendet. Weitere Informationen zu den einzelnen Feldern finden Sie im Abschnitt Anfragefelder.

• output_config: Der Konfigurationsblock der obersten Ebene, der die Struktur der Antwort des Modells steuert.
• output_config.format.type: Legen Sie json_schema fest, um die Antwort auf ein JSON-Objekt zu beschränken, das dem angegebenen Schema entspricht.
• output_config.format.schema: Ein JSON-Schema, das die erforderliche Struktur der Antwort des Modells definiert. Das Schema muss dem unterstützten JSON-Schema-Subset entsprechen.

HTTP-Methode und URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

JSON-Text der Anfrage:

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "email": {"type": "string"},
          "plan_interest": {"type": "string"},
          "demo_requested": {"type": "boolean"}
        },
        "required": ["name", "email", "plan_interest", "demo_requested"],
        "additionalProperties": false
      }
    }
  }
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt haben, die Sie automatisch in der gcloud-Befehlszeile anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict"

PowerShell

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt haben. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten: Das Feld text des Blocks content enthält einen JSON-String, der dem in output_config angegebenen Schema entspricht.

Antwort

{
  "id": "msg_vrtx_01ABcdEFghIJklMNopQRstUV",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-7",
  "content": [
    {
      "type": "text",
      "text": "{\"name\": \"John Smith\", \"email\": \"[e-mail]\", \"plan_interest\": \"Enterprise\", \"demo_requested\": true}"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 78,
    "output_tokens": 42
  }
}

Anfragefelder

Die folgenden Felder sind spezifisch für JSON-Ausgaben. Informationen zu den anderen Anfragefeldern finden Sie in der API-Referenz für Claude-Nachrichten.

• output_config: Der Konfigurationsblock der obersten Ebene, der die Struktur der Antwort des Modells steuert.
• output_config.format: Die Formatdefinition für die Ausgabe. Nur der Typ json_schema wird unterstützt.
• output_config.format.type: Der Typ des Ausgabeformats, das erzwungen werden soll. Legen Sie json_schema fest, um die Antwort auf ein JSON-Objekt zu beschränken.

• output_config.format.schema: Ein JSON-Schema, das die erforderliche Struktur der Antwort des Modells definiert. Strukturierte Ausgaben unterstützen das Standard-JSON-Schema mit einigen Einschränkungen. So muss beispielsweise additionalProperties für Objekte auf false festgelegt werden und numerische oder Stringlängen-Einschränkungen werden nicht unterstützt. Eine vollständige Liste der unterstützten und nicht unterstützten Funktionen finden Sie in der Dokumentation von Anthropic unter JSON Schema limitations. Im Schema geben Sie in der Regel Folgendes an:

  • type: Der JSON-Typ des Werts auf dieser Ebene (am häufigsten object für das Stammschema).
  • properties: Eine Zuordnung von Feldnamen zu ihren Typdefinitionen, die jedes Feld beschreiben, das das Modell zurückgeben muss.
  • required: Eine Liste von Attributnamen, die das Modell in seine Antwort aufnehmen muss.
  • additionalProperties: Ein boolescher Wert, der bei Festlegung auf false verhindert, dass das Modell Felder einbezieht, die nicht in properties deklariert sind.

Strenge Tool-Nutzung verwenden

Die strenge Tool-Nutzung sorgt dafür, dass die Argumente, die das Modell an ein Tool übergibt, mit dem input_schema des Tools übereinstimmen. Ohne den strikten Modus kann das Modell ein Tool mit Argumenten des falschen Typs aufrufen (z. B. "2" anstelle von 2) oder erforderliche Felder weglassen, was zu Fehlern in Ihren nachgelagerten Funktionen führen und eine Wiederholungslogik erfordern kann. Wenn der strikte Modus aktiviert ist, verwendet die API die grammatikbeschränkte Stichprobenerhebung, um Folgendes sicherzustellen:

• Der name des Tools ist immer eines der von Ihnen bereitgestellten Tools.
• Die input des Tools entspricht immer dem input_schema des Tools.

Verwenden Sie die strenge Tool-Nutzung, wenn Sie Tool-Parameter validieren, agentische Workflows erstellen, typsichere Funktionsaufrufe sicherstellen oder komplexe Tools mit verschachtelten Attributen verarbeiten müssen.

Wenn Sie die strenge Tool-Nutzung aktivieren möchten, legen Sie "strict": true als Feld der obersten Ebene in Ihrer Tool-Definition fest, zusammen mit name, description, und input_schema.

REST

Im folgenden Beispiel wird gezeigt, wie Sie eine Anfrage an die Agent Platform API senden, die ein strenges get_weather-Tool definiert. Das Modell ruft das Tool garantiert mit einem location-String und einer optionalen unit auf, die entweder celsius oder fahrenheit ist.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

• LOCATION: Eine Region, die Anthropic Claude-Modelle unterstützt. Informationen zum Verwenden des globalen Endpunkts finden Sie unter Globalen Endpunkt angeben.
• MODEL: Ein unterstütztes Claude-Modell, z. B. claude-opus-4-7.
• ROLE: Die einer Nachricht zugeordnete Rolle. Die erste Nachricht muss die Rolle user verwenden.
• CONTENT: Der Inhalt, z. B. Text der user oder assistant Nachricht. Beispiel: What is the weather in San Francisco?
• MAX_TOKENS: Maximale Anzahl an Tokens, die in der Antwort generiert werden können. Ein Token entspricht ungefähr 3,5 Zeichen. 100 Tokens entsprechen etwa 60–80 Wörtern.

  Geben Sie kürzere Werte für kürzere Antworten und höhere Werte für längere Antworten an.

• STREAM: Ein boolescher Wert, mit dem angegeben wird, ob die Antwort gestreamt wird oder nicht. Legen Sie true fest, um die Antwort zu streamen, und false fest, um die Antwort auf einmal zurückzugeben.

Im Beispiel werden die folgenden Felder für die strenge Tool-Nutzung verwendet. Weitere Informationen zu den einzelnen Feldern finden Sie im Abschnitt Felder für die strenge Tool-Nutzung.

• tools[].strict: Ein boolescher Wert, der bei Festlegung auf true, die grammatikbeschränkte Stichprobenerhebung für das Tool aktiviert. Das Modell ruft das Tool garantiert mit Argumenten auf, die dem input_schema entsprechen.
• tools[].input_schema: Ein JSON-Schema, das die Argumente definiert, die das Modell an das Tool übergeben kann. Wenn strict auf true gesetzt ist, muss das Schema dem gleichen unterstützten JSON-Schema-Subset entsprechen wie das output_config Schema für JSON Ausgaben.

HTTP-Methode und URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

JSON-Text der Anfrage:

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, for example San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }
  ]
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt haben, die Sie automatisch in der gcloud-Befehlszeile anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict"

PowerShell

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt haben. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten: Der tool_use Inhaltsblock enthält ein input Feld, dessen Schlüssel und Werttypen garantiert mit dem input_schema des Tools übereinstimmen.

Antwort

{
  "id": "msg_vrtx_01ABcdEFghIJklMNopQRstUV",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-7",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_vrtx_01TAJCTkxe8HhRoaQ69N4ouP",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA",
        "unit": "fahrenheit"
      }
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 412,
    "output_tokens": 64
  }
}

Felder für die strenge Tool-Nutzung

Die folgenden Felder sind spezifisch für die strenge Tool-Nutzung. Informationen zu den anderen Feldern der Tool-Definition finden Sie in der Dokumentation von Anthropic unter Define tools.

• tools[].strict: Ein boolescher Wert, der bei Festlegung auf true die grammatikbeschränkte Stichprobenerhebung für das Tool aktiviert. Wenn strict auf true gesetzt ist, ist die Tool-Eingabe des Modells so eingeschränkt, dass sie dem Schema in input_schema entspricht. Der Standardwert ist false.

• tools[].input_schema: Ein JSON-Schema, das die Argumente definiert, die das Modell an das Tool übergeben kann. Wenn strict auf true gesetzt ist, muss das Schema dem gleichen JSON-Schema-Subset entsprechen, das für JSON-Ausgaben verwendet wird. Insbesondere müssen Sie Folgendes tun:

  • Legen Sie additionalProperties für jedes Objekt im Schema auf false fest.
  • Listen Sie alle Attribute im Array required auf.

  Eine vollständige Liste der unterstützten und nicht unterstützten Funktionen finden Sie in der Dokumentation von Anthropic unter JSON Schema limitations.