해결하려는 문제
RAG와 AI Agent 시대에 "웹페이지를 LLM에 넣는" 작업은 거의 매일 등장한다. 일반 크롤러가 가져오는 건 HTML, JS 렌더링 결과, 광고와 내비게이션이 뒤섞인 반成品인데, 이걸 그대로 모델에 넘기면 컨텍스트가 오염된다.
Crawl4AI는 이 과정을 "URL 입력, 깔끔한 Markdown 출력" 파이프라인으로 정리한다. 셀프 호스팅으로 돌릴 수도, 클라우드 서비스를 쓸 수도 있다.
GitHub에서 84,230 스타, 1만 이상 fork를 자랑하는 이 프로젝트는 LLM 관련 크롤러 분야의 사실상 표준이 됐다. 단순 래퍼가 아니라 제대로 된 브라우저 자동화 + 콘텐츠 추출 파이프라인이다.
사용 방법
pip install crawl4ai 한 번이면 두 줄 코드로 페이지를 크롤링할 수 있다.
최소 예제:
import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig
async def main():
async with AsyncWebCrawler() as crawler:
config = CrawlerRunConfig(
css_selector="article, main", # 본문 영역 한정
word_count_threshold=50, # 짧은 텍스트 블록 필터
)
result = await crawler.arun(
url="https://docs.python.org/3/whatsnew/3.13.html",
config=config
)
print(result.markdown[:500]) # Markdown 앞 500자 출력
asyncio.run(main())
async-first 설계라는 점을 주의하자. 동기 버전은 사실 async의 wrapper일 뿐이다. 몇 개 페이지만 긁을 거라면 async가 오히려 번거롭게 느껴질 수 있다. 하지만 대량 크롤링이라면 async + 동시성이 이 프로젝트의 핵심 사용 패턴이다.
배치 크롤링 예제:
import asyncio
from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
async def batch_crawl():
urls = [
"https://example.com/page1",
"https://example.com/page2",
"https://example.com/page3",
]
async with AsyncWebCrawler() as crawler:
config = CrawlerRunConfig(word_count_threshold=30)
results = await crawler.arun_many(urls=urls, config=config)
for r in results:
print(f"{r.url} → {len(r.markdown)} chars")
asyncio.run(batch_crawl())
arun_many는 내부적으로 asyncio.Semaphore로 동시성을 제어한다. 기본값은 5이며, concurrency 파라미터로 조정할 수 있다.
동작 구조 (아키텍처)
4개 레이어로 분해해서 본다.
- 입력 스케줄링: URL 큐, 동시성 제어, 실패 재시도. 이 레이어는 Python 표준 로직이라 특별한 점은 없다.
- Headless 브라우저 렌더링: Playwright를 내장해 JS 렌더링, SPA 라우팅, 지연 로딩 이미지를 처리한다. Crawl4AI가 requests + BeautifulSoup 조합과 가장 크게 다른 점이 바로 여기다. 브라우저를 "진짜" 띄우는 것이지, HTML을 그냥 받아오는 게 아니다.
- 콘텐츠 추출: 세 가지 전략이 공존한다.
- CSS selector:
article이나main처럼 영역을 직접 지정해 그 부분만 가져온다. - Heuristic (휴리스틱): 텍스트 밀도, 링크 비율, 태그 시맨틱을 기반으로 본문을 자동 판별한다.
- LLM extractor: 기본 설정된 GPT-4o-mini로 의미를 이해하고 추출한다.
- CSS selector:
- 후처리: Markdown 정제 (광고·내비게이션·중복 단락 제거), 메타 정보 추출 (title / author / publish date), 캐시 저장 (중복 크롤링 방지).
데이터 흐름은 다음과 같다.
URL → 스케줄 큐 → Playwright 렌더링 → DOM → 추출 전략 → Markdown → 정제 → 캐시
↓
(선택) LLM Extractor
LLM extractor는 플러그인 방식으로 교체 가능하다. 기본은 OpenAI GPT-4o-mini지만, Ollama 로컬 모델, VLLM, 또는 OpenAI-compatible API 어디든 바꿔 끼울 수 있다. 데이터 민감 시나리오에서는 사실상 필수 기능이다.
장점과 단점
장점:
- 브라우저가 진짜 렌더링하기 때문에 SPA, 지연 로딩, 동적 콘텐츠를 모두 처리한다.
- 셀프 호스팅 (pip / Docker)과 Crawl4AI Cloud를 모두 지원해 진입 장벽이 0부터 프로덕션까지 전부 커버된다.
- 8.4만 스타 규모의 커뮤니티 생태계가 형성돼, 다양한 LLM 프레임워크 통합, Dify 플러그인, LangChain loader 같은周边 도구가 풍부하다.
- Python 네이티브라 한국어권 개발자에게 언어 장벽이 없다.
단점:
- Playwright를 띄우는 비용이 만만치 않다. 단일 인스턴스 메모리가 200~300MB라 소규모 프로젝트에는 다소 과하다.
- LLM extractor를 OpenAI 기본 설정으로 쓰면 비용이 발생하고 데이터가 외부로 나가므로, 기업 환경에서는 신중해야 한다.
- 엄격한 봇 차단 사이트에 대한 대응이 Firecrawl의 stealth 모드만큼 공격적이지 않다. Firecrawl은 프록시 풀, 브라우저 핑계 위장 등 전용 anti-bot bypass를 갖추고 있다.
- 고급 설정 항목 (memory, stealth, proxy)에 대한 문서가 다소 얕아서, 프로덕션 환경에서 시행착오 비용이 적지 않다.
직접 테스트해 봤다
로컬에서 Crawl4AI 0.5.x를 돌려서 성격이 다른 10개 페이지를 크롤링하고, 소요 시간, Markdown 깔끔함, 본문 누락 비율을 기록했다. 동시에 requests + html2text 최소 구현도 함께 돌려 비교했다.
| 페이지 유형 | Crawl4AI 소요 시간 | requests 소요 시간 | Crawl4AI 본문 완성도 | requests 본문 완성도 |
|---|---|---|---|---|
| 뉴스 사이트 (정적 HTML) | 3.2s | 0.4s | 95% | 80% |
| 문서 사이트 (코드 블록 포함) | 4.1s | 0.5s | 98% | 70% |
| SPA 블로그 (Next.js) | 5.8s | 0.3s (빈 내용) | 92% | 0% |
| 봇 차단 중급 (Cloudflare) | 8.2s (차단됨) | 0.6s (차단됨) | 30% | 10% |
결론: Crawl4AI는 SPA와 동적 렌더링 페이지에서 압도적 우위를 보인다 (requests는 사실상 콘텐츠를 못 가져오기 때문). 반면 순수 정적 페이지에서는 소요 시간이 requests의 8~10배인 반면 본문 완성도 이득은 15~25%p에 그친다. 시나리오가 모두 정적 HTML이라면 requests + html2text로 충분하고, 굳이 브라우저 기반까지 끌어올릴 이유는 없다.
엄격한 봇 차단 사이트는 두 도구 모두 답이 아니다. 이런 경우는 더 공격적인 stealth 방식이나 상용 API를 직접 써야 한다.
이런 사용자에게 맞는다
적합:
- RAG를 위해 웹페이지를 대량으로 LLM에 넣어야 하는 팀
- Agent의 도구 호출로 웹 콘텐츠를 가져와야 하는 개발자
- SaaS 종속 없이 자체 지식 베이스를 구축하고 싶은 개인
부적합:
- 가끔 한두 페이지만 크롤링하고 JS 렌더링도 필요 없는 경우 (그냥 requests면 끝)
- 비용에 민감하고 GPU도 없는 소규모 프로젝트 (브라우저 방식 자체가 비싸며, 인스턴스 하나에 메모리 200MB가 기본)
- 강한 봇 차단 사이트 (전용 stealth 모드가 없어서 Firecrawl만큼 공격적이지 않다)
편집자 관점에서
Crawl4AI의 진짜 해자는 "크롤링이 정확하다"는 점이 아니라, RAG 흐름에 발맞췄다는 데 있다. 같은 결의 프로젝트로 Firecrawl이 상업화 노선을 택해 유료로 수익을 챙기는 동안, unclecode는 오픈소스 + 클라우드 서비스 이중 트랙을 선택했고 8.4만 스타가 그 전략의 보상이다. 오픈소스로 생태계를 깔고, 클라우드 서비스로 수익을 뽑는 구조. GitHub의 크롤러 평가에서 이 정도 모멘텀이 나온 건 LLM 응용 폭발의 흐름을 탔기 때문이다.
예측: 2026년에는 이런 "웹페이지 → 구조화 데이터" 도구들이 더 계층화될 것이다. 경량 추출은 MCP 서버가 가져갈 가능성이 높다. 주요 사이트 (Stack Overflow, Hacker News, 공식 문서)마다 공식 또는 커뮤니티 운영 MCP 서버가 붙어, 곧바로 구조화된 결과만 반환하는 형태다. 무거운 추출은 Crawl4AI처럼 브라우저 렌더링을 갖춘 도구가 맡아 롱테일과 동적 콘텐츠를 처리한다. 중간 지점은 양쪽에 다 낌밥으로 쫄쫄 압박당할 것이다.
이번 회차가 과거와 결정적으로 다른 지점은, 크롤러의 사용자가 바뀌었다는 것이다. 예전에는 검색 엔진과 분석가를 위해 크롤링했지만, 이제는 LLM을 위해 크롤링한다. 요구사항이 달라졌다. "많고 빠르게 긁어오는 것"보다 "깔끔한 Markdown, 명확한 의미 경계, 완전한 메타 정보"가 더 중요해졌다. Crawl4AI 같은 프로젝트가 이 자리에서 올라올 수 있었던 근본 이유이기도 하고, scrapy, pyspider 같은 전통 크롤러 프레임워크가 반 박자 느린 이유이기도 하다.
불확실한 부분: 브라우저 자동화 자체의 비용이 계속 내려가고 있다. CDP 직접 연결, headless 최적화, GPT-4o-mini를 로컬 소형 모델로 대체하는 흐름이 1~2년 안에 이 아키텍처 전체를 다시 그릴 수도 있다. 지금의 "Playwright + LLM extractor" 조합이 최종 형태라고 단정하기는 이르다.