AnyCrawl을 사용하여 웹사이트를 LLM용 JSON으로 변환하는 방법

AnyCrawl을 사용하면 복잡한 웹 페이지를 LLM 애플리케이션을 위한 깔끔한 Markdown 또는 JSON 형식으로 변환할 수 있습니다. 이 튜토리얼에서는 AnyCrawl과 Atlas Cloud를 연동하여 모델 API 소스로 활용하는 방법, 단일 프로젝트 페이지를 스크랩하고 구조화된 필드를 추출하는 방법, 그리고 동일한 패턴을 확장하여 크롤링 및 검색 워크플로우를 구축하는 방법을 알아봅니다.

대부분의 웹 스크래핑 튜토리얼은 "HTML 다운로드"에서 끝납니다. 하지만 AI 앱의 경우, 진짜 작업은 바로 그 지점에서 시작됩니다. 원본 페이지에는 헤더, 푸터, 사이드바, 쿠키 배너, 중복 링크 및 JavaScript로 렌더링된 콘텐츠가 포함되어 있기 때문입니다. 모델에 실제로 필요한 것은 안정적인 데이터 인터페이스입니다. 즉, 문맥이 필요할 때는 깔끔한 텍스트가, 특정 필드가 필요할 때는 타입이 지정된 JSON이 필요합니다.

이것이 AnyCrawl의 핵심 개념입니다. AnyCrawl은 웹사이트를 LLM이 바로 처리할 수 있는 데이터로 변환하기 위해 설계된 Node.js/TypeScript 기반 크롤러 및 스크래퍼로, 단일 페이지 스크래핑, 사이트 크롤링, SERP 수집, 멀티스레딩/멀티프로세스 작업, 그리고 LLM 기반 JSON 추출 기능을 지원합니다.

우리가 만들 것

간단한 "프로젝트 리서치 추출기"를 만들어 보겠습니다.

입력:

plaintextCopy
1공개된 프로젝트 페이지 또는 문서 URL

출력:

plaintextCopy
1{
2  "project_name": "AnyCrawl",
3  "one_sentence_summary": "...",
4  "core_features": ["..."],
5  "best_for": ["..."],
6  "input_types": ["url", "search query"],
7  "output_formats": ["markdown", "json"],
8  "evidence_urls": ["..."]
9}

이 예제는 세 가지 AnyCrawl 기능을 활용합니다:

AnyCrawl의 Scrape API는 URL을 LLM이 바로 활용할 수 있는 구조화된 데이터로 변환하며, Markdown, HTML, 텍스트, 스크린샷, 원본 HTML, JSON, 요약 및 링크를 반환할 수 있습니다. 문서에 따르면 Scrape는 동기식으로 동작하므로 단일 페이지에 대해 별도의 폴링 루프를 작성할 필요가 없습니다.

단계별 가이드: AnyCrawl과 Atlas Cloud를 사용하여 웹페이지를 JSON으로 추출하기

이 튜토리얼에서는 Docker를 통해 AnyCrawl을 직접 호스팅하고, 추출을 위한 모델 API 제공자로 Atlas Cloud를 설정한 다음, 로컬 AnyCrawl 서버를 호출하여 웹페이지를 구조화된 JSON으로 변환합니다.

참고: 이 튜토리얼은 macOS 및 Linux 터미널 환경을 기준으로 작성되었습니다.

1단계: 프로젝트 폴더 생성

터미널을 열고 데모를 위한 작은 폴더를 만듭니다.

plaintextCopy
1mkdir anycrawl-atlas-demo
2cd anycrawl-atlas-demo

이 폴더에는 환경 파일과 API 테스트에 사용할 요청 본문만 저장됩니다.

2단계: Atlas Cloud API 키 발급

Atlas Cloud 콘솔로 이동하여 API Keys 페이지를 열고, Create API Key를 클릭한 후 키를 복사하여 안전하게 보관하세요. Atlas Cloud의 키는 생성 시 한 번만 표시되므로 반드시 안전한 곳에 저장해야 합니다.

키는 비공개로 유지하세요. 공개 GitHub 저장소, 공개 기사 초안, 스크린샷 등에 붙여넣지 마십시오.

3단계: .env 파일 생성

현재 폴더에 .env 파일을 생성합니다:

