unclecode/crawl4ai

신뢰할 수 있는 대규모 웹 추출 솔루션으로, 이제 기존의 어떤 솔루션보다 * 훨씬 더 비용 효율적(cost-effective)* 으로 구축되었습니다.

👉 얼리 액세스(early access)를 위해 여기에서 신청하세요

단계별로 온보딩을 진행하며 초기 사용자들과 긴밀히 협력할 예정입니다.
자리가 한정되어 있습니다.

Crawl4AI는 웹을 RAG(검색 증강 생성), 에이전트(agents), 그리고 데이터 파이프라인(data pipelines)을 위해 깨끗하고 LLM(대규모 언어 모델) 준비가 된 마크다운(Markdown) 형식으로 변환합니다. 빠르고 제어 가능하며, 5만 개 이상의 스타(star)를 보유한 커뮤니티를 통해 검증되었습니다.

✨ v0.8.6 신규 사항: 보안 핫픽스(Security hotfix) — PyPI 공급망 공격(supply chain compromise)으로 인해 litellm을 unclecode-litellm으로 교체했습니다.

v0.8.5를 사용 중이라면 즉시 업그레이드하십시오.

✨ 최근 v0.8.5: 안티 봇 탐지(Anti-Bot Detection), Shadow DOM 및 60개 이상의 버그 수정! 프록시 에스컬레이션(proxy escalation)을 포함한 자동 3단계 안티 봇 탐지, Shadow DOM 평탄화(flattening), 딥 크롤(deep crawl) 취소, 설정 기본값 API, 동의 팝업 제거 및 중요한 보안 패치가 포함되었습니다. 릴리스 노트(Release notes) →

✨ 이전 v0.8.0: 크래시 복구(Crash Recovery) 및 프리페치 모드(Prefetch Mode)! 장시간 실행되는 크롤링을 위해 resume_state 및 on_state_change 콜백(callbacks)을 지원하는 딥 크롤 크래시 복구 기능이 추가되었습니다. URL 발견 속도를 5~10배 높여주는 새로운 prefetch=True 모드가 도입되었습니다. 릴리스 노트(Release notes) →

✨ 이전 v0.7.8: 안정성 및 버그 수정 릴리스! Docker API 문제, LLM 추출 개선, URL 처리 수정 및 종속성(dependency) 업데이트를 포함한 11개의 버그 수정이 이루어졌습니다. 릴리스 노트(Release notes) →

🤓 나의 개인적인 이야기

저는 아버지 덕분에 Amstrad로 자랐고, 만드는 일을 멈춘 적이 없습니다. 대학원 시절에는 NLP(자연어 처리)를 전공하며 연구용 크롤러를 구축했습니다. 그때 추출(extraction)이 얼마나 중요한지 배웠습니다.

2023년, 저에게는 웹-투-마크다운(web-to-Markdown) 기능이 필요했습니다. 당시 "오픈 소스" 옵션들은 계정 생성, API 토큰, 그리고 16달러의 비용을 요구하면서도 성능은 기대에 미치지 못했습니다. 저는 엄청난 분노 모드(turbo anger mode)에 진입하여 며칠 만에 Crawl4AI를 구축했고, 이는 바이럴(viral)이 되었습니다. 이제 이것은 GitHub에서 가장 많은 스타를 받은 크롤러가 되었습니다.

저는 **가용성(availability)**을 위해 이를 오픈 소스로 만들었습니다. 누구든 제약 없이 사용할 수 있도록 말이죠. 이제 저는 **경제성(affordability)**을 위한 플랫폼을 구축하고 있습니다. 누구든 큰 비용 부담 없이 본격적인 크롤링을 수행할 수 있도록 말입니다. 이 방향에 공감하신다면, 함께 참여하여 피드백을 보내주시거나, 그저 놀라운 무언가를 크롤링해 보세요.

개발자들이 Crawl4AI를 선택하는 이유

