Pular para o conteúdo principal

Classificação

Você pode usar a Classificação para classificar seus documentos em categorias predefinidas com AI.

Exemplos de classificação incluem:

  • Classificando transcrições de chamadas de clientes por intenção
  • Classificando documentos por tipo de conteúdo
  • Classificando Avaliações de Produtos por Sentimento

A classificação está disponível por meio da IU do Agent Bricks, em SQL, com a API REST e com a API Assíncrona (Beta).

Criar um agente de classificação na IU​

Requisitos​

Vá para Ícone de Agentes. Agentes no painel de navegação esquerdo do seu workspace. Clique em Criar Agente e selecione Classificação de Texto .

O passo 1. Selecione seus dados de origem​

Use a Classificação para classificar seus documentos.

  1. Selecione seus dados de origem. Você pode selecionar um volume com documentos ou uma tabela com dados de texto.

  2. Clique em Criar Agente .

Etapa 2. Configurar rótulos de classificação​

Após a Classificação processar seus dados, configure e refine seus rótulos de classificação.

Adicionar rótulos de classificação manualmente:

  1. Clique em + Adicionar rótulo para adicionar um rótulo de classificação.
  2. Insira o nome do rótulo e a descrição opcional, depois clique em Adicionar rótulo .
  3. Repita os passos 1-2 para cada rótulo que você deseja adicionar.
  4. (Opcional) Habilite Múltiplos rótulos se você quiser que o agente retorne mais de um rótulo.

Para importar rótulos de uma tabela:

  1. Clique em Importar da tabela .
  2. Selecione a tabela e clique em **Avançar**.
  3. Selecione a coluna de rótulo, a coluna de descrição e o SQL warehouse.
  4. Clique em **Visualizar** para ver os rótulos que são importados.
  5. Se estiver satisfeito com os rótulos, clique em Importar e substituir rótulos .

Você deve ter pelo menos dois rótulos definidos para a execução da classificação. Após terminar de adicionar seus rótulos, clique em Salvar e executar a classificação .

Para configurar opções adicionais, clique na alternância de opções Ícone de controles deslizantes. ao lado de Salvar e executar a classificação e, em seguida, habilite uma ou mais das seguintes opções:

  • Pontuações de confiança : Mostra os níveis de confiança para os rótulos previstos.
  • Justificativas : Mostra a justificativa para os rótulos previstos.

A Classificação classifica até 5 documentos e linhas e exibe os resultados. Você pode adicionar mais também.

Interface do usuário de revisão de classificação mostrando rótulos e resultados de classificação

Passo 3. Revisar e aprimorar as respostas de classificação​

Revise as respostas de classificação e forneça feedback para melhorar o Agente.

  1. Revise o documento e a resposta de classificação:

    • Se a resposta estiver correta, forneça um polegar para cima.
    • Se a resposta estiver incorreta, dê um polegar para baixo. Ajude a Classificação a corrigir a resposta selecionando o rótulo correto. Clique em **Salvar**.
  2. Para melhorar as respostas do agente, ajuste as descrições dos rótulos de classificação.

  3. Compare as versões para otimizar o desempenho do agente. Clique em Versões . Ao lado de uma versão anterior, clique em Comparar para comparar as descrições do rótulo de classificação de uma versão anterior com a versão atual. Clique em Restaurar para restaurar uma versão anterior.

o passo 4: Use o agente de classificação​

Se estiver satisfeito com as respostas, comece a usar o agente para classificação em escala.

Clique em Usar Agente no canto superior direito. Você pode escolher uma destas opções:

  • **Execução em SQL** para usar o agente para classificar todo o volume ou tabela. Isso abre uma consulta SQL que usa ai_classify utilizando os rótulos de classificação que você definiu. Para obter mais informações sobre como usar ai_classify em consultas SQL, consulte a função ai_classify.
  • Crie um pipeline do Lakeflow que realize a execução em intervalos programados para invocar seu agente com novos dados. Isso cria um pipeline do Lakeflow que atualiza uma tabela de transmissão com seus dados classificados. Você pode programar o pipeline para que ele entre em execução quando novos dados chegarem. Para obter mais informações sobre pipelines do Lakeflow, consulte Spark Declarative Pipelines no Lakeflow.

