1인 수입 셀러를 위한 무역·외환 AI 에이전트 KB국민은행 제8회 AI Challenge 출품작 — 현직자 Pick ⑥ 「수출입 금융 지원 에이전트」
스마트스토어 셀러, 크라우드펀딩 굿즈 제작자, 구매대행 사업자 — 이제 무역은 노트북 앞 1인 셀러가 합니다. 하지만 이들에게는 신용장도, 포워더도, 환헤지도 없습니다. 바다 건너 사장님은 첫 수입에서 부딪히는 원가·환율·신뢰의 벽을 대화형 AI 에이전트로 낮추고, 그 여정을 KB의 외환 서비스와 연결합니다.
기획자이자 개발자가 실제로 1688·샤오홍슈에서 중국 공장을 찾고, 위챗으로 중국어 협상을 하고, 위안화로 선금을 보내 본 경험에서 출발한 서비스입니다.
| 에이전트 | 역할 | 핵심 설계 |
|---|---|---|
| ① 무역 길잡이 | 수입 절차·인증(KC 등) Q&A | RAG(FAISS) + 답변마다 출처 표기 |
| ② 진짜 원가 계산 | 랜디드 코스트·마진 시뮬레이션 | HS코드는 LLM이 '후보+확신도'로 추정, 세금·물류 합산은 룰베이스 |
| ③ 외환·상품 매칭 | 결제방식·환리스크 진단 → KB 상품 추천 | 추천 사유와 유의사항 병기 |
| ④ 서류 리스크 점검 | PI/인보이스 분석 → 신호등 리포트 | 중국어 문서 지원, 판정 근거 조항 표시 |
1. 계산은 코드가, 추정과 설명은 LLM이. 세율·환율 등 확정 수치는 LLM이 생성하지 않고 공공 API·룰베이스 계산 엔진에서만 가져옵니다. 계산 결과는 pytest로 손계산과 대조해 검증합니다.
2. 근거 없으면 답하지 않는다. 검색된 문서에 없는 내용은 지어내지 않고, "무엇을 어디서 확인해야 하는지"를 안내합니다. 모든 답변에 문서명·페이지 단위 출처를 붙입니다.
3. 폴백 우선. 모든 외부 API는 샘플 스냅숏 폴백을 내장해, 네트워크·API 키 상태와 무관하게 데모가 동작합니다.
같은 백엔드를 사용하는 얇은 네이티브 클라이언트로, 네이티브에서만 가능한 2가지에 집중합니다.
- 서류 촬영 스캔 — VisionKit으로 PI 촬영 → 온디바이스 중국어 텍스트 인식(Vision,
zh-Hans) → 점검 API 호출 - 환율 위젯 — 결제 D-day까지 대상 통화 환율 트래킹 (WidgetKit)
| # | 질문 | 확인 포인트 |
|---|---|---|
| 1 | "인형 500개, 개당 12위안. 얼마에 팔아야 남죠?" | HS 후보 추정 → 관세·부가세 룰 계산 → 환율 3케이스 마진 |
| 2 | "선금 30%를 위안화로 보내 달래요. 지금 환전할까요?" | 환리스크 진단 → KB 상품 추천(사유·유의사항 포함) |
| 3 | 중국어 PI 업로드 (웹) / iPhone 촬영 (iOS) | 핵심 조건 추출 → 신호등 리스크 리포트 |
각 화면에는 프리셋·샘플 버튼이 있어 클릭 한 번으로 시나리오를 재현할 수 있습니다.
[Web · React+Vite] [iOS 동행 앱 · SwiftUI]
│ │
└────────┬────────────┘
▼
[FastAPI 백엔드]
오케스트레이터(Claude API) — 의도 분류·라우팅
├─ ① 길잡이 : RAG (임베딩 + FAISS, 출처 메타데이터)
├─ ② 원가 계산 : 룰베이스 계산 엔진 + LLM HS 추정
├─ ③ 외환 매칭 : 환리스크 진단 + 상품 DB
└─ ④ 서류 점검 : 문서 파서(텍스트 추출·OCR)
│
▼
[외부 데이터] 한국수출입은행 환율 API · 관세청 오픈API/관세법령정보포털 · 무역통계 · 가이드 문서
(전 구간 샘플 스냅숏 폴백 내장)
| 메서드 | 경로 | 설명 |
|---|---|---|
GET |
/health |
헬스체크 |
POST |
/ask |
무역 길잡이 — 질문 → 출처 포함 답변 |
POST |
/cost |
원가 계산 — 품목·수량·단가 → 환율 시나리오별 마진 |
전체 명세와 테스트는 서버 실행 후 http://127.0.0.1:8000/docs (Swagger UI)에서 확인할 수 있습니다.
| 영역 | 스택 | 선택 이유 |
|---|---|---|
| 프론트엔드 | React + Vite, Zustand, styled-components | 개발 동아리 웹 프로젝트에서 사용한 스택 — 학습 비용 0 |
| 백엔드 | FastAPI (Python 3.11+) | LLM·임베딩 생태계 결합, 빠른 프로토타이핑 |
| LLM·에이전트 | Claude API + 경량 오케스트레이터 | 역할별 프롬프트 분리, 과설계 방지 |
| RAG | 임베딩 + FAISS | 로컬 실행·무료, 출처 메타데이터 유지 |
| iOS | SwiftUI, VisionKit·Vision, WidgetKit | 동아리 iOS 파트 경험 — 스캔·위젯은 네이티브에서만 가능 |
| 품질 | pytest | 계산 룰 손검산 대조 + 출처-답변 정합성 회귀 테스트 |
.
├── backend/ # FastAPI 서버
│ ├── app/
│ │ ├── main.py
│ │ ├── services/ # 계산 룰 엔진 · RAG · 문서 파서
│ │ └── agents/ # 오케스트레이터 · 4개 에이전트
│ ├── data/
│ │ ├── docs/ # RAG 원문 (관세청·무역협회 가이드)
│ │ ├── snapshots/ # 환율·세율 샘플 스냅숏 (폴백)
│ │ └── vectorstore/ # FAISS 인덱스 (gitignore)
│ ├── tests/
│ └── requirements.txt
├── frontend/ # React 웹 클라이언트
├── BadaSajangnim/ # iOS 동행 앱 (Xcode 프로젝트)
├── docs/ # 기술설명서 · 실행계획 · 데모 영상
├── .github/
│ └── pull_request_template.md
└── README.md
- Python 3.11+, Node.js 18+
- (iOS 앱 실행 시) Xcode 15+, 실기기
- API 키: Anthropic, 공공데이터포털(한국수출입은행 환율), 관세청 오픈API
backend/.env 파일을 생성합니다. .env는 절대 커밋하지 않습니다.
ANTHROPIC_API_KEY=sk-ant-...
KOREAEXIM_API_KEY=... # 한국수출입은행 환율 API
CUSTOMS_API_KEY=... # 관세청 오픈APIAPI 키가 없어도 됩니다. 키가 비어 있으면 자동으로 샘플 스냅숏 폴백 모드로 동작하며, 데모 시나리오 3종이 모두 정상 실행됩니다.
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000- API 문서: http://127.0.0.1:8000/docs
- 헬스체크:
curl http://127.0.0.1:8000/health
cd frontend
npm install
npm run dev # http://localhost:5173/api 요청은 Vite 프록시를 통해 백엔드(8000)로 전달됩니다. 백엔드를 먼저 실행해 주세요.
cd backend && pytest -vopen BadaSajangnim/BadaSajangnim.xcodeproj- Signing & Capabilities → Team에 본인 Apple ID(Personal Team) 지정
Config.swift의baseURL을 맥의 LAN IP로 변경 (ipconfig getifaddr en0) 실기기는localhost로 맥의 백엔드에 접근할 수 없습니다.- 실기기 선택 후 실행 — 문서 카메라는 시뮬레이터에서 동작하지 않습니다.
무료 Personal Team 서명은 7일 후 만료됩니다. 앱이 실행되지 않으면 Xcode에서 다시 빌드해 주세요.
- 한국수출입은행 현재환율 API (공공데이터포털)
- 관세청 오픈API · 관세법령정보포털 (HS코드·관세율)
- 관세청 수출입 무역통계
- KB국민은행 외환 상품 공개 정보
- 관세청·한국무역협회·제품안전정보센터 공개 가이드 문서 (RAG 지식 베이스)
세율·환율 값에는 조회 시점과 출처를 함께 기록하며, 서비스는 최종 확인처(관세청 유니패스 등)를 답변에 안내합니다.
- 개발 기간: 2026.7.26 – 8.3 (8일)
- 개발 인원: 1인
- 작업 방식: 이슈 단위 브랜치 → PR(템플릿) → 머지
- 상세 일정: docs/프로토타입_실행계획_0803.md
| 항목 | 위치 |
|---|---|
| 기술설명서 (PPT) | docs/ |
| 프로토타입 | 본 저장소 |
| 설명 영상 | docs/ (링크) |
- 접수 마감 전 최종 커밋에
v1.0-submission태그 후 저장소 동결 — 접수 기간 이후 수정 이력이 확인되면 심사에서 제외되는 규정에 대응합니다. - 심사용 데모는 네트워크·API 키 상태와 무관하게 동작하도록 폴백을 내장했습니다.
- 저장소에는 API 키·개인정보가 포함되어 있지 않습니다.
"신용장을 몰라도 되는 첫 수입" — 무역의 새 얼굴에게, 은행의 새 얼굴을.