[RAG] Crawl4AI + LLM으로 구축한 웹 콘텐츠(이미지 + 텍스트) 추출 파이프라인(feat. Gemini)

https://github.com/unclecode/crawl4ai

GitHub - unclecode/crawl4ai: 🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper. Don't be shy, join here: https:/

 

파이썬으로 크롤링을 구현하신 분들은 Selenium이나 BeautifulSoup으로 특정 사이트 전용 스크레퍼를 만들어 본 경험이 있을 것입니다. 하지만 이 방식에는 명확한 한계가 있습니다.

1. 구조적 종속성: 크롤링 대상이 A 사이트에서 B 사이트로 바뀌는 순간, 모든 코드는 쓸모없어집니다. div.content-area가 article#main으로 바뀌었다는 이유만으로, 매번 새로운 스크레퍼를 작성해야 합니다.
2. 이미지 콘텐츠 부재: 더 큰 문제는 정보가 텍스트가 아닌 이미지에 담겨있는 경우입니다. alt 태그가 비어있는 차트, 배너, 다이어그램은 그저 '파일 경로'일 뿐, 그 안의 핵심 정보를 놓치게 됩니다.

저는 이 두 가지 한계(구조적 종속성, 이미지 콘텐츠 부재)를 동시에 극복하기 위해, 특정 사이트의 HTML 구조에 의존하지 않는 AI 크롤링 파이프라인을 구축했습니다. 

 

이 파이프라인은 먼저

1. crawl4ai의 딥크롤링으로 사이트의 모든 URL을 수집하고,

2. 각 페이지의 모든 이미지를 Gemini Vision 모델로 분석합니다.

3. 그 후, 원본 텍스트와 분석된 이미지 설명을 '하나의 HTML' 구조로 결합한 뒤,

4. 이 통합 문서를 다시 Gemini LLM에게 넘겨 "핵심 본문"만 걸러내도록 설계되었습니다.

 

이 글에서는 crawl4ai, Gemini, BeautifulSoup를 사용해 이 과정을 어떻게 자동화했는지, 그리고 각 기술을 선택한 근거는 무엇인지 상세히 공유합니다. 예시 크롤링 페이지는... 제 깃허브 페이지로 하겠습니다. 

https://github.com/moonjoo98?tab=repositories

moonjoo98 - Overview

 

사용한 핵심 기술은 다음과 같습니다.

• 크롤링 엔진: crawl4ai (AsyncWebCrawler, LLMContentFilter)
• AI 모델: Google Gemini 2.5 Flash (VLM 및 LLM)
• HTML 처리: BeautifulSoup
• 비동기 처리: asyncio

---

프로세스 1: 사이트 맵핑 (모든 유효 URL 수집)

가장 먼저, 우리가 처리해야 할 대상이 몇 개인지 알아야 합니다. crawl4ai의 딥크롤링 기술을 사용하여 사이트 전체를 스캔하여 방문 가능한 모든 페이지의 url를 수집했습니다. 

 

사용한 기술: crawl4ai의 BFSDeepCrawlStrategy (너비 우선 탐색)

1. 체계적인 탐색 (BFS > DFS): 모든 링크를 빠짐없이 찾는 것이 목표일 때, BFS(너비 우선)는 가장 체계적이고 안정적인 방법입니다. 1단계 깊이의 모든 링크를 찾고, 그다음 2단계 깊이의 모든 링크를 찾는 방식이죠. 반면 DFS(깊이 우선)는 특정 경로에 너무 깊이 빠져(예: 무한 캘린더 페이지) 다른 중요한 섹션을 놓칠 위험이 있습니다.
2. 명확한 경계 설정 (include_external=False): 저의 목표는 github.com 내부 콘텐츠입니다. include_external=False 옵션은 크롤러가 외부 SNS, 블로그, 광고 링크로 빠져나가 자원을 낭비하는 것을 막아줍니다.
3. 작업의 분리 (Separation of Concerns): "URL 수집"과 "콘텐츠 처리"는 완전히 다른 작업입니다. 이 두 작업을 분리하면, URL 수집이 실패하더라도 이미 처리한 콘텐츠는 안전하며, 나중에 콘텐츠 처리만 재시도할 수 있어 매우 안정적이고 효율적인 파이프라인이 됩니다.
   • 단, CrawlerRunConfig와 같이 딥크롤링과 텍스트 수집을 동시에 진행할 수도 있는데요. 이게 훨씬 더 효율적이고 빠르긴 하나, 저는 이미지에 적혀있는 텍스트와 이미지에 대한 설명이 모두 필요했기 때문에 작업을 분리했습니다.
   • crawl4ai에서도 Tesseract OCR과 같은 것을 불러와서 사용할 수 있는 것으로 알긴하는데, Tesseract OCR은 한국어 성능이 떨어지는 것 같기도하고 이미지에 대한 설명을 달아줄 수는 없어서 작업을 분리했습니다.

