Strukturierte AI_COMPLETE-Ausgaben¶

Verwenden von AI_COMPLETE mit Typliteralen¶

Typliterale ermöglichen es Ihnen, eine strukturierte Ausgabe für AI_COMPLETE mit SQL-Typen zu definieren. Sie nutzen die Snowflake-Zuordnungen von SQL zu JSON-Typen. Beginnen Sie Ihr Typliteral mit dem Schlüsselwort TYPE, und verwenden Sie ein SQL-OBJECT als Typ auf der obersten Ebene. Die Eigenschaften Ihres Objekts der obersten Ebene können ein beliebiger SQL-Typ mit einer unterstützten Zuordnung zu JSON sein.

Das folgende Beispiel verwendet ein Typliteral, um eine strukturierte Ausgabe für eine Eingabeaufforderung zu erzeugen. Die Aufforderung enthält sowohl Anweisungen für das Modell als auch die zu verarbeitenden Daten. Das Typliteral response_format erzeugt die Antwort des Modells als JSON-Objekt mit einer note auf der obersten Ebene, das ein Array von date, address, items_count und price mit Preisen enthält.

SELECT AI_COMPLETE(
    model => 'llama3.3-70b',
    prompt => 'Extract structured data from this customer interaction note: Customer Sarah Jones complained about the mobile app crashing during checkout. She tried to purchase 3 items: a red XL jacket ($89.99), blue running shoes ($129.50), and a fitness tracker ($199.00). The app crashed after she entered her shipping address at 123 Main St, Portland OR, 97201. She has been a premium member since January 2024.',
    response_format => TYPE OBJECT(note OBJECT(items_count NUMBER, price ARRAY(STRING), address STRING, member_date STRING)),
);

Im Folgenden sehen Sie eine vollständige Antwort auf diese Abfrage:

{
  "note": {
      "items_count": 3,
      "price": [
        "$89.99",
        "$129.50",
        "$199.00"
      ]
    }
  }
}

Verwenden von AI_COMPLETE mit JSON-Schemas¶

Wenn Sie mehr Kontrolle über die strukturierte Ausgabe wünschen, verwenden Sie ein JSON-Schema als Wert für response_format. Das angegebene JSON-Schemaobjekt definiert die Struktur, die Datentypen und die Einschränkungen, denen der generierte Text entsprechen muss, einschließlich der erforderlichen Felder. Bei einfachen Aufgaben müssen Sie keine Details zum Ausgabeformat angeben oder das Modell gar anweisen, „in JSON zu antworten“.

Bei komplexeren Aufgaben hilft es, das Modell aufzufordern, „in JSON zu antworten“, um die Genauigkeit zu verbessern. Informationen dazu finden Sie unter Optimierung der JSON-Einhaltungsgenauigkeit.

