This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

제가 만든 것 (What I Built)

로컬 영수증 및 송장 분류기(Local Receipt & Invoice Sorter) — 이 도구를 영수증/송장 사진 또는 PDF 폴더에 지정하면, 판매자(vendor), 날짜(date), 금액(amount), 통화(currency), 카테고리(category)를 추출하여 깔끔하고 편집 가능한 CSV 파일로 만듭니다. 전체 추출 파이프라인은 Ollama을 통해 로컬 비전-언어 모델(vision-language model)을 거치므로, 금융 문서는 절대로 사용자 기기를 벗어나지 않습니다.

누가 비용을 지불하는가: 프리랜서, 컨설턴트, 그리고 자체 장부를 작성하는 소규모 상점 주인들입니다. 현재 이들은 영수증을 스프레드시트에 수동으로 입력하거나 (지루한 작업), Expensify와 같은 클라우드 도구를 사용합니다 (반복 비용 발생, 그리고 금융 문서는 제3자 API를 거칩니다). 이 도구는 두 가지 문제 모두를 해결합니다. 설정 후에는 무료로 실행할 수 있으며, ChatGPT에 영수증을 절대 업로드하지 않을 사생활 보호 민감 사용자에게도 실제로 사용할 이유를 제공합니다.

데모 (Demo)

코드 (Code)

GitHub logo loveyadav1015 / ollama-tax-man

영수증 및 송장 분류기 (Receipt & Invoice Sorter)

영수증 또는 송장 이미지 및 PDF 폴더를 Ollama가 사용자 기기에서 실행하는 비전-언어 모델을 사용하여 CSV 파일(vendor, date, amount, currency, category, source_filename)로 변환하는 로컬 우선(Local-first) 도구입니다. 문서는 클라우드 API로 전송되지 않습니다.

필수 조건 (Prerequisites)

1. 프로젝트 가상 환경(venv/)에 포함된 Python 3.10+.
2. 로컬에 설치 및 실행 중인 Ollama.
3. 추출하기 전에 비전 모델을 다운로드해야 합니다:

ollama pull qwen2.5vl:7b

만약 qwen2.5vl:7b를 사용할 수 없다면, 대체 모델을 다운로드하세요:

ollama pull llama3.2-vision

앱은 먼저 qwen2.5vl:7b (또는 설치된 모든 qwen2.5vl 태그)를, 그 다음 llama3.2-vision을 사용합니다. 만약 Ollama가 작동하지 않거나 두 모델 중 어느 것도 존재하지 않으면, UI는 스택 트레이스 대신 해당 정확한 ollama pull … 명령어를 표시합니다.

Qwen2.5-VL은 최신 버전의 Ollama (0.7 이상)를 필요로 합니다.

설정 (Setup)

cd ollama-tax-man
source venv/bin/activate

환경에 이미 설치된 패키지: streamlit, pandas, pydantic 등...

GitHub에서 보기

구축 과정 (How I Built It)

비전 기반 추출을 위해 로컬에서 Ollama를 실행하고 qwen2.5vl:7b를 사용하는 방식으로 구현했습니다. 파이프라인 어디에서도 OpenAI/Anthropic/Google의 비전 API 호출은 없습니다.

사용 스택:

• Ollama + qwen2.5vl:7b (로컬 추론, 비전 기능 지원)
• PDF 페이지를 이미지로 래스터화하여 모델에 전송하는 PyMuPDF
• 모델의 JSON 출력을 엄격한 스키마(판매자, 날짜, 금액, 통화, 카테고리, 신뢰도, 메모)와 비교하여 검증하는 Pydantic
• 표 형식의 CSV 출력을 위한 Pandas
• 내보내기 전에 편집 가능한 결과 테이블을 제공하는 드래그 앤 드롭 UI를 위한 Streamlit

추출 프롬프트는 엄격한 JSON 출력을 강제하며, 파싱에 실패할 경우 더 엄격한 지침으로 한 번 재시도하고, 충돌(crash)하는 대신 플래그가 지정된 '검토 필요' 행으로 대체됩니다. 신뢰도가 낮은 행은 시각적으로 강조되어 사용자가 CSV를 세금 목적으로 신뢰하기 전에 무엇을 다시 확인해야 하는지 알 수 있습니다.

아키텍처 (Architecture)

flowchart TD
    A[영수증 폴더<br/>이미지 / PDF] --> B{파일 유형?}
    B -->|PDF| C[PyMuPDF:<br/>페이지를 이미지로 래스터화]
...

처리 순서 (Processing sequence)

sequenceDiagram
    participant U as User
    participant S as Streamlit UI
...

Open Innovation은 왜 중요할까요? (Why Does Open Innovation Matter?)

이 도구의 전체 가치 제안은 모델이 로컬 환경에서 작동하는 것에 달려 있습니다. 폐쇄형 API(비싸지 않더라도)는 이 도구가 제거하도록 설계된 정확한 반론을 다시 불러옵니다. 즉, 사용자의 영수증—판매자 이름, 금액, 날짜, 지출 패턴—이 기기를 떠나게 됩니다. 이는 프리랜서들에게 가상의 우려 사항이 아니라, 실제로 일부가 경비 추적 SaaS 도구를 피하는 실제 이유입니다.

오픈 가중치 비전 모델 덕분에 이것이 가능해졌습니다. 몇 년 전만 해도 "충분히 좋은" 문서 OCR 및 추출 기능은 클라우드 API를 의미했고, 끝이었습니다. 이제 노트북 CPU/GPU에서 실행되는 7B 비전 모델은 구겨진 영수증 사진을 읽고 유용할 만큼 충분히 신뢰할 수 있는 구조화된 JSON을 반환할 수 있습니다. 오픈 모델들은 단순히 비용을 절감했을 뿐만 아니라, 이 제품의 프라이버시 우선 버전을 아예 가능하게 만들었습니다.

수상 부문 (Prize Categories)

• .tech 도메인 활용 최우수: Streamlit 데모를 receiptsorter.tech에 배포하여, 일반적인 서브도메인이 아닌 기억하기 쉽고 목적에 맞는 공간을 프로젝트에 제공했습니다. 이는 개발자 중심의 오픈 소스 AI 도구에 적합합니다.

• Sentry Agent Tracing 활용 최우수: Sentry의 에이전트 트레이싱을 사용하여 Ollama 추출 파이프라인을 실시간으로 모니터링했습니다. 각 비전 모델 호출의 지연 시간(latency)을 추적하고, JSON 구문 분석 실패가 조용히 나쁜 CSV 행이 되기 전에 포착했으며, 재시도 로직(잘못된 출력에 대한 엄격한 재프롬프트)을 추적하여 실패 패턴이 블랙박스 로컬 추론 호출 내부에 숨겨지는 대신 가시화되도록 했습니다.

• GitHub Copilot 활용 최우수: 빌드 전반에 걸쳐 Copilot을 사용하여 Pydantic 스키마 유효성 검사 골격화(scaffold)를 하고, Streamlit의 data_editor 연결 속도를 높였으며, sample_data/ 폴더에 합성 더미 영수증을 생성했습니다. 이를 통해 상당한 양의 반복 코드를 줄여서 추출 프롬프트와 재시도 로직을 올바르게 구현하는 데 더 많은 시간을 할애할 수 있었습니다.