싱커의 익스코드

[스나이퍼팩토리] 한컴AI 2기 - 성과발표회 회고록

싱커 — Thu, 18 Dec 2025 13:06:54 +0900

문서를 이해하는 시스템을 만들며

이번 성과발표회는 단순히 결과물을 보여주는 자리가 아니라, 그동안 내가 어떤 문제를 고민했고, 어떤 방식으로 해결해 왔는지를 스스로 정리하는 과정이었다. 프로젝트를 시작할 때와 지금을 비교해 보면, 생각보다 많이 달라져 있었다.

(1) 이번 프로젝트/성과발표회를 통해 배우고 느낀 점

가장 크게 깨달은 점

가장 크게 느낀 점은 기술을 구현하는 것과, 기술을 설명하는 것은 완전히 다른 능력이라는 것이다. 기능 자체는 어느 정도 구현되어 있었지만, 발표를 준비하면서

왜 이 구조를 선택했는지
기존 방식과 무엇이 다른지
이게 실제로 어떤 가치를 주는지

를 설명하려다 보니, 내가 만든 시스템을 내 언어로 다시 이해해야만 했다.

발표 준비·협업 과정에서 느낀 변화

초반에는 일단 되는 걸 만들자에 가까웠다면, 발표를 준비하면서부터는 이게 왜 필요한가, 왜 이렇게 설계했는가를 항상 같이 생각하게 됐다. 특히

이 슬라이드는 왜 필요한지
이 설명은 너무 기술적인지
이 부분은 시연으로 보여주는 게 맞는지

를 계속 고민해가며, 기술 중심 사고에서 사용자·청중 중심 사고로 전환되는 경험을 했다.

이번 과정을 통해 이전의 나와 달라진 점

이전의 나는

“이 정도면 설명 없이도 알겠지”

라고 생각하는 편이었다면, 지금은

“설명할 수 없다면, 아직 정리가 안 된 상태다”

라고 생각하게 됐다.

(2) 내가 맡은 역할과 성과

맡은 역할

백엔드 (Fast API 및 MySQL) 전반 설계 및 구현
인프라와 문서 처리 파이프라인(RAG) 통합
비동기 처리 구조(Celery 기반)
발표 및 시연

구현한 기능 및 기여

서비스 기획
서비스를 위한 각종 API
임베딩 → 검색 → 리랭커 → LLM 응답으로 이어지는 RAG 파이프라인 통합
API 서버와 Worker를 분리한 Docker 기반 비동기 구조
ACL 기반 문서 접근 제어 흐름 설계

해결한 문제 또는 책임졌던 과제

가장 신경 썼던 부분은

문서 승인 → 처리 → 완료로 이어지는 상태 관리
시연 중 실패 가능성을 고려한 영상/흐름 설계

였다. 발표 당일 안정적으로 돌아가야 한다는 관점에서, 기술뿐 아니라 운영 시나리오까지 함께 책임졌던 경험이었다.

(3) 아쉬운 점 및 개선하고 싶은 부분

기술적으로 아쉬웠던 점

관리자 자동 업로드 파이프라인이 워커로 완전히 분리되지 못한 점
표 데이터를 HTML로 리턴하는 OWPML 기능을 백엔드에 온전히 통합하지 못한 점.

핵심 기능은 구현했지만, 사용자 경험 측면에서 한 단계 더 다듬지 못한 부분이 아쉬움으로 남았다.

발표에서 충분히 전달하지 못한 부분

기술적으로 준비했던 내용이 많았던 만큼,

모델 비교 및 선정 이유
트러블 슈팅
성능평가

등은 시간 관계상 생략해야 했다. 발표 분량 컨트롤은 괜찮았지만, 시연을 잘 못한 부분이 큰 아쉬움이었다.

(4) 정규 교육 과정 중 나에게 도움이 되었던 파트

정규 교육 과정 중 가장 실질적으로 도움이 되었던 파트는 AI 교육 과정이었다.

특히 임베딩과 벡터 검색을 단순히 “모델을 호출해 결과를 받는 과정”이 아니라, 데이터를 어떤 단위로 표현하고, 그 표현을 어떤 기준으로 검색하고 해석할 것인가의 문제로 다룬 점이 인상 깊었다. 이 관점 덕분에 Vector DB를 단순한 저장소로 사용하는 대신,

하나의 벡터가 무엇을 대표하는지
검색 결과가 왜 이 순서로 나오는지를
설계 단계에서부터 설명 가능하도록 구조를 잡고자 했다.

이번 프로젝트에서는 문서 전체나 임의 길이의 텍스트 조각이 아니라, 장·조·항·호 단위의 의미 블록을 하나의 벡터 단위로 정의했고, 이를 통해 벡터 간 거리가 단순 문장 유사도가 아니라 같은 규정 맥락 안에서의 의미적 근접성을 반영하도록 설계했다.

또한 검색 과정 역시 단일 점수에 의존하지 않고, ACL 및 메타데이터 기반 구조 필터링으로 검색 대상 문서를 먼저 제한한 뒤,
벡터 검색으로 후보를 수집하고 구조 정보와 함께 리랭킹하는 단계적 흐름으로 구성했다.

이렇게 함으로써 “왜 어떤 문서는 검색되지 않는지”, “왜 이 조항이 다른 결과보다 위에 노출되는지”를 검색 파이프라인 전체 관점에서 설명할 수 있게 되었다.

반면, 이번 프로젝트에서 일부 요구되었던 클라우드 인프라 관련 작업은 프로젝트의 핵심 목표와는 다소 거리가 있었고,
사실상 해야 해서 한 작업에 가까웠다. 그 과정에서 시간과 에너지가 분산되면서 문서 처리 엔진이나 검색 품질처럼 내가 더 집중하고 싶었던 영역의 완성도를 충분히 끌어올리지 못한 점은 아쉬움으로 남는다.

이번 경험을 통해 모든 기술을 억지로 끼워 넣기보다는, 프로젝트의 성격에 맞는 기술을 선택하고 집중하는 것이 결과물의 완성도에 훨씬 중요하다는 점을 분명히 느끼게 되었다.

(5) 향후 목표 및 포트폴리오 개선 방향

강화하고 싶은 기술

문서 기반 RAG 고도화
멀티모달(표·이미지) 활용

포트폴리오 개선 방향

이번 프로젝트를 단순 결과물이 아니라 설계 의도가 드러나는 포트폴리오로 정리
코드뿐 아니라 왜 이렇게 만들었는지를 설명할 수 있는 문서 보강

취업 준비에서의 다음 단계

“이 기술을 쓸 줄 안다”가 아니라 “이 상황에서 이 구조를 선택했다”를 말할 수 있는 개발자가 되는 것
면접에서 이 프로젝트 하나로도 충분히 대화가 이어질 수 있도록 준비하는 것이 목표다.

