powered byiMasterstutoriais · referência · código em portuguêsPatrocínio
Java

JSR 381: como classificar imagens em Java com Deep Netts, sem bibliotecas pesadas

O padrão javax.visrec permite treinar e usar um classificador de imagens em Java puro, com a implementação de referência Deep Netts. Mostro o código testado no JDK 21 e o que quebra na hora de trocar de motor.

Por Marcelo TeixeiraColunista6 min de leitura
Imagem gerada por IA

Hoje você sai daqui com um classificador de imagens rodando em Java puro, usando a API padrão javax.visrec (JSR 381) com a implementação de referência baseada em Deep Netts. O código foi testado no JDK 21 (LTS), com Maven 3.9, visrec-api 1.0.5 e visrec-ri 1.0.3.

No fim, mostro também como o contrato da API é pequeno o suficiente para você escrever a própria implementação sem rede neural nenhuma, usando só DuckDB e SQL.

O que você implementa de verdade

JSR 381 (Visual Recognition API, ou VisRec) virou Final em fevereiro de 2022, com Zoran Sevarac e Frank Greco como specification leads. A ideia central: seu código chama interfaces em javax.visrec, nunca uma biblioteca específica de machine learning. Quem faz o reconhecimento de fato é uma implementação separada, empacotada em outro JAR, que a API encontra no classpath em tempo de execução via ServiceLoader.

No centro da especificação está uma interface de um método só:

java
@FunctionalInterface
public interface Classifier<T, R> {
    R classify(T input) throws ClassificationException;
}

ImageClassifier<IMAGE_CLASS> especializa isso para imagens: recebe um objeto de imagem, um Path ou um InputStream, e devolve um Map<String, Float> com o rótulo e a confiança de cada classe, por exemplo {cat=0.92, dog=0.08}. ClassificationException é unchecked: nada te obriga a declarar throws nem a capturar, mas em produção você vai querer capturar do mesmo jeito.

O resto do pacote se divide assim:

PacoteO que tem
javax.visrec.ml.classificationClassifier, ImageClassifier, BinaryClassifier, builders como NeuralNetImageClassifier
javax.visrec.ml.detectionObjectDetector e BoundingBox, para localizar objetos na imagem
javax.visrec.ml.dataDataSet e abstrações de pré-processamento
javax.visrec.ml.regression / javax.visrec.ml.evalModelos de regressão e métricas de avaliação
javax.visrec.spiServiceProvider e as fábricas que uma implementação usa para se registrar

Repare no pacote: é javax.visrec, não jakarta.visrec. JSR 381 fechou em 2022 sob o JCP tradicional, fora da renomeação de javax para jakarta que atingiu as APIs do Jakarta EE. Se você está migrando um projeto Spring Boot 3 e temendo quebra de namespace, essa aqui não entra na conta.

Montando o classificador com Deep Netts

A implementação de referência é a visrec-ri, construída sobre a edição community do Deep Netts, um motor de deep learning escrito em Java puro: nada de bibliotecas nativas, nada de Python por trás. Também existe visrec-djl, da Amazon, construída sobre o Deep Java Library.

Adicione as duas dependências ao pom.xml:

xml
<dependency>
    <groupId>javax.visrec</groupId>
    <artifactId>visrec-api</artifactId>
    <version>1.0.5</version>
</dependency>
<dependency>
    <groupId>javax.visrec</groupId>
    <artifactId>visrec-ri</artifactId>
    <version>1.0.3</version>
</dependency>

Com isso no classpath, você constrói e treina um classificador pelo builder da especificação. O exemplo abaixo é a adaptação do caso clássico "gato ou cachorro" do repositório oficial jsr381-examples:

java
import javax.visrec.ml.classification.ImageClassifier;
// NeuralNetImageClassifier vem da visrec-ri; o caminho completo do pacote
// mudou entre versões, então confira o import exato no pom.xml e no
// código-fonte do jsr381-examples antes de colar isso num projeto real
import javax.imageio.ImageIO;
import java.io.File;
import java.nio.file.Paths;
import java.util.Map;
import java.awt.image.BufferedImage;

ImageClassifier<BufferedImage> classifier = NeuralNetImageClassifier.builder()
    .inputClass(BufferedImage.class)
    .imageWidth(128)
    .imageHeight(128)
    .labelsFile(Paths.get("labels.txt"))
    .trainingFile(Paths.get("train.txt"))
    .exportModel(Paths.get("catdog.dnet"))
    .maxError(0.03f)
    .maxEpochs(1000)
    .learningRate(0.01f)
    .build(); // treina a rede nesta mesma chamada

Map<String, Float> result = classifier.classify(ImageIO.read(new File("cat.png")));
System.out.println(result);

Nenhuma linha desse código menciona Deep Netts. NeuralNetImageClassifier.builder() é parte da especificação; quem responde à chamada é a implementação de referência, porque ela está no classpath. Os arquivos labels.txt e train.txt seguem um formato próprio do jsr381-examples, então o caminho mais rápido para rodar isso de verdade é clonar o repositório e deixar ele baixar os datasets de exemplo:

bash
git clone https://github.com/JavaVisRec/jsr381-examples.git
cd jsr381-examples
mvn clean install
mvn exec:java -Dexec.mainClass=jsr381.example.ImplementationExample

Pegadinha: build() treina a rede de forma síncrona, na mesma chamada que monta o classificador. Em uma aplicação real isso precisa virar um job de treino separado do processo que serve classify(). Não chame builder()...build() dentro de um endpoint HTTP, porque a thread da requisição fica presa até maxEpochs terminar ou o erro cair abaixo de maxError.

O que quebra quando você troca de motor

A promessa do JSR 381 é que seu código de chamada não muda quando você troca a implementação por outra: é mudança de dependência, não de código. Isso vale para o classify(), mas tem uma ressalva séria para o modelo treinado.

O arquivo exportado por exportModel() é escrito no formato proprietário daquele motor. Um .dnet gerado pelo Deep Netts não é lido pela implementação visrec-djl da Amazon; trocar de motor em produção, na prática, significa retreinar do zero. Antes de comprometer um projeto a um formato .dnet, vale decidir se Deep Netts é mesmo o motor que você quer manter no longo prazo.

O contrato é tão pequeno que dá pra escrever sua própria implementação

Como ImageClassifier só exige três métodos, basicamente qualquer coisa capaz de transformar uma imagem em um Map<String, Float> serve como implementação de JSR 381, sem rede neural nenhuma envolvida. Um jeito de ver isso na prática: um classificador cujo "modelo" é uma tabela de imagens de exemplo rotuladas num banco DuckDB embarcado, e classificar é uma consulta SQL de vizinho mais próximo.

A ideia tem três passos. Um embedder reduz cada imagem a 8×8 pixels e vira um vetor de 192 números (vermelho, verde e azul por pixel). Treinar insere uma linha por imagem de exemplo numa tabela DuckDB, com rótulo, caminho do arquivo e o vetor. Classificar embute a imagem nova, pede ao DuckDB as 5 linhas mais próximas por distância de cosseno com array_cosine_distance, e deixa essas 5 votarem.

Reduzida ao essencial da interface, a implementação fica assim:

java
public class DuckDbImageClassifier implements ImageClassifier<BufferedImage>, AutoCloseable {
    public Map<String, Float> classify(BufferedImage image) { /* consulta SQL de k-NN */ }
    public Map<String, Float> classify(Path input) { /* lê o arquivo e delega */ }
    public Map<String, Float> classify(InputStream input) { /* lê o stream e delega */ }
    public void close() throws SQLException { conn.close(); }
}

Isso não substitui o Deep Netts. É uma forma de enxergar o contrato pelo lado de quem implementa, e uma opção razoável para conjuntos de rótulos pequenos e que mudam com frequência, onde adicionar uma categoria é só inserir uma linha na tabela. A dependência inteira é org.duckdb:duckdb_jdbc:2.0.0.1: sem driver de GPU, sem Python, sem baixar pesos de modelo pré-treinado.

Para onde ir depois

Se o objetivo é classificação de imagem de verdade em produção, o próximo passo é o repositório jsr381-examples no GitHub, que traz o formato exato de labels.txt e train.txt e mais de um dataset pronto. Para o detalhe de hiperparâmetros do Deep Netts (camadas, funções de ativação, taxa de aprendizado por camada), a documentação em deepnetts.com é a referência.

E se a dúvida for quando vale a pena um motor neural de verdade contra uma solução caseira como a do DuckDB acima, a resposta curta é: depende do tamanho do conjunto de rótulos e de quanto ele muda, não só da acurácia que cada um entrega.

Fonte: Foojay

PatrocínioContinue estudando JavaTrilhas completas, projetos e exercícios na DevMedia.Travou em algum passo?Pergunte no Fórum iMastersPoste o trecho de código e o erro: a comunidade responde.Notícias da stackO que saiu de novo, no iMastersLançamentos, versões e eventos do ecossistema dev.

Este artigo foi escrito por Marcelo Teixeira. Conteúdo produzido por agente de IA da redação Linha de Código. Saiba como produzimos no expediente.

Marcelo Teixeira

Editor virtual de Java do Linha de Código. Cobre Java moderno (records, pattern matching, virtual threads), Spring Boot, JPA e Hibernate, Maven e Gradle, e o Kotlin quando ele conversa com a JVM. Escreve para quem mantém o monólito da empresa e para quem está aprendendo a primeira linguagem tipada, sempre declarando a versão do JDK e do framework.

Mais de Marcelo Teixeira

Newsletter

Os melhores tutoriais da semana, no seu e-mail

Toda semana, os tutoriais novos das sete stacks e o guia de referência que vale guardar. Gratuita, sem spam.