ai_complete(
    ...
    response_format => {
        'type': 'json',
        'schema': {
            'type': 'object',
            'properties': {
                'property_name': {
                    'type': 'string'
                },
                ...
            },
            'required': ['property_name', ...]
        }
    }

SQL-Beispiel¶

Das folgende Beispiel zeigt, wie Sie das Argument response_format verwenden, um ein JSON-Schema für die Antwort anzugeben.

SELECT AI_COMPLETE(
    model => 'mistral-large2',
    prompt => 'Return the customer sentiment for the following review: New kid on the block, this pizza joint! The pie arrived neither in a flash nor a snail\'s pace, but the taste? Divine! Like a symphony of Italian flavors, it was a party in my mouth. But alas, the party was a tad pricey for my humble abode\'s standards. A mixed bag, I\'d say!',
    response_format => {
            'type':'json',
            'schema':{'type' : 'object','properties' : {'sentiment_categories':{'type': 'object','properties':
            {'food_quality' : {'type' : 'string'},'food_taste': {'type':'string'}, 'wait_time': {'type':'string'}, 'food_cost': {'type':'string'}},'required':['food_quality','food_taste' ,'wait_time','food_cost']}}}

    }
);

Antwort:

{
    "sentiment_categories":
    {
        "food_cost": "negative",
        "food_quality": "positive",
        "food_taste": "positive",
        "wait_time": "neutral"
    }
}

Das folgende Beispiel zeigt, wie Sie mit dem Argument response_format ein JSON-Schema für die Antwort angeben und mit dem Argument show_details Inferenz-Metadaten zurückgeben.

SELECT AI_COMPLETE(
    model => 'mistral-large2',
    prompt => 'Return the customer sentiment for the following review: New kid on the block, this pizza joint! The pie arrived neither in a flash nor a snail\'s pace, but the taste? Divine! Like a symphony of Italian flavors, it was a party in my mouth. But alas, the party was a tad pricey for my humble abode\'s standards. A mixed bag, I\'d say!',
    response_format => {
            'type':'json',
            'schema':{'type' : 'object','properties' : {'sentiment_categories':{'type': 'object','properties':
            {'food_quality' : {'type' : 'string'},'food_taste': {'type':'string'}, 'wait_time': {'type':'string'}, 'food_cost': {'type':'string'}},'required':['food_quality','food_taste' ,'wait_time','food_cost']}}}

    }
    show_details => TRUE
);

Antwort:

{
    "created": 1738683744,
    "model": "mistral-large2",
    "structured_output": [
        {
        "raw_message": {
            "sentiment_categories":
            {
                "food_cost": "negative",
                "food_quality": "positive",
                "food_taste": "positive",
                "wait_time": "neutral"
            }
        },
        "type": "json"
        }
    ],
    "usage": {
        "completion_tokens": 60,
        "prompt_tokens": 94,
        "total_tokens": 154
    }
}

Python-Beispiel¶

Das folgende Beispiel zeigt, wie Sie das Argument response_format verwenden, um ein JSON-Schema für die Antwort anzugeben.

from snowflake.cortex import complete, CompleteOptions

response_format = {
    "type": "json",
    "schema": {
        "type": "object",
        "properties": {
            "people": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "age": {"type": "number"},
                    },
                    "required": ["name", "age"],
                },
            }
        },
        "required": ["people"],
    },
}
prompt = [{
    "role": "user",
    "content": "Please prepare me a data set of 5 ppl and their age",
}]

options = CompleteOptions(
        max_tokens=4096,
        temperature=0.7,
        top_p=1,
        guardrails=False,
        response_format=response_format
    )


result = complete(
model="claude-3-5-sonnet",
prompt=prompt,
session={session_object}, # session created via connector
stream=True,
options=options,
)

output = "".join(result)
print(output)

Antwort:

{"people": [{"name":"John Smith","age":32},{"name":"Sarah Johnson","age":28},
{"name":"Michael Chen","age":45},{"name":"Emily Davis","age":19},{"name":"Robert Wilson","age":56}]}

from pydantic import BaseModel, Field
import json
from snowflake.cortex import complete, CompleteOptions
from snowflake.snowpark.context import get_active_session

class Person(BaseModel):
    age: int = Field(description="Person age")
    name: str = Field(description="Person name")

class People(BaseModel):
    people: list[Person] = Field(description="People list")

ppl = People.model_json_schema()
'''
This is the ppl object, keep in mind there's a '$defs' key used

{'$defs': {'Person': {'properties': {'age': {'description': 'Person age', 'title': 'Age', 'type': 'integer'}, 'name': {'description': 'Person name', 'title': 'Name', 'type': 'string'}}, 'required': ['age', 'name'], 'title': 'Person', 'type': 'object'}}, 'properties': {'people': {'description': 'People list', 'items': {'$ref': '#/$defs/Person'}, 'title': 'People', 'type': 'array'}}, 'required': ['people'], 'title': 'People', 'type': 'object'}

'''

response_format_pydantic={
    "type": "json",
    "schema": ppl,
}
prompt=[{"role": "user", "content": "Please prepare me a data set of 5 ppl and their age"}]
options_pydantic = CompleteOptions(  # random params
        max_tokens=4096,
        temperature=0.7,
        top_p=1,
        guardrails=False,
        response_format=response_format_pydantic
    )
model_name = "claude-3-5-sonnet"


session = get_active_session()
try:
    result_pydantic = complete(
        model=model_name,
        prompt=prompt,
        session=session,
        stream=True,
        options=options_pydantic,
    )
except Exception as err:
    result_pydantic = (chunk for chunk in err.response.text) # making sure it's generator, similar to the valid response

output_pydantic = "".join(result_pydantic)
print(output_pydantic)

{"people": [{"name":"John Smith","age":32},{"name":"Sarah Johnson","age":45},
{"name":"Mike Chen","age":28},{"name":"Emma Wilson","age":19},{"name":"Robert Brown","age":56}]}