plaintextCopy
1cat > .env <<'EOF'
2NODE_ENV=production
3ANYCRAWL_API_PORT=8080
4ANYCRAWL_HEADLESS=true
5ANYCRAWL_API_AUTH_ENABLED=false
6
7ATLASCLOUD_BASE_URL=https://api.atlascloud.ai/v1
8ATLASCLOUD_API_KEY=YOUR_ATLASCLOUD_API_KEY
9DEFAULT_LLM_MODEL=atlascloud/deepseek-v4
10DEFAULT_EXTRACT_MODEL=atlascloud/deepseek-v4
11EOF

YOUR_ATLASCLOUD_API_KEY를 실제 키로 교체하세요.

모델 제공자를 설정하는 곳은 여기입니다. 스크랩 요청 자체는 URL, 출력 형식, JSON 스키마에 집중하고, 모델 라우팅은 AnyCrawl 서버 환경에서 관리해야 합니다. AnyCrawl이 LLM 기반 추출 단계를 실행하는 서비스이기 때문입니다.

4단계: Docker로 AnyCrawl 시작

참고: macOS의 경우, AnyCrawl을 시작하기 전에 Docker Desktop이 설치되어 실행 중인지 확인하세요. Apple Silicon Mac의 경우, amd64 이미지를 명시적으로 실행하지 않는다면 puppeteer 대신 auto 또는 playwright를 사용하세요.

All-in-one AnyCrawl 컨테이너를 실행하고 .env 파일을 마운트합니다.

plaintextCopy
1docker run -d \
2  --name anycrawl-atlas-demo \
3  -p 8080:8080 \
4  -v "$(pwd)/.env:/usr/src/app/.env:ro" \
5  ghcr.io/any4ai/anycrawl:latest

서비스가 정상 작동하는지 확인합니다:

plaintextCopy
1curl http://localhost:8080/health

Docker 문서는 로컬 배포를 위해 8080 포트를 사용하며, /health를 확인용 엔드포인트로 사용합니다.

5단계: 기본 스크랩 요청 테스트

JSON을 요청하기 전에, AnyCrawl이 페이지를 읽고 Markdown을 반환할 수 있는지 먼저 테스트합니다.

plaintextCopy
1curl -X POST "http://localhost:8080/v1/scrape" \
2  -H "Content-Type: application/json" \
3  -d '{
4    "url": "https://github.com/any4ai/AnyCrawl",
5    "engine": "auto",
6    "formats": ["markdown"],
7    "only_main_content": true
8  }'

AnyCrawl의 Scrape API는 URL을 LLM이 바로 활용할 수 있는 구조화된 데이터로 변환합니다. auto, cheerio, playwright, puppeteer와 같은 엔진을 지원하며, 출력 형식으로는 markdown, html, text, json, summary, links를 지원합니다.

첫 번째 요청에서는 markdown만으로 충분합니다. 모델에게 구조화된 필드 추출을 요청하기 전에 페이지 콘텐츠가 정상적으로 보이는지 확인하는 단계입니다.

6단계: JSON 추출 요청 생성

이제 AnyCrawl에게 구조화된 프로젝트 프로필 추출을 요청하는 본문을 생성합니다.

plaintextCopy
1cat > scrape-project.json <<'EOF'
2{
3  "url": "https://github.com/any4ai/AnyCrawl",
4  "engine": "auto",
5  "formats": ["markdown", "json"],
6  "only_main_content": true,
7  "extract_source": "markdown",
8  "json_options": {
9    "schema_name": "open_source_project_profile",
10    "schema_description": "A structured profile of an open-source project based only on the visible page content.",
11    "schema": {
12      "type": "object",
13      "properties": {
14        "project_name": {
15          "type": "string"
16        },
17        "one_sentence_summary": {
18          "type": "string"
19        },
20        "core_features": {
21          "type": "array",
22          "items": {
23            "type": "string"
24          }
25        },
26        "best_for": {
27          "type": "array",
28          "items": {
29            "type": "string"
30          }
31        },
32        "supported_tasks": {
33          "type": "array",
34          "items": {
35            "type": "string"
36          }
37        },
38        "developer_setup_notes": {
39          "type": "array",
40          "items": {
41            "type": "string"
42          }
43        }
44      },
45      "required": [
46        "project_name",
47        "one_sentence_summary",
48        "core_features"
49      ]
50    },
51    "user_prompt": "Extract only facts that are visible on the page. Do not guess. Summarize the project for a developer who wants to use web data in an AI application."
52  }
53}
54EOF