(6) 팀원들과의 협업에서 느낀 점

이번 팀 프로젝트는 항상 이상적인 협업만 있었던 경험은 아니었다. 모든 팀원이 처음부터 끝까지 같은 온도로 몰입했다고 말하기는 어렵고, 중간중간 역할 분담이나 책임감의 차이로 부담이 한쪽으로 쏠리는 순간도 있었다.

그럼에도 불구하고 이 경험이 의미 있었던 이유는, 그 상황 속에서 “어디까지 내가 책임져야 하는지”를 스스로 정리하게 되었기 때문이다.

누군가 대신 해주길 기다리기보다는,

이건 지금 내가 정리하지 않으면 안 되는 부분인지
이건 굳이 끌고 갈 필요가 없는 영역인지

를 구분하면서 기술적인 판단뿐 아니라 협업에 대한 기준도 함께 세울 수 있었다.

또한 팀 내에서 의견이 다를 때 조용히 넘기기보다는 최소한의 근거를 가지고 설명하려 노력했던 경험은, 이후 어떤 협업 환경에서도 도움이 될 것이라 생각한다.

이번 프로젝트를 통해 “모든 팀원이 항상 같은 방향을 보지는 않는다”는 현실을 인정하게 되었고, 그 안에서 내가 통제할 수 있는 부분에 집중하는 태도가 결과적으로 나 자신을 지키는 방법이라는 것도 배우게 되었다.

이번 성과발표회는 “잘 끝냈다”기보다는 다음 단계로 가기 위한 기준을 하나 세웠다는 느낌에 가깝다.

이 경험을 발판 삼아, 앞으로는 더 명확한 문제의식과 설명 가능한 설계를 하는 개발자가 되고 싶다.

[스나이퍼팩토리] 한컴AI 2기 - BACKEND 통합 테스트 및 오류 수정 리포트

싱커 — Fri, 12 Dec 2025 23:35:41 +0900

제출 목적

전체 Backend API에 대한 통합 테스트 수행 결과 정리
테스트 과정에서 발견된 오류 및 수정 내역 기록
Docker 기반 배포 환경에서 재현 가능한 실행 상태 검증

1. 테스트 개요

본 테스트는 5차 과제 요구사항에 따라
Swagger Docs 기반 API 테스트 및 실제 Docker 배포 환경에서 수행하였다.

테스트 범위

문서 업로드 → 파싱/청킹 → 임베딩 → Vector Store 저장 → 검색 → RAG 응답
비동기 작업(Celery) 연동 여부
스트리밍 응답 API 동작 여부

테스트 환경

API Server: FastAPI (Docker)
Worker: Celery (Docker)
DB: MySQL
Vector Store: ChromaDB (Persistent)
배포 방식: docker-compose

2. 엔드투엔드 통합 테스트 시나리오

2.1 문서 업로드 및 비동기 처리 테스트

관련 API

POST /documents/upload
POST /requests/{id}/approve

테스트 항목

파일 업로드 시 DB 저장 여부
승인 시 Celery Worker 작업 실행 여부
작업 완료 후 문서 상태 변경 여부

요청 승인과 완료

결과

업로드 요청 정상 처리
승인 후 비동기 작업 큐 정상 전달
파싱/임베딩 완료 후 문서 상태 정상 갱신

2.2 Vector Search API 테스트

관련 API

POST /api/v1/vector-search

테스트 항목

top_k 파라미터 동작 여부
문서 기반 검색 결과 반환 여부
검색 결과 정렬 및 개수 확인

결과

top_k 값에 따라 결과 개수 정상 반환
문서 임베딩 완료 이후 검색 정상 동작

rag search 결과

2.3 RAG 질의응답 API 테스트

관련 API

POST /api/v1/chat
POST /api/v1/chat/stream

테스트 항목

검색 결과 기반 컨텍스트 생성 여부
LLM 응답 생성 정상 여부
스트리밍 응답 종료 이벤트 정상 수신 여부

결과

검색 결과를 기반으로 한 답변 정상 생성
스트리밍 응답에서 end 이벤트 정상 수신

수정 내역

스트리밍 응답 처리 방식 불일치로 인한 응답 누락 문제 발생
→ 스트리밍 전용 처리 로직 분리하여 안정화

3. 통합 테스트 중 주요 오류 및 수정 내역

3.1 저장소 및 배포 환경 관련 오류

항목내용

오류	ChromaDB deprecated 오류
원인	구버전 Client API 사용
조치	0.4.x 기준 Client 방식으로 수정
결과	API 서버 정상 기동

항목내용

오류	API / Worker vector store 경로 불일치
원인	Docker volume 설정 불일치
조치	global persist directory 고정
결과	검색 결과 정상 반환

3.2 실행 환경 및 처리 안정성 오류

항목내용

오류	API / Worker GPU 자원 충돌
원인	모든 컨테이너에 GPU 할당
조치	API 컨테이너만 GPU 사용
결과	GPU 인식 문제 해결

항목내용

오류	병렬 요청 시 DB commit 충돌
원인	전역 싱글턴 DB 세션
조치	요청 단위 DB 세션 분리
결과	트랜잭션 안정성 확보

4. 테스트 결과 로그 (요약)

Swagger Docs 기반 전체 API 테스트 완료
Docker 환경에서 API / Worker 재시작 후에도 동일 결과 확인
문서 업로드 → 검색 → 응답 전 구간 정상 동작 확인

5. 결론

본 과제에서는 전체 API 기능 구현 여부뿐만 아니라, 실제 배포 환경에서 발생할 수 있는 오류를 통합 테스트를 통해 발견하고 수정하였다. 이를 통해 최종 발표 시연이 가능한 수준의 안정적인 Backend 파이프라인을 구축하였다.

본 후기는 [한글과컴퓨터x한국생산성본부x스나이퍼팩토리] 한컴 AI 아카데미 2기 (B-log) 리뷰로 작성 되었습니다.

[스나이퍼팩토리] 한컴AI 2기 - Vercel - FastAPI Mixed Content 트러블 슈팅 (무료 도메인, Nginx https, 서트봇)

싱커 — Thu, 4 Dec 2025 10:09:26 +0900

이번 글은 내가 진행했던 RAG 프로젝트 환경 세팅 중,
무료 도메인 확보 → 서버 연결 → HTTPS 적용 → Nginx 리팩토링 전 과정을 정리한 기록이다.

AWS EC2에서 FastAPI 백엔드를 운영하고 있었는데,
Vercel 프론트엔드에서 API 요청을 보내려면 반드시 HTTPS가 필요했다.
하지만 초기 상태는 HTTP IP 기반 서버뿐이라
브라우저에서 "Mixed Content" 에러가 터졌다.

그래서 결국 무료 도메인 확보 → Nginx HTTPS 구성 → Certbot 발급을 직접 해보기로 했다.