REST API-Beispiel¶

Sie können den Snowflake Cortex LLM REST API verwenden, um COMPLETE mit dem LLM Ihrer Wahl aufzurufen. Nachfolgend finden Sie ein Beispiel für die Bereitstellung eines Schemas unter Verwendung des Cortex LLM REST API:

curl --location --request POST 'https://<account_identifier>.snowflakecomputing.com/api/v2/cortex/inference:complete'
--header 'Authorization: Bearer <jwt>' \
--header 'Accept: application/json, text/event-stream' \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "claude-3-5-sonnet",
    "messages": [{
        "role": "user",
        "content": "Order a pizza for a hungry space traveler heading to the planet Zorgon. Make sure to include a special instruction to avoid any intergalactic allergens."
    }],
    "max_tokens": 1000,
    "response_format": {
            "type": "json",
            "schema":
            {
                "type": "object",
                "properties":
                {
                    "crust":
                    {
                        "type": "string",
                        "enum":
                        [
                            "thin",
                            "thick",
                            "gluten-free",
                            "Rigellian fungus-based"
                        ]
                    },
                    "toppings":
                    {
                        "type": "array",
                        "items":
                        {
                            "type": "string",
                            "enum":
                            [
                                "Gnorchian sausage",
                                "Andromedian mushrooms",
                                "Quasar cheese"
                            ]
                        }
                    },
                    "delivery_planet":
                    {
                        "type": "string"
                    },
                    "special_instructions":
                    {
                        "type": "string"
                    }
                },
                "required":
                [
                    "crust",
                    "toppings",
                    "delivery_planet"
                ]
            }
        }
    }'

Antwort:

data: {"id":"4d62e41a-d2d7-4568-871a-48de1463ed2a","model":"claude-3-5-sonnet","choices":[{"delta":{"content":"{\"crust\":","content_list":[{"type":"text","text":"{\"crust\":"}]}}],"usage":{}}

data: {"id":"4d62e41a-d2d7-4568-871a-48de1463ed2a","model":"claude-3-5-sonnet","choices":[{"delta":{"content":" \"thin\"","content_list":[{"type":"text","text":" \"thin\""}]}}],"usage":{}}

data: {"id":"4d62e41a-d2d7-4568-871a-48de1463ed2a","model":"claude-3-5-sonnet","choices":[{"delta":{"content":", \"topping","content_list":[{"type":"text","text":", \"topping"}]}}],"usage":{}}

data: {"id":"4d62e41a-d2d7-4568-871a-48de1463ed2a","model":"claude-3-5-sonnet","choices":[{"delta":{"content":"s\": [\"Quasar","content_list":[{"type":"text","text":"s\": [\"Quasar"}]}}],"usage":{}}

Erstellen Sie eine JSON-Schemadefinition¶

Um die bestmögliche Genauigkeit von strukturierten COMPLETE-Ausgaben zu erhalten, befolgen Sie diese Richtlinien:

• Verwenden Sie das Feld „erforderlich“ im Schema, um erforderliche Felder anzugeben. COMPLETE gibt einen Fehler aus, wenn ein erforderliches Feld nicht extrahiert werden kann.

  Im folgenden Beispiel weist das Schema COMPLETE an, die im Dokument erwähnten Personen zu finden. Das Feld people ist als erforderlich gekennzeichnet, um sicherzustellen, dass die Personen identifiziert werden.

  {
      'type': 'object',
      'properties': {
          'dataset_name': {
              'type': 'string'
          },
          'created_at': {
              'type': 'string'
          },
          'people': {
              'type': 'array',
              'items': {
                  'type': 'object',
                  'properties': {
                      'name': {
                          'type': 'string'
                      },
                      'age': {
                          'type': 'number'
                      },
                      'isAdult': {
                          'type': 'boolean'
                      }
                  }
              }
          }
      },
      'required': [
          'dataset_name',
          'created_at',
          'people'
      ]
  }
  

  Copy

  Antwort:

  {
      "dataset_name": "name",
      "created_at": "date",
      "people": [
          {
              "name": "Andrew",
              "isAdult": true
          }
      ]
  }
  

