JoseRFJunior/I-JEPA-Agro

I-JEPA Agro

Projeto completo de triagem visual de anomalias em folhas de soja usando facebook/ijepa_vitg16_22k como extrator de representações e HeraclitusDB como banco de eventos e vetores.

O que o produto faz

1. lê um manifesto com fazenda, talhão, safra e cultivar;
2. executa o I-JEPA ViT-G/16 localmente;
3. aplica média aos patch tokens e normalização L2;
4. persiste cada imagem e seu embedding euclidiano no HeraclitusDB;
5. cria um artefato local para avaliação offline;
6. treina uma sonda linear;
7. busca imagens visualmente semelhantes;
8. oferece busca por uma API FastAPI.

Requisitos reais

• Python 3.11+;
• HeraclitusDB ativo em 127.0.0.1:7474;
• vários GB livres para o checkpoint;
• RAM suficiente para um modelo com aproximadamente 1B parâmetros;
• GPU é recomendada, mas a configuração começa em CPU para deixar o hardware explícito.

O checkpoint tem licença CC-BY-NC-4.0. Confira a licença antes de qualquer uso comercial.

1. Ambiente

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e .[dev]
pip install -e D:\DEV\HeraclitusDB\sdk\python
Copy-Item config.example.toml config.toml

Fora deste workspace, instale o SDK Python do HeraclitusDB a partir da localização em que ele estiver disponível.

2. Banco

Verifique o serviço local:

Get-Service HeraclitusDB

O projeto nunca desliga nem recria o banco. Ele escreve eventos do tipo IJepaAgroFolha com chave idempotente baseada em modelo, pooling e caminho.

3. Modelo

& .\scripts\download_model.ps1

O modelo fica em models/ijepa_vitg16_22k e não é versionado pelo Git.

4. Dataset

data/
  manifest.csv
  images/
    folha_0001.jpg
    folha_0002.jpg

O manifesto contém path,label,split,fazenda_id,talhao_id,safra,cultivar. O programa rejeita um talhão presente em treino e teste.

5. Ingestão

ijepa-ingest --config config.toml

Saídas:

• eventos e embeddings no HeraclitusDB;
• artifacts/embeddings.pt para avaliação offline.

6. Linear probe

ijepa-probe --config config.toml

O relatório fica em artifacts/probe-report.txt.

7. Busca semântica

ijepa-search data/images/folha_consulta.jpg --config config.toml -k 5

A consulta usa DIST_EUC no embedding normalizado. Em vetores de norma 1, distância euclidiana e cosseno induzem a mesma ordem, embora seus valores sejam diferentes.

8. API

uvicorn ijepa_inspector.api:app --host 127.0.0.1 --port 8000

curl.exe -F "file=@data/images/folha_consulta.jpg" "http://127.0.0.1:8000/search?k=5"

9. Testes

pytest -q
ruff check .

Os testes unitários não carregam o modelo de 1B parâmetros. Um teste de integração deve ser executado separadamente numa máquina que possua checkpoint e banco.

Caso de uso brasileiro

As classes ilustrativas são saudavel, ferrugem_asiatica, mancha_alvo e dano_inseto. O resultado é triagem e recuperação de casos semelhantes, não diagnóstico agronômico autônomo nem recomendação automática de defensivo.

Arquitetura

PIL Image
   │
AutoProcessor
   │ pixel_values [1,3,H,W]
   ▼
I-JEPA ViT-G/16
   │ last_hidden_state [1,N,D]
   ▼
mean pooling + L2 normalize
   │ embedding [D]
   ├────────────> HeraclitusDB euc[]
   ├────────────> LogisticRegression
   └────────────> FastAPI /search

Limitações

• Mean pooling é uma escolha do projeto, não a única representação possível.
• O checkpoint é gigante e pode ser impraticável em hardware limitado.
• A conversão OpenVINO não possui suporte I-JEPA nativo listado no Optimum Intel; trate-a como experimento separado e valide numericamente.
• Uma sonda linear mede acessibilidade da informação, não “compreensão” universal.