Skip to content
프로젝트

rasidi3112/Q-Edge has 62 GitHub stars and 0 forks. GitHot measured +1 stars in 24 hours, +1 in 7 days, and +1 in 15 days. Last checked 2026-11-22 10:28 UTC. Last push 2026-11-19.

이 수치를 측정하는 방법

측정된 스타 증가

in 24h
+1
in 7 days
+1
in 15 days
+1
in 1 month
기록 수집 중

서로 겹치는 기간의 순증가량이며 일별 합계가 아닙니다. 측정값이 없으면 비워 둡니다. 스타는 관심도를 나타내며 품질을 보장하지 않습니다.

소개

Research testbed for federated learning with hybrid quantum-classical models and post-quantum protection (ML-KEM, ML-DSA, secure aggregation). Reproducible results: a 4-qubit VQC head vs a matched classical head, robust aggregation vs poisoning, PQC cost per round. PennyLane, PyTorch, Flower, FastAPI.

머신러닝

README_ko.md

Original

Q-Edge

CI License: Apache-2.0 Python 3.11-3.13

English | العربية | Deutsch | Español | Français | हिन्दी | Bahasa Indonesia | Italiano | 日本語 | 한국어 | Bahasa Melayu | Português | Русский | Türkçe | Tiếng Việt | 中文

이 문서는 README.md의 번역본입니다. 내용이 다를 경우 영어판이 우선합니다.

Q-Edge는 양자-고전 하이브리드 모델을 사용하는 연합 학습과 클라이언트 업데이트의 양자내성 보호를 위한 연구용 테스트베드입니다. 세 가지 질문에 재현 가능한 수치로 답합니다.

  1. 비 IID 데이터에서 작은 변분 양자 회로(VQC) 헤드는 파라미터 수가 같은 고전 헤드만큼 성능을 낼까? 노이즈가 있을 때와 없을 때, 제로 노이즈 외삽을 적용했을 때와 하지 않았을 때를 비교합니다.
  2. 양자내성 보호(ML-KEM-768, ML-DSA-65, 하이브리드 X25519 + ML-KEM-768, 보안 집계)는 라운드당 얼마의 비용이 드는가?
  3. 악의적인 클라이언트는 얼마나 큰 피해를 줄 수 있고, 강건 집계 규칙은 얼마나 도움이 되며, 이 규칙들은 보안 집계와 어떻게 충돌하는가?

