Ir para o conteúdo

HDT-AF

Aprendizagem Federada Confiável para Gêmeos Digitais

Doutorado — DCCMAPI - UFMA / LSDi José Daniel Pereira Ribeiro Filho josedaniel@lsdi.ufma.br


Contextualização

  • Gêmeos Digitais (pacientes, dispositivos, processos, organizações) dependem de modelos de aprendizado de máquina treinados sobre dados contínuos, sensíveis e heterogêneos — sinais fisiológicos, comportamentais ou de processo, atrelados à instância física que representam.
  • Cada gêmeo pertence a um dono distinto — não há um único detentor dos dados capaz de simplesmente reuni-los para treinar um modelo único.
  • A Aprendizagem Federada (FL) surge como resposta natural: treina modelos colaborativos sem centralizar dados brutos.
  • Mas frameworks de FL consolidados (Flower, NVIDIA FLARE, IBM FL, Substra, Fed-BioMed) tratam governança, proveniência e auditabilidade como preocupações extrínsecas — resolvidas fora do protocolo, por configuração de aplicação, não por invariante estrutural.

Problemática (na perspectiva dos Gêmeos Digitais)

  • Cada Gêmeo Digital (dispositivo, paciente, processo ou organização) gera continuamente dados locais sensíveis e heterogêneos, atrelados à instância física que representa.
  • Evoluir os modelos que sustentam esses gêmeos exige aprendizado colaborativo entre vários deles — mas centralizar os dados brutos de cada gêmeo fere a soberania de quem os gerou e pode violar LGPD e governança.
  • Como cada gêmeo tem um "dono" distinto, a colaboração exige, ao mesmo tempo:
  • soberania local dos dados de cada gêmeo;
  • rastreabilidade técnica de como cada gêmeo contribuiu para o modelo compartilhado;
  • validade científica dos resultados, apesar da heterogeneidade entre gêmeos.
  • Lacuna central: nenhum framework de FL existente une contrato pré-rodada verificável, auditoria blockchain imutável e isolamento real de código não confiável num único protocolo coeso.

Justificativa

  • Gêmeos digitais de saúde e comportamento humano operam sobre dados pessoais e sensíveis (Art. 5º, II da LGPD) — a ausência de governança estrutural não é só um risco técnico, é um risco de conformidade legal.
  • Depender de configuração correta (e não de invariante de protocolo) para proteger dados brutos, autenticar participantes e auditar decisões deixa a segurança do sistema tão forte quanto a disciplina operacional de quem o opera — um ponto único de falha humana.
  • A falta de confiança verificável entre participantes é uma barreira real de adoção de FL em domínios regulados (saúde, indústria), onde auditabilidade e responsabilização não são opcionais.
  • Contribuição pretendida: uma metodologia — não apenas um algoritmo — que eleva contrato, soberania de dados, transporte autenticado, auditoria imutável e isolamento de processo a invariantes estruturais do protocolo, com uma implementação de referência aberta e reprodutível.

A proposta

O HDT-AF é uma arquitetura de aprendizagem federada confiável para gêmeos digitais.

Permite treinar modelos colaborativos sem centralizar dados brutos, combinando:

  1. Contrato de experimento formal e obrigatório
  2. Execução local verificável no cliente
  3. Agregação robusta com quórum
  4. Auditoria em Hyperledger Fabric
  5. Comunicação federada — MQTT 5 ponta a ponta, para ingestão de dados e para o protocolo de rodada (cliente↔orquestrador); o cliente nunca fala com o agregador — o orquestrador relaya os updates e chama o agregador (função pura, sem I/O) diretamente

Uma metodologia inovadora para FL em Gêmeos Digitais

O HDT-AF trata confiança, governança e soberania de dados como requisitos de primeira classe do processo federado — não só novos algoritmos de agregação:

  1. Contrato formal e obrigatório rege dados, código, agregação e auditoria antes de cada rodada
  2. Governança nativa em blockchain: contrato, consentimento, evidência e modelo global viram ativos imutáveis
  3. Soberania de dados por construção: DataComponent como único acesso local é invariante de código — e só devolve o que o contrato autoriza, de um catálogo fechado de tipos (DataTypeCatalog, BL-245)
  4. Transporte federado real e seguro (mTLS + assinatura) — sensores e dispositivos físicos como participantes de fato

Papéis do sistema (C4 Context)

Papel Responsabilidade
Pesquisador Define o experimento e monitora rodadas (Monitor Web)
Cliente Consentimento + dataset local do nó (DataComponent)
Auditor Verifica evidências e hashes no ledger Fabric

Separação por desenho: quem autoriza o dado ≠ quem quer o resultado ≠ quem audita — soberania local + governança independente.

