Função ai_classify

Aplica-se a: Databricks SQL Databricks Runtime

A ai_classify() função classifica o conteúdo do texto de acordo com os rótulos personalizados fornecidos. Você pode usar nomes de rótulo simples para classificação básica ou adicionar descrições de rótulo e instruções para melhorar a precisão para casos de uso, como roteamento de suporte ao cliente, categorização de documentos e análise de conteúdo.

A função aceita texto ou VARIANT saída de outras funções de IA, como ai_parse_documenthabilitar fluxos de trabalho composáveis.

Para obter uma versão da interface do usuário em ai_classifyque iterar, consulte Classificação.

Requisitos

O modelo que alimenta essa função é disponibilizado usando AS APIs de modelo do Model Serving Foundation. Consulte os termos de modelo aplicáveis para obter informações sobre quais modelos estão disponíveis no Databricks e as licenças e políticas que regem o uso desses modelos.

Se surgirem modelos com melhor desempenho de acordo com os parâmetros de comparação internos da Azure Databricks, o Databricks poderá alterar os modelos e atualizar a documentação.

• Essa função só está disponível em algumas regiões, consulte a disponibilidade da função de IA.

• Para workspaces com o complemento segurança e conformidade aprimorados,

  • Consulte o suporte regional para ai_classify obter o padrão de conformidade apropriado.
  • Consulte Gerenciar Azure Databricks visualizações de como habilitá-lo em seu workspace.

• Essa função não está disponível em sql warehouses profissionais ou clássicos.

• O Databricks Runtime 18.2 ou superior é necessário.

• A computação sem servidor é necessária para notebooks e fluxos de trabalho do Databricks.

• Confira a página de preços do SQL do Databricks.

Sintaxe

Versão 2 (recomendado)

ai_classify(content, labels [, options])

Versão 1 (Herdada)

ai_classify(content, labels [, options])

Argumentos

Versão 2 (recomendado)

• content: uma expressão VARIANT ou STRING. Aceita um:

  • Texto bruto como um STRING
  • Uma VARIANT produzida por outra função de IA (como ai_parse_document ou ai_extract)

• labels: uma STRING expressão que define os rótulos de classificação. Isso pode ser um literal de cadeia de caracteres ou qualquer expressão SQL que seja avaliada como uma STRING, incluindo uma coluna de tabela Delta. Os rótulos podem ser:

  • Rótulos simples: uma matriz JSON de nomes de rótulo.

    ["urgent", "not_urgent"]
    

  • Rótulos com descrições: um rótulo de mapeamento de objeto JSON para descrições. As descrições de rótulo devem ter de 0 a 1.000 caracteres.

    {
      "billing_error": "Payment, invoice, or refund issues",
      "product_defect": "Any malfunction, bug, or breakage",
      "account_issue": "Login failures, password resets"
    }
    

  Cada rótulo deve ter de 1 a 100 caracteres. labels deve conter pelo menos dois rótulos e no máximo 500 rótulos. Para taxonomias maiores que 500 rótulos, consulte a Classificação com mais de 500 rótulos.

• options: um opcional MAP<STRING, STRING> que contém opções de configuração:

  • version: opção de versão para dar suporte à migração ("1.0" para comportamento v1, "2.0" para comportamento v2). O padrão é baseado em tipos de entrada, mas volta para "1.0".
  • instructions: descrição global da tarefa e do domínio para melhorar a qualidade da classificação. Deve ter menos de 20.000 caracteres.
  • multilabel: defina para "true" retornar vários rótulos quando várias categorias se aplicarem. O padrão é "false" (classificação de rótulo único).

Versão 1 (Herdada)

• content: uma STRING expressão que contém o texto a ser classificado.

• labels: um ARRAY<STRING> literal com os rótulos de classificação de saída esperados. Deve conter pelo menos 2 elementos e não mais do que 20 elementos. Cada rótulo deve ter de 1 a 50 caracteres.

• options: um opcional MAP<STRING, STRING> que contém opções de configuração:

  • version: opção de versão para dar suporte à migração ("1.0" para comportamento v1, "2.0" para comportamento v2). O padrão é baseado em tipos de entrada, mas volta para "1.0".

Retornos

Versão 2 (recomendado)

Retorna um VARIANT que contém:

{
  "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
}

O response campo contém:

• Modo de rótulo único (padrão): uma matriz com um elemento que contém o melhor rótulo correspondente
• Modo de vários rótulos (multilabel: "true"): uma matriz com vários rótulos quando várias categorias se aplicam
• Os nomes de rótulo correspondem exatamente aos fornecidos no labels parâmetro

Retorna NULL se content for NULL ou se o conteúdo não puder ser classificado.

Versão 1 (Herdada)

Retorna um STRING. O valor corresponde a uma das cadeias de caracteres fornecidas no argumento labels.

Retorna NULL se content for NULL ou se o conteúdo não puder ser classificado.

Exemplos

Versão 2 (recomendado)

Rótulos simples – somente nomes de rótulo

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

Rótulos com descrições

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

Rótulos da Tabela Delta

Passe rótulos de uma tabela Delta convertendo-os em uma cadeia de caracteres JSON. Por exemplo, considerando uma tabela de rótulos com esquema news_topics(topic STRING, description STRING), você pode passar seus rótulos da ai_classify seguinte maneira:

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;

Usando instruções globais

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

Classificação de vários rótulos

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

Composição com 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('instructions', 'Customer support ticket classification.')
    ) AS ticket_category
  FROM parsed_docs;

Classificação em lote

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

Classificação com mais de 500 rótulos

Para classificar com mais de 500 rótulos, recomendamos inserir seus documentos e rótulos, recuperar os principais rótulos k por documento e, em seguida, executar ai_classify no subconjunto menor.

Confira o Tutorial: Classificar documentos com mais de 500 rótulos para um passo a passo passo.

Versão 1 (Herdada)

> 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;

Limitações

Versão 2 (recomendado)

Limitações da versão 2:

• Essa função não está disponível no Azure Databricks SQL Classic.

• Essa função não pode ser usada com Exibições.

• Os nomes de rótulo devem ter de 1 a 100 caracteres cada.

• O labels parâmetro deve conter entre 2 e 500 rótulos exclusivos.

• As descrições de rótulo devem ter de 0 a 1.000 caracteres cada.

• O tamanho máximo total do contexto é de 128.000 tokens.

Versão 1 (Herdada)

Limitações da versão 1 (herdada):

• Essa função não está disponível no Azure Databricks SQL Classic.

• Essa função não pode ser usada com Exibições.

• Os nomes de rótulo devem ter de 1 a 50 caracteres cada.

• A labels matriz deve conter entre 2 e 20 rótulos.

• A content entrada deve ter menos de 128.000 tokens (cerca de 300.000 caracteres).

Funções relacionadas

• ai_extract função
• ai_parse_document função