1. 무료 도메인 확보 — alain.r-e.kr

프로덕션용이 아니라 연구 프로젝트였기 때문에, 우선 HTTPS를 빠르게 적용하는 것이 목표였다.

무료 도메인을 제공하는 내도메인.한국 사이트에서 alain.r-e.kr을 선택했다.

내도메인.한국의 도메인 설정

DNS A레코드에 EC2 퍼블릭 IP(v4)만 등록하면 끝. DNS 전파는 보통 1~5분 내로 완료되었다.

2. 기존 문제 상황 — Certbot이 실패했다

처음 Certbot을 실행했을 때 다음과 같은 오류가 발생했다:

Error while running nginx -t:
cannot load certificate "/etc/letsencrypt/live/alain.r-e.kr/fullchain.pem"

원인은 매우 명확했다.

Nginx 설정에 이미 HTTPS server block이 존재하고 있었고,
아직 발급되지 않은 인증서를 로딩하려다가 nginx test가 실패한 것이다.

그래서 전략을 바꿨다:

1) 발급 전 → HTTP-only 구성 → Certbot 성공
2) 발급 후 → HTTPS 블록 다시 적용 → Nginx Reload

3. Nginx 설정 — HTTP 전용 버전으로 리팩토링

Certbot이 인증서를 발급하려면, Nginx 설정에 HTTPS 블록이 존재하면 안 된다.
그래서 HTTPS 관련 내용을 모두 제거한 “HTTP-only 구성”으로 바꿨다.

server {
  listen 80;
  server_name alain.r-e.kr;

  location /.well-known/acme-challenge/ {
    root /var/www/certbot;
  }

  location / {
    proxy_pass http://localhost:8000;
  }
}

4. Certbot 설치 & 인증서 발급

설치 명령어는 다음과 같다:

sudo apt install certbot python3-certbot-nginx -y

인증서 발급:

sudo certbot --nginx -d alain.r-e.kr --agree-tos --email my@email.com

아래 문구가 뜨면 성공이다:

Congratulations! Your certificate has been successfully issued!

5. HTTPS 서버블록 추가 — 본격 안전 API 구축

인증서 발급 후 HTTPS server block을 다시 추가하고, nginx -t → reload 를 수행했다.

sudo nginx -t
sudo systemctl reload nginx

이제 아래 URL에서 Swagger가 HTTPS로 열린다.

https://alain.r-e.kr/docs

swagger docs

6. Mixed Content 문제 해결

HTTPS API가 준비되면서, Vercel에서 발생하던 Mixed Content 오류가 모두 사라졌다.

proxy_set_header X-Forwarded-Proto https;
→ Mixed Content 방지의 핵심 설정

7. 마무리하며 — 배운 점

이번 도메인/HTTPS 구축 과정에서 배운 핵심은 다음과 같다.

① Certbot은 “HTTPS 블록이 없는 상태”에서 실행해야 한다.
→ 인증서 파일이 없는데 HTTPS server block이 미리 있으면 nginx test가 죽는다.

② 도메인은 HTTPS 구축의 필수 요소다.
→ IP만으로는 무료/정식 인증서 발급 불가능.

③ Nginx는 HTTP → HTTPS 단계적 관리가 중요하다.
→ 특히 SSE, CORS가 필요할 때는 더 세심한 설정 필요.

정리

1	무료 도메인 선택 (alain.r-e.kr)
2	DNS A레코드 → EC2 IP 매핑
3	Nginx HTTP-only 구성
4	Certbot으로 SSL 발급
5	HTTPS 서버블록 최종 적용

마치며

이 기록이, 나처럼 “무료 도메인 + EC2 + FastAPI + Nginx + Certbot” 조합으로 HTTPS를 적용하려는 사람에게 도움이 되길 바란다.

Cloudflare SSL Mode는 본 글에서 다루지 않았지만 필요하다면 후속 포스팅으로 정리해볼 수도 있다.

본 후기는 [한글과컴퓨터x한국생산성본부x스나이퍼팩토리] 한컴 AI 아카데미 2기 (B-log) 리뷰로 작성 되었습니다.

[스나이퍼팩토리] 한컴AI 2기 - 알랭 서비스 통합

싱커 — Fri, 28 Nov 2025 18:00:04 +0900

아키텍처 흐름도

2차멘토링과 중간발표에서 사용자 흐름에 따른 데이터 이동에 대한 질문을 받았었다. 말로 설명했지만 충분한 전달이 이뤄지지 않았는데, 결국 그림이 필요했다. gemini3.0이 공개되고, 나노 바나나 프로가 사용가능해진 타이밍이 실로 적절했다. 우리의 서비스에 대한 설명을 기반으로 이미지를 만들어달라고 했더니, 꽤 그럴싸하게 만들어줬다. 해당 이미지에서 몇가지 수정 또한 프롬프팅으로 가능했다.

비동기 문서 업로드 파이프라인과 질의 응답 파이프라인은 서비스의 중요한 축이고, 전체 흐름도로부터 별도로 보여줄 필요가 있었다.

문서 업로드 흐름도

사용자 → 프론트엔드에 문서 업로드 → 백엔드 FastAPI로 전달 → Celery 워커의 처리(파싱-청킹-임베딩) → DB 의 흐름이 잘 표현되었다.

사용자 질의응답 시나리오

사용자 → 프론트엔드에 질문 → 백엔드 FastAPI로 전달 → 사전필터링과 임베딩 → 벡터DB에서의 검색 → LLM의 응답 까지의 흐름이 역시 잘 표현되었다.

환경 분리(Docker Profile)

이 모든 과정이 하나의 파이프라인으로 자동화되어 있고, Docker 환경에서 각 서비스가 독립적으로 동작하면서도 유기적으로 연결되어 있다. 각 도커 프로필의 역할은 다음과 같다.

1. Redis (Message Broker)

역할: 비동기 작업 큐(Task Queue)를 관리하는 메시지 브로커.
학습: API 서버와 워커 사이의 결합도를 낮추는 핵심 미들웨어다. API가 요청받은 무거운 작업을 Redis 큐에 넣어두면(Push), 워커가 상황에 맞춰 가져가서(Pull) 처리한다. 덕분에 트래픽이 몰려도 요청이 유실되지 않고 큐에 안전하게 쌓인다.

2. FastAPI (API Server)

스펙: FastAPI, Port 8000
역할: 사용자 요청 수신, 파일 저장, Task 발행, 상태 조회.
학습: 무거운 연산(임베딩 등)은 직접 하지 않고 '접수창구' 역할에만 집중하도록 설계했다. 덕분에 동시 접속자가 많아져도 메인 스레드가 차단되지 않고 즉각적인 응답(Non-blocking)을 줄 수 있다.

3. Celery Worker (Task Consumer)