⚠️ Hoje é conceitual (C4 Context) — o Monitor Web ainda não tem RBAC por papel.


Fluxo de um experimento

Diagrama 00-fluxo-experimento-plantuml


Componentes principais

Componente Papel
Pesquisador Define objetivo, desenho experimental, métricas, código de treino e contrato
Contrato de experimento Formaliza dados permitidos, código, aceite, políticas, métricas, agregação e auditoria
Cliente federado Aceita contrato, resolve dados via DataComponent, roda preflight e treina localmente
DataComponent Único caminho de acesso a data/{client_id}/{experiment_id}; authorizedTrainingView(...) filtra pelo contrato (BL-245)

Componentes principais (cont.)

Componente Papel
Orquestrador Coordena contrato, seleção de clientes, rodadas e configuração federada; único caminho do update local até o agregador (ClientUpdateRelay, BL-242); chama o agregador diretamente e publica/registra o resultado (BL-244)
Agregador Valida updates, aplica quórum, rejeita outliers, gera modelo global candidato — função pura, sem I/O (BL-244)
Artifact Experiment Service Deve ser apenas staging temporário de artefatos durante a rodada, com remoção após confirmação do commit no ledger; a implementação ainda mantém cópias
Hyperledger Fabric Armazenamento permanente único desejado para o núcleo federado: contratos, consentimentos, eventos, updates/modelos e metadados de auditoria

Componentes principais (cont. 2)