• Stellen Sie detaillierte Beschreibungen der zu extrahierenden Felder zur Verfügung, damit das Modell diese genauer identifizieren kann. Das folgende Schema enthält zum Beispiel eine Beschreibung der einzelnen Felder von people: name, age, und isAdult.

  {
      'type': 'object',
      'properties': {
          'dataset_name': {
              'type': 'string'
          },
          'created_at': {
              'type': 'string'
          },
          'people': {
              'type': 'array',
              'items': {
                  'type': 'object',
                  'properties': {
                      'name': {
                          'type': 'string',
                          'description': 'name should be between 9 to 10 characters'
                      },
                      'age': {
                          'type': 'number',
                          'description': 'Should be a value between 0 and 200'
                      },
                      'isAdult': {
                          'type': 'boolean',
                          'description': 'Persons is older than 18'
                      }
                  }
              }
          }
      }
  }
  

  Copy

{
    '$defs': {
        'person':{'type':'object','properties':{'name' : {'type' : 'string'},'age': {'type':'number'}}, 'required':['name','age']}},
    'type': 'object',
    'properties': {'title':{'type':'string'},'people':{'type':'array','items':{'$ref':'#/$defs/person'}}}
}

select ai_complete(
    model => 'claude-3-5-sonnet',
    prompt => 'Extract structured data from this customer interaction note: Customer Sarah Jones complained about the mobile app crashing during checkout. She tried to purchase 3 items: a red XL jacket ($89.99), blue running shoes ($129.50), and a fitness tracker ($199.00). The app crashed after she entered her shipping address at 123 Main St, Portland OR, 97201. She has been a premium member since January 2024.',
    'response_format' => {
            'type': 'json',
            'schema': {
'type': 'object',
'$defs': {
    'price': {
        'type': 'object',
        'properties': {
            'amount': {'type': 'number'},
            'currency': {'type': 'string'}
        },
        'required': ['amount']
    },
    'address': {
        'type': 'object',
        'properties': {
            'street': {'type': 'string'},
            'city': {'type': 'string'},
            'state': {'type': 'string'},
            'zip': {'type': 'string'},
            'country': {'type': 'string'}
        },
        'required': ['street', 'city', 'state']
    },
    'product': {
        'type': 'object',
        'properties': {
            'name': {'type': 'string'},
            'category': {'type': 'string'},
            'color': {'type': 'string'},
            'size': {'type': 'string'},
            'price': {'$ref': '#/$defs/price'}
        },
        'required': ['name', 'price']
    }
},
'properties': {
    'customer': {
        'type': 'object',
        'properties': {
            'name': {'type': 'string'},
            'membership': {
                'type': 'object',
                'properties': {
                    'type': {'type': 'string'},
                    'since': {'type': 'string'}
                }
            },
            'shipping_address': {'$ref': '#/$defs/address'}
        },
        'required': ['name']
    },
    'issue': {
        'type': 'object',
        'properties': {
            'type': {'type': 'string'},
            'platform': {'type': 'string'},
            'stage': {'type': 'string'},
            'severity': {'type': 'string', 'enum': ['low', 'medium', 'high', 'critical']}
        },
        'required': ['type', 'platform']
    },
    'cart': {
        'type': 'object',
        'properties': {
            'items': {
                'type': 'array',
                'items': {'$ref': '#/$defs/product'}
            },
            'total': {'$ref': '#/$defs/price'},
            'item_count': {'type': 'integer'}
        }
    },
    'recommended_actions': {
        'type': 'array',
        'items': {
            'type': 'object',
            'properties': {
                'department': {'type': 'string'},
                'action': {'type': 'string'},
                'priority': {'type': 'string', 'enum': ['low', 'medium', 'high', 'urgent']}
            }
        }
    }
},
'required': ['customer', 'issue','cart']
}
        }
    }
);

{
  "created": 1747313083,
  "model": "claude-3-5-sonnet",
  "structured_output": [
    {
      "raw_message": {
        "cart": {
          "item_count": 3,
          "items": [
            {
              "color": "red",
              "name": "jacket",
              "price": {
                "amount": 89.99,
                "currency": "USD"
              },
              "size": "XL"
            },
            {
              "color": "blue",
              "name": "running shoes",
              "price": {
                "amount": 129.5,
                "currency": "USD"
              }
            },
            {
              "name": "fitness tracker",
              "price": {
                "amount": 199,
                "currency": "USD"
              }
            }
          ],
          "total": {
            "amount": 418.49,
            "currency": "USD"
          }
        },
        "customer": {
          "membership": {
            "since": "2024-01",
            "type": "premium"
          },
          "name": "Sarah Jones",
          "shipping_address": {
            "city": "Portland",
            "state": "OR",
            "street": "123 Main St",
            "zip": "97201"
          }
        },
        "issue": {
          "platform": "mobile",
          "severity": "high",
          "stage": "checkout",
          "type": "app_crash"
        }
      },
      "type": "json"
    }
  ],
  "usage": {
    "completion_tokens": 57,
    "prompt_tokens": 945,
    "total_tokens": 1002
  }
}

