crawl4ai: 웹사이트를 LLM 친화적 마크다운으로 변환하는 설치 가이드

crawl4ai: 웹사이트를 LLM 친화적 마크다운으로 변환하는 설치 가이드

crawl4ai는 웹사이트를 LLM이 이해하기 쉬운 깔끔한 마크다운 형식으로 변환해주는 강력한 오픈소스 웹 크롤러입니다. 이 가이드에서는 pip를 이용한 설치와 Docker를 이용한 서버 구축 방법을 안내합니다.

1. pip를 이용한 설치

Python 환경에 crawl4ai를 직접 설치하여 사용하는 방법입니다. 로컬 환경에서 테스트하거나 자주 사용할 때 유용합니다.

1. 기본 설치: pip를 사용하여 crawl4ai를 설치합니다. -U 옵션은 최신 버전으로 업그레이드합니다.

   pip install -U crawl4ai
   

2. 브라우저 설정: crawl4ai는 백엔드에서 웹 페이지 렌더링을 위해 브라우저를 사용합니다. 다음 명령어로 필요한 브라우저를 설치하고 환경을 설정합니다.

   crawl4ai-setup
   

3. 설치 확인: 설정이 올바르게 되었는지 확인합니다.

   crawl4ai-doctor
   

   만약 crawl4ai-setup 과정에서 브라우저 설치에 실패했다면, Playwright를 직접 설치할 수 있습니다.

   python -m playwright install --with-deps chromium
   

2. Docker를 이용한 서버 구축

Docker 환경에서 crawl4ai 서버를 실행하여 API 형태로 서비스를 이용하는 방법입니다. 별도 환경 구축 없이 빠르게 시작할 수 있습니다.

1. API 토큰 생성 및 설정: crawl4ai 서버는 인증을 위해 API 토큰이 필요합니다. 임의의 32자리 16진수 토큰을 생성하여 환경 변수로 설정합니다. 이 토큰은 서버 외부에서 API 요청 시 사용됩니다.

   export CRAWL4AI_API_TOKEN="$(openssl rand -hex 32)"
   

2. Docker 컨테이너 실행: unclecode/crawl4ai:latest 이미지를 사용하여 Docker 컨테이너를 백그라운드(-d)로 실행합니다. 컨테이너 이름은 crawl4ai로 지정하고, 포트 11235를 호스트와 연결하며, 공유 메모리(--shm-size)를 1GB로 설정합니다. 앞서 설정한 API 토큰을 환경 변수로 전달합니다.

   docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g \
     -e CRAWL4AI_API_TOKEN="$CRAWL4AI_API_TOKEN" \
     unclecode/crawl4ai:latest
   

3. 서버 테스트: 컨테이너 시작 후 약 10초 뒤, curl 명령어를 사용하여 API가 정상적으로 응답하는지 확인합니다. news.ycombinator.com 웹사이트를 대상으로 마크다운 변환을 요청하고, 결과를 jq를 이용해 보기 좋게 출력합니다. 요청 시 Authorization 헤더에 발급받은 API 토큰을 포함해야 합니다.

   curl -s http://localhost:11235/md \
     -H "Authorization: Bearer $CRAWL4AI_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://news.ycombinator.com"}' | jq -r .markdown
   

   • 대시보드: http://localhost:11235/dashboard
   • 플레이그라운드: http://localhost:11235/playground

활용 사례

상황 1: LLM 학습용 데이터셋 구축 중 특정 웹사이트의 텍스트 추출이 어려운 경우

누가: AI 모델 개발자

무엇을 하려다 막혔나: 최신 기술 동향에 대한 정보를 LLM 학습 데이터셋에 포함시키려 했으나, 웹사이트의 복잡한 동적 요소나 광고 등으로 인해 단순 웹 스크래핑으로는 원하는 텍스트만 깔끔하게 추출하기 어려웠습니다.

어떤 단계: pip로 설치된 crawl4ai의 CLI 기능을 활용합니다.

1. crawl4ai가 설치된 환경에서 다음 명령어를 실행하여 특정 URL의 콘텐츠를 마크다운 형식으로 추출합니다.

   crawl4ai --url https://example.com/tech-news --output tech_news.md
   

결과: tech_news.md 파일에는 https://example.com/tech-news 페이지의 주요 텍스트 콘텐츠가 LLM이 처리하기 용이한 마크다운 형식으로 저장됩니다. 이를 통해 데이터 전처리 단계를 간소화하고 모델 학습에 집중할 수 있게 됩니다.

상황 2: 자체 구축한 LLM 에이전트가 외부 웹사이트 정보를 실시간으로 분석하도록 연동하고 싶은 경우

누가: DevOps 엔지니어

무엇을 하려다 막혔나: 개발 중인 LLM 에이전트가 실시간으로 뉴스 기사를 요약하고 답변하는 기능을 구현하고 싶었으나, 웹사이트 내용을 API 요청으로 받아 처리하는 과정이 매끄럽지 않았습니다.

어떤 단계: Docker로 실행 중인 crawl4ai 서버의 API를 활용합니다.

1. LLM 에이전트 코드 내에서 crawl4ai Docker 서버로 HTTP POST 요청을 보냅니다. 요청 본문에는 크롤링할 URL과 인증을 위한 API 토큰을 포함합니다.

   import requests
   import os
   
   CRAWL4AI_URL = "http://localhost:11235/md"
   API_TOKEN = os.environ.get("CRAWL4AI_API_TOKEN") # Docker 실행 시 설정한 토큰
   target_url = "https://news.ycombinator.com"
   
   headers = {
       "Authorization": f"Bearer {API_TOKEN}",
       "Content-Type": "application/json"
   }
   data = {"url": target_url}
   
   try:
       response = requests.post(CRAWL4AI_URL, headers=headers, json=data)
       response.raise_for_status() # HTTP 오류 발생 시 예외 발생
       result = response.json()
       markdown_content = result.get("markdown")
       
       # markdown_content를 LLM 에이전트의 입력으로 사용
       print("Successfully fetched markdown content.")
       # print(markdown_content)
   except requests.exceptions.RequestException as e:
       print(f"Error fetching data from crawl4ai: {e}")
   
   

결과: LLM 에이전트는 crawl4ai API를 통해 웹사이트의 텍스트를 마크다운 형식으로 받아 처리할 수 있게 됩니다. 이를 통해 에이전트는 최신 정보를 기반으로 요약, 질의응답 등 더욱 정확하고 풍부한 기능을 수행할 수 있습니다.

출처: https://github.com/unclecode/crawl4ai