역할: 실제 문서 파싱, 청킹, 임베딩(GPU 연산) 수행.
학습: Redis에서 대기 중인 작업을 가져와 처리하는 일꾼이다. 가장 중요한 점은 스케일 아웃(Scale-out)이 용이하다는 것이다. 지금은 컨테이너가 하나지만, 향후 문서 처리량이 급증하면 이 워커 컨테이너의 레플리카만 늘려서 병렬 처리 능력을 손쉽게 확장할 수 있다.

4. Celery Flower (Monitoring)

스펙: Port 5555
역할: 비동기 작업 상태 모니터링 및 대시보드.
학습: 눈에 보이지 않는 백그라운드 작업들의 상태(처리 중, 성공, 실패)를 시각화(Observability) 해준다. 비동기 로직 개발 시 디버깅 툴로 매우 유용하다.

환경 분리의 장점

이렇게 분리하면서 얻은 장점들은 위와 같다.

문서 파싱 (OWPML)

문서 파싱 파이프라인

파싱되는 문서는 다섯가지의 단계를 거친다. 먼저 확장자를 확인하고, 형식에 맞는 파싱을 한다. 이후 데이터 정규화를 거쳐 문서의 구조정보, 메타데이터 등을 추출한다. 이 결과는 디렉토리에 .txt, .json 형태로 저장된다.

HWP 파일

레거시 바이너리 파일 포맷이다. JPype 브릿지를 통해 hwplib을 활용하여 파싱한다. JVM 환경에서 텍스트를 추출하며, 텍스트 추출은 가능하나 표와 이미지는 제한적이다.

HWPX 파일

HWPX는 ZIP 파일이다. 압축을 풀면 XML 파일들이 나오는데, 이 파일들을 파싱하고, OWPML 스키마를 따라 구조화 시킨다. (표준 라이브러리인 zipfile과 ElementTree를 사용해서 이 XML을 파싱한다.)
HWPX에서는 텍스트뿐만 아니라 표와 이미지도 추출할 수 있다. 표는 행과 열 구조를 그대로 유지한 채 JSON으로 변환하고, 이미지는 원본 포맷 그대로 파일로 저장한다.

파싱 전략

정규식 기반 계층 구조 분석

공공기관의 문서 데이터를 주로 사용하기에, 이러한 공문서의 작성규칙에 맞춘 파싱 전략을 세웠다.

근거 추적 메커니즘

청크 메타데이터

Hierarchy Path 자동 태깅
작동 원리: 단순히 문서를 500자, 1000자 단위로 뚝뚝 자르기만 하면, 그 조각(Chunk)이 원래 문서의 어느 소속인지 문맥을 잃어버리기 쉽다. 이를 해결하기 위해 청킹 시점에 상위 헤더를 역추적하는 로직을 구현했다. _find_structure_context 메서드는 현재 청크의 위치에서 가장 가까운 상위 '장(Chapter)'과 '조(Article)'를 찾아내어, 메타데이터에 hierarchy_path("제3장 급여의 지급 > 제15조")를 자동으로 각인시킨다.

RAG 서비스의 핵심은 답변의 신뢰도다. 사용자가 "급여는 언제 나오나요?"라고 물었을 때, AI가 내용을 뭉뚱그려 답하는 것과 "공무원연금규정 제3장 제15조에 따르면..."이라며 정확한 조항을 인용하는 것은 천지 차이다. 메타데이터를 꼼꼼하게 관리한 덕분에, 이제 우리 서비스는 LLM이 답변할 때 정확한 근거(Source)를 함께 제시할 수 있게 되었다.

본 후기는 [한글과컴퓨터x한국생산성본부x스나이퍼팩토리] 한컴 AI 아카데미 2기 (B-log) 리뷰로 작성 되었습니다.

[스나이퍼팩토리] 한컴AI 2기 - 알랭 프로젝트 중간발표 회고

싱커 — Fri, 21 Nov 2025 17:46:43 +0900

중간발표가 끝났다. 결과만 놓고 보면 발표는 조금 흔들렸지만,
발표 과정 자체가 이번 프로젝트에서 가장 많은 배움을 남긴 순간이었다.
이 글에서는 중간발표 준비 과정에서 배운 점과 프로젝트 자체의 기술적/협업적 인사이트를 정리해보고자 한다.

백엔드 API 스웨거 문서

1. 중간발표가 남긴 것들

발표를 준비하면서 처음 느낀 건,
우리가 만든 기능들이 많아질수록 설명해야 할 맥락도 비례해 폭발적으로 많아진다는 사실이었다.

HWP/HWPX 파싱, OWPML, 청킹, 임베딩, RAG, 권한 시스템, 문서 Diff, 프론트 구조, 크롤러…
하고 있는 건 분명 많았지만, 그것들을 한 문장으로 압축해서 말하는 능력은 부족했다.

이번 발표는 그 공백을 정확히 드러냈다.

“핵심 메시지가 너무 많다.”
“한 번에 전달할 스토리가 정리되지 않았다.”
“기술을 보여주려다 보니 흐름이 길어졌다.”

하지만 덕분에 내가 무엇을 더 배워야 하는지 명확하게 알 수 있었다.

2. 발표 준비 과정에서 배운 것

1) 기술은 ‘순서’로 설명된다

우리는 서비스를 만들 때는 흐름을 알고 있지만,
발표에서는 청중이 그 흐름을 처음부터 다시 따라갈 수 있게 순서를 재정렬해야 한다.

이번 발표 준비에서 다음과 같은 구조를 확실히 익혔다.

문제 정의
왜 기존 방식으로는 안 되는가
우리가 선택한 기술적 접근
실제 구현 결과
미래 계획

이 단순한 구조가 발표의 생명줄이라는 걸 느꼈다.

2) 핵심 메시지를 줄여라

처음에는 100장 가까운 자료를 만들었고,
그걸 40여장까지 줄여서 리허설에서 해볼 때만 해도 괜찮을 줄 알았다.

급격한 변화를 수용하지 말았어야했는데, 결국 내 파트는 날림 뒷파트는 타임오버가 되어버렸다.

3) 대상에 맞춘 설명이 필요하다

중간발표의 타깃은
공공기관·기업 실무자 / 팀장·중간관리자 / 어드민이었다.

그러나 우리를 심사하는 멘토들은 대체로 개발자들이었다.

원하는 형태의 그림을 보여주지 못해, 신뢰를 얻지 못했다.

3. 프로젝트 자체에서 얻은 인사이트

✔ 1) HWP/HWPX는 한국형 문서 RAG의 험지다

HWPX는 XML 기반이지만 구조가 제각각이고,
표, 각주, 문단 스타일, heading 처리 등 신경 써야 할 부분이 많다.

이걸 OWPML 기반으로 처리하며 느낀 건,

“한국어 문서에 특화된 RAG는 글로벌 기술을 그대로 가져다 쓰는 것으로는 충분하지 않다.”

