Funkce ai_classify

Platí pro:označeno zaškrtnutím ano Databricks SQL označeno zaškrtnutím ano Databricks Runtime

Funkce ai_classify() klasifikuje textový obsah podle vlastních popisků, které zadáte. Pro základní klasifikaci můžete použít jednoduché názvy popisků nebo přidat popisy popisků a pokyny ke zlepšení přesnosti případů použití, jako je směrování zákaznické podpory, kategorizace dokumentů a analýza obsahu.

Funkce přijímá text nebo VARIANT výstup z jiných funkcí umělé inteligence, jako je ai_parse_documentnapříklad povolení kompozibilních pracovních postupů.

Informace o verzi uživatelského rozhraní pro iteraci ai_classifynajdete v tématu Klasifikace.

Zabezpečení dat

Vaše data dokumentu se zpracovávají v rámci hraniční sítě zabezpečení Databricks. Databricks neukládá parametry, které jsou předávány do volání funkcí AI, ale uchovává metadata o běhu během operací, například použitou verzi Databricks Runtime.

Požadavky

Licence Apache 2.0

Základní modely, které lze v tuto chvíli použít, jsou licencované v rámci licence Apache 2.0, Copyright © Apache Software Foundation. Zákazníci nesou odpovědnost za zajištění dodržování příslušných modelových licencí.

Databricks doporučuje zkontrolovat tyto licence, abyste zajistili soulad s platnými podmínkami. Pokud se modely objeví v budoucnu, které fungují lépe podle interních srovnávacích testů Databricks, může Databricks změnit model (a seznam použitelných licencí uvedených na této stránce).

Model, který tuto funkci pohání, je zpřístupněn pomocí Model Serving Foundation Model API. Informace o modelech dostupných v Databricks a licencích a zásadách, které řídí používání těchto modelů, najdete v příslušných podmínkách modelu .

Pokud se objeví modely, které fungují lépe podle interních srovnávacích testů Azure Databricks, databricks může změnit modely a aktualizovat dokumentaci.

  • Tato funkce je dostupná jenom v některých oblastech, viz dostupnost funkce AI.

  • Pro pracovní prostory s doplňkem Rozšířené zabezpečení a dodržování předpisů

    • Informace o ai_classify najdete v regionální podpoře.
    • Informace o tom, jak ji povolit ve vašem pracovním prostoru, najdete v tématu Správa Azure Databricks preview.

  • Tato funkce není k dispozici v Azure Databricks SQL Classic.

  • Databricks Runtime 15.4 LTS nebo vyšší je vyžadován. Databricks Runtime 18.2 nebo novější je doporučen pro nejlepší výkon a přístup k nejnovějším funkcím.

  • Podívejte se na stránku s cenami SQL služby Databricks.

Návod

Databricks doporučuje používat verzi 2.1 pro ai_classify. Verze 1.0 je starší rozhraní, které tyto funkce nepodporuje a nedoporučuje se pro nové nebo produkční úlohy.

Verze 2.0 podporuje:

  • Popisy popisků pro lepší přesnost
  • Klasifikace více popisků
  • Globální pokyny
  • Až 500 popisků ve verzi 1.0 ve srovnání s 20
  • VARIANT vstup z upstreamových funkcí umělé inteligence, jako je ai_parse_document
  • Vrátí strukturu VARIANT s informacemi o chybách.

Verze 2.1 také podporuje:

  • Skóre spolehlivosti pro každý vrácený popisek s povoleným enableConfidenceScores
  • Odůvodnění vysvětlující jednotlivé vrácené popisky s povolenou funkcí enableRationales

Ve verzi 2.1 je každá klasifikace response objektem pro každý popisek s value klíčem místo řetězce prostého popisku. Tato změna výstupního obrazce platí pro všechna volání verze 2.1, i když jsou nové možnosti zakázané. Přechod z verze 2.0 na verzi 2.1 není kompatibilní s výstupem. Aktualizujte dotazy a podřízený kód tak, aby popisek přečetly z value klíče, a nečtěte ho přímo.

Pokud chcete verzi připnout explicitně, předejte options => map('version', '2.1')ji .

Syntaxe

ai_classify(content, labels [, options])