Componente Papel
MQTT (Eclipse Paho) Barramento real para ingestão de dados (iot//mhub/) e para o protocolo de rodada (config/updates/modelo), em todo composition root JVM/Docker e Android (BL-259 reverteu a migração para REST+SSE do BL-240/BL-241/BL-242/BL-254)
ClientUpdateRelay (BL-242) Único caminho do update local ao agregador — o cliente publica só no orquestrador, que relaya (mesmo envelope assinado, sem re-assinar) e, a partir daí, chama o agregador direto em Java (BL-244)
Monitor Web Contratos, consentimentos, rodadas, métricas, assets, tarefas e containers; deploy dinâmico de experimentos
Empacotador de Experimentos Formato ExperimentPackage v1 (.zip) para implantar experimentos sem recompilar
Gêmeo Digital Local (broker embarcado) Interface local de acesso ao gêmeo digital (ADR-002) — broker HTTP+SSE embarcado (BL-243) que aciona o cliente e decide PROMOTE/REJECT/DEFER do modelo candidato

Assets da Blockchain (Hyperledger Fabric)

Registrados imutavelmente no World State via chaincode federated-governance:

Asset Descrição / Papel no Sistema
ExperimentContractAsset Contrato formal do experimento (status, validade, política, URI e hash SHA-256)
TrainingCodeAsset Código de treino autorizado (hash do JAR, entrypoint, manifesto e assinatura)
ClientConsentAsset Decisão de consentimento do cliente federado (ACCEPTED, REJECTED, REVOKED)

Assets da Blockchain (cont.)

Asset Descrição / Papel no Sistema
DatasetEvidenceAsset Evidência de integridade do dataset local (hashes de dataset.csv e metadata.json; sem dados brutos)
AuditEventAsset Registros auditáveis append-only de eventos de rodada, preflight e submissão de updates
GlobalModelAsset Versão do modelo global candidato, pesos e métricas registrados no Fabric

Arquitetura em camadas

Diagrama 01-arquitetura-plantuml


Núcleo Federado — detalhe interno

Diagrama 09-nucleo-federado-plantuml


Cliente Federado — detalhe interno

Diagrama 10-cliente-federado-plantuml


Pipeline de simulação de coleta de dados

Diagrama 02-pipeline-mqtt-plantuml


Técnicas de segurança empregadas

  • Cifragem & Autenticação Mútua: TLS 1.3 + mTLS (certificados X.509) no barramento MQTT.
  • Integridade de Payload (HMAC-SHA256): Assinatura criptográfica com chave secreta que valida a autenticidade da origem e garante que as observações não foram adulteradas ou injetadas por terceiros.
  • Providência Estrutural (BL-091): MqttTimeSeriesIngestor é o único escritor de produção de timeseries.db — presença de dados na store já comprova proveniência MQTT, sem checagem de runtime nem bypass possível.
  • Auditoria On-Chain: Registro imutável dos hashes SHA-256 dos updates no Hyperledger Fabric.

Ciclo de vida (status) do experimento

Diagrama 03-ciclo-vida-experimento-plantuml


Status do cliente por rodada

Diagrama 04-status-cliente-rodada-plantuml


Consentimento do usuário (LGPD)

Diagrama 08-consentimento-usuario-plantuml


Diagrama de componentes simplificado

Diagrama 05-componentes-simplificado-plantuml


Diagrama de containers (Docker)

Diagrama 06-containers-plantuml


Fluxo de simulação — MQTT + Docker + Fabric

Diagrama 07-fluxo-simulacao-plantuml


Invariantes obrigatórias

  • Java-only. Ingestão de dados (iot//mhub/) e protocolo de rodada (fl/, cliente↔orquestrador): MQTT 5 (TLS/mTLS), em todo composition root — JVM/Docker e Android. (BL-241/BL-242/BL-240/BL-254 haviam migrado o protocolo de rodada para REST+SSE; revertido pelo BL-259 a pedido explícito do usuário.)
  • O cliente nunca fala diretamente com o agregador (BL-242) — só publica no orquestrador; o ClientUpdateRelay é o único caminho até o agregador, sem re-assinar o envelope.
  • O agregador não acessa MQTT, Artifact Service nem Fabric (BL-244) — é uma função pura chamada diretamente pelo orquestrador, que também publica o resultado e registra os hashes.
  • Hyperledger Fabric como armazenamento permanente único do núcleo federado e camada de auditoria/governança. Artefatos externos são apenas staging temporário e devem ser removidos após confirmação do commit no ledger.
  • DataComponent é o único caminho de acesso aos dados locais do experimento, e só devolve o que o contrato autoriza (authorizedTrainingView(...), BL-245).
  • Os tipos de dado do contrato pertencem a um vocabulário fechado (DataTypeCatalog, federated-common) — não são texto livre; prohibitedFields tem precedência sobre allowedObservationCodes (BL-245).
  • Nenhum dado bruto sai do cliente federado.
  • Nenhum treinamento ocorre sem:
  • contrato aceito;
  • preflight válido;
  • compatibilidade de runtime verificada.
  • O gêmeo digital só é acessado via o broker HTTP+SSE embarcado (loopback, ADR-002, BL-243) — nunca exposto fora do processo/container do cliente.

Estratégias de seleção de clientes

Implementadas em federated-orchestrator, escolhidas por rodada via RoundCoordinator (hiperparâmetro participation_strategy):

Estratégia Resumo
AllAccepted (padrão)
all_accepted
Todos os aceitos participam a cada rodada — ideal para poucos clientes (< 100)
RandomSampled
random_sampled:fraction=F
Amostra uma fração por rodada; seed reprodutível baseSeed·31 + roundId
RoundRobin
round_robin:window=N
Rotaciona janelas de clientes; janela (roundId-1) % numWindows — participação equitativa

Todas garantem o quórum mínimo do contrato na seleção (SelectionStrategyCatalog).


Estratégias de agregação

Implementadas em Java puro no federated-aggregator:

  • FedAvg
  • FedProx
  • FedMedian
  • TrimmedMean
  • Krum
  • FedAdam

Todas com validação de quorum e rejeição de outliers antes de gerar o modelo global candidato.


Quórum: duas checagens distintas

"Aplicar quórum" não é responsabilidade de um componente só — são duas checagens diferentes, sobre populações diferentes, em estágios diferentes:

  • Quórum de participação — Orquestrador (RoundClientSelector), antes de iniciar a rodada clientes aceitos ≥ minimumClients — se falhar, lança QUORUM_NOT_REACHED e a rodada nem começa

  • Quórum do resultado — Agregador (FedAvgAggregationService), depois de coletar os updates updates recebidos ≥ minimumClients — se falhar, o modelo fica REJECTED (não é promovido)

Ambas usam o mesmo AggregationPolicy.minimumClients(), mas quem aceitou ≠ quem enviou update.


Privacidade e conformidade (LGPD)

Conformidade LGPD parcialmente implementada:

  • Pseudonimização on-chain (LGPD_PSEUDONYM_SALT)
  • TLS no monitor web (ADMIN_TLS_KEYSTORE)
  • TLS 1.3/mTLS no broker MQTT (mosquitto só expõe 8883, require_certificate true)
  • Política de retenção de artefatos (validTo)
  • consentTermsMarkdown legível no contrato de experimento
  • Privacidade diferencial aplicada no experimento de ECG (dado sensível de saúde)

Experimentos de pesquisa disponíveis

ID Dataset Tipo LGPD
exp-har-smartphones-001 UCI HAR Smartphones (21 sujeitos) Classificação multi-classe (6 atividades) — MLP Dado pessoal
exp-ecg5000-anomaly-001 ECG5000 (UCR Archive) Detecção de anomalias — MLP Autoencoder Dado sensível de saúde

Especificação de Empacotamento (Código & Datasets)

Permite implantar novos experimentos e dados de simulação sem recompilar a plataforma:

  • Pacote de Experimento ({id}.hdtpkg.zip):
  • package-descriptor.json: Formato v1, experimentId, contractVersion, sessionFactoryClass.
  • code/{id}.jar: Bytecode compilado do modelo de treinamento local.
  • manifest.yaml / specification.md: Metadados e especificação científica do experimento.
  • SHA256SUMS: Hash de integridade SHA-256 de todos os arquivos contidos.

  • Pacote de Dados de Simulação ({id}-simdata.hdtpkg.zip):

  • simulation-descriptor.json: packageFormatVersion: 1, experimentId, csvEntry.
  • dataset/data.csv: Séries temporais de observações para replay via MQTT.

  • Validação & Segurança no Desempacotamento:

  • Proteção contra Zip Slip (../), limite de descompressão (Zip Bomb) e checagem determinística de hashes.

Monitor Web

Aplicação web na porta 8088 (HTTP/HTTPS), com:

  • Contratos, consentimentos e evidências por cliente
  • Rodadas, gráficos de desempenho e configuração de hiperparâmetros
  • Explorer de blockchain por tipo de asset e eventos de auditoria
  • Deploy dinâmico de novos experimentos via upload de pacote (.hdtpkg.zip)
  • Modo de ledger: blockchain ( Fabric sempre obrigatório)
  • Execução de clientes em modo Docker, com logs e artefatos expostos em logs/<nome>/

Stack tecnológica

  • Java 25 + Maven
  • Hyperledger Fabric 2.5+ (chaincode federated-governance)
  • MQTT 5 — Eclipse Paho (federated-containers), ingestão de dados e protocolo de rodada (BL-259 reverteu a migração para REST+SSE do BL-240/BL-241/BL-242/BL-254)
  • HTTP+SSE embarcado — broker do gêmeo digital local (federated-digital-twin-broker, ADR-002, BL-243; substituiu o Moquette/MQTT interno) — federated-digital-twin-broker/java.net.http.HttpClient sobrevive só para este salto interno
  • HMAC-SHA256 para integridade de payloads e evidências
  • ML federado em Java puro (FedAvg, FedProx, FedMedian, TrimmedMean, Krum, FedAdam)
sh scripts/compile.sh            # build (Maven obrigatório)
sh scripts/run-admin-web.sh      # monitor web :8088
sh scripts/run-tests.sh          # suíte de testes

Estado atual (MVP funcional)

  • ✅ Compila e executa os dois experimentos reais (HAR, ECG5000)
  • ✅ Ingestão de dados via broker MQTT real (Eclipse Paho)
  • ✅ Chaincode federated-governance deployado (Org1 + Org2, federated-channel)
  • ✅ Monitor web com TLS opcional e deploy dinâmico de experimentos

Estado atual (cont.)

  • ✅ Modo de ledger: blockchain (único suportado — Fabric sempre obrigatório)
  • ✅ TLS 1.3/mTLS no broker MQTT (BL-016)
  • ✅ Interface local de acesso ao gêmeo digital — broker HTTP+SSE embarcado (ADR-002, BL-238; migrado de MQTT/Moquette para HTTP+SSE interno no BL-243)
  • ✅ Protocolo de rodada é MQTT-only em toda composition root — JVM/Docker e Android (BL-259 reverteu a migração para REST+SSE do BL-240/BL-241/BL-242/BL-254, a pedido explícito do usuário); federated-digital-twin-broker sobrevive só para o salto interno do BL-243
  • ✅ Cliente nunca fala diretamente com o agregador — ClientUpdateRelay no orquestrador é o único caminho do update local até o agregador (BL-242)
  • ✅ Agregador é função pura — não acessa MQTT, Artifact Service nem Fabric; o orquestrador chama aggregate(...) diretamente e publica/registra o resultado (AggregationResultPublisher, BL-244); DockerAggregatorDaemonApp (exp-ergonomic-risk-001) segue com transporte próprio, redesenho previsto numa entrega futura separada
  • ✅ Catálogo fechado de tipos de dados (DataTypeCatalog, federated-common) — o contrato só aceita tipos da tabela; DataComponent.authorizedTrainingView(...) é o único método que devolve dados ao FederatedClientService; prohibitedFields agora é de fato aplicado (BL-245)
  • ⚠️ Deploy dinâmico de pacotes: risco de execução de código arbitrário aceito e documentado

Obrigado

HDT-AF — Aprendizagem Federada Confiável para Gêmeos Digitais Doutorado UFMA/LSDi — José Daniel

Documentação completa: docs/README.md Base de conhecimento: .agent-config/rag/