LLM 친화적 출력 (LLM ready output), 제목, 표, 코드, 인용 힌트가 포함된 스마트한 Markdown
실제 환경에서의 빠른 속도 (Fast in practice), 비동기 브라우저 풀 (async browser pool), 캐싱 (caching), 최소한의 홉 (minimal hops)
완전한 제어 (Full control), 세션 (sessions), 프록시 (proxies), 쿠키 (cookies), 사용자 스크립트 (user scripts), 훅 (hooks)
적응형 지능 (Adaptive intelligence), 사이트 패턴 학습, 중요한 요소만 탐색
어디든 배포 가능 (Deploy anywhere), 키 (keys) 불필요, CLI 및 Docker 지원, 클라우드 친화적

Crawl4AI 설치:

# 패키지 설치
pip install -U crawl4ai
# 프리릴리스 (pre release) 버전을 위한 설치
...

브라우저 관련 문제를 겪는 경우, 수동으로 설치할 수 있습니다:

python -m playwright install --with-deps chromium

Python으로 간단한 웹 크롤링 실행:

import asyncio
from crawl4ai import *
async def main():
...

또는 새로운 명령줄 인터페이스 (CLI) 사용:

# 마크다운 (markdown) 출력을 포함한 기본 크롤링
crwl https://www.nbcnews.com/business -o markdown
# BFS 전략을 사용한 딥 크롤 (Deep crawl), 최대 10페이지
...

🎉

스폰서십 프로그램 오픈! 5만 1천 명 이상의 개발자를 지원하고 1년간 성장해 온 Crawl4AI가 스타트업과 기업을 위한 전용 지원을 시작합니다. 우리의 명예의 전당 (Hall of Fame)에 영구적으로 이름을 올릴 수 있는 초기 50인의 창립 스폰서 (Founding Sponsors)가 되어보세요.

Crawl4AI는 GitHub에서 가장 인기 있는 (trending) 1위 오픈 소스 웹 크롤러입니다. 여러분의 후원은 Crawl4AI가 독립적이고 혁신적이며 커뮤니티를 위해 무료로 유지될 수 있게 하며, 동시에 여러분에게는 프리미엄 혜택을 직접 제공합니다.

🌱 Believer ($5/mo)— 데이터 민주화를 위한 움직임에 동참하세요
🚀 Builder ($50/mo)— 우선 지원 및 기능 조기 액세스
💼 Growing Team ($500/mo)— 격주 싱크 (syncs) 및 최적화 지원
🏢 Data Infrastructure Partner ($2000/mo)— 전담 지원을 포함한 전체 파트너십

맞춤형 협의 가능 - 자세한 내용 및 연락처는 SPONSORS.md를 참조하세요

왜 스폰서십을 해야 하나요?

속도 제한 (rate-limited)이 있는 API는 없습니다. 종속성 (lock-in)도 없습니다. Crawl4AI 제작자의 직접적인 가이드를 받으며 여러분만의 데이터 파이프라인을 구축하고 소유하세요.

📝 마크다운 생성 (Markdown Generation)

🧹
Clean Markdown (클린 마크다운): 정확한 포맷팅을 갖춘 깨끗하고 구조화된 마크다운을 생성합니다. - 🎯
Fit Markdown (핏 마크다운): AI 친화적인 처리를 위해 노이즈와 무관한 부분을 제거하는 휴리스틱(Heuristic) 기반 필터링을 수행합니다. - 🔗
Citations and References (인용 및 참조): 페이지 링크를 깔끔한 인용구가 포함된 번호 매겨진 참조 목록으로 변환합니다. - 🛠️
Custom Strategies (커스텀 전략): 사용자는 특정 요구 사항에 맞춘 자신만의 마크다운 생성 전략을 만들 수 있습니다. - 📚
BM25 Algorithm (BM25 알고리즘): 핵심 정보를 추출하고 무관한 콘텐츠를 제거하기 위해 BM25 기반의 필터링을 채택합니다.

📊 Structured Data Extraction (구조화된 데이터 추출)