# 1단계: URL 수집 코드 예시
deep_crawl_config = BFSDeepCrawlStrategy(
    max_depth=5,          # 사이트 구조에 맞춰 적절한 깊이
    include_external=False, # 우리 도메인에만 집중
    max_pages=500         # 서버 부담을 줄이기 위한 안전장치
)

 

아래와 같이 시작 페이지 https://github.com/moonjoo98?tab=repositories 에서 모든 링크를 max_depth = 5 까지 탐색하면서 모든 링크를 빠짐없이 찾고 있고, githun.com 도메인의 URL만 수집하는 것을 보실 수 있습니다.

 

import asyncio
from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
from crawl4ai.deep_crawling import BFSDeepCrawlStrategy
from crawl4ai.content_scraping_strategy import LXMLWebScrapingStrategy

async def main():
    # 크롤링할 시작 URL
    start_url = "https://github.com/moonjoo98?tab=repositories"
    
    # 딥크롤링 전략 설정
    deep_crawl_config = BFSDeepCrawlStrategy(
        max_depth=5,  
        # include_external=False: 해당 도메인 내의 링크만 수집
        include_external=False, 
        max_pages=500 
    )

    # 전체 크롤러 실행 설정
    config = CrawlerRunConfig(
        deep_crawl_strategy=deep_crawl_config,
        scraping_strategy=LXMLWebScrapingStrategy(),
        verbose=True  # 크롤링 진행 상황을 콘솔에 출력
    )
    
    # 수집된 고유 링크를 저장할 Set
    collected_links = set()

    print(f"크롤링을 시작합니다. 대상: {start_url}")

    async with AsyncWebCrawler() as crawler:
        results = await crawler.arun(start_url, config=config)
        
        for result in results:
            if result.url:
                collected_links.add(result.url)

    print(f"\n--- 크롤링 완료 ---")
    print(f"총 {len(collected_links)}개의 고유한 링크를 수집했습니다.")
    
    # 수집된 링크 목록을 정렬하여 반환
    return sorted(list(collected_links))

# --- 메인 실행 부분 ---
if __name__ == "__main__":
    # main 함수를 실행하고 URL 리스트를 받음
    url_list = asyncio.run(main())
    
    # URL 리스트를 파일에 저장
    output_filename = "collected_urls_test.txt"
    try:
        with open(output_filename, "w", encoding="utf-8") as f:
            for url in url_list:
                f.write(url + "\n") # 각 URL을 새 줄에 저장
        
        print(f"'{output_filename}' 파일에 {len(url_list)}개의 URL을 성공적으로 저장했습니다.")
        
    except Exception as e:
        print(f"파일 저장 중 오류가 발생했습니다: {e}")

 

---

프로세스 2: 동적 HTML 콘텐츠 확보

수집한 URL을 이제 하나씩 처리합니다. 하지만 직접 해보시면 웹사이트는 requests.get()만으로는 원하는 HTML 구조를 모두 가져올 수 없다는 것을 아실겁니다.

• 사용한 기술: crawl4ai의 AsyncWebCrawler + BrowserConfig