부정적인 답도 결과로 인정합니다. 아래의 모든 수치는 make reproduce가 다시 만드는 results/summary/*.json에서 가져왔으며, 전체 표와 그림은 docs/results.md에 있습니다.

무엇이고 무엇이 아닌가

이 프로젝트는:

  • scikit-learn의 breast_cancer와 digits에 Dirichlet 레이블 편향을 적용한 연합 학습 시뮬레이터(qedge simulate)입니다. 전략: FedAvg, FedProx, FedAdam, FedYogi. 그 밖에 top-k 압축, 공격, 강건 규칙, 보안 집계를 제공합니다. 같은 클라이언트·서버 코드가 Flower 1.40 앱으로도 실행됩니다 (flwr run experiments/flower).
  • PennyLane VQC 헤드를 가진 PyTorch 하이브리드 모델입니다. 게이트 및 판독 노이즈 시뮬레이션, 전역 폴딩을 이용한 ZNE, 진단(기울기 분산, 커널 집중, 표현력)을 갖추고 있습니다.
  • 관리자에 의한 클라이언트 등록, ML-DSA 챌린지-응답 로그인, 서명된 X25519 + ML-KEM-768 전송, 검증된 라운드, server-sent events, Prometheus 지표를 갖춘 FastAPI 서버입니다. 읽기 전용 Flutter 대시보드가 상태를 보여 줍니다.

이 프로젝트는 다음이 아닙니다:

  • 양자 하드웨어. 모든 회로는 시뮬레이터(default.qubit, default.mixed)에서 실행됩니다.
  • 실제 배포. 클라이언트는 하나의 프로세스 안에서 시뮬레이션되거나 Python 스크립트이며, 모바일 기기에서의 학습은 없습니다.
  • 감사를 거친 암호. 하이브리드 KEM 결합 방식, 전송 계층, 보안 집계 프로토콜은 이 프로젝트 자체의 설계입니다. 순수 Python 백엔드는 상수 시간이 아닙니다.
  • 양자 우위의 증거. 이번 실험에서 VQC 헤드가 고전 헤드보다 확실히 나은 경우는 한 번도 없었습니다.

아키텍처

flowchart LR
  subgraph clients["FL clients"]
    sim["qedge simulate<br/>(in-process clients)"]
    remote["RemoteClient<br/>(Python)"]
  end
  subgraph server["qedge-api"]
    auth["enrollment + ML-DSA login"]
    transport["X25519 + ML-KEM-768<br/>handshake, ChaCha20-Poly1305"]
    rounds["rounds: FedAvg or<br/>robust rule"]
    db[("SQL + blobs")]
  end
  dash["Flutter dashboard<br/>(read-only)"]
  q["PennyLane simulators<br/>VQC, noise, ZNE"]
  remote -- "sealed updates" --> transport --> rounds --> db
  remote -- "token" --> auth
  dash -- "REST + SSE" --> rounds
  sim --> q
  rounds -. "Celery run_circuit" .-> q

자세한 내용: docs/architecture.md, 설계 결정: docs/decisions/, 위협: docs/threat-model.md.

빠른 시작

git clone https://github.com/rasidi3112/Q-Edge.git && cd Q-Edge
python -m venv .venv && source .venv/bin/activate
pip install torch --index-url https://download.pytorch.org/whl/cpu   # optional: CPU-only torch
pip install -e ".[fl,pqc-pure]"

qedge demo                       # one run of each component, about 5 s
qedge simulate --dataset breast_cancer --clients 10 --rounds 30 --alpha 0.5 --strategy fedavg
qedge simulate --model hybrid-vqc --qubits 4 --layers 2 --noise 0.01 --zne richardson
qedge simulate --dataset digits --model mlp --attack scaling --attack-fraction 0.3 --defense multi_krum
qedge simulate --secure-aggregation

simulate를 실행할 때마다 results/runs/<run_id>/config.yaml(설정, 클라이언트 분할, 파라미터 수, 패키지 버전, 머신)과 metrics.jsonl(라운드마다 한 줄)이 기록됩니다. pqc-pure는 시험용 순수 Python ML-KEM 및 ML-DSA입니다. 그 밖의 용도에는 liboqs 0.16을 빌드하고 q-edge[pqc]를 설치하세요.

Extra 추가되는 것
fl PyTorch, Flower, scikit-learn, PyYAML: 시뮬레이터, 하이브리드 모델
server FastAPI 서버, Celery 워커, qedge clients
pqc liboqs-python (liboqs C 라이브러리 필요)
pqc-pure kyber-py와 dilithium-py: 상수 시간 아님, 테스트 전용
report python -m experiments.report용 matplotlib
flower-sim flwr run용 Ray
postgres compose 스택용 psycopg
dev pytest, hypothesis, ruff, mypy, pre-commit

서버

pip install -e ".[server,pqc-pure]"
qedge keys init --dir ./keys --backend pure        # server KEM and ML-DSA keys
qedge clients keygen --out ./admin --backend pure  # admin key pair, stays local
qedge clients add --id admin --scope admin --public-key ./admin/client.pub --backend pure
JWT_SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(48))") \
  QEDGE_CRYPTO_BACKEND=pure QEDGE_KEY_DIR=./keys qedge-api

관리자가 클라이언트를 등록하고 라운드를 엽니다(POST /admin/rounds). 클라이언트(qedge.fl.remote.RemoteClient)는 nonce에 서명해 로그인하고, 암호화된 세션을 연 뒤 라운드마다 봉인된 업데이트 하나를 보냅니다. 서버는 min_clients개의 업데이트가 도착하거나 마감 시간이 지나면 QEDGE_AGGREGATION(fedavg, median, trimmed_mean, krum, multi_krum, bounded)으로 집계합니다. 키나 암호 백엔드가 없으면 시작을 거부합니다. Docker 사용 시:

cp .env.example .env   # set JWT_SECRET_KEY, REDIS_PASSWORD, POSTGRES_PASSWORD
qedge clients keygen --out ./admin
docker compose run --rm api qedge keys init --dir /keys
docker compose run --rm -v "$PWD/admin:/admin:ro" api \
  qedge clients add --id admin --scope admin --public-key /admin/client.pub
docker compose up --build

대시보드: cd mobile_app && flutter run -d chrome --web-port 3000 --dart-define=QEDGE_API_URL=http://localhost:8000 (mobile_app/README.md).

결과

노트북 CPU에서 시뮬레이션한 클라이언트, seed 0-2에 대한 평균 ± 표준편차. 전체 표, 그림, 설정: docs/results.md, experiments/configs/.

RQ1: VQC 헤드 대 고전 헤드. 클라이언트 5, 라운드 15, 큐비트 4, strongly entangling 층 2개(파라미터 24)를 파라미터 20의 tanh 헤드와 비교합니다. 인코더와 출력층은 동일합니다.

데이터셋, α 고전 헤드 VQC VQC, p = 0.01 VQC, p = 0.01, ZNE
breast_cancer, 0.1 0.968 ± 0.018 0.965 ± 0.032 0.930 ± 0.092 0.965 ± 0.032
breast_cancer, 1.0 0.974 ± 0.018 0.977 ± 0.018 0.974 ± 0.018 0.977 ± 0.018
digits, 0.1 0.643 ± 0.125 0.486 ± 0.093 0.496 ± 0.086 0.491 ± 0.084
digits, 1.0 0.685 ± 0.143 0.514 ± 0.061 0.485 ± 0.100 0.512 ± 0.058

VQC 헤드는 breast_cancer에서 고전 헤드와 비슷하고 digits에서는 약 0.16 낮습니다. p = 0.01 탈분극 노이즈와 ZNE가 최종 정확도를 바꾸는 폭은 seed 간 편차보다 작으며, 가장 큰 효과는 α = 0.1의 breast_cancer(노이즈 없음 0.965, 노이즈 있음 0.930, ZNE 적용 0.965)에서 나타납니다. ZNE는 학습을 약 8배 느리게 만듭니다. 무작위 4큐비트 회로에서 ZNE는 p = 0.01의 기댓값 오차를 0.055에서 0.005(Richardson) 또는 0.003(지수)으로 줄입니다.

RQ2: 양자내성 보호의 비용 (liboqs 0.16):

  • 전송 핸드셰이크는 세션당 한 번, 0.57 ms와 7 840 바이트가 들며 업데이트 프레임마다 52 바이트가 추가됩니다.
  • 라운드·클라이언트당 보안 집계 비용(일반 float32 업로드와 비교):
    • 클라이언트 10, 파라미터 1 210: 4.7 KiB 대신 36.6 KiB 업로드, 2.6 ms; 서버 3.8 ms.
    • 클라이언트 50, 파라미터 100 000: 391 KiB 대신 895 KiB, 33 ms; 서버 95 ms.
  • 마스킹된 값이 8 바이트를 차지하므로 업로드가 두 배가 되며, 키 교환은 클라이언트 수에 비례해 늘어납니다.

RQ3: 악의적인 클라이언트 (digits, MLP, 클라이언트 10, 라운드 30, 10명 중 3명이 공격):

공격 FedAvg 중앙값 Multi-Krum
없음 0.952 ± 0.003 0.931 ± 0.006 0.922 ± 0.003
레이블 뒤집기 0.700 ± 0.314 0.883 ± 0.032 0.938 ± 0.013
스케일링(모델 교체) 0.177 ± 0.094 0.908 ± 0.015 0.936 ± 0.022
무작위 노이즈 0.578 ± 0.065 0.933 ± 0.014 0.936 ± 0.022
샘플 수 위조 0.030 ± 0.018 0.883 ± 0.032 0.938 ± 0.013

FedAvg는 모든 공격에 실패합니다. Multi-Krum은 공격이 없을 때 자신의 정확도에서 0.02 이내를 유지하지만, 공격자가 없을 때 0.03의 손실이 있습니다. Krum만 쓰면 비 IID 데이터에서 0.28 손실이 납니다. 이 규칙들은 모두 검사 대상인 개별 업데이트를 숨기는 보안 집계 아래에서는 동작할 수 없습니다(ADR 0010). 절사 평균, 노름 클리핑, 샘플 수 상한은 docs/results.md에 있습니다.

보안 모델

보호되는 것: 현재 또는 양자 컴퓨터가 X25519를 깬 이후의 통신 중 업데이트 도청·위조(하이브리드 KEM, 서명된 핸드셰이크, AEAD 프레임, 재전송 카운터), 서버나 등록된 클라이언트로의 위장, 잘못된 형식이거나 중복된 업데이트, 클라이언트에 의한 집계 개시. 부분적으로 보호되는 것: 프로토콜을 따르는 악의적 클라이언트(강건 규칙을 통해). 보호되지 않는 것: 시뮬레이터 밖의 호기심 많은 서버(보안 집계는 HTTP로 제공되지 않음), 전역 모델로부터의 추론(프라이버시 회계 없음), 서비스 거부, 순수 백엔드의 부채널, 만료 전에 탈취된 토큰. docs/threat-model.md를 참고하세요.

한계

  • 작고 쉬운 데이터셋 두 개뿐입니다. 표준편차 하나 정도(RQ1 digits에서 최대 0.14)보다 작은 차이는 seed 3개로는 판별할 수 없습니다.
  • RQ1은 ZNE 실행 시간을 감당할 수 있도록 클라이언트 5, 라운드 15를 쓰므로 digits 정확도(0.5-0.7)는 30라운드 MLP(0.95)보다 훨씬 낮습니다.
  • 시뮬레이션 노이즈는 게이트와 와이어마다 채널 하나이며, 크로스토크, 유휴 노이즈, 코히어런트 오류가 없습니다. default.mixed를 통한 역전파는 하드웨어로는 얻을 수 없는 기울기를 줍니다(ADR 0009).
  • 보안 집계에는 이탈 복구가 없고 프로세스 내부에서만 실행됩니다. 측정된 비용에는 네트워크 지연이 포함되지 않습니다.
  • 클리핑과 가우시안 노이즈는 있지만 프라이버시 회계가 없어 ε는 보고하지 않습니다.
  • 강건 규칙은 공격자가 최대 30 %라고 가정하며, 표적형 백도어나 적응형 공격자에 대해서는 테스트하지 않았습니다.
  • Flutter 앱은 읽기 전용이며 암호 처리를 하지 않습니다. Android와 iOS 빌드는 테스트하지 않았습니다.

개발

pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install uv==0.13.7   # pip gives up resolving fl together with server
uv pip install -e ".[dev,server,pqc-pure,fl,report]"
pre-commit install
make lint             # ruff check, ruff format --check, mypy --strict on src/qedge
make test             # pytest -m "not slow"
pytest -m slow        # Flower end-to-end and a noisy ZNE run (needs flower-sim)
make reproduce        # every experiment and docs/results.md, about 62 minutes

python -m experiments.run_all --skip quantum_head는 ZNE 그리드를 제외한 모든 것을 약 7분 만에 다시 실행합니다. CI는 Python 3.11-3.13에서 lint와 테스트, liboqs 작업, Flutter 테스트, Docker 빌드를 실행합니다.

구조

src/qedge/
  crypto/     ML-KEM, ML-DSA, hybrid KEM, transport, key files, backends
  fl/         datasets, models, training, strategies, robust rules, attacks,
              compression, privacy, secure aggregation, simulator, Flower apps
  quantum/    circuits, noise, ZNE and readout mitigation, kernels, models,
              diagnostics
  server/     FastAPI app, auth, rounds, storage, metrics, Celery worker
  cli.py      qedge keys | clients | simulate | demo
  demo.py
experiments/  configs/*.yaml, one script per experiment, run_all.py, report.py
bench/        crypto.py, secagg.py
results/      summary/*.json (committed), runs/ (ignored)
docs/         architecture.md, threat-model.md, results.md, figures/, decisions/
mobile_app/   Flutter dashboard

참고 문헌

  • McMahan et al., "Communication-Efficient Learning of Deep Networks from Decentralized Data", 2017, arXiv:1602.05629 (FedAvg).
  • Li et al., "Federated Optimization in Heterogeneous Networks", 2018, arXiv:1812.06127 (FedProx).
  • Reddi et al., "Adaptive Federated Optimization", 2020, arXiv:2003.00295 (FedAdam, FedYogi).
  • Karimireddy et al., "Error Feedback Fixes SignSGD and other Gradient Compression Schemes", 2019, arXiv:1901.09847.
  • Yin et al., "Byzantine-Robust Distributed Learning: Towards Optimal Statistical Rates", 2018, arXiv:1803.01498 (median, trimmed mean).
  • Blanchard et al., "Machine Learning with Adversaries: Byzantine Tolerant Gradient Descent", NeurIPS 2017 (Krum).
  • Sun et al., "Can You Really Backdoor Federated Learning?", 2019, arXiv:1911.07963 (norm clipping).
  • Bagdasaryan et al., "How To Backdoor Federated Learning", 2018, arXiv:1807.00459 (model replacement).
  • Bonawitz et al., "Practical Secure Aggregation for Privacy-Preserving Machine Learning", CCS 2017.
  • Schuld et al., "Circuit-centric quantum classifiers", 2018, arXiv:1804.00633.
  • Pérez-Salinas et al., "Data re-uploading for a universal quantum classifier", 2020, arXiv:1907.02085.
  • Havlíček et al., "Supervised learning with quantum-enhanced feature spaces", Nature 2019.
  • Temme et al., "Error mitigation for short-depth quantum circuits", 2017, arXiv:1612.02058.
  • Giurgica-Tiron et al., "Digital zero noise extrapolation for quantum error mitigation", 2020, arXiv:2005.10921.
  • McClean et al., "Barren plateaus in quantum neural network training landscapes", 2018, arXiv:1803.11173.
  • Thanasilp et al., "Exponential concentration in quantum kernel methods", 2022, arXiv:2208.11060.
  • Sim et al., "Expressibility and entangling capability of parameterized quantum circuits", 2019, arXiv:1905.10876.
  • NIST FIPS 203 (ML-KEM) and FIPS 204 (ML-DSA), 2024.

라이선스

Apache 2.0, LICENSE를 참고하세요. 변경 사항은 CHANGELOG.md에 있습니다.

관련 프로젝트 살펴보기

불러오는 중…