fletimageanalysis/docs/user_guide.md

사용자 가이드

PDF 도면 분석기의 상세한 사용법을 안내합니다.

목차

1. 설치 후 첫 실행
2. 기본 사용법
3. 고급 기능
4. 문제 해결
5. 팁과 요령

설치 후 첫 실행

1. API 키 설정 확인

애플리케이션을 처음 실행하기 전에 Gemini API 키가 올바르게 설정되었는지 확인하세요.

# .env 파일 확인
GEMINI_API_KEY=your_actual_api_key_here

2. 테스트 실행

설치가 올바르게 되었는지 확인:

python test_project.py

3. 애플리케이션 실행

python main.py

기본 사용법

1. PDF 파일 업로드

1. 파일 선택: “PDF 파일 선택” 버튼을 클릭합니다.
2. 파일 확인: 선택된 파일의 정보(이름, 페이지 수, 크기)를 확인합니다.
3. 유효성 검사: 시스템이 자동으로 PDF 파일의 유효성을 검사합니다.

지원되는 파일:

• ✅ PDF 형식 파일
• ✅ 최대 50MB 크기
• ✅ 모든 페이지 수

지원되지 않는 파일:

• ❌ 암호로 보호된 PDF
• ❌ 손상된 PDF 파일
• ❌ 이미지 파일 (JPG, PNG 등)

2. 분석 설정

페이지 선택

• 첫 번째 페이지: 첫 페이지만 분석 (빠름, 비용 절약)
• 모든 페이지: 전체 페이지 분석 (상세함, 시간 소요)

분석 모드

• 기본 분석: 문서 유형과 기본 정보 분석
• 상세 분석: 도면, 도표, 텍스트 등 상세 분석
• 사용자 정의: 원하는 분석 내용을 직접 입력

3. 분석 실행

1. 분석 시작: “분석 시작” 버튼을 클릭합니다.
2. 진행 상황 확인: 진행률 바와 상태 메시지를 확인합니다.
3. 결과 확인: 분석 완료 후 결과를 검토합니다.

4. 결과 저장

분석 완료 후 두 가지 형식으로 저장할 수 있습니다:

• 텍스트 저장: 읽기 쉬운 텍스트 형식
• JSON 저장: 구조화된 데이터 형식

고급 기능

사용자 정의 분석

분석 모드에서 “사용자 정의“를 선택하면 원하는 분석 내용을 직접 지정할 수 있습니다.

예시 프롬프트:

이 도면에서 다음 정보를 추출해주세요:
1. 도면 제목과 도면 번호
2. 주요 치수 정보
3. 사용된 재료 정보
4. 특별한 주의사항

대용량 PDF 처리

큰 PDF 파일을 처리할 때 팁:

1. 첫 페이지만 분석: 전체 분석 전에 테스트
2. 인터넷 연결 확인: 안정적인 연결 필요
3. 충분한 시간 확보: 페이지당 1-2분 소요

배치 처리

여러 PDF를 순차적으로 처리하는 방법:

1. 첫 번째 PDF 분석 완료
2. 결과 저장
3. 다음 PDF 업로드
4. 반복

문제 해결

일반적인 오류들

1. API 키 오류

오류: Gemini API 키가 설정되지 않았습니다.

해결책:

• .env 파일의 GEMINI_API_KEY 확인
• API 키가 올바른지 Google AI Studio에서 확인

2. PDF 파일 오류

오류: 유효하지 않은 PDF 파일입니다.

해결책:

• 다른 PDF 뷰어에서 파일 열어보기
• 파일 손상 여부 확인
• 파일 크기 제한 확인 (50MB 이하)

3. 네트워크 오류

오류: 분석 중 오류가 발생했습니다.

해결책:

• 인터넷 연결 상태 확인
• 방화벽 설정 확인
• 잠시 후 다시 시도

4. 메모리 부족

오류: 메모리가 부족합니다.

해결책:

• 다른 프로그램 종료
• 첫 번째 페이지만 분석
• 시스템 재시작

로그 확인

문제 발생 시 콘솔 출력을 확인하세요:

python main.py > app.log 2>&1

팁과 요령

1. 효율적인 분석

빠른 분석을 위해:

• 첫 번째 페이지만 선택
• 기본 분석 모드 사용
• 작은 크기의 PDF 사용

정확한 분석을 위해:

• 모든 페이지 선택
• 상세 분석 모드 사용
• 구체적인 사용자 정의 프롬프트 작성

2. 프롬프트 작성 요령

좋은 프롬프트 예시:

이 건축 도면을 분석하여 다음을 알려주세요:
- 건물 유형과 규모
- 주요 치수 (길이, 폭, 높이)
- 방의 개수와 용도
- 특별한 설계 요소

피해야 할 프롬프트:

분석해줘  (너무 일반적)
모든 것을 알려줘  (너무 광범위)

3. 결과 활용

텍스트 결과:

• 보고서 작성에 적합
• 직접 복사/붙여넣기 가능

JSON 결과:

• 다른 시스템과 연동
• 추가 데이터 처리 가능

4. 성능 최적화

시스템 성능 향상:

• 충분한 RAM 확보 (8GB 이상 권장)
• SSD 사용 시 더 빠른 처리
• 안정적인 인터넷 연결

비용 최적화:

• 필요한 페이지만 분석
• 기본 분석 모드 우선 사용
• 중복 분석 방지

자주 묻는 질문 (FAQ)

Q: 분석 시간이 얼마나 걸리나요?

A: 페이지당 1-2분 정도 소요됩니다. 네트워크 상태와 이미지 복잡도에 따라 달라집니다.

Q: 어떤 종류의 도면을 분석할 수 있나요?

A: 건축 도면, 기계 도면, 전기 회로도, 지도, 차트 등 모든 종류의 이미지가 포함된 PDF를 분석할 수 있습니다.

Q: 분석 결과의 정확도는 어느 정도인가요?

A: Google Gemini AI의 최신 기술을 사용하여 높은 정확도를 제공하지만, 복잡한 도면이나 불분명한 이미지의 경우 제한이 있을 수 있습니다.

Q: 개인정보나 민감한 문서도 안전한가요?

A: 업로드된 파일은 로컬에서만 처리되며, Google API로는 이미지 데이터만 전송됩니다. 원본 파일은 로컬에 보관됩니다.

Q: 오프라인에서도 사용할 수 있나요?

A: 아니요. Gemini API 호출을 위해 인터넷 연결이 필요합니다.

---

추가 질문이나 문제가 있으시면 GitHub Issues에서 문의해 주세요.