commit a94c9f76379f3764c6065836567b8c1a8d0aff93 Author: kkt Date: Tue Jun 23 09:21:51 2026 +0900 README.md 추가 diff --git a/README.md b/README.md new file mode 100644 index 0000000..a5a79be --- /dev/null +++ b/README.md @@ -0,0 +1,400 @@ +# Hansero VisionCore / Hai-Studio Installer Releases + +한세로테크노 AI 비전 학습 프로그램 및 검사 런타임 설치파일 배포용 저장소입니다. + +이 저장소는 **소스코드 저장소가 아니라 설치파일 릴리즈 저장소**입니다. +프로그램 소스코드, 개발 이력, 내부 구현 파일은 별도 소스 저장소에서 관리하며, 이 저장소에는 사내 설치 및 배포에 필요한 설치파일과 사용 안내만 보관합니다. + +--- + +## 1. 프로그램 개요 + +### Hai-Studio / AI Trainer + +Hai-Studio는 한세로테크노 내부에서 사용하는 AI 비전 학습 프로그램입니다. + +주요 기능은 다음과 같습니다. + +* 이미지 데이터셋 관리 +* Detection / Segmentation / Classification / Pose 학습 프로젝트 구성 +* YOLO 기반 PT/Python 학습 및 추론 +* 학습 모델 ONNX 변환 +* C# Native ONNX 추론 모드 지원 +* 라벨링 및 검수 기능 +* 샘플 프로젝트 실행 +* 검사 프로그램 연동용 모델 생성 + +--- + +## 2. 저장소 용도 + +이 저장소는 다음 목적에 사용합니다. + +* 최종 설치파일 보관 +* 버전별 릴리즈 관리 +* 사내 PC 설치용 파일 배포 +* 설치 방법 및 주의사항 안내 +* 소스코드와 배포파일 분리 관리 + +이 저장소에는 원칙적으로 다음 파일만 포함합니다. + +```text +README.md +CHANGELOG.md +installers/ +docs/ +checksums/ +``` + +권장 구조는 다음과 같습니다. + +```text +. +├─ README.md +├─ CHANGELOG.md +├─ installers/ +│ ├─ HaiStudioTrainer_Setup_v1.0.xx.exe +│ ├─ HanseroInspectionRuntime_Setup_v1.0.xx.exe +│ └─ HanseroVisionCore_Full_Setup_v1.0.xx.exe +├─ docs/ +│ ├─ 설치_방법.md +│ ├─ 사용_전_확인사항.md +│ └─ 문제해결.md +└─ checksums/ + └─ SHA256SUMS.txt +``` + +--- + +## 3. 설치파일 구분 + +### 3.1 Hai-Studio Trainer Installer + +학습 프로그램 설치파일입니다. + +포함 대상: + +* Hai-Studio / AI Trainer 실행 프로그램 +* AI Engine SDK +* Native ONNX 추론 모듈 +* Python / PT YOLO 학습 런타임 +* ONNX 변환 기능 +* 샘플 프로젝트 +* Tools +* Assets +* Docs + +일반적으로 학습 프로그램을 설치할 PC에는 이 설치파일을 사용합니다. + +--- + +### 3.2 Inspection Runtime Installer + +검사 프로그램 실행용 런타임 설치파일입니다. + +포함 대상: + +* AI Engine SDK +* Native ONNX Runtime +* 검사 프로그램 실행에 필요한 공통 런타임 +* 샘플 검사 프로젝트 +* Tools +* Assets +* Docs + +학습 기능이 필요 없고, 검사 프로그램 실행만 필요한 PC에는 이 설치파일을 사용합니다. + +--- + +### 3.3 Full Local Installer + +전체 통합 설치파일입니다. + +포함 대상: + +* Hai-Studio / Trainer +* SDK +* Runtime +* Samples +* Tools +* Assets +* Docs + +개발, 테스트, 오프라인 설치, 현장 대응용 PC에는 전체 통합 설치파일을 사용합니다. + +--- + +## 4. 파일명 규칙 + +설치파일은 다음 형식을 권장합니다. + +```text +HaiStudioTrainer_Setup_v1.0.xx.exe +HanseroInspectionRuntime_Setup_v1.0.xx.exe +HanseroVisionCore_Full_Setup_v1.0.xx.exe +``` + +예시: + +```text +HaiStudioTrainer_Setup_v1.0.95.exe +HanseroInspectionRuntime_Setup_v1.0.95.exe +HanseroVisionCore_Full_Setup_v1.0.95.exe +``` + +버전 표기는 가능한 한 다음 기준을 따릅니다. + +```text +Major.Minor.Build +``` + +예시: + +```text +v1.0.95 +v1.0.96 +v1.0.97 +``` + +--- + +## 5. 설치 위치 + +기본 설치 위치는 다음과 같습니다. + +```text +C:\Program Files\Hansero\VisionCore\ +``` + +설치 후 권장 폴더 구조는 다음과 같습니다. + +```text +C:\Program Files\Hansero\VisionCore\ +├─ Studio +├─ Trainer +├─ SDK +├─ Runtime +├─ Samples +├─ Tools +├─ Assets +└─ Docs +``` + +설치파일 종류와 버전에 따라 일부 폴더는 포함되지 않을 수 있습니다. + +--- + +## 6. 설치 전 확인사항 + +설치 전 다음 사항을 확인합니다. + +* Windows 10 또는 Windows 11 64bit +* 관리자 권한 설치 권장 +* 기존 버전 실행 중이면 종료 후 설치 +* 백신 또는 보안 프로그램에서 설치파일 차단 여부 확인 +* GPU 사용 시 NVIDIA 드라이버 설치 여부 확인 +* 오프라인 설치 시 설치파일 용량과 포함 런타임 확인 + +--- + +## 7. 설치 방법 + +1. 최신 릴리즈 설치파일을 다운로드합니다. +2. 설치파일을 마우스 오른쪽 버튼으로 클릭합니다. +3. `관리자 권한으로 실행`을 선택합니다. +4. 설치 경로를 확인합니다. +5. 설치를 완료합니다. +6. 시작 메뉴 또는 바탕화면 바로가기로 프로그램을 실행합니다. + +--- + +## 8. 설치 후 확인사항 + +설치 후 다음 항목을 확인합니다. + +### Hai-Studio / Trainer + +* 프로그램 정상 실행 여부 +* 새 프로젝트 생성 가능 여부 +* 샘플 프로젝트 열기 가능 여부 +* PT / Python YOLO 모드 선택 가능 여부 +* Native ONNX 추론 모드 선택 가능 여부 +* ONNX 변환 기능 동작 여부 +* GPU 장치 표시 여부 +* 추론 테스트 실행 여부 + +### Runtime + +* Runtime 폴더 존재 여부 +* SDK 폴더 존재 여부 +* Samples 폴더 존재 여부 +* 검사 샘플 실행 여부 +* ONNX 모델 로드 여부 + +--- + +## 9. 설치파일 용량 확인 기준 + +런타임 포함 여부는 설치파일 용량으로 1차 확인할 수 있습니다. + +```text +수십 MB 수준 +→ 런타임 또는 샘플 누락 가능성 있음 + +수 GB 수준 +→ Python / AI Runtime / Samples 포함 가능성 높음 +``` + +특히 Trainer 설치파일은 Python 기반 학습 런타임을 포함하는 경우 용량이 크게 증가할 수 있습니다. + +--- + +## 10. 버전 업데이트 절차 + +새 설치파일을 등록할 때는 다음 순서로 진행합니다. + +1. 설치파일 생성 +2. 테스트 PC에서 설치 검증 +3. 실행 및 샘플 프로젝트 검증 +4. 설치파일명을 버전 규칙에 맞게 변경 +5. `installers/` 폴더에 업로드 +6. `CHANGELOG.md` 업데이트 +7. 필요 시 `checksums/SHA256SUMS.txt` 업데이트 +8. Git tag 또는 Gitea Release 등록 + +권장 커밋 메시지: + +```text +Add Hai-Studio Trainer installer v1.0.xx +``` + +또는: + +```text +Release Hansero VisionCore installer v1.0.xx +``` + +--- + +## 11. 소스코드 저장소와의 관계 + +이 저장소는 설치파일 배포 전용 저장소입니다. + +소스코드는 별도 저장소에서 관리합니다. + +예시: + +```text +소스코드 저장소 +→ hansero-visioncore +→ hansero-ai-trainer +→ hansero-ai-engine-sdk + +릴리즈 저장소 +→ hansero-visioncore-installer-releases +``` + +릴리즈 저장소에는 다음 항목을 올리지 않습니다. + +```text +bin/ +obj/ +.vs/ +.git/ +소스 전체 압축본 +개발 중간 산출물 +개인 토큰 +개인 설정 파일 +임시 테스트 파일 +``` + +--- + +## 12. 보안 주의사항 + +설치파일 배포 저장소에는 다음 정보를 포함하지 않습니다. + +* Gitea 개인 토큰 +* API Key +* 서버 접속 비밀번호 +* 사내 DB 접속 정보 +* 고객사 보안 자료 +* 학습 데이터 원본 중 외부 반출 제한 자료 +* 모델 파일 중 고객사 반출 제한 대상 + +설치파일을 외부에 전달하기 전에는 포함 파일을 반드시 확인합니다. + +--- + +## 13. 문제 해결 + +### 설치파일 실행이 차단되는 경우 + +Windows SmartScreen 또는 백신에서 차단할 수 있습니다. + +조치 방법: + +1. 설치파일 우클릭 +2. 속성 선택 +3. 차단 해제 항목이 있으면 체크 +4. 관리자 권한으로 실행 + +--- + +### 프로그램이 실행되지 않는 경우 + +다음을 확인합니다. + +* 설치 경로에 한글 또는 특수문자가 과도하게 포함되어 있는지 확인 +* Runtime 폴더 존재 여부 확인 +* 필요한 DLL 파일 존재 여부 확인 +* 백신에서 일부 파일을 격리했는지 확인 +* 로그 파일 확인 + +--- + +### GPU가 표시되지 않는 경우 + +다음을 확인합니다. + +* NVIDIA 드라이버 설치 여부 +* CUDA 지원 GPU 여부 +* ONNX Runtime GPU 패키지 포함 여부 +* 프로그램 설정에서 GPU 장치 선택 여부 + +GPU 사용이 불가능한 경우 CPU 모드로 실행할 수 있습니다. + +--- + +### 샘플 프로젝트가 열리지 않는 경우 + +다음을 확인합니다. + +* Samples 폴더가 설치되었는지 확인 +* 샘플 이미지, 모델, 설정 파일이 모두 포함되어 있는지 확인 +* 설치파일 용량이 비정상적으로 작지 않은지 확인 + +--- + +## 14. 담당 + +* 개발 / 유지보수: 한세로테크노 +* 용도: 사내 AI 비전 학습 및 검사 프로그램 배포 +* 배포 대상: 사내 개발 PC, 검사 PC, 현장 테스트 PC + +--- + +## 15. 변경 이력 + +자세한 변경 내용은 `CHANGELOG.md`를 확인합니다. + +간단한 릴리즈 기록은 아래 형식으로 작성합니다. + +```text +v1.0.xx +- Hai-Studio Trainer 설치파일 업데이트 +- Native ONNX 추론 모드 추가 +- PT/Python YOLO 학습 모드 유지 +- 샘플 프로젝트 포함 +- Runtime 경로 자동 탐색 개선 +```