Classificar documentos em SQL​

Chame ai_classify em SQL para classificar documentos em escala:

SQL
SELECT ai_classify(
'My password is leaked.',
'["urgent", "not_urgent"]',
MAP('version', '2.1')
);

Consulte a referência de SQL ai_classify.

Classificar documentos com a API REST​

Use a API REST para classificar documentos de aplicativos, serviços e fluxos de trabalho de automação. Consulte a documentação da API REST para referência.

The default rate limit for ai_classify REST API requests is 1,200 requests per minute per workspace. Contact your Databricks account team to request a higher limit.

O exemplo a seguir classifica uma mensagem de suporte ao cliente:

Bash
curl -X POST "$DATABRICKS_HOST/api/2.0/ai-functions/ai-classify" \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": "My password is leaked.",
"labels": ["urgent", "not_urgent"],
"options": {
"instructions": "Classify the support request by urgency."
}
}'

Classificar documentos com a API assíncrona (Beta)​

Para processamento em lotes, o Databricks recomenda tarefas de AI no Lakeflow Jobs. Para classificar registros em um job, use uma tarefa ai_classify, que faz o seguinte:

  • Realiza a execução do processamento em background e grava os resultados em uma tabela do Unity Catalog, para que você não precise enviar lotes, verificar seu status ou fazer download de arquivos de saída.
  • Processa apenas as linhas que são novas ou alteradas desde a execução anterior.
  • Mostra o progresso de cada execução e quantos inputs foram bem-sucedidos e falharam.

Use a API assíncrona do AI Functions (Beta) em vez disso quando quiser integrar o processamento a um aplicativo existente ou a um orquestrador externo e gerenciar os envios e resultados por conta própria.

info

Beta

Este recurso está em Beta. Para usá-lo, um administrador do workspace deve habilitar o AI Functions Asynchronous API na página Previews . Consulte Gerenciar prévias do Databricks.

Para os campos de solicitação e resposta, e para as solicitações para cancelar e listar lotes, consulte a referência da API assíncrona.

Arquivo de entrada​

O arquivo de entrada de um lote ai_classify é um arquivo JSONL em um volume do Unity Catalog, com uma solicitação em cada linha. Cada linha é um objeto JSON com exatamente os seguintes campos:

campo

Descrição

custom_id

Uma string que identifica a solicitação. Cada linha do arquivo de saída tem o custom_id da sua solicitação, portanto, use um valor com o qual você possa combinar os resultados, como a key da linha de origem.

body

O texto a classificar, na forma de {"text": "..."}.

campo

Descrição

custom_id

Uma string que identifica a solicitação. Cada linha do arquivo de saída tem o custom_id da sua solicitação, portanto, use um valor com o qual você possa combinar os resultados, como a key da linha de origem.

body

O texto a classificar, na forma de {"text": "..."}.

O seguinte arquivo de entrada possui duas solicitações:

JSON
{"custom_id": "ticket-001", "body": {"text": "My password is leaked."}}
{"custom_id": "ticket-002", "body": {"text": "How do I change my billing address?"}}

O arquivo de entrada possui apenas o texto e o ID de cada registro. Você define os outros parâmetros de ai_classify em params quando cria o lote, e eles se aplicam a cada solicitação:

  • labels (obrigatório): Os rótulos para classificar os registros em uma lista de rótulos ou como um objeto que mapeia cada rótulo para sua descrição.
  • options: As opções de função, como instructions e multilabel.

Para o que cada parâmetro faz, consulte a referência da API REST Classificação de AI. Em params.options, escreva o nome de cada opção em camelCase, por exemplo enableRationales em vez de enable_rationales.