🤖
LLM-Driven Extraction (LLM 기반 추출): 구조화된 데이터 추출을 위해 모든 LLM (오픈 소스 및 독점 모델)을 지원합니다. - 🧱
Chunking Strategies (청킹 전략): 타겟팅된 콘텐츠 처리를 위해 청킹 (주제 기반, 정규 표현식(regex), 문장 단위)을 구현합니다. - 🌌
Cosine Similarity (코사인 유사도): 의미론적 추출을 위해 사용자 쿼리를 기반으로 관련 콘텐츠 청크를 찾습니다. - 🔎
CSS-Based Extraction (CSS 기반 추출): XPath 및 CSS 선택자(selectors)를 사용하여 스키마 기반의 빠른 데이터 추출을 수행합니다. - 🔧
Schema Definition (스키마 정의): 반복적인 패턴에서 구조화된 JSON을 추출하기 위해 커스텀 스키마를 정의합니다.

🌐 Browser Integration (브라우저 통합)

🖥️
Managed Browser (관리형 브라우저): 사용자 소유의 브라우저를 사용하여 완전한 제어권을 가지며, 봇 탐지 (Bot Detection)를 회피합니다. - 🔄
Remote Browser Control (원격 브라우저 제어): Chrome Developer Tools Protocol에 연결하여 원격 및 대규모 데이터 추출을 수행합니다. - 👤
Browser Profiler (브라우저 프로파일러): 저장된 인증 상태, 쿠키 및 설정을 포함하는 지속적인 프로필을 생성하고 관리합니다. - 🔒
Session Management (세션 관리): 브라우저 상태를 보존하고 다단계 크롤링 (Multi-step Crawling)을 위해 재사용합니다. - 🧩
Proxy Support (프록시 지원): 보안 접속을 위해 인증 기능이 포함된 프록시와 원활하게 연결합니다. - ⚙️
Full Browser Control (전체 브라우저 제어): 맞춤형 크롤링 설정을 위해 헤더 (Headers), 쿠키 (Cookies), 사용자 에이전트 (User Agents) 등을 수정합니다. - 🌍
Multi-Browser Support (멀티 브라우저 지원): Chromium, Firefox 및 WebKit과 호환됩니다. - 📐
Dynamic Viewport Adjustment (동적 뷰포트 조정): 페이지 콘텐츠에 맞춰 브라우저 뷰포트 (Viewport)를 자동으로 조정하여, 완전한 렌더링과 모든 요소의 캡처를 보장합니다.

🔎 Crawling & Scraping (크롤링 및 스크래핑)