1. 자바스크립트 렌더링 대응: 특정 사이트는 EgovPageLink.do?link=...와 같이 URL 파라미터를 기반으로 자바스크립트가 콘텐츠를 동적으로 생성합니다. requests나 httpx 같은 단순 라이브러리는 텅 빈 껍데기 HTML만 가져옵니다. BrowserConfig(headless=True)는 crawl4ai가 백그라운드에서 실제 브라우저(Playwright)를 실행하도록 지시합니다. 이 브라우저는 자바스크립트를 모두 실행하여 사용자가 보는 최종 렌더링 결과(HTML)를 우리에게 전달합니다.
2. 추상화의 편리함: Selenium이나 Playwright를 직접 쓰면 코드가 매우 복잡해집니다. crawl4ai는 이 복잡한 브라우저 제어를 crawler.arun(url)이라는 단 하나의 명령어로 추상화해 줍니다.

browser_config = BrowserConfig(headless=True, verbose=False) # 루프 중에는 False 권장
    crawl_config = CrawlerRunConfig(
        cache_mode=CacheMode.ENABLED,
        delay_before_return_html=2 # html이 모두 랜더링 될 때까지 지연시간 추가
    )
    
    final_result = { "url": url, "combined_markdown": None }

    try:
        print(f"  [시작] 크롤링 시작: {url}")
        async with AsyncWebCrawler(config=browser_config) as crawler:
            result = await crawler.arun(url, config=crawl_config)

---

프로세스 3: 이미지 의미론적 분석 (VLM)

HTML을 확보했다면, 이제 '텍스트'와 '이미지'를 분리합니다. 이미지는 단순한 파일이 아니라 그 자체로 중요한 콘텐츠입니다.

• 사용한 기술: BeautifulSoup + asyncio.gather + Gemini-2.5-Flash (Vision)

1. 신뢰할 수 없는 alt 태그: <img> 태그의 alt 속성은 대부분 비어있거나, "메인 배너", "아이콘"처럼 무의미합니다. 우리는 이미지에 실제로 무슨 내용이 있는지 알아야 합니다. Gemini는 이미지를 직접 보고 그 안에 담긴 텍스트를 그대로 인식하거나 표, 다이어그램, 상품 이미지 등의 설명을 생성할 수 있습니다.
2. 병렬 처리 : 한 페이지에 20개의 이미지가 있다면, 순차적으로 처리 시 1분 이상 걸릴 수 있습니다. asyncio.gather(*image_tasks)는 20개의 이미지 분석 요청을 동시에 Gemini 서버로 전송하고 가장 빠른 순서대로 응답을 받습니다. 이는 전체 프로세스 속도를 향상시키는 핵심 기술입니다.
3. 비용 및 노이즈 최적화 (MIN_IMAGE_SIZE): 웹페이지에는 1x1 픽셀짜리 추적용 이미지나 작은 아이콘이 많습니다. if img.width < 100: 같은 필터를 추가하여, 의미 없을 확률이 높은 작은 이미지에 대해서는 VLM API 호출을 차단했습니다.

async def get_image_description_from_llm(image_url: str):
    if not image_url or image_url.startswith("data:"):
        return "데이터 URI 또는 빈 이미지"
    
    
    model = genai.GenerativeModel('gemini-2.5-flash') 
    
    try:
        headers = {'User-Agent': 'Mozilla/5.0'} 
        response_img = requests.get(image_url, headers=headers, timeout=30) 
        response_img.raise_for_status()
        img = Image.open(BytesIO(response_img.content))

        if img.width < MIN_IMAGE_SIZE or img.height < MIN_IMAGE_SIZE:
            return "" # 필터링됨 (빈 문자열)
        
        response_llm = await model.generate_content_async([instruction_for_images, img])

        if not response_llm.parts:
            return "" 
        
        return response_llm.text
    except Exception as e:
        return f"LLM/이미지 다운로드/열기 실패: {e}"