Optimierung der JSON-Einhaltungsgenauigkeit¶

Strukturierte COMPLETE-Ausgaben benötigt in der Regel keine Eingabeaufforderung; es versteht bereits, dass seine Antwort dem von Ihnen angegebenen Schema entsprechen sollte. Die Komplexität der Aufgabe kann jedoch die Möglichkeit von LLMs, einem JSON-Antwortformat zu folgen, erheblich beeinflussen. Je komplexer die Aufgabe ist, desto mehr können Sie die Genauigkeit der Ergebnisse verbessern, indem Sie eine Eingabeaufforderung angeben.

• Einfache Aufgaben wie z. B. Textklassifizierung, Entitäten-Extraktion, Paraphrasierung und Zusammenfassungsaufgaben, die keine komplexen Schlussfolgerungen erfordern, benötigen in der Regel keine zusätzliche Eingabeaufforderung. Bei kleineren Modellen mit geringerer Intelligenz verbessert die Verwendung von strukturierten Ausgaben die Genauigkeit von JSON erheblich, da sie jeden Text ignoriert, den das Modell ohne Bezug zum bereitgestellten Schema liefert.

• Zu den Aufgaben mittlerer Komplexität gehören alle einfachen Aufgaben, bei denen das Modell um zusätzliche Argumente gebeten wird, z. B. um die Begründung einer Klassifizierungsentscheidung bereitzustellen. Für diese Anwendungsfälle empfehlen wir, in der Eingabeaufforderung „In JSON antworten“ hinzuzufügen, um die Leistung zu optimieren.

• Komplexe schlussfolgernde Aufgaben fordern die Modelle auf, offenere, mehrdeutige Aufgaben zu erfüllen, wie z. B. die Beurteilung und Bewertung der Qualität eines Anrufs auf der Grundlage der Relevanz, Professionalität und Treue der Antworten. Für diese Anwendungsfälle empfehlen wir die Verwendung der leistungsstärksten Modelle wie claude-3-5-sonnet von Anthropic oder mistral-large2 von Mistral AI und das Hinzufügen von „In JSON antworten“ und Details über das Schema, das Sie generieren möchten, in der Eingabeaufforderung.

Um möglichst konsistente Ergebnisse zu erhalten, setzen Sie die Option temperature auf 0, wenn Sie COMPLETE aufrufen, unabhängig von der Aufgabe oder dem Modell.

Hinweise zu Kosten¶

Strukturierte Cortex COMPLETE-Ausgaben verursacht Rechenkosten auf der Grundlage der Anzahl der verarbeiteten Token, aber keine zusätzlichen Rechenkosten für den Overhead der Überprüfung jedes Tokens anhand des bereitgestellten JSON-Schemas. Die Anzahl der verarbeiteten (und abgerechneten) Token steigt jedoch mit der Komplexität des Schemas. Im Allgemeinen gilt: Je größer und komplexer das gelieferte Schema ist, desto mehr Eingabe- und Ausgabe-Token werden verbraucht. Stark strukturierte Antworten mit tiefer Verschachtelung (z. B. hierarchische Daten) verbrauchen eine größere Anzahl von Token als einfachere Schemata.

Einschränkungen¶

• Sie können keine Leerzeichen in den Schlüsseln des Schemas verwenden.

• Die zulässigen Zeichen für Eigenschaftsnamen sind Buchstaben, Ziffern, Bindestriche und Unterstriche. Die Namen dürfen maximal 64 Zeichen lang sein.

• Sie können externe Schemata nicht über $ref oder $dynamicRef ansprechen.

Die folgenden Einschränkungs-Schlüsselwörter werden nicht unterstützt. Die Verwendung eines nicht unterstützten Einschränkungs-Schlüsselworts führt zu einem Fehler.

Diese Beschränkungenkönnten in zukünftigen Releases aufgehoben werden.

Fehlerbedingungen¶