Verze 2

ai_classify(content, labels [, options])

Verze 1 (starší verze)

ai_classify(content, labels [, options])

Argumenty

  • content: VARIANT nebo STRING výraz. Přijímá buď:

    • Nezpracovaný text jako STRING
    • A VARIANT vytvořené jinou funkcí umělé inteligence (například ai_parse_document nebo ai_extract)

  • labels: Výraz STRING definující popisky klasifikace. Může to být řetězcový literál nebo jakýkoli výraz SQL, který se vyhodnotí jako STRINGsloupec tabulky Delta. Popisky můžou být:

    • Jednoduché popisky: Pole JSON s názvy popisků. 
      ["urgent", "not_urgent"]
    • Popisky s popisy: Názvy popisků mapování objektů JSON na popisy Popisy popisků musí být 0–1 000 znaků. 
      {
  "billing_error": "Payment, invoice, or refund issues",
  "product_defect": "Any malfunction, bug, or breakage",
  "account_issue": "Login failures, password resets"
}

    Každý popisek musí mít 1 až 100 znaků. labels musí obsahovat alespoň 2 štítky a nesmí obsahovat více než 500 štítků. U taxonomií větších než 500 popisků se podívejte na klasifikaci s 500+ popisky.

  • options: Volitelné MAP<STRING, STRING> obsahující možnosti konfigurace:

    • version: Přepnutí verze na podporu migrace ("1.0", "2.0"nebo "2.1"). Výchozí hodnota je založena na vstupních typech, ale vrátí se zpět na "1.0".
    • instructions: Globální popis úlohy a domény, aby se zlepšila kvalita klasifikace. Musí být kratší než 20 000 znaků.
    • multilabel: Pokud se použije více kategorií, nastavte na "true" vrácení více popisků. Výchozí hodnota je "false" (klasifikace s jedním popiskem).
    • enableConfidenceScores: Nastavte na "true" zahrnutí confidence_score (0–1) pro každý vrácený popisek. Vyžaduje verzi "2.1". Výchozí hodnota je "false".
    • enableRationales: Nastavte na "true" zahrnutí krátkého odůvodnění vysvětlujícího každý vrácený popisek, který je uzemněný ve vstupním textu. Vyžaduje verzi "2.1". Výchozí hodnota je "false".

Verze 2

  • content: VARIANT nebo STRING výraz. Přijímá buď:

    • Nezpracovaný text jako STRING
    • A VARIANT vytvořené jinou funkcí umělé inteligence (například ai_parse_document nebo ai_extract)

  • labels: Výraz STRING definující popisky klasifikace. Může to být řetězcový literál nebo jakýkoli výraz SQL, který se vyhodnotí jako STRINGsloupec tabulky Delta. Popisky můžou být:

    • Jednoduché popisky: Pole JSON s názvy popisků. 
      ["urgent", "not_urgent"]
    • Popisky s popisy: Názvy popisků mapování objektů JSON na popisy Popisy popisků musí být 0–1 000 znaků. 
      {
  "billing_error": "Payment, invoice, or refund issues",
  "product_defect": "Any malfunction, bug, or breakage",
  "account_issue": "Login failures, password resets"
}

    Každý popisek musí mít 1 až 100 znaků. labels musí obsahovat alespoň 2 štítky a nesmí obsahovat více než 500 štítků. U taxonomií větších než 500 popisků se podívejte na klasifikaci s 500+ popisky.

  • options: Volitelné MAP<STRING, STRING> obsahující možnosti konfigurace:

    • version: Přepnutí verze na podporu migrace ("1.0" pro chování v1, "2.0" pro chování v2). Výchozí hodnota je založena na vstupních typech, ale vrátí se zpět na "1.0".
    • instructions: Globální popis úlohy a domény, aby se zlepšila kvalita klasifikace. Musí být kratší než 20 000 znaků.
    • multilabel: Pokud se použije více kategorií, nastavte na "true" vrácení více popisků. Výchozí hodnota je "false" (klasifikace s jedním popiskem).

