Snapdragon X Elite NPU 실험 프로젝트

🎯 프로젝트 목적

⚠️ 핵심: 이 프로젝트는 NPU 실험만을 목적으로 합니다. CPU/GPU는 이미 확인되었으므로 범위 밖입니다.

유일한 목표: Snapdragon X Elite의 **NPU(Neural Processing Unit)**를 활용한 LLM 추론 실험

실험 목표 (NPU만 해당)

1. ✅ NPU 직접 제어: onnxruntime-genai + QNN을 통한 NPU 가속
2. ✅ 성능 측정: NPU 추론 속도 측정
3. ✅ 전력 효율: NPU 사용 시 배터리 소모량 측정
4. ✅ 기술 습득: NPU 활용 기술 및 지식 확보

범위 밖 (Out of Scope)

• ❌ CPU 추론 (이미 확인됨)
• ❌ GPU 추론 (이미 확인됨)
• ❌ 대안 탐색

현재 상태 (2025-12-20)

• ✅ NPU 모드: Native ARM64 Python을 통해 QNN 가속 활성화 성공!
• ✅ 모델: Phi-3.5 Mini Instruct (128K context window) 기본 탑재
• ✅ RAG: 문서(txt, md 등) 기반 고도화된 답변 생성 기능 추가
• ✅ 성능: Phi-3.5 기준 NPU 추론 시 실시간 응답 속도 확보

---

📚 문서 구조

핵심 문서 (반드시 읽기)

문서	목적	대상
README.md	프로젝트 개요 및 문서 네비게이션	모든 사용자
walkthrough.md	전체 현황 종합 보고서	프로젝트 파악
PROJECT_OBJECTIVE.md	NPU 활성화 로드맵 및 목표	핵심 가이드
SECURITY_BEST_PRACTICES.md	보안 가이드라인 및 체크리스트	오픈소스 배포 전 필독

기술 문서

문서	내용
docs/NPU_Inference_Guide_KR.md	NPU/CPU 추론 사용 가이드
docs/NPU_Debugging_Report.md	디버깅 결과 및 모델 호환성
docs/npu_strategy_comparison.md	NPU 접근 전략 비교

활용 문서

문서	내용
docs/Edge_AI_Use_Cases.md	Edge AI 활용 사례
roadmap.md	프로젝트 진행 로드맵
work_log.md	작업 일지

---

🎯 프로젝트 개요

본 프로젝트는 Snapdragon X Elite 프로세서의 핵심인 NPU(Hexagon) 가속을 활용하여, 온디바이스(On-device) 환경에서 최신 LLM인 Phi-3.5를 효율적으로 구동하는 웹 서비스를 구현하는 것이 목표입니다. 단순히 모델을 실행하는 것을 넘어, 로컬 문서 기반의 RAG(Retrieval-Augmented Generation) 시스템을 통합하여 실용적인 Edge AI 에이전트의 기술적 가능성을 실험하고 기록합니다.

🏗️ 시스템 구조

graph TB
    User[사용자/API Client] --> FastAPI[FastAPI Server :8000]
    
    subgraph "Python Layer"
        FastAPI --> Agent[EdgeAIAgent Core]
        Agent --> ModelMgr[Model Manager]
        Agent --> RAG[RAG Engine]
        
        ModelMgr --> Phi35[Phi-3.5 NPU]
    end
    
    subgraph "Execution Layer"
        Phi35 --> ORT[ONNX Runtime GenAI]
    end
    
    subgraph "Hardware"
        ORT -->|QNN| NPU[Hexagon NPU]
    end

Loading

✨ 주요 기능

1. 멀티 모델 지원

• Microsoft Phi-3.5 Mini Instruct (NPU/QNN optimized, 128K Context)
• Google Gemma 2 2B (DirectML INT4, ~1.5GB)

2. RAG (Retrieval-Augmented Generation) 시스템

• 로컬 문서 파일을 업로드하여 AI의 지식 베이스로 활용
• 질문에 가장 적합한 문맥(Context)을 자동으로 검색하여 답변에 반영

2. 하드웨어 가속 자동화

• NPU (Hexagon) 자동 인식 및 활성화
• 최적의 Execution Provider (QNN) 선택

📦 프로젝트 구조

npu_ai_web/
├── app/
│   ├── main.py              # FastAPI 서버 (Phi-3.5 NPU 가속 및 RAG 적용)
│   └── static/
│       └── index.html       # 웹 채팅 UI
├── edge_ai/                 # Edge AI Agent 모듈
│   ├── core.py             # EdgeAIAgent 핵심 로직
│   ├── hardware.py         # 하드웨어 감지
│   └── model_manager.py    # 모델 선택/로딩
├── models/                 # 모델 저장소 (사용자 준비 필요)
└── scripts/                # 유틸리티 및 테스트 스크립트

🚀 사용 방법

1. NPU 서버 실행 (추천)

.\run_npu_server.bat

Wait for "Application startup complete" and "DEBUG: Loaded with QNNExecutionProvider".

2. 웹 UI 접속

Open your browser and go to: http://localhost:8000

Python에서 자동 실행:

from edge_ai.copilot import CopilotConnector

connector = CopilotConnector()
connector.start_bridge()
result = connector.generate("Hello from Python!")
print(result)

3. Edge AI Agent 사용 (통합 인터페이스)

from edge_ai.core import EdgeAIAgent

agent = EdgeAIAgent()
await agent.initialize(preferred_model="gemma-2")

# 자동으로 최적 하드웨어 선택
print(f"Running on: {agent.active_accelerator}")
response = await agent.generate("Tell me about AI.")

🔔 자동 모니터링 & 알림

Telegram 알림 시스템

• 📱 실시간 알림: Phi Silica API 출시 시 즉시 알림
• 🌐 24/7 모니터링: PC + GitHub Actions 이중 체계
• 📊 자동 체크: NuGet 패키지, ONNX Runtime 릴리스

설정 방법: docs/telegram_setup.md 참조

실행 방법

# 수동 실행 (테스트)
python run_scheduled_monitor.py

# Windows Task Scheduler (PC 켜져있을 때)
# docs/telegram_setup.md 가이드 참조

# GitHub Actions (PC 꺼져있을 때)
# docs/github_actions_setup.md 가이드 참조

---

📦 재사용 가능한 모듈

TelegramNotifier

다른 프로젝트에서도 사용 가능한 독립 모듈:

# 단 1개 파일만 복사
from utils.telegram_notifier import TelegramNotifier

notifier = TelegramNotifier(bot_token="...", chat_id="...")
notifier.send("서버 재시작 완료!")

자세한 사용법: docs/telegram_notifier_reuse.md

---

🔧 환경 요구사항

Python 환경

• Python 3.13+
• Windows 11 (Build 22621+)
• 필수 패키지:

  pip install fastapi uvicorn
  pip install onnxruntime-genai-directml
  pip install huggingface_hub requests
  pip install winrt-Windows.AI.MachineLearning  # Copilot 연결용

C# 환경 (선택사항)

• .NET SDK 8.0
• Windows App SDK 1.6+

  winget install Microsoft.DotNet.SDK.8

🎮 현재 상태

✅ 작동 중

• Phi-3.5 Mini (NPU/QNN 가속)
• RAG 엔진 (문서 업로드 및 문맥 검색)
• FastAPI 서버 & 웹 채팅 UI
• C# Bridge (Windows Copilot Runtime 연동)

🔬 NPU 실험 현황

실험 결과 요약

항목	GPU (DirectML)	NPU (QNN)	상태
하드웨어	Adreno X1-45	Hexagon NPU	-
가속 방식	DirectML	QNN	-
모델	Phi-3 Mini / Gemma 2	Phi-3.5 Mini	-
추론 속도	실시간 (기준)	가속 확인 ✅	-
전력 효율	기준	최적화됨 ✅	-
작동 여부	✅ 완전 작동	✅ 완전 작동	🚀 성공

NPU 활성화 성공 요인

1. 아키텍처 전환: Native ARM64 Python (3.12) 환경 구축
2. onnxruntime-genai: QNN 지원 특수 빌드 및 DLL 경로 명시적 PATH 주입
3. 모델 호환성: Phi-3.5 Mini Instruct 최적화 사용

해결 방안 (최종)

• Native ARM64 Python (3.12) 환경 구축
• QNN DLL 경로의 명시적 PATH 주입

상세 여정: docs/NPU_Journey.md

---

📊 성능 비교 (기존)

🔬 기술 스택

• AI 런타임: ONNX Runtime GenAI
• 웹 프레임워크: FastAPI
• 하드웨어 가속: QNN (NPU 가속 활성화 ✅), DirectML (GPU)
• 모델 포맷: ONNX (INT4 Quantized)
• 언어: Python 3.12 (ARM64 Native), C# 12 (.NET 8)

📝 다음 계획

1. ✅ Copilot Runtime 통합 (완료)
2. ⏳ README 및 문서화
3. 📦 패키징 (pip 설치 가능하도록)
4. 🔄 NPU 모니터링 자동화 (Task Scheduler)
5. 🎯 성능 벤치마킹 도구

---

🧪 테스트 및 검증 (Testing & Verification)

✅ 자동화 테스트 (Automated Tests)

시스템의 안정성과 RAG 기능을 검증하기 위한 자동화 스크립트를 제공합니다.

1. RAG 엔진 단위 테스트:

   python scripts/test_rag_engine.py

2. RAG 통합 테스트 (서버 실행 시):

   python scripts/test_rag_full_flow.py

🔬 상세 검증 계획 (Roadmap)

현재 시스템은 성공적으로 구축되었으나, 안정성 확보를 위해 다음과 같은 추가 테스트가 예정되어 있습니다.

1. NPU 롱런(Long-run) 테스트: 장시간 추론 시 발열 및 성능 저하 여부 확인.
2. RAG 정확도 고도화: 대용량 문서에 대한 검색 정확도 및 컨텍스트 주입 최적화.
3. 배터리 효율 분석: CPU/GPU 대비 NPU 사용 시 실제 에너지 효율 데이터 확보.

---