async def process_url_structured(url: str):
    """
    하나의 URL을 받아 텍스트/이미지를 결합한 마크다운 결과를
    파이썬 딕셔너리 형태로 반환합니다.
    """
    
    browser_config = BrowserConfig(headless=True, verbose=False) # 루프 중에는 False 권장
    crawl_config = CrawlerRunConfig(
        cache_mode=CacheMode.ENABLED,
        delay_before_return_html=2 
    )
    
    final_result = { "url": url, "combined_markdown": None }

    try:
        print(f"  [시작] 크롤링 시작: {url}")
        async with AsyncWebCrawler(config=browser_config) as crawler:
            result = await crawler.arun(url, config=crawl_config)
            
            if not result.success or not result.cleaned_html:
                print(f"  [실패] HTML을 가져오지 못했습니다: {url}")
                return None # 실패 시 None 반환

            html_content = result.cleaned_html
            soup = BeautifulSoup(html_content, 'html.parser')

            # --- 단계 1: 이미지 태그 찾기 및 병렬 처리 준비 ---
            print(f"  [진행] LLM Vision 처리 (이미지)...")
            image_tags = soup.find_all('img')
            
            processed_urls = set()
            image_tasks = []
            url_to_tag_map = {} 

            for img_tag in image_tags:
                img_src = img_tag.get('src')
                if not img_src:
                    img_tag.decompose() # src 없는 태그는 HTML에서 제거
                    continue
                
                absolute_img_url = urljoin(url, img_src)
                
                if absolute_img_url in processed_urls:
                    continue # 중복 URL
                
                processed_urls.add(absolute_img_url)
                
                url_to_tag_map[absolute_img_url] = img_tag
                image_tasks.append(get_image_description_from_llm(absolute_img_url))

            # --- 단계 2: 모든 이미지 LLM 병렬 처리 ---
            if image_tasks:
                print(f"  [진행] 고유 이미지 {len(image_tasks)}개 병렬 처리 중...")
                image_results = await asyncio.gather(*image_tasks)
                print(f"  [완료] 이미지 LLM 처리 완료.")
            else:
                image_results = []

            # --- 단계 3: HTML에 이미지 설명 추가 ---
            for (img_url, img_tag), description in zip(url_to_tag_map.items(), image_results):
                if description and "LLM/이미지" not in description: 
                    # [성공] LLM 결과를 <img> 태그 대신 삽입
                    placeholder_text = f"\n\n--- [이미지: {img_url}] ---\n{description}\n--- [이미지 끝] ---\n\n"
                    img_tag.replace_with(BeautifulSoup(placeholder_text, 'html.parser'))
                else:
                    # [실패 또는 필터링됨] <img> 태그를 HTML에서 그냥 삭제
                    img_tag.decompose()

            # 중복 사용된 <img> 태그들 처리 (첫 번째가 아니었던 태그들)
            for img_tag in soup.find_all('img'):
                img_tag.decompose() # 남은 <img> 태그 모두 제거

            modified_html = str(soup)

            # --- 단계 4: 최종 텍스트 필터링 ---
            print(f"  [진행] LLM 필터링 (텍스트 + 이미지 설명 통합본)...")
            filter = LLMContentFilter(
                llm_config=LLMConfig(
                    provider="gemini/gemini-2.5-flash", # 모델명 수정
                    api_token=API_KEY
                ),
                instruction=instruction_to_keep_all, # HTML 구조에서 추출하고 싶은 부분을 프롬프트로 전달.
                verbose=False # 루프 중에는 False 권장
            )
            
            filtered_content_list = filter.filter_content(modified_html)
            final_result["combined_markdown"] = "\n".join(filtered_content_list)
            
            text_snippet = final_result["combined_markdown"][:100].replace("\n", " ")
            print(f"  [결과] 텍스트 (100자): {text_snippet}...")
            
            return final_result # 성공 시 결과 딕셔너리 반환

    except Exception as e:
        print(f"  [오류] {url} 처리 중 예외 발생: {e}")
        return None # 실패 시 None 반환

---

프로세스 4: 텍스트-이미지 콘텐츠 결합

이제 '원본 텍스트'와 '이미지 설명 텍스트'를 각각 가지고 있습니다. 근데 저는 웹페이지의 구조를 최대한 보존한 상태로 하나의 마크다운 구조로 변환하는 것이 목표입니다. 그래서 이미지 태그를 이미지 OCR 결과나 설명으로 교체해버려서 최대한 실제 웹페이지에 보이는 순서대로 텍스트를 배열합니다.

 

이렇게 텍스트-이미지 콘텐츠를 결합해서 최종 Output으로 정제하고 싶어 url 수집과 스크래핑 작업을 분리했습니다.

• 사용한 기술: BeautifulSoup의 img_tag.replace_with()

텍스트와 이미지 분석 결과를 별개의 파일로 저장하는 대신, 원본 HTML의 <img> 태그를 VLM이 분석한 "이미지 설명 텍스트"로 교체해 버렸습니다.

 