이를 위해 청킹 전략, 텍스트 정리, 메타데이터 스키마 설계를 하나씩 조정해가며
우리만의 파이프라인을 만들 수 있었다.

✔ 2) ChromaDB 선택은 단순한 비교 이상의 결정이었다

FAISS와 Chroma를 비교했을 때
FAISS는 확실히 강력하지만,
우리가 필요한 것은 메타데이터 중심 검색 + 개발 생산성이었다.

구조화된 검색
프로젝트/부서 샤딩
FastAPI와의 통합 편의성

이 모든 점에서 Chroma는 우리의 “프로젝트 기간 내 완성 가능성”을 높여줬다.

✔ 3) RBAC은 단순한 UI 아니라 ‘업무 로직’이다

실무자-팀장-어드민의 요구사항을 기술적으로 녹여내면서
권한 구조가 단순한 UI 토글이 아님을 배웠다.

실제로 문서 변경 요청 플로우를 넣으면서
실제 조직의 문서 흐름과 거의 흡사한 비즈니스 로직을 구현하게 됐다.

4. 발표는 완벽하지 않았지만, 성장의 순간이었다

발표는 솔직히 잘 되진 않았다.
하지만 발표를 망친 만큼 프로젝트는 더 잘 보이기 시작했다.

무엇을 더 줄여야 하는지
왜 설명이 어려웠는지
어떤 기능이 진짜 가치인지
어떤 기술이 프로젝트의 중심인지

개발의 병목이 되지 않기 위해, 더 많은 백엔드 API를 만들고, 앞으로의 통합 개선을 더욱 도모해야겠다.

본 후기는 [한글과컴퓨터x한국생산성본부x스나이퍼팩토리] 한컴 AI 아카데미 2기 (B-log) 리뷰로 작성 되었습니다.

[스나이퍼팩토리] 한컴AI 2기 - Docker CE 및 Nginx를 활용한 GPU 서버 구축 과정

싱커 — Wed, 12 Nov 2025 17:51:28 +0900

AWS EC2에서 NVIDIA GPU를 사용하는 FastAPI 백엔드 서버를 Docker Compose로 구동하고, Nginx 리버스 프록시를 통해 외부 접속 환경을 구축했다. 최종적으로 안정적인 배포 환경을 확보했지만, 그 과정은 결코 순탄하지만은 않았다.

우선 프로젝트 경로에 back 레포지토리를 클론했다.

ubuntu@hancom-team2:~/project$ git clone https://github.com/Newrun-way/back.git
'back'에 복제합니다...
remote: Enumerating objects: 175, done.
remote: Counting objects: 100% (175/175), done.
remote: Compressing objects: 100% (116/116), done.
remote: Total 175 (delta 68), reused 148 (delta 41), pack-reused 0 (from 0)
오브젝트를 받는 중: 100% (175/175), 918.49 KiB | 61.23 MiB/s, 완료.
델타를 알아내는 중: 100% (68/68), 완료.
ubuntu@hancom-team2:~/project$ ls
OWPML1  back

도커파일을 포함한 레포지토리의 내용이 잘 복제되었다. 속도가 무지막지하게 빨랐다. 그램 노트북과는 비교를 불허했다.

바로 도커 빌드를 하려고 하니,

ubuntu@hancom-team2:~/project/back$ sudo docker compose up -d --build
sudo: docker: 명령이 없습니다
ubuntu@hancom-team2:~/project/back$ docker compose up -d --build
명령어 'docker' 을(를) 찾을 수 없습니다. 그러나 다음을 통해 설치할 수 있습니다:
sudo snap install docker         # version 28.4.0, or
sudo snap install docker         # version 28.1.1+1
sudo apt  install podman-docker  # version 3.4.4+ds1-1ubuntu1.22.04.3
sudo apt  install docker.io      # version 28.2.2-0ubuntu1~22.04.1
'snap info <snapname>'에서 추가 버전을 확인하십시오.

도커가 설치되지 않은 것을 확인할 수 있었다.

sudo 명령어로 설치를 할 수 있는지 권한을 확인해보려면, sudo whami를 사용해서 root가 출력되는지 확인하면 된다.

ubuntu@hancom-team2:~/project/back$ sudo whoami
root
ubuntu@hancom-team2:~/project/back$ sudo apt update
기존:1 http://us-east-1.ec2.archive.ubuntu.com/ubuntu jammy InRelease
받기:2 http://us-east-1.ec2.archive.ubuntu.com/ubuntu jammy-updates InRelease [128 kB]
받기:3 http://us-east-1.ec2.archive.ubuntu.com/ubuntu jammy-backports InRelease [127 kB]
받기:4 http://security.ubuntu.com/ubuntu jammy-security InRelease [129 kB]
받기:5 http://us-east-1.ec2.archive.ubuntu.com/ubuntu jammy-updates/main amd64 Packages [3,076 kB]
받기:6 http://us-east-1.ec2.archive.ubuntu.com/ubuntu jammy-updates/main Translation-en [475 kB]
받기:7 http://us-east-1.ec2.archive.ubuntu.com/ubuntu jammy-updates/main amd64 c-n-f Metadata [19.0 kB]
받기:8 http://us-east-1.ec2.archive.ubuntu.com/ubuntu jammy-updates/restricted amd64 Packages [4,853 kB]
받기:9 http://us-east-1.ec2.archive.ubuntu.com/ubuntu jammy-updates/restricted Translation-en [903 kB]
받기:10 http://us-east-1.ec2.archive.ubuntu.com/ubuntu jammy-updates/universe amd64 Packages [1,242 kB]
받기:11 http://us-east-1.ec2.archive.ubuntu.com/ubuntu jammy-updates/universe Translation-en [308 kB]
받기:12 http://security.ubuntu.com/ubuntu jammy-security/main amd64 Packages [2,815 kB]
받기:13 http://security.ubuntu.com/ubuntu jammy-security/main Translation-en [408 kB]
받기:14 http://security.ubuntu.com/ubuntu jammy-security/restricted amd64 Packages [4,700 kB]
받기:15 http://security.ubuntu.com/ubuntu jammy-security/restricted Translation-en [876 kB]
받기:16 http://security.ubuntu.com/ubuntu jammy-security/universe amd64 Packages [1,009 kB]
받기:17 http://security.ubuntu.com/ubuntu jammy-security/universe Translation-en [220 kB]
내려받기 21.3 M바이트, 소요시간 2초 (9,767 k바이트/초)
패키지 목록을 읽는 중입니다... 완료
의존성 트리를 만드는 중입니다... 완료
상태 정보를 읽는 중입니다... 완료
4 패키지를 업그레이드할 수 있습니다. 확인하려면 'apt list --upgradable'를 실행하십시오.

나는 root가 출력되었고, 도커를 설치하기 위해 sudo apt update를 우선 진행했다.