Verze 1 (starší verze)

  • content: Výraz STRING obsahující text, který se má klasifikovat.

  • labels ARRAY<STRING>: Literál s očekávanými popisky klasifikace výstupu. Musí obsahovat alespoň 2 prvky a nesmí obsahovat více než 20 prvků. Každý popisek musí mít 1 až 50 znaků.

  • options: Volitelné MAP<STRING, STRING> obsahující možnosti konfigurace:

    • version: Přepnutí verze na podporu migrace ("1.0" pro chování v1, "2.0" pro chování v2). Výchozí hodnota je založena na vstupních typech, ale vrátí se zpět na "1.0".

Návraty

VARIANT Vrátí hodnotu obsahující:

{
  "response": [{ "value": "label_name", "confidence_score": 0.97, "rationale": "Short justification for the label." }],
  "metadata": {
    "version": "2.1"
  },
  "error_message": null // null on success, or error message on failure
}

Každý prvek v response je objekt pro každý popisek s value klíčem místo řetězce prostého popisku. Pokud enableConfidenceScores je , "true"každý objekt obsahuje confidence_score také (0–1). Pokud enableRationales je , "true"každý objekt obsahuje také .rationale Pokud jsou obě možnosti povoleny, pořadí klíčů v každém objektu je value, confidence_scorepak rationale.

Pole response obsahuje:

  • Režim s jedním popiskem (výchozí): Pole s jedním prvkem obsahujícím nejlepší odpovídající popisek
  • Režim více popisků (multilabel: "true"): Pole s více popisky při použití více kategorií
  • Názvy popisků přesně odpovídají názvům zadaným v parametru labels .

Vrátí NULL , pokud content je NULL nebo pokud nelze klasifikovat obsah.

Verze 2

VARIANT Vrátí hodnotu obsahující:

{
  "response": ["label_name"], // Array with single label (or multiple if multilabel=true)
  "metadata": {
    "version": "2.0"
  },
  "error_message": null // null on success, or error message on failure
}

Pole response obsahuje:

  • Režim s jedním popiskem (výchozí): Pole s jedním prvkem obsahujícím nejlepší odpovídající popisek
  • Režim více popisků (multilabel: "true"): Pole s více popisky při použití více kategorií
  • Názvy popisků přesně odpovídají názvům zadaným v parametru labels .

Vrátí NULL , pokud content je NULL nebo pokud nelze klasifikovat obsah.

Verze 1 (starší verze)

Vrátí hodnotu STRING. Hodnota odpovídá jednomu z řetězců zadaných v argumentu labels .

Vrátí NULL , pokud content je NULL nebo pokud nelze klasifikovat obsah.

Příklady

Jednoduché popisky – jenom názvy popisků