여기서 흔히 하는 실수가 있습니다. json_options를 사용할 때는 반드시 formats에 "json"을 포함해야 합니다. 그렇지 않으면 응답에 추출된 JSON 데이터가 포함되지 않습니다. AnyCrawl의 JSON 모드는 프롬프트 전용, 스키마 전용, 그리고 프롬프트와 스키마 혼합 추출을 모두 지원합니다. 이 튜토리얼에서는 필드 제어와 추출 가이드를 모두 활용하기 위해 혼합 방식을 사용합니다.

7단계: JSON 추출 실행

요청을 로컬 AnyCrawl 서버로 보냅니다:

plaintextCopy
1curl -X POST "http://localhost:8080/v1/scrape" \
2  -H "Content-Type: application/json" \
3  -d @scrape-project.json

설정이 올바르다면, 응답에 스크랩 결과와 정의한 스키마를 따른 JSON 추출 결과가 포함될 것입니다.

전체 워크플로우는 다음과 같습니다:

plaintextCopy
1GitHub 프로젝트 페이지
2→ 로컬 AnyCrawl 스크랩 API
3→ Markdown 추출
4→ LLM 기반 JSON 추출
5→ 구조화된 프로젝트 프로필

중요한 점은 요청 시 모델 제공자를 직접 호출할 필요가 없다는 것입니다. AnyCrawl이 스크랩 및 추출 워크플로우를 처리하며, 모델 API 소스는 서버 수준에서 이미 설정되어 있습니다.

8단계: Markdown이 비어 있다면 JavaScript 기반 페이지 시도

Markdown 결과가 너무 짧거나, 비어 있거나, 주요 콘텐츠가 누락되었다면 엔진을 playwright로 변경하세요.

plaintextCopy
1{
2  "url": "https://example.com",
3  "engine": "playwright",
4  "formats": ["markdown", "json"],
5  "only_main_content": true,
6  "json_options": {
7    "user_prompt": "Extract the main topic, key facts, and important links from this page."
8  }
9}

AnyCrawl 문서에 따르면 cheerio는 정적 HTML에 빠르고, playwright는 JavaScript 렌더링이 필요한 페이지에 적합하며, auto는 상황에 맞춰 엔진을 자동으로 선택하는 범용 옵션입니다.

9단계: 데모 컨테이너 중지 및 정리

테스트가 완료되면 컨테이너를 중지합니다:

plaintextCopy
1docker stop anycrawl-atlas-demo
2docker rm anycrawl-atlas-demo

나중에 .env 파일이 있는 폴더에서 Docker 명령을 다시 실행하여 동일한 워크플로우를 재개할 수 있습니다.

무엇을 구축했나요?

이제 공개 웹페이지를 스크랩하고, 이를 Markdown으로 정리한 뒤, 스키마 기반 LLM 워크플로우를 통해 구조화된 JSON을 추출할 수 있는 로컬 AnyCrawl 서비스를 갖게 되었습니다. 이 설정은 크롤러, 추출 모델, 애플리케이션 출력의 순서를 웹페이지(데이터 소스) → 구조화된 콘텐츠 → 앱 통합 순으로 유지합니다.

FAQ

AnyCrawl은 어디에 사용되나요?

AnyCrawl은 웹페이지, 웹사이트, 검색 결과를 Markdown이나 구조화된 JSON 등 LLM이 활용하기 좋은 데이터로 변환하는 데 사용됩니다. 단일 페이지 스크래핑, 전체 사이트 크롤링, SERP 수집, LLM 기반 JSON 추출을 지원하므로 RAG 앱, AI 에이전트, 연구 도구 및 내부 데이터 파이프라인에 유용합니다.

AnyCrawl로 웹페이지에서 JSON을 어떻게 추출하나요?

/v1/scrape를 사용하고 formats에 "json"을 포함한 뒤, 프롬프트나 스키마(또는 둘 다)를 담은 json_options를 전달하세요. json_options를 사용하면서 formats에 "json"을 빼먹으면 추출된 데이터가 반환되지 않으니 주의하세요.

