따라 할 순서
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의 데모는 출력 폴더가 다르므로 혼동하지 마세요.
- 기본 config.json 그대로 실행하면 가상 공고 수신 8건 → 중복제거 7건 → 최종 6건입니다. 조건을 바꾸면 최종 건수가 달라질 수 있습니다. 기준일은 데모 자료의 날짜이며 오늘이 아닙니다.
03. 설정 · 내 검색 조건 만들기
- 구매 설정이 반영되어 있다면 먼저 config.json을 확인하고 그대로 유지할지 결정하세요. 수정 전 사본을 보관합니다. 아래는 기본 설정 예시이며 기존 파일을 무조건 덮어쓰라는 뜻은 아닙니다.
{ "keywords": [ "콘텐츠", "창업" ], "exclude_keywords": [], "regions": [ "서울", "경기" ], "fields": [], "include_nationwide": true, "include_unknown_region": true, "include_closed": false, "include_upcoming": true, "include_unknown_period": true, "page_size": 100, "max_pages": 30, "output": "results/latest" }- keywords는 제목·사업개요·해시태그에서 하나 이상 일치하면 포함합니다. regions는 공고의 지역 태그, fields는 지원분야입니다. 각 빈 목록 []은 해당 조건을 전체로 봅니다. exclude_keywords는 제외할 단어입니다.
- 예시 조건은 콘텐츠 또는 창업, 서울·경기이며 전국과 지역 미상 후보도 포함합니다. 지역 미상은 신청 가능한 지역이라는 뜻이 아니라 원문 확인이 필요한 후보입니다.
- include_closed는 마감된 공고, include_upcoming은 접수 예정, include_unknown_period는 날짜가 불명확한 공고를 포함할지 정합니다. page_size와 max_pages는 수집 한도입니다.
- JSON은 큰따옴표를 사용하며 마지막 항목 뒤에 쉼표를 붙이지 않습니다. API 키는 config.json에 넣지 마세요. 저장 후 run.py --demo로 다시 점검합니다.
- AI 요청 예시: START.md와 config.json을 읽고 내가 정한 키워드와 조건만 반영해줘. .env는 읽거나 출력하지 말고, 기존의 나머지 설정을 유지해줘. --demo로 실행하고 변경한 조건·결과 경로·건수·경고를 알려줘.
04. 연결 · 본인 API 키 준비
- 기업마당 공식 API 안내의 「사용신청」 절차에 따라 본인 인증키를 준비합니다. 나라장터 공공데이터 키와는 다른 키입니다. 발급·이용 조건은 공식 화면을 따릅니다.
- 기업마당 API 공식 안내
- 동봉된 API-KEY-GUIDE.md에 자세한 절차가 있습니다. 이 실습에서는 기본 수집 범위만 다룹니다. 추가 서비스는 해당 안내를 보고 따로 확인해야 합니다.
- .env가 이미 있으면 복사로 덮어쓰지 말고 해당 항목만 수정하세요. 없을 때만 .env.example을 같은 폴더의 .env로 복사합니다. 파일 이름이 .env.txt가 되지 않도록 확인하세요.
BIZINFO_API_KEY=본인이_발급받은_키
- 등호 오른쪽을 본인 키로 직접 바꾸고 저장합니다. 키를 AI 대화·Git·스크린샷·이메일에 넣지 마세요.
Mac / Linux python3 doctor.py Windows py -3 doctor.py
- api_key_present: true는 로컬 키가 있다는 뜻입니다. 실제 인증 성공은 다음 수집으로 확인합니다. 진단만 통과했다고 실제 연결이 끝난 것은 아닙니다.
05. 수집 · 실제 공고와 상태 확인
- 지원사업은 아래처럼 --live를 붙여야 실제 API를 호출합니다. 키가 있어도 run.py만 실행하면 연습 실행입니다. --live를 붙이면 진단·테스트·데모를 거친 뒤 실제 수집을 시작합니다.
Mac / Linux python3 run.py --live Windows py -3 run.py --live
- 기본 실제 결과는 results/latest에 생성됩니다. config.json의 output을 바꿨다면 그 폴더를 확인하세요. 결과를 다시 받으려면 같은 명령을 실행합니다.
- run-report.json에서 status, as_of, received_count, selected_count, warnings를 확인합니다. as_of는 기간상태의 기준일입니다.
- complete는 이번 수집 완료, partial은 일부만 수집되었거나 연결·데이터 경고가 있는 상태, blocked는 정상 수집을 마치지 못한 상태입니다. 경고를 읽기 전에는 결과를 완전한 목록으로 보지 마세요.
- 결과가 0건이면 상태·수신 건수·경고부터 확인합니다. complete이고 경고가 없다면 조건을 하나씩 완화해 다시 조회하세요. 인증 오류나 호출 한도 오류를 검색 결과 없음으로 처리하지 마세요.
- 지원사업의 partial·blocked는 종료코드 2입니다. partial 결과는 보존되어 있으니 경고와 원문을 먼저 확인하세요.
06. 활용 · 결과 읽고 정리하기
- results/latest/review.html을 더블클릭합니다. 검색창에 목록에서 보이는 사업명 일부를 입력하고, 기간상태를 바꿔 목록이 줄어드는지 확인합니다. 검색을 지우고 전체 상태로 되돌립니다.
- 대표 공고 2건의 원문 링크를 열어 공고ID·사업명·기관·기간·지역 태그를 대조합니다. 1건뿐이면 1건을 확인하세요. 접수중 표시는 날짜 기준이며 당일 마감 시각·예산 소진을 보장하지 않습니다.
- notices.csv는 스프레드시트용 표, notices.json은 상세 자료, summary.md는 요약, run-report.json은 실행 상태입니다. HTML·CSV·JSON의 공고 건수가 같은지 확인합니다.
- Sheets·Notion은 notices.csv 가져오기 방식입니다. DESTINATION-GUIDE.md를 따라 새 표에 먼저 가져오고 한글·공고ID·기간·링크를 확인하세요. 자동 동기화하지 않으며 반복 가져오기는 중복을 만들 수 있습니다.
- 지역·분야 일치는 검토 후보라는 뜻입니다. 지원대상·업력·업종·중복수혜·제출서류는 원문에서 확인합니다. 키트가 자동으로 신청하거나 선정 가능성을 판정하지 않습니다.
- 다음 실행은 같은 결과 파일을 갱신합니다. 이전 결과가 필요하면 실행 전에 결과 폴더를 날짜별 사본으로 보관하세요. 키트 폴더 전체나 .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일 이내
- 완료 확인: 내 조건의 실제 수집 상태와 경고를 확인하고 대표 원문을 대조했습니다. 외부 정리를 선택했다면 그 대상의 실제 데이터도 확인했습니다. 데모 성공만으로 실제 연결 완료를 선언하지 않습니다.