이제 도커 설치를 해야하는데, 여러 옵션이 있어서 이를 gemini에게 물어봤다.

io와 community edition

보안을 고려하여 커뮤니티 에디션을 설치하려고 했으나, GPG키 등록과 같은 복잡한 절차가 지금으로서는 불필요하다고 여겨 snap파일을 설치하기로 했다.

ubuntu@hancom-team2:~/project/back$ sudo snap install docker
docker 28.4.0 from Canonical✓ installed
ubuntu@hancom-team2:~/project/back$ sudo usermod -aG docker ${USER}

도커 설치 후 sudo usermod -aG docker ${USER} 명령어를 사용해 권한을 주었고, docker compose를 실행했더니, 명령어 부재 문제가 있었다. 이 오류 대응으로 많은 시간을 소비하게되었다. (snap방식 뿐만 아니라 io쪽에서도 문제가 있었으나 생략)

1. GPU 컨테이너 구동 문제 최종 해결

1.1 초기 문제와 원인

초기에는 docker compose 실행 시 libnvidia-ml.so.1: cannot open shared object file 오류가 반복됐다.

원인: nvidia-smi로 드라이버는 설치된 것을 확인했지만, Snap Docker가 시스템의 NVIDIA 라이브러리 경로를 컨테이너에 연결하지 못하는 격리 문제가 근본 원인이었다.

1.2 해결: 공식 Docker CE로 전환

문제를 해결하기 위해 Docker 환경 자체를 표준으로 바꿨다.

Snap 제거: sudo snap remove docker로 기존 환경을 정리.
Docker CE 설치: GPG 키 등록 후 docker-ce 및 docker-compose-plugin을 설치해서 공식 Docker 환경을 구축했다.
결과: 환경 전환 후 GPU 컨테이너 구동이 성공적으로 이루어지면서 NVIDIA 연동 문제를 해결했다.

2. 포트 및 서비스 충돌 정리

GPU 연동 후에도 8000번 포트 충돌 오류가 발생했다.

원인: docker-compose.yml에서 backend-cpu 서비스에 profiles 설정이 누락(개발의 편의를 위해 주석처리 했었다!)되어, --profile gpu를 써도 CPU 컨테이너가 자동으로 시작되어 포트를 선점했기 때문이었다.
또한 삭제한 도커에 남아있는 컨테이너 이름 충돌도 있었다.

2.1 최종 실행 및 서비스 분리

포트를 점유 중이던 컨테이너를 docker stop 및 docker rm으로 제거
backend-cpu 서비스의 container_name을 owpml_backend에서 다른 이름으로 변경했다.
명령어에 backend-gpu 서비스 이름만 명시해서 실행했다.

docker compose --profile gpu up -d backend-gpu

이 명령으로 backend-gpu 컨테이너만 백그라운드에서 성공적으로 구동됐다.

3. Nginx 리버스 프록시로 외부 접속 오픈

서버에 올리는 이유는, 동료 개발자를 포함한 다른 일반 사용자도 접속이 가능하게 하기 위함이었다. AWS 보안 그룹에서 8000번 포트가 막혀 있었고, 내가 그걸 풀 권한은 없었다. Nginx 리버스 프록시를 써서 이 문제를 해결했다. nginx 서버블록은 전 직장에서 경험했어서 비교적 익숙했다.

Nginx를 설치하고, 설정 파일(/etc/nginx/sites-available/fastapi)을 만들었다.
프록시 설정: Nginx가 열려 있는 80번 포트로 들어오는 요청을 Docker 컨테이너의 내부 8000번 포트로 전달하도록 구성했다.
결과: Nginx 설정 후, 인스턴스 공인 IP를 통해 http://52.21.185.171/docs로 접속했을 때 FastAPI Swagger UI에 정상적으로 접근되는 것을 확인하며 외부 서비스 환경 구축을 마무리했다.

