웹 문서를 rag 지식 베이스나 AI 에이전트 입력으로 쓰려면 광고와 네비게이션이 섞인 HTML보다 본문 중심 Markdown과 구조화 데이터가 유용하다. Crawl4AI는 비동기 브라우저 크롤링, HTML-to-Markdown 변환, CSS/XPath 또는 LLM 기반 추출을 결합한 Python 오픈소스 크롤러다. 공식 README는 5만 개 이상의 GitHub 스타 커뮤니티가 사용한다고 소개하며, 현재 README 기준 v0.8.6은 공급망 보안 문제 대응을 포함한다.

어떤 문제를 푸나

최소 사용법

pip install -U crawl4ai
crawl4ai-setup
crawl4ai-doctor

import asyncio
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun("https://example.com")
        print(result.markdown)

asyncio.run(main())

AsyncWebCrawler는 기본적으로 페이지를 가져와 Markdown을 만든다. 탐색 메뉴나 반복 요소를 줄여 LLM 입력 크기를 관리하려면 DefaultMarkdownGenerator에 콘텐츠 필터를 연결하고 result.markdown.fit_markdown을 사용한다.

구조화 추출과 인제스트 파이프라인

단순 문서 수집은 Markdown이 적합하지만, 가격 목록이나 공고 카드처럼 반복 구조가 있는 페이지는 JSON으로 뽑는 편이 낫다. Crawl4AI는 CSS/XPath 추출을 지원하므로 정해진 DOM 구조를 가진 사이트에서는 LLM 호출 없이도 빠르고 재현 가능한 수집이 가능하다. 구조가 불규칙한 페이지에만 LLM 추출을 적용하면 비용과 변동성을 줄일 수 있다.

URL 목록
  -> 브라우저 크롤링
  -> 본문 Markdown 또는 schema 기반 JSON
  -> 중복 제거·출처 기록
  -> 임베딩/키워드 색인
  -> RAG 또는 에이전트 도구

운영 시 주의점

• v0.8.5 이하 사용자는 공식 README가 안내하는 공급망 보안 핫픽스가 포함된 최신 버전으로 업그레이드할 필요가 있다.
• robots 정책, 서비스 약관, 인증이 필요한 데이터의 접근 권한을 수집 전에 확인한다.
• 대량 크롤링에서는 캐시, 속도 제한, 재개 상태와 출처 URL 기록을 설계한다.
• LLM 기반 추출은 입력 데이터를 외부 모델 제공자에게 보낼 수 있으므로 민감 데이터에는 schema 기반 로컬 추출을 우선한다.

언제 사용하면 좋은가

• 웹 문서를 Markdown으로 변환해 RAG 색인에 넣는 팀
• 동적 페이지를 읽어야 하는 조사·모니터링 에이전트
• DOM이 정해진 사이트에서 JSON 추출과 LLM 요약을 분리하려는 데이터 파이프라인
• API 키가 필요한 외부 스크레이핑 서비스 대신 직접 실행 가능한 오픈소스 수집기를 원하는 경우

라이선스

Apache-2.0 라이선스로 공개되어 있다.

관련 문서

• rag — 수집한 문서를 검색·생성에 연결하는 기본 아키텍처
• rag-tutorial-hybrid-search-python — 색인한 문서를 하이브리드 검색하는 최소 구현
• agent-friendly-websites — 에이전트가 읽고 조작하기 쉬운 웹 구조

참고 자료

• unclecode/crawl4ai — GitHub 공식 저장소
• Getting Started with Crawl4AI — Crawl4AI Docs (v0.8.x)