AnyCrawl에서 Atlas Cloud를 어떻게 사용하나요?

개별 스크랩 요청 내부가 아닌, AnyCrawl 서버 환경 변수 설정을 통해 Atlas Cloud를 OpenAI 호환 LLM 제공자로 등록하세요. Atlas Cloud 문서에 명시된 기본 URL https://api.atlascloud.ai/v1과 함께 ATLASCLOUD_BASE_URL, ATLASCLOUD_API_KEY, 기본 추출 모델 설정 변수를 사용하면 됩니다.

AnyCrawl로 웹사이트 전체를 크롤링할 수 있나요?

네, /v1/crawl을 통해 비동기 크롤 작업이 가능합니다. max_depth, limit, include_paths, exclude_paths 등의 옵션으로 크롤링 범위를 제어하고 작업 상태를 폴링하여 결과를 가져올 수 있습니다.

AnyCrawl로 Google 검색 결과를 스크랩할 수 있나요?

네, URL을 스크랩하기 전에 구조화된 SERP 결과를 수집하는 검색 API를 제공합니다. query, pages, limit, lang, country, timeRange 매개변수를 지원하여 검색 쿼리에서 시작하는 AI 워크플로우에 적합합니다.

AnyCrawl이 Firecrawl이나 Crawl4AI보다 나은가요?

절대적인 비교는 어렵습니다. 사용 목적과 배포 환경에 따라 다릅니다. 이 튜토리얼처럼 로컬 Docker 서비스, 서버 수준의 모델 제공자 설정, 간단한 /v1/scrape JSON 워크플로우가 필요하다면 AnyCrawl이 적합한 선택이 될 수 있습니다.

AnyCrawl에서 Cheerio, Playwright, Puppeteer 중 무엇을 사용해야 하나요?

auto 또는 cheerio로 시작하고, JavaScript 렌더링이 필요한 페이지인 경우 playwright로 전환하세요. 정적 HTML에는 경량화된 cheerio가, 복잡한 페이지에는 브라우저 기반 엔진이 유리하므로 Markdown 결과를 먼저 확인한 후 필요할 때만 무거운 엔진을 사용하는 것이 실용적입니다.

AnyCrawl의 JSON 출력이 누락되는 이유는 무엇인가요?

가장 흔한 이유는 formats에 "json"을 포함하지 않았기 때문입니다. 또 다른 이유는 선택한 엔진이 페이지 콘텐츠를 제대로 가져오지 못한 경우(특히 JavaScript 렌더링 사이트)입니다. 이 경우 auto 또는 playwright로 재시도하고 Markdown 결과부터 먼저 확인하세요.

AnyCrawl을 RAG 데이터 파이프라인에 사용할 수 있나요?

네, 웹페이지를 Markdown이나 스키마 기반 JSON으로 변환하여 벡터 데이터베이스나 지식 시스템에 입력할 수 있어 RAG 준비에 매우 실용적입니다. 스크랩 후 필드 검증을 거치고 원본 URL과 Markdown을 디버깅용으로 유지하는 것이 생산적인 방식입니다.

초보자를 위한 가장 쉬운 AnyCrawl 워크플로우는 무엇인가요?

URL 하나를 스크랩하여 Markdown으로 출력하고 콘텐츠를 확인한 후, JSON 모드를 추가해 출력을 검증하고, 이후에 크롤링이나 검색으로 확장하는 것입니다. 이렇게 하면 페이지 접근 문제, 렌더링 문제, 추출 스키마 문제를 분리하여 디버깅하기 쉽습니다.

결론

AnyCrawl은 웹 페이지를 단순한 HTML 문서가 아닌 AI 시스템을 위한 입력값으로 처리하기 때문에 매우 유용합니다. 하나의 페이지부터 시작해 Markdown을 검토하고 스키마를 추가하여 JSON을 검증하는 순서로 진행하세요.

이 순서를 따르면 워크플로우가 단순해질 뿐만 아니라, 웹 데이터가 AI 앱의 일부가 되었을 때 발생할 수 있는 장애 지점을 명확하게 파악할 수 있습니다.