Quando você cria um lote, a API verifica o arquivo de entrada inteiro e params primeiro. Se o arquivo de entrada ou params quebrar uma das seguintes regras, a solicitação falha com HTTP 400 e nenhum lote é criado:

  • O arquivo está codificado em UTF-8 e cada linha é um objeto JSON com exatamente os campos custom_id e body. O arquivo não tem linhas em branco.

  • Cada custom_id é uma string não vazia, e nenhuma linha tem o mesmo custom_id.

  • Cada body tem exatamente uma key, text.

    • Se um valor text não for uma string, o lote ainda será criado e essa solicitação falhará com o tipo de erro invalid_request.
  • O arquivo tem de 1 a 50.000 linhas e no máximo 200 MiB.

    • Para processar mais registros, divida-os em vários arquivos de entrada e crie um lote para cada arquivo.
  • params tem labels e nenhum parâmetro que ai_classify não leve.

Para um problema em uma linha do arquivo de entrada, a mensagem de erro fornece o número da linha e a regra, por exemplo Batch input line 3 custom_id must be unique. Se você não conseguir ler o arquivo de entrada ou gravar em output_ref, a solicitação falhará com HTTP 403.

A API copia o arquivo de entrada quando cria o lote, de modo que as alterações feitas posteriormente no arquivo não afetam o lote.

Execução de um lote​

Para classificar registros com a API assíncrona:

  1. Crie o arquivo de entrada e faça upload dele para um volume do Unity Catalog, por exemplo, com a Files API.

  2. Crie um lote que realiza a execução de ai_classify no arquivo de entrada. Defina input_ref como o caminho do arquivo de entrada, params como os parâmetros para cada solicitação e output_ref como um diretório de volume ou um novo caminho de arquivo para o arquivo de saída:

    Bash
    curl -X POST "$DATABRICKS_HOST/api/2.0/ai-functions/batches" \
    -H "Authorization: Bearer $DATABRICKS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "endpoint": "ai_classify",
    "input_ref": "/Volumes/my_catalog/my_schema/my_volume/requests.jsonl",
    "params": {
    "labels": ["urgent", "not_urgent"],
    "options": {
    "instructions": "Classify the support request by urgency."
    }
    },
    "output_ref": "/Volumes/my_catalog/my_schema/my_volume/output/"
    }'

    A resposta contém o lote name. Use-o no lugar de <batch-name> nos passos seguintes. Por default, um workspace pode ter até 20 lotes não concluídos por vez, em todos os usuários. Se estiver no limite, a solicitação falhará com HTTP 409. Crie o lote novamente após outro lote ser concluído ou cancelado.

  3. Verifique o status do lote. O lote termina quando status é COMPLETED, CANCELLED ou FAILED:

    Bash
    curl -X GET "$DATABRICKS_HOST/api/2.0/ai-functions/batches/<batch-name>" \
    -H "Authorization: Bearer $DATABRICKS_TOKEN"

    Quando o arquivo de saída estiver pronto, output_ref na resposta conterá o caminho dele.

  4. download o arquivo de saída com a Files API:

    Bash
    curl -X GET "$DATABRICKS_HOST/api/2.0/fs/files/Volumes/my_catalog/my_schema/my_volume/output/<batch-name>_output.jsonl" \
    -H "Authorization: Bearer $DATABRICKS_TOKEN" \
    -o output.jsonl

Arquivo de saída​

A API assíncrona grava o arquivo de saída de um lote ai_classify no local em output_ref:

  • Se output_ref terminar com / ou nomear um diretório existente, a API gravará o arquivo de saída em <batch-name>_output.jsonl nesse diretório. Vários lotes podem compartilhar um único diretório de saída.
  • Caso contrário, output_ref é o caminho do arquivo de saída. O arquivo não deve existir quando você criar o lote.

O arquivo de saída tem uma linha para cada linha do arquivo de entrada. As linhas estão na mesma ordem que o arquivo de entrada. Cada linha tem o custom_id da sua solicitação e um dos seguintes campos:

  • response: O resultado do pedido. Tem os mesmos campos que a resposta da API REST Classificação de AI.
  • error: O type e message do erro, se a solicitação falhou. Se o lote foi cancelado antes da execução da solicitação, o tipo é cancelled.

O exemplo a seguir mostra uma linha para uma solicitação que obteve êxito e uma linha para uma solicitação que falhou:

Text
{"custom_id": "ticket-001", "response": {...}}
{"custom_id": "ticket-002", "error": {"type": "request_failed", "message": "..."}}

Limitações​

Consulte Limitações