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 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.
-
Selecione seus dados de origem. Você pode selecionar um volume com documentos ou uma tabela com dados de texto.
-
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:
- Clique em + Adicionar rótulo para adicionar um rótulo de classificação.
- Insira o nome do rótulo e a descrição opcional, depois clique em Adicionar rótulo .
- Repita os passos 1-2 para cada rótulo que você deseja adicionar.
- (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:
- Clique em Importar da tabela .
- Selecione a tabela e clique em **Avançar**.
- Selecione a coluna de rótulo, a coluna de descrição e o SQL warehouse.
- Clique em **Visualizar** para ver os rótulos que são importados.
- 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 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.

Passo 3. Revisar e aprimorar as respostas de classificação
Revise as respostas de classificação e forneça feedback para melhorar o Agente.
-
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**.
-
Para melhorar as respostas do agente, ajuste as descrições dos rótulos de classificação.
-
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_classifyutilizando os rótulos de classificação que você definiu. Para obter mais informações sobre como usarai_classifyem consultas SQL, consulte a funçãoai_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:
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:
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.
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 |
|---|---|
| Uma string que identifica a solicitação. Cada linha do arquivo de saída tem o |
| O texto a classificar, na forma de |
O seguinte arquivo de entrada possui duas solicitações:
{"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, comoinstructionsemultilabel.
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_idebody. O arquivo não tem linhas em branco. -
Cada
custom_idé uma string não vazia, e nenhuma linha tem o mesmocustom_id. -
Cada
bodytem exatamente uma key,text.- Se um valor
textnão for uma string, o lote ainda será criado e essa solicitação falhará com o tipo de erroinvalid_request.
- Se um valor
-
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.
-
paramstemlabelse nenhum parâmetro queai_classifynã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:
-
Crie o arquivo de entrada e faça upload dele para um volume do Unity Catalog, por exemplo, com a Files API.
-
Crie um lote que realiza a execução de
ai_classifyno arquivo de entrada. Definainput_refcomo o caminho do arquivo de entrada,paramscomo os parâmetros para cada solicitação eoutput_refcomo um diretório de volume ou um novo caminho de arquivo para o arquivo de saída:Bashcurl -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. -
Verifique o status do lote. O lote termina quando
statuséCOMPLETED,CANCELLEDouFAILED:Bashcurl -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_refna resposta conterá o caminho dele. -
download o arquivo de saída com a Files API:
Bashcurl -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_refterminar com/ou nomear um diretório existente, a API gravará o arquivo de saída em<batch-name>_output.jsonlnesse 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: Otypeemessagedo 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:
{"custom_id": "ticket-001", "response": {...}}
{"custom_id": "ticket-002", "error": {"type": "request_failed", "message": "..."}}
Limitações
Consulte Limitações