Ve verzi 2.1 je každá klasifikace objektem pro každý popisek s value klíčem místo prostého řetězce, i když jsou nové možnosti zakázané.

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1')
  );
 {
   "response": [{"value": "urgent"}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

Se skóre spolehlivosti

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1', 'enableConfidenceScores', 'true')
  );
 {
   "response": [{"value": "urgent", "confidence_score": 0.97}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

S racionalizacemi

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1', 'enableRationales', 'true')
  );
 {
   "response": [{"value": "urgent", "rationale": "A leaked password is a security incident requiring immediate action."}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

Se skóre spolehlivosti a racionalizací (více popisků)

> SELECT ai_classify(
    'Customer wants refund and reports product arrived broken.',
    '{
      "billing_issue": "Payment or refund requests",
      "product_defect": "Damaged or malfunctioning items"
    }',
    MAP('version', '2.1', 'multilabel', 'true', 'enableConfidenceScores', 'true', 'enableRationales', 'true')
  );
 {
   "response": [
     {"value": "billing_issue", "confidence_score": 0.91, "rationale": "Customer explicitly requests a refund."},
     {"value": "product_defect", "confidence_score": 0.88, "rationale": "Reports the product arrived broken."}
   ],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

Kompozability with ai_parse_document

> WITH parsed_docs AS (
    SELECT
      path,
      ai_parse_document(
        content,
        MAP('version', '2.0')
      ) AS parsed_content
    FROM READ_FILES('/Volumes/support/tickets/', format => 'binaryFile')
  )
  SELECT
    path,
    ai_classify(
      parsed_content,
      '["billing_error", "product_defect", "account_issue", "feature_request"]',
      MAP('version', '2.1', 'instructions', 'Customer support ticket classification.')
    ) AS ticket_category
  FROM parsed_docs;

Dávková klasifikace

> SELECT
    description,
    ai_classify(
      description,
      '["clothing", "shoes", "accessories", "furniture", "electronics"]',
      MAP('version', '2.1')
    ) AS category
  FROM products
  LIMIT 10;

Klasifikace s 500+ popisky

Pokud chcete klasifikovat více než 500 popisků, doporučujeme vložit dokumenty a popisky, načíst horní k popisky na dokument a pak spustit ai_classify menší podmnožinu.

Viz kurz: Klasifikace dokumentů s popisky 500+ pro podrobný návod.

Verze 2

Jednoduché popisky – jenom názvy popisků

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]'
  );
 {
   "response": ["urgent"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Popisky s popisy

> SELECT ai_classify(
    'Customer cannot complete checkout due to payment processing error.',
    '{
      "billing_error": "Payment, invoice, or refund issues",
      "product_defect": "Any malfunction, bug, or breakage",
      "account_issue": "Login failures, password resets",
      "feature_request": "Customer suggestions for improvements"
    }'
  );
 {
   "response": ["billing_error"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Popisky z tabulky Delta

Předejte popisky z tabulky Delta jejich převodem na řetězec JSON. Pokud máte například tabulku popisků se schématem news_topics(topic STRING, description STRING), můžete popisky ai_classify předat následujícím způsobem:

SELECT
  ai_classify(
    "Leicester City Wins Premier League Title at 5000-1 Odds",
    l.labels,
    MAP('version', '2.0')
  ) AS classification
FROM (
  SELECT to_json(map_from_entries(collect_list(struct(topic, description)))) AS labels
  FROM news_topics
) l;

Použití globálních pokynů

> SELECT ai_classify(
    'User reports app crashes on startup after update.',
    '["critical", "high", "medium", "low"]',
    MAP('instructions', 'Classify bug severity based on user impact and frequency.')
  );
 {
   "response": ["critical"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Klasifikace více popisků

> SELECT ai_classify(
    'Customer wants refund and reports product arrived broken.',
    '{
      "billing_issue": "Payment or refund requests",
      "product_defect": "Damaged or malfunctioning items",
      "shipping_issue": "Delivery problems"
    }',
    MAP('version', '2.0','multilabel', 'true')
  );
 {
   "response": ["billing_issue", "product_defect"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Verze 1 (starší verze)

> SELECT ai_classify("My password is leaked.", ARRAY("urgent", "not urgent"));
  urgent

> SELECT
    description,
    ai_classify(description, ARRAY('clothing', 'shoes', 'accessories', 'furniture')) AS category
  FROM
    products
  LIMIT 10;

Omezení

Omezení verze 2.1:

  • Tato funkce není k dispozici v Azure Databricks SQL Classic.

  • Tuto funkci nelze použít se zobrazeními.

  • Názvy popisků musí mít každý 1 až 100 znaků.

  • Parametr labels musí obsahovat 2 až 500 jedinečných popisků.

  • Popisy popisků musí mít každý z nich 0–1 000 znaků.

  • Maximální celková velikost kontextu je 1 milion tokenů.

Verze 2

Omezení verze 2:

  • Tato funkce není k dispozici v Azure Databricks SQL Classic.

  • Tuto funkci nelze použít se zobrazeními.

  • Názvy popisků musí mít každý 1 až 100 znaků.

  • Parametr labels musí obsahovat 2 až 500 jedinečných popisků.

  • Popisy popisků musí mít každý z nich 0–1 000 znaků.

  • Maximální celková velikost kontextu je 1 milion tokenů.

Verze 1 (starší verze)

Omezení verze 1 (starší verze):

  • Tato funkce není k dispozici v Azure Databricks SQL Classic.

  • Tuto funkci nelze použít se zobrazeními.

  • Názvy popisků musí mít každý 1–50 znaků.

  • Matice labels musí obsahovat 2 až 20 popisků.

  • Vstup content musí být menší než 128 000 tokenů (asi 300 000 znaků).

  • Last updated on