따라 할 순서
01. 준비 · 폴더와 실행 환경
- ZIP 원본을 보관하고 내 컴퓨터의 쓰기 가능한 폴더에 압축을 완전히 풉니다. ZIP 안에서 실행하거나 run.py만 따로 옮기지 마세요.
- Python 3.11 이상이 필요합니다. 추가 Python 패키지는 필요 없습니다. 아직 없다면 아래 공식 Python 다운로드 안내를 이용해 설치하고 터미널을 다시 여세요.
- Python 공식 다운로드
Mac / Linux python3 --version Windows py -3 --version
- 이후 명령은 setup.py와 run.py가 있는 키트 폴더에서 실행합니다. VS Code에서는 키트 폴더를 연 뒤 「터미널 → 새 터미널」로 시작할 수 있습니다.
- 파일·터미널을 다루는 AI 에이전트를 쓴다면 이 폴더를 열고 START.md를 읽어 달라고 요청하세요. 일반 채팅형 AI는 내 컴퓨터에서 명령을 대신 실행하지 못합니다. AI 이용료는 별도입니다.
02. 연습 · API 키 없이 시작
- START.html을 열고 안내를 읽습니다. Mac은 START.command, Windows는 START.bat를 실행하면 준비 결과 화면이 열립니다. 시작 파일이 열리지 않으면 아래 명령을 사용하세요. OS 보안을 끌 필요는 없습니다.
Mac / Linux python3 setup.py --demo Windows py -3 setup.py --demo
- SETUP-RESULT.local.html을 열어 「샘플 준비 완료」와 결과 파일 링크를 확인합니다. 이 준비 실행은 기존 config.json 대신 연습용 설정을 쓰고, 실행마다 새 샘플 폴더를 만듭니다.
- 이어서 아래 명령으로 현재 설정의 데모와 오프라인 테스트를 실행합니다. --demo는 키가 있어도 실제 API나 외부 저장소를 호출하지 않습니다.
Mac / Linux python3 run.py --demo Windows py -3 run.py --demo
- 정상 확인: 테스트가 OK로 끝나고 마지막에 demo-ready가 표시됩니다. 결과는 results/demo에 있습니다. 준비 검사와 run.py의 데모는 출력 폴더가 다르므로 혼동하지 마세요.
- 나라장터 데모는 고정 공고로 중복·정정·금액·기관 필터를 연습합니다. 실제 최신 공고가 아니며 키워드를 바꾸어도 실시간 검색을 하지 않습니다.
03. 설정 · 내 검색 조건 만들기
- 구매 설정이 반영되어 있다면 먼저 config.json을 확인하고 그대로 유지할지 결정하세요. 수정 전 사본을 보관합니다. 아래는 기본 설정 예시이며 기존 파일을 무조건 덮어쓰라는 뜻은 아닙니다.
{ "keywords": [ "영상", "콘텐츠", "홍보" ], "days": 7, "institution": "", "min_amount": null, "max_amount": null, "only_open": true, "include_cancelled": false, "include_pre_spec": false, "download_attachments": false, "max_pages": 10, "formats": [ "json", "csv", "markdown" ], "output": "results/latest", "destination": "local", "destination_name": "나라장터 용역 공고" }- keywords에 찾을 용역의 단어를 넣습니다. 예: 영상, 콘텐츠, 홍보. 실제 수집에는 하나 이상의 키워드가 필요합니다.
- days는 게시일 조회기간입니다. institution은 기관명 조건, min_amount와 max_amount는 금액 조건(원)입니다. 금액 제한이 없으면 null을 유지합니다. only_open은 진행중 공고 필터입니다.
- 첫 실행에서는 destination: local로 두고 로컬 저장부터 확인하세요. include_pre_spec와 download_attachments는 false를 유지해 입찰공고와 첨부 링크 중심으로 시작합니다. formats에 json, csv, markdown을 유지하면 아래 예시 파일이 모두 생성됩니다.
- JSON은 큰따옴표를 사용하며 마지막 항목 뒤에 쉼표를 붙이지 않습니다. API 키는 config.json에 넣지 마세요. 저장 후 run.py --demo로 다시 점검합니다.
- AI 요청 예시: START.md와 config.json을 읽고 내가 정한 키워드와 조건만 반영해줘. .env는 읽거나 출력하지 말고, 기존의 나머지 설정을 유지해줘. --demo로 실행하고 변경한 조건·결과 경로·건수·경고를 알려줘.
04. 연결 · 본인 API 키 준비
- 공공데이터포털의 「조달청_나라장터 입찰공고정보서비스」에서 활용신청 상태를 확인하고 본인 인증키를 준비합니다. 나라장터 로그인 비밀번호를 쓰는 것이 아닙니다.
- 조달청 입찰공고 API 공식 안내
- 동봉된 API-KEY-GUIDE.md에 자세한 절차가 있습니다. 이 실습에서는 기본 수집 범위만 다룹니다. 추가 서비스는 해당 안내를 보고 따로 확인해야 합니다.
- .env가 이미 있으면 복사로 덮어쓰지 말고 해당 항목만 수정하세요. 없을 때만 .env.example을 같은 폴더의 .env로 복사합니다. 파일 이름이 .env.txt가 되지 않도록 확인하세요.
G2B_API_KEY=본인이_발급받은_키
- 등호 오른쪽을 본인 키로 직접 바꾸고 저장합니다. 키를 AI 대화·Git·스크린샷·이메일에 넣지 마세요.
Mac / Linux python3 doctor.py Windows py -3 doctor.py
- live_requirements.g2b_api_key: true는 로컬 키가 있다는 뜻입니다. live-ready도 준비 상태일 뿐 실제 인증 성공은 다음 수집으로 확인합니다.
05. 수집 · 실제 공고와 상태 확인
- 나라장터는 키를 넣은 뒤 아래 명령을 실행하면 실제 API로 전환됩니다. 키가 없으면 데모로 실행되므로 마지막 상태와 결과 폴더를 반드시 확인하세요.
Mac / Linux python3 run.py Windows py -3 run.py
- 기본 실제 결과는 results/latest에 생성됩니다. config.json의 output을 바꿨다면 그 폴더를 확인하세요. 결과를 다시 받으려면 같은 명령을 실행합니다.
- notices.json의 metadata에서 status, received_count, filtered_count, warnings를 확인합니다. 데모 JSON도 complete일 수 있으므로 results/demo와 실제 수집을 구분하세요.
- complete는 이번 수집 완료, partial은 일부만 수집되었거나 연결·데이터 경고가 있는 상태, blocked는 정상 수집을 마치지 못한 상태입니다. 경고를 읽기 전에는 결과를 완전한 목록으로 보지 마세요.
- 결과가 0건이면 상태·수신 건수·경고부터 확인합니다. complete이고 경고가 없다면 조건을 하나씩 완화해 다시 조회하세요. 인증 오류나 호출 한도 오류를 검색 결과 없음으로 처리하지 마세요.
- 나라장터는 partial에서도 명령이 정상 종료될 수 있습니다. 종료 여부만 보지 말고 JSON의 상태와 경고를 확인하세요.
06. 활용 · 결과 읽고 정리하기
- results/latest/notices.csv를 Excel 등에서 열고, summary.md에서 목록을 읽습니다. notices.json에는 수집 상태와 상세 정보가 있습니다. 선택한 formats에 따라 일부 파일만 생길 수 있습니다.
- 대표 공고 2건의 원문 링크를 열어 공고번호·차수·제목·기관·마감·금액을 대조합니다. 1건뿐이면 1건을 확인하세요. 입찰 자격과 제출 서류는 원문에서 직접 확인합니다.
- Sheets 또는 Notion 자동 정리를 원하면 DESTINATION-GUIDE.md에 따라 대상과 로컬 연결값을 준비한 뒤 destination을 google-sheets 또는 notion으로 바꿉니다. 다음 실제 실행에서는 선택한 외부 대상에도 추가하거나 갱신합니다.
- destination-report.json에서 실제 연결 결과를 확인하세요. 연결값이 없으면 가져오기용 CSV를 사용합니다. CSV가 생겼다고 외부 저장까지 끝난 것은 아닙니다.
- Notion은 .destination-state.json을 같은 결과 폴더에서 유지하고 함께 백업하세요. 상태 파일이 없으면 다시 실행할 때 중복 페이지가 생길 수 있습니다.
- 다음 실행은 같은 결과 파일을 갱신합니다. 이전 결과가 필요하면 실행 전에 결과 폴더를 날짜별 사본으로 보관하세요. 키트 폴더 전체나 .env를 웹에 공개하지 마세요.
07. 해결 · 오류와 문의
- Python 명령을 찾을 수 없음 → Python 3.11 이상 설치 후 터미널을 다시 엽니다. Windows에서 py가 없고 python이 있다면 python --version을 확인하고 같은 명령의 py -3를 python으로 바꿀 수 있습니다.
- run.py 또는 config.json을 찾을 수 없음 → 압축이 완전히 풀렸는지, 키트 루트에서 실행했는지 확인합니다.
- 설정 오류 → config.json을 templates/config.example.json과 비교합니다. 큰따옴표·쉼표·숫자·true/false를 확인하고 기존 파일은 백업한 뒤 필요한 항목만 고칩니다.
- 인증 실패 → 키 이름·복사 오류·해당 서비스 신청 상태를 확인합니다. 키 값을 출력하거나 인증서 검증을 끄지 마세요.
- 한도·시간초과·partial → warnings를 읽고 무한 재시도하지 않습니다. 조회 범위와 페이지 한도를 검토하고 공식 API 이용 조건에 맞춰 다시 실행합니다.
- 예전 결과가 보여요 → demo/latest 폴더와 수집 시각을 확인하세요. 초기 단계에서 실패하면 이전 결과가 남아 있을 수 있습니다.
- 저장 실패 → 폴더 쓰기 권한과 디스크 여유 공간을 확인합니다. 전체 재설치 전에 실패한 단계만 다시 실행하세요.
- 문의에는 키트명·버전, OS·Python 버전, 단계 번호, 실행한 명령, 기대/실제 결과, 키를 제거한 오류 문구를 적습니다. 키나 .env 전체는 보내지 마세요.
- KitForAI 고객센터 · 첫 답변 목표 영업일 2일 이내
- 완료 확인: 내 조건의 실제 수집 상태와 경고를 확인하고 대표 원문을 대조했습니다. 외부 정리를 선택했다면 그 대상의 실제 데이터도 확인했습니다. 데모 성공만으로 실제 연결 완료를 선언하지 않습니다.