예시는 다음과 같습니다.

<p>시술 안내입니다.</p>
<img src="chart.jpg">
<p>주의사항입니다.</p>

<p>시술 안내입니다.</p>
"--- [이미지: .../chart.jpg] ---
증상(Symptom)과 치료법(Treatment)을 나타내는 표.
코막힘: 약물 치료
--- [이미지 끝] ---"
<p>주의사항입니다.</p>

 

이유: 이렇게 하면 '텍스트'와 '이미지'라는 두 종류의 데이터를 "하나의 순수한 텍스트 문서"로 통합할 수 있습니다. 이제 다음 단계의 LLM은 이 통합된 문서를 보고 "아, 이 텍스트 다음에 이런 이미지가 있었구나"라며 문맥(Context)을 완벽하게 이해할 수 있습니다. 그리고, 실제로 RAG에서 문서를 검색할 때도 관련 있는 이미지까지 포함해서 검색을 수행할 수 있어 성능 향상에 도움이 됩니다.

---

프로세스 5: 최종 콘텐츠 정제 (LLM)

이제 우리는 텍스트와 이미지 설명이 합쳐진, 하지만 여전히 "헤더", "푸터", "메뉴", "광고" 등 노이즈가 가득한 HTML을 가지고 있습니다.

• 사용한 기술: crawl4ai의 LLMContentFilter + 맞춤형 프롬프트

1. soup.get_text()의 한계: 단순히 get_text()를 쓰면 "Copyright", "로그인", "맨 위로 가기", "빠른 상담" 등 온갖 UI 텍스트가 뒤섞인 데이터가 나옵니다.
2. 프롬프트는 = 로직: 저는 AI에게 명확한 규칙을 지시했습니다. (instruction_to_keep_all는 프롬프트입니다.)
   • 규칙 1 (링크 정제): [대림점](/dl/index.do) 같은 마크다운 링크를 "대림점"이라는 순수 텍스트로 변환합니다. []()과 URL을 제거하여 의미만 남깁니다.
   • 규칙 2 (노이즈 제거): "공통 헤더/푸터", "사업자 정보", "Copyright" 등 [제외할 내용]에 명시된 모든 UI 요소를 삭제합니다.
   • 규칙 3 (본문 보존): [포함할 내용]에 명시된 "핵심 본문"과 "이미지 설명"은 보존합니다.
   • 규칙 4 (마크다운 변환):  LLM은 마크다운 포맷의 문맥을 더 잘 이해한다는 연구 결과가 있습니다. 또한, 테이블도 마크다운으로 변환하면 LLM의 표 이해도가 올라가기도 하죠. 그래서 HTML 구조를 마크다운 형식으로 변환한 최종 결과를 생성하도록 지시합니다.

LLMContentFilter는 이 지시문을 받아, 노이즈가 많은 modified_html을 입력받고, 우리가 원하는 순수한 핵심 콘텐츠(combined_markdown)만 마크다운 형식으로 출력해 줍니다.

---

결론

이 파이프라인은 Selenium 코드가 특정 HTML 구조에 종속되는 한계와, 이미지 중심의 콘텐츠를 놓치는 한계를 crawl4ai와 Gemini를 활용하여 극복했습니다.

 

각 단계에서 왜 requests 대신 브라우저를, 왜 alt 태그 대신 VLM을, 왜 순차 대신 병렬 처리를, 왜 get_text() 대신 LLM 필터를, 그리고 왜 단일 파일 대신 개별 파일을 선택했는지에 대해 제가 생각한 부분들도 글에 담아봤습니다.

 

물론, LLM으로 정제하고 이미지 해석을 맡기다보니 할루시네이션이 발생할 수도 있습니다. 이러한 경우를 고려한 후처리 방식들을 직접 구현하셔서 사용하시면 좋을 것 같습니다.

 

또한, 이미지 설명은 제외하고 OCR + 순수 텍스트 전체를 수집하고 싶으시다면 crawl4ai 자체 기능만으로도 충분히 구현 가능한 방법들이 있으니 아래의 공식 문서와 예시를 참고하여 필요한 상황에 맞게 사용하시면 좋을 것 같습니다.

 

감사합니다.