매일 아침 문서 사이트를 전부 긁어와야 하는 개발자라면, 페이지마다 중복된 네비게이션 링크와 피드백 버튼을 직접 걸러내는 작업에 지쳐 있을 것이다. 이번 주 깃허브 트렌드에 올라온 Olostep 기반 크롤러가 이 문제를 다른 방식으로 접근한다.

Olostep SDK로 문서 사이트 전체를 마크다운으로 추출하는 방법

연구팀은 Olostep(웹 데이터를 검색·크롤링·스크래핑·구조화하는 하나의 API)을 사용해 문서 사이트 전체를 크롤링하는 파이썬 스크립트를 공개했다. 이 프로젝트는 kingabzpro/web-crawl-olostep에서 확인할 수 있다. Olostep SDK는 Python 3.11 이상을 요구하며, 공식 문서와 통합 가이드는 Olostep 대시보드의 API 키 페이지에서 설정하도록 안내한다.

설치는 다음 명령어로 진행한다:

bash
pip install olostep python-dotenv

환경 변수 파일(.env)을 프로젝트 폴더에 생성한다:

OLOSTEP_API_KEY=your_api_key_here

핵심 크롤링 스크립트(crawl_docs_with_olostep.py)는 다음과 같은 구조로 작성된다:

python
import os
from dotenv import load_dotenv
from olostep import OlostepClient

load_dotenv()

크롤링 설정

START_URL = "https://docs.example.com"

CRAWL_DEPTH = 2

PAGE_LIMIT = 50

OUTPUT_FOLDER = "crawled_docs"

INCLUDE_PATTERNS = ["/docs/"]

EXCLUDE_PATTERNS = ["/blog/", "/community/"]

def url_to_filename(url: str) -> str:

"""URL을 파일시스템에 안전한 파일명으로 변환"""

return url.replace("https://", "").replace("http://", "").replace("/", "_").replace("?", "_") + ".md"

def clean_markdown(content: str) -> str:

"""불필요한 UI 텍스트, 반복 줄바꿈, 피드백 프롬프트 제거"""

import re

content = re.sub(r'\n{3,}', '\n\n', content)

content = re.sub(r'(Was this page helpful\?|Edit this page).*', '', content)

return content.strip()

def save_markdown(url: str, content: str, folder: str):

"""정제된 마크다운을 파일로 저장, 상단에 소스 URL 추가"""

filename = url_to_filename(url)

filepath = os.path.join(folder, filename)

with open(filepath, 'w', encoding='utf-8') as f:

f.write(f"<!-- Source: {url} -->\n\n")

f.write(content)

print(f"Saved: {filepath}")

def clear_output_folder(folder: str):

"""기존 크롤링 결과 파일 삭제"""

if os.path.exists(folder):

for f in os.listdir(folder):

if f.endswith('.md'):

os.remove(os.path.join(folder, f))

메인 크롤러

client = OlostepClient(api_key=os.getenv("OLOSTEP_API_KEY"))

clear_output_folder(OUTPUT_FOLDER)

os.makedirs(OUTPUT_FOLDER, exist_ok=True)

crawl = client.crawl(

url=START_URL,

max_depth=CRAWL_DEPTH,

max_pages=PAGE_LIMIT,

include=INCLUDE_PATTERNS,

exclude=EXCLUDE_PATTERNS,

output_format="markdown"

)

for page in crawl.pages:

cleaned = clean_markdown(page.content)

save_markdown(page.url, cleaned, OUTPUT_FOLDER)

스크립트 실행은 터미널에서 다음 명령어로 한다:

bash
python crawl_docs_with_olostep.py

실행이 완료되면 `crawled_docs` 폴더에 각 페이지가 개별 마크다운 파일로 저장된다. 각 파일 상단에는 원본 URL이 주석으로 포함되어 있어 출처 추적이 가능하다.

예전에는 Scrapy나 Selenium으로 직접 파싱해야 했지만, 이제는 API 호출 한 번으로 끝난다

예전에는 Scrapy(전체 스크래핑 프레임워크)로 깊은 제어를 하거나 Selenium(브라우저 자동화 도구)으로 자바스크립트 페이지를 처리해야 했다. 두 도구 모두 문서 사이트 크롤링에 특화되지 않아 중복 링크 제거, 페이지 구조 파악, LLM 친화적 포맷 변환을 수동으로 해야 했다. Olostep은 검색·크롤링·스크래핑·구조화를 하나의 API로 통합하고, 마크다운·텍스트·HTML·구조화된 JSON 등 LLM(대규모 언어 모델)이 바로 사용할 수 있는 출력을 기본 지원한다. 이는 URL에서 usable content까지 가는 경로를 크게 단축시킨다.

개발자가 바로 체감하는 변화는 크롤링 결과를 AI 워크플로에 즉시 연결할 수 있다는 점이다

개발자는 더 이상 크롤링 스택을 직접 조립하는 데 시간을 쓰지 않고, 추출된 마크다운 파일을 검색·질의응답·에이전트 기반 시스템에 바로 투입할 수 있다. 프로젝트는 여기에 Gradio(파이썬으로 웹 UI를 만드는 라이브러리) 기반 웹앱을 추가해, URL과 크롤링 설정만 입력하면 결과를 미리보기까지 할 수 있는 인터페이스를 제공한다. 웹앱 실행은 다음 명령어로 한다:

bash
python app.py

실행 후 브라우저에서 `http://127.0.0.1:7860`으로 접속하면 된다. 웹앱 코드는 web-crawl-olostep/app.py에서 확인할 수 있다.

문서 크롤링이 더 이상 엔지니어링 작업이 아니라 API 호출 한 번으로 끝나는 시대가 왔다.