server {
    listen 80;
    server_name _; # 인스턴스의 공인 IP 또는 도메인 이름 (IP 사용 시: 52.21.185.171)

    location / {
        # 요청을 Docker 컨테이너의 8000번 포트로 전달
        proxy_pass http://localhost:8000;
        # Docker Compose 컨테이너 이름을 사용해도 됩니다: http://back_gpu:8000;
        
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

헬스체크를 해보니 응답이 제대로 온다.

본 후기는 [한글과컴퓨터x한국생산성본부x스나이퍼팩토리] 한컴 AI 아카데미 2기 (B-log) 리뷰로 작성 되었습니다.

[스나이퍼팩토리] 한컴AI 2기 - 알랭 RAG 로컬 도커에서의 구동기 (w FAISS 샤딩)

싱커 — Mon, 10 Nov 2025 17:28:24 +0900

샤딩 (Sharding)

FAISS의 특성상, (성능 개선을 기대할 수 없는) 사후필터링만이 가능해서, 초기의 업로드부터 권한별로 분산해서 저장하면 어떨까? 하는 아이디어로 샤딩을 시도했다. (샤딩은 DB 트래픽을 분산할 수 있는 중요한 수단이다.)

시도와 성공

경로 통일 이전의 스크린샷이라, 벡터스토어는 app/data/uploads에 들어가있고, 문서파일은 data/uploads에 들어가있다 ㅎㅎ.. 나중에 다시 app/data/uploads로 통합했다.

hwpx RAG 구현 in 도커

metadata 내에 dept_id, project_id, user_id 임의로 넣어봤다. 구조 확장엔 큰 문제가 없어보인다.

hwp 파싱 테스트

hwp를 파싱했는데, 왜인지 text_content가 하나의 통문자열 리스트로 왔다.

hwpx의 파싱, 청킹, 임베딩

hwpx파일은 hwp와 달리 파싱-청킹-임베딩의 과정이 모두 잘 이뤄졌다.

도커 환경에서의 RAG 수행

리스폰스를 받았지만, 데이터가 없었다. 검색권한쪽 컨트롤이 필요한건지, 성능이슈인지 원인을 찾지 못했다.

hwp RAG 구현 in 도커

hwp 파일은 청킹-임베딩-저장이 되지 않던 문제가 있었다. (jar, jpype, JAVA_HOME으로 고통받던 지난 주가 생각났다...)

이전 응답에서 text_content가 분할되지 않은 것에 주목했다.

hwp는 단락(para)생성이 안되던 문제가 있었는데, 이를 해결하기위해 문단 보정을 해주기로 했다. _iter_paragraph_texts라는 유틸 함수를 app/services/rag/rag_service.py에다 넣어 구현했다.

RAG 디버그

샤딩 검색이 제대로 안되어서, 디버그를 추가해보았다. 문제는 config 안에 있었다. 컨피그에 샤딩검색을 False로 두었던 것을, True로 바꾸었다. 이제 req.body에 user_id를 포함해 전달하면, 해당 폴더의 FAISS 벡터 스토어로부터 검색이 이뤄지고, LLM이 응답을 생성한다.

본 후기는 [한글과컴퓨터x한국생산성본부x스나이퍼팩토리] 한컴 AI 아카데미 2기 (B-log) 리뷰로 작성 되었습니다.

[스나이퍼팩토리] 한컴AI 2기 - OWPML 프로젝트 알랭 1주차 회고

싱커 — Sun, 9 Nov 2025 10:13:24 +0900

프로젝트 2팀 '뉴런웨이'의 1주차가 정신없이 지나갔다. 우리 팀의 목표는 OWPML 기반의 문서 Q&A 서비스인 알랭(AlAIn)을 개발하는 것. 이번 1주차의 핵심 목표는 인프라, 백엔드, 프론트엔드의 완전한 통합 개발 환경을 구축하고, 가장 핵심적인 문서 파싱 기능을 구현하는 것이었다. 돌아보니, 단순한 '환경 설정'을 넘어 프로젝트의 뼈대 전체를 세운 한 주였다.

1. INFRA: 견고한 개발 생태계 구축기

프로젝트의 성패는 팀원 모두가 동일하고 안정적인 환경에서 개발할 수 있느냐에 달려있다고 생각한다. 우리는 1주차에 이 '개발 생태계'를 구축하는 데 총력을 기울였다.

A. 협업 도구 통일 우선 파편화된 소통을 막기 위해 협업 도구를 명확히 정했다.

Notion: 모든 프로젝트 관리의 허브로 사용한다. 주차별 과제 관리, 개인별 회고록 작성, 회의록 아카이빙, 전체 일정표를 노션에서 관리한다.

Discord: 실시간 토론 및 자료 공유 채널로 활용한다. 특히 '임베딩 모델'이나 'HWPX 파싱' 같은 특정 주제에 대해 스레드를 열어 깊이 있는 논의를 진행했다.

GitHub: 백엔드와 프론트엔드의 형상 관리를 담당한다.

Figma/Canva: 프론트엔드 와이어프레임 및 발표 자료 디자인을 위해 세팅했다.

B. Docker 기반의 표준 개발 환경 이번 프로젝트에서 가장 공들인 부분이다. "로컬 Python 실행 금지"라는 원칙을 세우고, 모든 개발 환경을 Docker 기반으로 통일했다.

Backend Stack: 백엔드는 FastAPI를 기반으로 한다.
Java 연동 (JPype): OWPML 문서(HWP, HWPX) 파싱을 위해 Java 라이브러리를 사용해야 했다. 이를 위해 python:3.11-slim 베이스 이미지에 openjdk-17-jdk를 설치하고 , JPype1 패키지를 통해 Python과 Java를 연동하는 환경을 구축했다. ENV JAVA_HOME 설정에 꽤 공을 들였다.
Docker Compose: docker-compose.yml을 통해 개발 환경을 정의했다. 특히 cpu와 gpu 프로파일을 분리하여 로컬 개발 환경(CPU)과 향후 서버 배포(GPU) 환경에 모두 대응할 수 있도록 설계했다. 또한 Hugging Face 모델 캐시(hf_cache) 등을 볼륨으로 관리하여 불필요한 재다운로드를 방지했다.

C. 개발 지원을 위한 커스텀 GPT 팀원들의 개발 효율을 극대화하기 위해 'OWPML RAG 개발 어시스턴트'라는 이름의 커스텀 GPT를 구축했다. 이 GPT는 우리 프로젝트의 전체 코드베이스(Dockerfile, jpype_setup.py, rag.py 등)를 '지식'으로 학습했다. 덕분에 Dockerfile 설정이나 JPype 관련 문제 해결, FAISS와 LangChain을 사용한 RAG 파이프라인 설계 등 우리 코드에 최적화된 답변을 즉시 얻을 수 있게 되었다.

2. BACKEND: 핵심 기능의 첫걸음, 문서 파싱 API

인프라가 튼튼하게 구축되었음을 확인한 것은 백엔드 API의 성공적인 동작이었다.

Health Check: docker compose up 명령어로 서버를 실행하고, FastAPI의 자동 문서(http://localhost:8000/docs)에 접속해 API가 정상적으로 동작하는 것을 확인했다. /api/v1/health 엔드포인트는 {"status": "ok"}를 성공적으로 반환했다.
HWP/HWPX 파싱 성공: 1주차 핵심 목표였던 문서 파싱 API(api/v1/parsing/upload_and_parse)를 구현했다. Swagger UI에서 HWP 파일과 HWPX 파일을 직접 업로드하여 테스트한 결과, 두 형식의 파일 모두에서 텍스트 콘텐츠를 성공적으로 추출하여 JSON 형태로 반환하는 것을 확인했다.

3. FRONTEND: 서비스의 얼굴을 그리다

백엔드가 엔진을 만드는 동안, 프론트엔드에서는 서비스의 얼굴을 디자인했다.

Figma 와이어프레임: 'Alain'의 메인 채팅 페이지와 사이드바 구조를 Figma로 신속하게 설계했다.
Vercel 초기 배포: 놀랍게도 1주차 만에 이 기본 구조를 Vercel을 통해 실제 웹에 배포까지 완료했다. 물론 아직 기능은 없지만, 눈에 보이는 결과물이 있다는 것은 팀의 사기를 높이는 데 큰 도움이 되었다.

1주차를 마치며

첫 주였지만 인프라, 백엔드, 프론트엔드 전반에 걸쳐 예상보다 더 견고한 기반을 다졌다. 특히 Docker와 JPype라는 복잡한 기술 스택을 성공적으로 연동하고, HWP/HWPX라는 특수한 문서를 파싱하는 API까지 구현해낸 것은 큰 성과다. 이제 이 튼튼한 기반 위에 본격적으로 RAG 파이프라인을 얹을 2주차가 기대된다.

[스나이퍼팩토리] 한컴AI 2기 - OWPML 프로젝트 CLI와 백엔드 FastAPI 세팅

싱커 — Mon, 3 Nov 2025 08:47:43 +0900

처음 목표는 명확했다. 한글(HWP, HWPX) 문서를 AI가 이해하게 만들자.
그런데 막상 열어보니 구조가 너무 복잡했다.
텍스트는 있지만 의미 단위로 구분되지 않았고, 문단과 표, 각주가 한데 엉켜 있었다.

OWPML(Open Word Processor Markup Language) 필터를 활용해
한글 문서를 XML 구조로 풀 수 있다면, AI가 이해할 수 있는 데이터로 바꿀 수 있을 것 같았다.
그 순간 “이걸 파싱해서 RAG 구조에 얹으면 되겠다”는 감이 왔다.

2️⃣ extract.py — 문서를 뜯어내는 과정

HWPX 파일은 내부적으로 ZIP 형식이었다.
압축을 풀면 XML 파일들이 나오고, 그 안에 <hp:p>는 문단, <hp:tbl>은 표를 의미했다.
파이썬의 xml.etree.ElementTree로 태그를 읽고, 문단과 표를 각각 리스트로 정리했다.
이미지는 BinData 폴더에서 추출했다.

이 과정을 자동화하기 위해 extract.py를 만들었다.
파일을 넣으면 자동으로 텍스트, 표, 이미지, 구조 정보를 모두 뽑아 JSON으로 저장하도록 했다.
결과를 처음 봤을 때는 꽤 감동적이었다.

예시 데이터로 충주의료원 규정집을 파싱했는데, 문단이 1만 5천 개, 표가 400개가 넘었다.
그 방대한 데이터가 전부 구조화된 순간, “이제 이걸 AI가 읽을 수 있겠구나”라는 확신이 들었다.

3️⃣ RAG 구상 — 문서 이해의 뼈대를 세우다

문서 구조를 추출했으니, 이제는 ‘이해’를 시켜야 했다.
핵심은 RAG(Retrieval-Augmented Generation)였다.
문단 단위로 청킹하고, 임베딩 후 벡터 검색을 수행해 GPT가 근거를 포함한 답변을 생성하도록 하는 구조다.

문제는 표였다.
“이건 표입니다”라는 텍스트 형태로 들어가는데, 표 데이터와 결합해 전달할 방식이 필요하다.
문서의 형태적 구조가 답변의 품질을 결정한다는 걸 실감했다.

4️⃣ FastAPI

AI 모델을 실제 서비스처럼 다루려면 API가 필요했다.
그래서 FastAPI를 선택했다

추출함수를 모듈화하여 FastAPI에서 구동하여 API 라우트를 제공할 수 있기를 기대했다. jpype임포트에 문제가 있어서 난항을 겪었다. hwpx에는 jar파일이 필요하지 않아서, 그쪽에는 로컬에서도 문제가 없었다.

동일한 환경을 만들기 위해 도커 빌드가 필요했다.

docker build -t owpml-fastapi-backend
의 형태로 명령어를 실행할 수 있었다.

[스나이퍼팩토리] 한컴AI 2기 - OWPML 프로젝트 0주차

싱커 — Mon, 27 Oct 2025 13:24:34 +0900

OWPML필터 기반의 문서검색 서비스를 만들기로 했다.

나의 역할은 팀장, PM, 백엔드 전담이다. 요구 기술스택에 대한 이해를 바탕으로, 전반적인 통합을 내가 이끌게 될 것이다.

작성한 프로젝트 기획서는 아래와 같다.

프로젝트 기획서

1. 프로젝트 개요

1.1. 기획 목적

OWPML 기반 문서 이해 파이프라인을 구축하여, 한글 문서(HWPX)의 내용을 구조적으로 분석하고 질의응답이 가능한 AI 문서 어시스턴트 「알랭(AlAin)」을 개발한다. ‘문서 이해 및 질의응답’ 핵심 기능인 RAG 기반 검색·응답 시스템 개발을 지원하고, 문서 구조 인식, 벡터 임베딩, 프롬프트 엔지니어링을 통합한 완성형 프로토타입을 구현한다.

1.2. 기획 배경

기업·기관에서 사용하는 다수의 공문서와 보고서가 HWPX 형식으로 저장되어 있으나, 이 형식은 일반 텍스트 검색이나 LLM 학습에 바로 활용하기 어렵다. 따라서, OWPML 필터를 활용해 문서의 구조적 정보를 보존하며 텍스트를 추출하고, 이를 기반으로 문서 내 질문에 정확한 근거와 함께 답변을 제시하는 한국어 문서 특화 RAG 시스템이 필요하다. 본 프로젝트는 한글 문서 파싱–임베딩–검색–응답까지의 엔드투엔드 파이프라인을 구현하고, 사용자 입장에서는 문서를 업로드하면 내용을 이해하고 대답하는 웹 서비스로 경험할 수 있도록 프론트엔드–백엔드 통합형 문서지능 서비스(AlAin)를 개발하기 위해 진행한다.

1.3. 주요 타겟

HWPX 문서에서 필요한 정보를 빠르게 찾고자 하는 공공기관·기업 실무자 (예: 사업공고 검토자, 지침서 담당자, 내부문서 검색자) 문서 기반 AI 챗봇을 구축하려는 개발자 및 연구자 AlAin의 구조를 통해 국산 문서 포맷(HWPX) 기반 RAG 구현 사례를 학습하고 자체 문서 Q&A 시스템으로 확장하고자 하는 사용자 문서 이해 자동화에 관심 있는 일반 사용자 “문서를 올리면, 문서가 말해주는 AI” 경험을 통해 문서 이해의 새로운 방식 체험

기능정의서 초안

구분	필요 기능	래퍼런스/상세설명	필요기술	중요도
회원 FE + BE	이메일 로그인 구글 로그인 회원가입 비밀번호 찾기	MySQL 사용 회원가입: 이메일, 비밀번호, 닉네임	DBMS	★☆
관리자 FE + BE	문서 업로드 및 처리	HWPX 파일 업로드 후 OWPML 파싱	Python, FastAPI	★★★★
관리자 FE + BE	어드민 페이지 (대시보드, 문서관리, 프로젝트 관리 등)	업로드된 문서 리스트 관리	FastAPI + Admin UI	★★★
AI개발 + FE	추천질문 기능	추천 질문 생성 및 바로 실행	FastAPI + React	★★
AI개발 + FE	근거 하이라이트	원문 내 근거 문단 강조	React HighLNight.js	★★★
AI개발 + FE	질의응답	문맥 기반 Q&A 생성 + 근거 표시	GPT API + RAG	★★★★★
AI개발	텍스트·메타 추출	문단·제목·섹션 태그 구조화	OWPML Parser	★★★★
AI개발	청킹 & 임베딩	문단 단위로 쪼개고 벡터화	bge-m3-korean, pgvector	★★★★★
FE	FAQ버튼	주요 질문 바로 실행	React, JSON Config	★

가장 필수적인 기능들만 분류했고, 간단한 설명 및 요구 기술에 대해 작성했다. 또한 프로젝트 관점에서의 중요도 또한 병기했다.

WBS - 간트차트

작업구조를 분해했고, 이를 바탕으로 간트차트를 만들었다.

TASK별로 정, 부 담당자를 기입했고, 계획 시작일 및 예상 완료일을 기입했다. 놓친 내용들이 분명 있을 수 있어서, 일자별 백업을 해두고, 지속 업데이트 하기로 했다.

아키텍처 설계도

최초버전 -> 이후버전

최초에는 깃허브 README.MD와 유사한 마크다운 느낌으로 작성했었는데, 강사님의 피드백을 받고 다이어그램 이미지로 변경하였다. 머메이드 다이어그램 또한 고려했으나, 최종적으로 피그마로 만들었다.