Strukturierte AI_COMPLETE-Ausgaben¶
Mit strukturierten AI_COMPLETE-Ausgaben können Sie ein JSON-Schema angeben, dem die Abschlussantworten folgen müssen. Dies reduziert den Bedarf an Nachbearbeitung in Ihren AI-Datenpipelines und ermöglicht eine nahtlose Integration mit Systemen, die deterministische Antworten erfordern. AI_COMPLETE prüft jedes generierte Token anhand Ihres JSON-Schemas, um sicherzustellen, dass die Antwort mit dem angegebenen Schema übereinstimmt.
Jedes von AI_COMPLETE unterstützte Modell unterstützt eine strukturierte Ausgabe, aber die leistungsstärksten Modelle erzeugen in der Regel Antworten von höherer Qualität.
Strukturierte AI_COMPLETE-Ausgaben verwenden¶
Um eine Antwort in einem strukturierten Format zu erhalten, geben Sie als response_format
-Argument ein Objekt an, das ein JSON-Schema darstellt. Das mitgelieferte JSON-Schema-Objekt definiert die Struktur, die Datentypen und die Einschränkungen, denen der generierte Text entsprechen muss, einschließlich der erforderlichen Felder. Für einfache Aufgaben müssen Sie keine Details des Ausgabeformats angeben oder das Modell sogar anweisen, „in JSON zu antworten“. Bei komplexeren Aufgaben kann es die Genauigkeit verbessern, wenn Sie das Modell auffordern, unter JSON zu antworten; siehe 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':'array','items':{'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':'array','items':{'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¶
Bemerkung
Die strukturierte Ausgabe wird in snowflake-ml-python
ab Version 1.8.0 unterstützt.
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}]}
Pydantic-Beispiel¶
Pydantic ist eine Bibliothek zur Datenvalidierung und Verwaltung von Einstellungen für Python. Dieses Beispiel verwendet Pydantic, um ein Schema für das Antwortformat zu definieren. Der Code führt diese Schritte aus:
Verwendet Pydantic zur Definition eines Schemas
Konvertiert das Pydantic-Modell in ein JSON-Schema unter Verwendung der Methode
model_json_schema
Übergibt das JSON-Schema als Argument
response_format
an die Funktioncomplete
Bemerkung
Dieses Beispiel soll in einem Snowsight Python-Arbeitsblatt ausgeführt werden, das bereits eine Verbindung zu Snowflake hat. Wenn Sie die Anwendung in einer anderen Umgebung ausführen möchten, müssen Sie möglicherweise unter eine Verbindung zu Snowflake mit dem Snowflake Connector für Python herstellen.
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")
people: list[Person] = Field(description="People list")
ppl = Person.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)
Antwort:
{"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' ] }
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
, undisAdult
.{ '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' } } } } } }
Verwendung der JSON-Referenz¶
Schemareferenzen lösen praktische Probleme bei der Verwendung von strukturierten Cortex COMPLETE-Ausgaben. Mit Referenzen, die durch $ref
dargestellt werden, können Sie gemeinsame Objekte wie Adressen oder Preise einmal definieren und dann im gesamten Schema darauf verweisen. Auf diese Weise können Sie, wenn Sie die Validierungslogik aktualisieren oder ein Feld hinzufügen müssen, die Änderungen an einer Stelle vornehmen, anstatt an mehreren Stellen, was die Fehleranfälligkeit verringert.
Die Verwendung von Referenzen reduziert Fehler durch inkonsistente Implementierungen und macht Code-Reviews einfacher. Referenzierte Komponenten schaffen klarere Hierarchien, die die Beziehungen zwischen Entitäten in Ihrem Datenmodell besser darstellen. Da Projekte immer komplexer werden, hilft Ihnen dieser modulare Ansatz, technische Schulden zu verwalten und gleichzeitig die Integrität des Schemas zu wahren.
Bibliotheken von Drittanbietern wie Pydantic unterstützen den Referenzmechanismus nativ in Python, was die Verwendung von Schemas in Ihrem Code vereinfacht.
Die folgenden Richtlinien gelten für die Verwendung von Referenzen in JSON-Schema:
Beschränkungen des Umfangs: Der Mechanismus
$ref
ist nur auf das Schema des Benutzers beschränkt; externe Schemareferenzen (wie HTTP URLs) werden nicht unterstützt.Platzierung von Definitionen: Objektdefinitionen sollten auf der obersten Ebene des Schemas platziert werden, und zwar unter dem Schlüssel Definitionen oder
$defs
.Durchsetzung: Während die JSON-Schema-Spezifikation die Verwendung des Schlüssels
$defs
für Definitionen empfiehlt, setzt der Validierungsmechanismus von Snowflake diese Struktur strikt durch. Dies ist ein Beispiel für ein gültiges$defs
-Objekt:
{
'$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'}}}
}
Beispiel mit JSON-Referenz¶
Dieses SQL-Beispiel demonstriert die Verwendung von Referenzen in einem JSON-Schema.
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']
}
}
}
);
Antwort:
{
"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 odermistral-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.
Tipp
Um mit möglichen Fehlern, die ein Modell auslöst, umzugehen, verwenden Sie TRY_COMPLETE und nicht COMPLETE.
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.
Typ |
Schlüsselwörter |
---|---|
Ganzzahl |
|
number |
|
string |
|
Array |
|
Objekt |
|
Diese Beschränkungenkönnten in zukünftigen Releases aufgehoben werden.
Fehlerbedingungen¶
Situation |
Beispiel-Nachricht |
HTTP-Statuscode |
---|---|---|
Validierung der Anfrage fehlgeschlagen. Die Abfrage wurde abgebrochen, da das Modell nicht in der Lage war, eine gültige Antwort zu erzeugen. Dies kann durch eine fehlerhafte Anfrage verursacht werden. |
|
400 |
Validierung des Eingabeschemas fehlgeschlagen. Die Abfrage wurde abgebrochen, da das Modell nicht in der Lage war, eine gültige Antwort zu erzeugen. Dies kann durch das Fehlen erforderlicher Eigenschaften in der Nutzlast der Anfrage oder durch die Verwendung nicht unterstützter Features des JSON-Schemas, wie z. B. Einschränkungen, oder durch die unsachgemäße Verwendung des $ref-Mechanismus verursacht werden (z. B. durch das Verlassen des Schemas |
|
400 |
Validierung der Modellausgabe fehlgeschlagen. Das Modell konnte keine Antwort erzeugen, die dem Schema entsprach. |
|
422 |