🖼️
Media Support (미디어 지원): 이미지, 오디오, 비디오 및 srcset 및 picture와 같은 반응형 이미지 형식을 추출합니다. - 🚀
Dynamic Crawling (동적 크롤링): 동적 콘텐츠 추출을 위해 JS를 실행하고 비동기 (Async) 또는 동기 (Sync) 작업을 기다립니다. - 📸
Screenshots (스크린샷): 디버깅 또는 분석을 위해 크롤링 중에 페이지 스크린샷을 캡처합니다. - 📂
Raw Data Crawling (원시 데이터 크롤링): 원시 HTML (raw:) 또는 로컬 파일 (file://)을 직접 처리합니다. - 🔗
Comprehensive Link Extraction (포괄적 링크 추출): 내부 링크, 외부 링크 및 임베디드 iframe 콘텐츠를 추출합니다. - 🛠️
Customizable Hooks (커스터마이징 가능한 훅): 크롤링 동작을 맞춤 설정하기 위해 모든 단계에서 훅 (Hooks)을 정의합니다 (문자열 및 함수 기반 API 모두 지원). - 💾
Caching (캐싱): 속도 향상 및 중복 페치 (Fetch) 방지를 위해 데이터를 캐싱합니다. - 📄
Metadata Extraction (메타데이터 추출): 웹 페이지에서 구조화된 메타데이터를 검색합니다. - 📡
IFrame Content Extraction (IFrame 콘텐츠 추출): 임베디드 iframe 콘텐츠에서 원활하게 추출합니다. - 🕵️
Lazy Load Handling (지연 로딩 처리): 이미지가 완전히 로드될 때까지 기다려, 지연 로딩 (Lazy Loading)으로 인해 콘텐츠가 누락되지 않도록 보장합니다. - 🔄
Full-Page Scanning (전체 페이지 스캐닝): 스크롤을 시뮬레이션하여 모든 동적 콘텐츠를 로드하고 캡처하며, 이는 무한 스크롤 (Infinite Scroll) 페이지에 적합합니다.

🚀 배포 (Deployment)

🐳 Docker화된 설정 (Dockerized Setup): 쉬운 배포를 위해 FastAPI 서버가 포함된 최적화된 Docker 이미지 제공.
🔑 보안 인증 (Secure Authentication): API 보안을 위한 내장된 JWT 토큰 인증.
🔄 API 게이트웨이 (API Gateway): API 기반 워크플로우를 위한 보안 토큰 인증이 포함된 원클릭 배포.
🌐 확장 가능한 아키텍처 (Scalable Architecture): 대규모 프로덕션 및 최적화된 서버 성능을 위해 설계됨.
☁️ 클라우드 배포 (Cloud Deployment): 주요 클라우드 플랫폼을 위한 즉시 배포 가능한 구성 제공.

🎯 추가 기능 (Additional Features)

🕶️ 스텔스 모드 (Stealth Mode): 실제 사용자를 모방하여 봇 탐지를 회피.
🏷️ 태그 기반 콘텐츠 추출 (Tag-Based Content Extraction): 커스텀 태그, 헤더 또는 메타데이터를 기반으로 크롤링 정교화.
🔗 링크 분석 (Link Analysis): 상세한 데이터 탐색을 위해 모든 링크를 추출하고 분석.
🛡️ 에러 핸들링 (Error Handling): 원활한 실행을 위한 강력한 에러 관리.
🔐 CORS 및 정적 서빙 (CORS & Static Serving): 파일 시스템 기반 캐싱 및 교차 출처 리소스 공유 (CORS) 요청 지원.
📖 명확한 문서 (Clear Documentation): 온보딩 및 고급 사용을 위한 단순화되고 업데이트된 가이드.
🙌 커뮤니티 인정 (Community Recognition): 투명성을 위해 기여자 및 풀 리퀘스트 (Pull Request) 명시.

✨ 문서 웹사이트를 방문하세요

Crawl4AI는 다양한 사용 사례에 적합한 유연한 설치 옵션을 제공합니다. Python 패키지로 설치하거나 Docker를 사용할 수 있습니다.

🐍 pip 사용하기

귀하의 필요에 가장 잘 맞는 설치 옵션을 선택하세요:

기본적인 웹 크롤링 및 스크레이핑 (Scraping) 작업을 위한 경우:

pip install crawl4ai
crawl4ai-setup # 브라우저 설정

기본적으로, 이는 웹 크롤링을 위해 Playwright를 사용하는 Crawl4AI의 비동기 (Asynchronous) 버전을 설치합니다.

👉 참고: Crawl4AI를 설치할 때, crawl4ai-setup이 자동으로 Playwright를 설치하고 설정해야 합니다. 하지만 Playwright 관련 에러가 발생할 경우, 다음 방법 중 하나를 사용하여 수동으로 설치할 수 있습니다:

명령줄 (Command Line)을 통해:

playwright install

위 방법이 작동하지 않으면, 더 구체적인 다음 명령어를 시도하세요:

python -m playwright install chromium

이 두 번째 방법은 일부 사례에서 더 신뢰할 수 있는 것으로 증명되었습니다.

동기식 (sync) 버전은 지원 중단 (deprecated) 되었으며 향후 버전에서 제거될 예정입니다. 만약 Selenium을 사용하는 동기식 버전이 필요하다면:

pip install crawl4ai[sync]

소스 코드를 수정할 계획이 있는 기여자(contributors)를 위한 안내:

git clone https://github.com/unclecode/crawl4ai.git
cd crawl4ai
pip install -e . # 편집 가능 모드 (editable mode)로 기본 설치

선택적 기능 (optional features) 설치:

pip install -e ".[torch]" # PyTorch 기능 포함
pip install -e ".[transformer]" # Transformer 기능 포함
pip install -e ".[cosine]" # 코사인 유사도 (cosine similarity) 기능 포함
...

🐳 Docker 배포 (Docker Deployment)

🚀

이제 사용 가능합니다! 완전히 재설계된 Docker 구현체가 출시되었습니다! 이 새로운 솔루션은 배포를 그 어느 때보다 효율적이고 매끄럽게 만들어 줍니다.

새로운 Docker 구현체에는 다음이 포함됩니다:

실시간 모니터링 대시보드 (Real-time Monitoring Dashboard): 실시간 시스템 메트릭 및 브라우저 풀 (browser pool) 가시성 제공
브라우저 풀링 (Browser pooling): 더 빠른 응답 시간을 위한 페이지 프리워밍 (pre-warming) 기능 포함
대화형 플레이그라운드 (Interactive playground): 요청 코드를 테스트하고 생성할 수 있는 환경
MCP 통합 (MCP integration): Claude Code와 같은 AI 도구에 직접 연결 가능
포괄적인 API 엔드포인트 (Comprehensive API endpoints): HTML 추출, 스크린샷, PDF 생성 및 JavaScript 실행 포함
멀티 아키텍처 지원 (Multi-architecture support): 자동 감지 기능 (AMD64/ARM64)
최적화된 리소스 (Optimized resources): 개선된 메모리 관리

# 최신 릴리스를 가져와서 실행
docker pull unclecode/crawl4ai:latest
docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g unclecode/crawl4ai:latest
...

빠른 테스트 실행 (두 Docker 옵션 모두 작동합니다):

import requests
# 크롤링 작업 제출
response = requests.post(
...

더 많은 예시는 Docker 예제 (Docker Examples)를 참조하세요. 고급 설정, 모니터링 기능 및 프로덕션 배포에 대해서는 셀프 호스팅 가이드 (Self-Hosting Guide)를 참조하세요.

docs/examples 디렉토리에서 프로젝트 구조를 확인할 수 있습니다. 그곳에서 다양한 예제를 찾을 수 있으며, 여기에는 몇 가지 인기 있는 예제들이 공유되어 있습니다.

📝 Clean 및 Fit Markdown을 사용한 휴리스틱 마크다운 생성

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode
from crawl4ai.content_filter_strategy import PruningContentFilter, BM25ContentFilter
...

🖥️ LLM 없이 JavaScript 실행 및 구조화된 데이터 추출

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode
from crawl4ai import JsonCssExtractionStrategy
...

📚 LLM을 사용한 구조화된 데이터 추출

import os
import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode, LLMConfig
...

🤖 사용자 지정 사용자 프로필을 이용한 자체 브라우저 사용

import os, sys
from pathlib import Path
import asyncio, time
...

💡 팁: 일부 웹사이트는 자동화된 접근을 방지하기 위해 CAPTCHA 기반 검증 메커니즘을 사용할 수 있습니다. 워크플로우에서 이러한 문제에 직면하는 경우, CapSolver와 같은 타사 CAPTCHA 처리 서비스를 선택적으로 통합할 수 있습니다. 이 서비스들은 reCAPTCHA v2/v3, Cloudflare Turnstile, Challenge, AWS WAF 등을 지원합니다. 사용 시 대상 웹사이트의 이용 약관 및 관련 법률을 준수해야 합니다.

Version 0.8.6 — 보안 긴급 패치: litellm 공급망 수정

원래 패키지에 영향을 미친 PyPI 공급망 문제로 인해 litellm 의존성을 unclecode-litellm 으로 교체했습니다. v0.8.5 이하 버전을 사용 중이라면 즉시 업그레이드하십시오.

pip install -U crawl4ai

Version 0.8.5 릴리스 하이라이트 - Anti-Bot 감지, Shadow DOM 및 60개 이상의 버그 수정