lasta/AI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dd7bc4e8942a492c5fbe6276dffdceaf9ef48761
AI/오픈소스분석자료/Firecrawl_분석_및_기능명세.md
LASTA_DEV01\lasta 9e88f4c7ad ontology
2026-05-13 19:57:34 +09:00

31 KiB
Raw Blame History

Firecrawl 프로젝트 분석 및 기능명세

분석 대상: C:\Users\lasta\MyProject\AI\참고\firecrawl-main
분석일: 2026-05-13
목적: 범용 온톨로지 구축 플랫폼의 웹 수집/정제/구조화 기반 소스로 Firecrawl을 거의 원형에 가깝게 재사용할 수 있는지 판단하고, 향후 구현 기준이 될 기능 명세를 정리한다.

1. 결론 요약

Firecrawl은 단순 크롤러가 아니라 검색 -> URL 발견 -> 페이지 수집 -> 동적 브라우저 실행 -> Markdown/HTML/JSON/스크린샷/파일 파싱 -> 비동기 작업 관리 -> SDK 제공까지 포함하는 웹 데이터 수집 API 플랫폼이다. 현재 프로젝트의 범용 온톨로지 구축 플랫폼에는 다음 영역이 특히 직접 재사용 가치가 높다.

  • apps/api/src/scraper/scrapeURL: 단일 URL 수집의 핵심. Fetch, Playwright, PDF, 문서, 인덱스, Fire-engine 계열 엔진을 fallback 방식으로 선택한다.
  • apps/api/src/scraper/WebScraper/crawler.ts: 사이트 내부 URL 탐색, sitemap, robots.txt, include/exclude path, depth, subdomain/external link 제어.
  • apps/api/src/controllers/v2/types.ts: API 입력/출력 스키마. 특히 scrape/crawl/map/search 옵션 체계가 잘 정리되어 있다.
  • apps/api/src/controllers/v2/*: 외부 API 기능 명세의 실제 기준. scrape, crawl, map, search, batch scrape, parse, monitor, browser, agent로 분리되어 있다.
  • apps/api/src/services/worker/scrape-worker.ts, queue-*: 대량 수집, 크롤 작업, billing/logging/webhook/상태 관리의 운영 흐름.
  • apps/python-sdk, apps/js-sdk/firecrawl: 우리 플랫폼 API 클라이언트 설계 시 참고할 수 있는 SDK 표면.

다만 Firecrawl은 Node.js/TypeScript 기반의 API 서버, Redis/BullMQ 또는 NuQ/RabbitMQ/Postgres, Playwright microservice, Supabase/Autumn/Stripe/GCS/Sentry 등 SaaS 운영 요소가 섞여 있다. 현재 Python/FastAPI/SQLAlchemy 기반 프로젝트에 그대로 병합하기보다는, Firecrawl을 별도 수집 서비스로 두고 Python 온톨로지 파이프라인이 Firecrawl API를 호출하는 구조가 가장 안전하다.

2. 프로젝트 성격

Firecrawl의 제품 목표는 웹 페이지를 LLM/RAG/Agent가 바로 사용할 수 있는 깨끗한 데이터로 변환하는 것이다. 제공 기능은 다음 세 가지 축으로 요약된다.

  • 단일 페이지 변환: URL을 Markdown, HTML, raw HTML, link/image 목록, screenshot, structured JSON 등으로 변환한다.
  • 사이트 단위 수집: seed URL에서 sitemap과 링크 그래프를 따라가며 여러 페이지를 비동기로 수집한다.
  • 지능형 데이터 추출: JSON Schema, LLM prompt, browser action, search result scraping, file parsing을 결합한다.

온톨로지 구축 플랫폼 관점에서는 Firecrawl이 웹 수집 계층과 텍스트/문서 정제 계층을 맡고, 현재 프로젝트의 Python 코드는 도메인 어댑터, 엔티티/관계 추출, Claim/Evidence 저장, 추천/검증 UI를 맡는 분업이 적합하다.

3. 최상위 구조

firecrawl-main/
  apps/
    api/                    # 핵심 API 서버, 스크래퍼, 크롤러, 큐/워커
    playwright-service-ts/  # Playwright 브라우저 마이크로서비스
    python-sdk/             # Python SDK
    js-sdk/firecrawl/       # JS/TS SDK
    php-sdk, ruby-sdk,
    rust-sdk, elixir-sdk    # 다언어 SDK
    ui/ingestion-ui/        # ingestion UI
    test-suite/             # API/load 테스트
    test-site/              # 테스트용 사이트
    go-html-to-md-service/  # HTML -> Markdown 변환 보조 서비스
    nuq-postgres/           # NuQ 큐용 Postgres 구성
  examples/                 # LLM/agent/추출 예제 다수
  docker-compose.yaml       # self-host 전체 구성
  SELF_HOST.md              # 자체 호스팅 안내
  README.md                 # 제품/SDK/API 개요

핵심은 apps/api이다. 나머지는 SDK, 배포, 예제, 테스트, UI 보조 레이어다.

4. 기술 스택

  • 언어: TypeScript/Node.js, 일부 Rust native package, 일부 Go service
  • API: Express, express-ws, Zod validation, multer multipart
  • 브라우저: 별도 playwright-service-ts, Fire-engine CDP/TLS client 연동 가능
  • HTML 처리: Cheerio, JSDOM, Turndown, joplin-turndown-plugin-gfm, Rust 기반 link filtering/extraction
  • 문서 처리: PDF, DOC/DOCX/ODT/RTF/XLS/XLSX 계열 파일 처리 모듈
  • 큐/상태: BullMQ, Redis, NuQ, RabbitMQ, Postgres
  • 검색: Google 기본, SearXNG 대체, DuckDuckGo/v2 검색 코드
  • LLM: OpenAI, Anthropic, Google, Groq, xAI, OpenRouter, Ollama/OpenAI-compatible
  • 운영: Docker Compose, Kubernetes/Helm 예제, Sentry, Prometheus, logging, billing

5. 런타임 아키텍처

flowchart TD
    A["Client / SDK / API"] --> B["Express v2 Router"]
    B --> C["Auth / rate limit / credit / blocklist"]
    C --> D{"Endpoint"}
    D --> E["Scrape Controller"]
    D --> F["Crawl Controller"]
    D --> G["Map Controller"]
    D --> H["Search Controller"]
    E --> I["scrapeURL engine fallback"]
    F --> J["WebCrawler URL discovery"]
    J --> K["Queue scrape jobs"]
    G --> J
    H --> L["Search provider"]
    H --> I
    K --> M["Scrape Worker"]
    M --> I
    I --> N["Fetch / Playwright / PDF / Document / Index / Fire-engine"]
    N --> O["Markdown / metadata / formats / actions"]
    O --> P["Result / status / webhook / logs"]

핵심 흐름

  1. API 요청은 apps/api/src/routes/v2.ts에서 endpoint별 controller로 라우팅된다.
  2. Zod 스키마가 URL, 옵션, format, crawler option을 strict하게 검증한다.
  3. 단일 scrape는 동기적으로 처리하되 내부적으로 semaphore와 worker 공통 함수를 사용한다.
  4. crawl/batch scrape는 작업 ID를 반환하고 큐에 개별 scrape job을 넣는다.
  5. worker는 URL별로 scrapeURL을 실행하고 성공/실패/robots 차단/비용/로그/웹훅을 기록한다.
  6. 결과는 status endpoint, websocket, webhook, SDK polling을 통해 조회된다.

6. 핵심 모듈 분석

6.1 API 라우터

파일: apps/api/src/routes/v2.ts

주요 endpoint:

  • POST /v2/search
  • POST /v2/parse
  • POST /v2/scrape
  • GET /v2/scrape/:jobId
  • POST /v2/scrape/:jobId/interact
  • DELETE /v2/scrape/:jobId/interact
  • POST /v2/batch/scrape
  • GET /v2/batch/scrape/:jobId
  • DELETE /v2/batch/scrape/:jobId
  • GET /v2/batch/scrape/:jobId/errors
  • POST /v2/map
  • POST /v2/crawl
  • POST /v2/crawl/params-preview
  • GET /v2/crawl/ongoing
  • GET /v2/crawl/:jobId
  • DELETE /v2/crawl/:jobId
  • WS /v2/crawl/:jobId
  • GET /v2/crawl/:jobId/errors
  • POST /v2/extract
  • GET /v2/extract/:jobId
  • POST /v2/agent
  • GET /v2/agent/:jobId
  • DELETE /v2/agent/:jobId
  • POST /v2/monitor
  • GET /v2/monitor
  • GET /v2/monitor/:monitorId
  • PATCH /v2/monitor/:monitorId
  • DELETE /v2/monitor/:monitorId
  • POST /v2/monitor/:monitorId/run
  • GET /v2/monitor/:monitorId/checks
  • GET /v2/monitor/:monitorId/checks/:checkId
  • POST /v2/browser
  • GET /v2/browser
  • POST /v2/browser/:sessionId/execute
  • DELETE /v2/browser/:sessionId
  • GET /v2/team/credit-usage
  • GET /v2/team/token-usage
  • GET /v2/concurrency-check
  • GET /v2/team/queue-status
  • GET /v2/team/activity

우리 프로젝트에서 우선 필요한 것은 scrape, crawl, map, batch scrape, parse, search다. billing, credit, team, x402, agent signup, support proxy는 초기에는 제외 가능하다.

6.2 스키마와 옵션 체계

파일: apps/api/src/controllers/v2/types.ts

Firecrawl은 입력 옵션을 Zod로 strict validation한다. 알 수 없는 key는 거부하는 방식이라 API 안정성이 높다.

공통 Scrape 옵션

  • formats: 기본 markdown. 지원 format은 markdown, html, rawHtml, links, images, summary, json, changeTracking, screenshot, attributes, branding, question, highlights, query, audio.
  • headers: 요청 header.
  • includeTags, excludeTags: 특정 selector 포함/제외. iframe selector 변환도 처리한다.
  • onlyMainContent: 기본 true. 본문 중심 추출.
  • onlyCleanContent: 기본 false.
  • timeout: 최소 1000ms.
  • waitFor: 기본 0, 최대 60000ms, timeout의 절반 이하.
  • mobile: 모바일 viewport 사용.
  • parsers: PDF/문서 parser 옵션.
  • actions: wait/click/write/press/scroll/scrape/screenshot 등 브라우저 액션.
  • location: country/languages. 기본 country는 us-generic.
  • skipTlsVerification: TLS 검증 skip.
  • removeBase64Images: 기본 true.
  • fastMode: 빠른 수집 모드.
  • blockAds: 기본 true.
  • proxy: basic, stealth, enhanced, auto. 기본 auto.
  • maxAge, minAge, storeInCache: 캐시 사용 기준.
  • lockdown: 캐시/index 기반 제한 모드.
  • profile: 브라우저 profile 이름과 저장 여부.

중요 transform:

  • JSON format이 있고 기본 timeout 30000ms이면 60000ms로 늘린다.
  • stealth/enhanced/auto proxy이며 기본 timeout이면 120000ms로 늘린다.
  • changeTracking은 markdown format을 요구하고 waitFor/timeout을 늘린다.
  • actions + waitFor 총 대기 시간은 60초를 넘지 못한다.

Crawler 옵션

  • includePaths: 포함할 path regex.
  • excludePaths: 제외할 path regex.
  • maxDiscoveryDepth: 발견 깊이 제한.
  • limit: 기본 10000.
  • crawlEntireDomain: 전체 domain 허용.
  • allowExternalLinks: 기본 false.
  • allowSubdomains: 기본 false.
  • ignoreRobotsTxt: 기본 false.
  • robotsUserAgent: robots.txt 확인 user-agent.
  • sitemap: skip, include, only. 기본 include.
  • deduplicateSimilarURLs: 기본 true.
  • ignoreQueryParameters: 기본 false.
  • regexOnFullURL: 기본 false.
  • delay: URL 간 delay.

Map 옵션

Map은 URL 목록 발견용이다. 기본 includeSubdomains=true, ignoreQueryParameters=true, limit=5000, 최대 100000이다. search, sitemap, filterByPath, useIndex, ignoreCache, location, headers를 지원한다.

Search 옵션

  • query: 검색어.
  • limit: 기본 10, 최대 100.
  • sources: web, images, news.
  • categories: github, research, pdf.
  • includeDomains, excludeDomains: 동시에 지정 불가.
  • lang: 기본 en.
  • country/location.
  • timeout: 기본 60000ms.
  • asyncScraping: 검색 결과 scraping을 비동기 job으로 반환 가능.
  • scrapeOptions: 검색 결과 페이지를 바로 scrape할 때 사용하는 제한된 scrape 옵션.

6.3 단일 URL 수집 엔진

파일: apps/api/src/scraper/scrapeURL/index.ts, apps/api/src/scraper/scrapeURL/engines/index.ts

Firecrawl의 핵심은 URL과 요청 feature를 보고 엔진 후보를 만든 뒤 fallback 순서로 시도하는 구조다.

지원 엔진:

  • index: 기존 index/cache에서 문서 조회.
  • index;documents: 문서 index 조회.
  • fire-engine;chrome-cdp: 고급 브라우저 엔진.
  • fire-engine;chrome-cdp;stealth: stealth proxy 브라우저 엔진.
  • fire-engine;tlsclient: TLS client 기반 수집.
  • fire-engine;tlsclient;stealth: stealth TLS client.
  • playwright: 자체 Playwright microservice.
  • fetch: HTTP fetch 기반 빠른 수집.
  • pdf: PDF 전용 처리.
  • document: DOCX/ODT/RTF/XLS/XLSX 등 문서 처리.
  • wikipedia: Wikimedia 전용 엔진.
  • x-twitter: X/Twitter 전용 엔진.

Feature flag:

  • actions, waitFor, screenshot, screenshot@fullScreen, pdf, document, audio, atsv, location, mobile, skipTlsVerification, useFastMode, stealthProxy, branding, disableAdblock.

선택 방식:

  1. URL 확장자, option, format을 보고 필요한 feature flag를 계산한다.
  2. 각 엔진이 feature를 지원하는지 확인한다.
  3. quality와 feature priority를 기준으로 fallback list를 만든다.
  4. 엔진별 max reasonable time을 계산하고 timeout/abort manager와 함께 실행한다.
  5. HTML을 Markdown으로 변환하고 metadata, links, images, screenshot, extract 결과 등을 조립한다.
  6. 실패 시 NoEnginesLeftError, DNSResolutionError, SSLError, PDFOCRRequiredError, ActionError, CrawlDenialError 등 typed error로 전달한다.

온톨로지 플랫폼에는 이 구조가 매우 유용하다. 특정 쇼핑몰/공식몰/문서/PDF마다 직접 fetcher를 분기하지 않고, Firecrawl이 feature 기반 fallback을 담당하게 할 수 있다.

6.4 URL 발견과 사이트 크롤링

파일: apps/api/src/scraper/WebScraper/crawler.ts

WebCrawler는 seed URL에서 사이트 내부 링크를 발견하고 filtering한다.

주요 기능:

  • sitemap 로드와 sitemap 링크 제한.
  • robots.txt 로드와 robots parser.
  • max depth, max discovery depth 적용.
  • include/exclude regex path filtering.
  • backward crawling 차단.
  • external link/subdomain 허용 여부 판단.
  • query parameter 무시/중복 제거.
  • 비웹 프로토콜, social/mailto, section anchor, 비문서 file type 제거.
  • URL별 denial reason 생성.

현재 프로젝트의 crawler_platform.app.core.crawler.discovery, site_crawler, content_zone, fetchers를 Firecrawl 방식으로 강화할 수 있다. 단, Python 코드에 직접 포팅하기보다는 POST /v2/map 또는 POST /v2/crawl을 호출해 URL discovery를 위임하는 것이 빠르다.

6.5 Crawl 작업 처리

파일: apps/api/src/controllers/v2/crawl.ts, apps/api/src/services/worker/scrape-worker.ts

Crawl은 단일 요청에서 모든 페이지를 즉시 반환하지 않는다.

처리 절차:

  1. crawlRequestSchema로 URL, crawler option, scrape option 검증.
  2. 자연어 prompt가 있으면 site structure를 일부 map한 뒤 LLM으로 crawler option 생성.
  3. include/exclude regex 유효성 확인.
  4. credit 또는 self-host 설정에 따라 limit 조정.
  5. Redis/queue에 StoredCrawl 저장.
  6. kickoff job을 큐에 넣고 id, status URL을 반환.
  7. worker가 URL을 발견하고 개별 scrape job으로 확장한다.
  8. GET /v2/crawl/:jobId 또는 websocket으로 진행률과 결과를 조회한다.

응답 status:

  • scraping
  • completed
  • failed
  • cancelled

status 응답은 completed, total, creditsUsed, expiresAt, next, data: Document[]를 포함한다.

6.6 Search

파일: apps/api/src/controllers/v2/search.ts, apps/api/src/search/*

Search는 검색 결과를 반환하고, 옵션에 따라 각 결과 페이지를 scrape해서 markdown까지 포함한다.

온톨로지 플랫폼 활용:

  • 브랜드/상품/성분/카테고리 후보 URL 발견.
  • 공식 문서, PDF, research 자료 검색.
  • seed URL이 부족한 신규 도메인 bootstrap.
  • includeDomains/excludeDomains로 신뢰 출처 제한.

초기 MVP에서는 외부 검색 품질보다 검색 결과 -> 후보 Source/Page -> 검토 큐 흐름을 만드는 것이 중요하다.

6.7 Parse

POST /v2/parse는 multipart file upload를 받아 HTML/PDF/document를 scrape-like document로 변환한다. 파일 크기 제한은 50MB다.

온톨로지 플랫폼 활용:

  • 로컬 PDF catalog, 제품 설명서, 성분표 문서 ingest.
  • HTML fixture나 저장된 페이지 snapshot ingest.
  • URL이 아닌 파일 기반 evidence 확보.

6.8 Browser / Interact / Actions

Firecrawl은 두 종류의 상호작용을 제공한다.

  • scrape request의 actions: scrape 전에 wait, click, write, press, scroll, screenshot, scrape 등을 수행한다.
  • POST /v2/scrape/:jobId/interact: scrape job에 연결된 browser session에 code 또는 prompt 기반 조작을 수행한다.

온톨로지 플랫폼 활용:

  • 쿠키 배너 닫기.
  • 검색/필터/더보기 버튼 클릭.
  • pagination 또는 lazy-loaded product list 수집.
  • 특정 selector 대기 후 수집.

주의: action 기반 수집은 재현성과 비용이 낮아질 수 있으므로, Source 단위 설정으로 제한하고 audit log를 남기는 것이 좋다.

6.9 Monitor

Monitor는 특정 URL/옵션을 주기적으로 실행하고 check 결과/diff를 관리하는 기능이다.

온톨로지 플랫폼 활용:

  • 공식 상품 페이지 변경 감지.
  • 성분/가격/품절/리뉴얼 페이지 모니터링.
  • Claim evidence의 stale 여부 판단.

초기 버전에서는 Firecrawl Monitor 전체를 들여오기보다, 현재 프로젝트의 scheduler/update_policy.py에서 Firecrawl scrape를 주기 호출하고 content hash/changeTracking을 저장하는 방식이 단순하다.

6.10 SDK

Python SDK는 apps/python-sdk/firecrawl 아래에 있으며, v2 메서드가 /v2/scrape, /v2/crawl, /v2/map, /v2/search, /v2/batch/scrape, /v2/parse, browser interaction을 감싼다.

우리 프로젝트가 Firecrawl을 별도 서비스로 사용할 경우 Python SDK를 직접 사용하거나, 현재 FastAPI 서비스 내부에 얇은 adapter를 만드는 방식이 적합하다.

7. 기능명세

7.1 Document 모델

Firecrawl의 핵심 결과 단위는 Document다.

필드:

  • title, description, url
  • markdown, html, rawHtml
  • links, images
  • screenshot, audio
  • json, extract, summary, answer, highlights, branding
  • attributes: selector/attribute/value 목록
  • actions: action 중 생성된 screenshot/scrape/javascript return/pdf
  • changeTracking: 이전 scrape 대비 상태와 diff
  • metadata: title, description, language, keywords, robots, OpenGraph, favicon, sourceURL, statusCode, scrapeId, contentType, proxyUsed, cacheState, cachedAt, creditsUsed 등
  • serpResults: search result title/description/url

온톨로지 플랫폼 매핑:

  • Document.url -> Page.url
  • Document.markdown -> Page.cleaned_text 또는 Page.markdown
  • Document.html/rawHtml -> 저장 여부 선택. 기본은 저장하지 않고 hash만 저장 권장.
  • Document.metadata.sourceURL/statusCode/contentType -> Page.fetch_status, Page.metadata
  • Document.links/images -> discovery 후보와 media evidence
  • Document.json/extract -> 도메인 extractor 입력 또는 사전 추출값
  • Document.changeTracking -> claim freshness/update scheduling

7.2 Scrape API 명세

Endpoint: POST /v2/scrape

목적: 단일 URL을 LLM-ready document로 변환한다.

필수 입력:

  • url: HTTP/HTTPS URL. protocol이 없으면 http://를 보정한다.

선택 입력:

  • 공통 Scrape 옵션 전체.
  • origin: 요청 출처 tag. 기본 api.
  • integration: 외부 통합 정보.
  • zeroDataRetention: 데이터 보존 제한.

정상 응답:

{
  "success": true,
  "data": {
    "markdown": "...",
    "metadata": {
      "sourceURL": "https://example.com",
      "statusCode": 200,
      "proxyUsed": "basic"
    }
  }
}

실패 응답:

{
  "success": false,
  "code": "ERROR_CODE",
  "error": "message"
}

우리 플랫폼 수용 기준:

  • URL 단위 수집의 기본 provider는 Firecrawl scrape로 한다.
  • 기본 format은 markdown, 필요 시 html, links, images, screenshot, json을 Source config에서 켠다.
  • extractor는 Firecrawl JSON을 그대로 신뢰하기보다, markdown + metadata + sourceURL을 현재 ontology extractor에 넣어 Claim/Evidence를 만든다.

7.3 Crawl API 명세

Endpoint: POST /v2/crawl

목적: seed URL에서 여러 URL을 발견하고 각 페이지를 scrape한다.

필수 입력:

  • url

선택 입력:

  • Crawler 옵션: includePaths, excludePaths, limit, maxDiscoveryDepth, allowExternalLinks, allowSubdomains, ignoreRobotsTxt, sitemap, delay 등.
  • scrapeOptions: 각 페이지에 적용할 scrape 옵션.
  • webhook: 상태 통지.
  • maxConcurrency
  • prompt: 자연어로 crawler option 생성.

정상 응답:

{
  "success": true,
  "id": "job-id",
  "url": "http://host/v2/crawl/job-id"
}

Status 조회:

{
  "success": true,
  "status": "scraping",
  "completed": 12,
  "total": 100,
  "creditsUsed": 12,
  "expiresAt": "...",
  "data": []
}

우리 플랫폼 수용 기준:

  • 사이트 전체 수집은 crawl-site 내부 구현을 Firecrawl crawl 호출로 대체 또는 선택 가능하게 한다.
  • 결과 Document[]는 Page 단위로 upsert하고, 각 Page를 ontology extraction queue로 넘긴다.
  • includePaths/excludePaths는 Source config의 url_patterns로 매핑한다.

7.4 Map API 명세

Endpoint: POST /v2/map

목적: scrape 없이 URL 후보 목록만 빠르게 발견한다.

입력:

  • url
  • search: path/title 검색 조건.
  • sitemap: only, include, skip
  • limit: 기본 5000, 최대 100000
  • includeSubdomains, allowExternalLinks, ignoreQueryParameters, filterByPath
  • useIndex, ignoreCache

응답:

{
  "success": true,
  "links": [
    { "url": "https://example.com/a", "title": "...", "description": "..." }
  ]
}

우리 플랫폼 수용 기준:

  • 신규 Source 등록 시 먼저 Map을 실행해 수집 범위 preview를 보여준다.
  • 사용자가 선택한 URL 패턴을 config로 저장한다.
  • 대규모 크롤 전에 Map 결과로 예상 page 수와 domain/path 분포를 산출한다.

7.5 Batch Scrape API 명세

Endpoint: POST /v2/batch/scrape

목적: URL 배열을 비동기 scrape job으로 처리한다.

입력:

  • urls: 1개 이상 URL 배열.
  • 공통 Scrape 옵션.
  • webhook, appendToId, ignoreInvalidURLs, maxConcurrency, zeroDataRetention.

응답:

{
  "success": true,
  "id": "job-id",
  "url": "http://host/v2/batch/scrape/job-id",
  "invalidURLs": []
}

우리 플랫폼 수용 기준:

  • Map으로 발견한 URL 중 우선순위가 높은 URL 묶음을 batch scrape로 실행한다.
  • 실패 URL은 crawl_errors 또는 Page status로 저장하고 재시도 정책에 연결한다.

7.6 Search API 명세

Endpoint: POST /v2/search

목적: query 기반으로 web/news/images 결과를 얻고, 필요하면 결과 페이지 내용까지 scrape한다.

입력:

  • query
  • limit, sources, categories, includeDomains, excludeDomains
  • lang, country, location
  • timeout
  • asyncScraping
  • scrapeOptions

응답:

{
  "success": true,
  "id": "job-id",
  "creditsUsed": 3,
  "data": {
    "web": [
      {
        "url": "https://example.com",
        "title": "Example",
        "description": "...",
        "markdown": "..."
      }
    ]
  }
}

우리 플랫폼 수용 기준:

  • 자동 Source 후보 발굴 기능에 사용한다.
  • includeDomains를 우선 사용해 공식몰/공식 문서/신뢰 출처 탐색을 제한한다.
  • 검색 결과는 즉시 Claim으로 넣지 않고 Source/Page 후보 검토 큐로 넣는다.

7.7 Parse API 명세

Endpoint: POST /v2/parse

목적: 업로드 파일을 Document로 변환한다.

입력:

  • multipart field file
  • 공통 Scrape 옵션.
  • 파일 최대 50MB.
  • kind: html, pdf, document.

우리 플랫폼 수용 기준:

  • 로컬 catalog/PDF/manual ingest에 사용한다.
  • parse 결과는 URL source가 없을 수 있으므로 Source.type=file, Page.url=file://... 또는 별도 documents 테이블 정책을 정한다.

7.8 Monitor API 명세

Endpoint 집합:

  • POST /v2/monitor
  • GET /v2/monitor
  • GET /v2/monitor/:monitorId
  • PATCH /v2/monitor/:monitorId
  • DELETE /v2/monitor/:monitorId
  • POST /v2/monitor/:monitorId/run
  • GET /v2/monitor/:monitorId/checks
  • GET /v2/monitor/:monitorId/checks/:checkId

목적: 특정 수집 대상의 변경을 주기적으로 감시한다.

우리 플랫폼 수용 기준:

  • MVP에서는 직접 도입하지 않고, Firecrawl changeTracking 또는 주기 scrape 결과의 content hash 비교로 대체한다.
  • 장기적으로 Claim freshness, 상품 리뉴얼, 가격/품절 변경에 연결한다.

7.9 Browser Session API 명세

Endpoint:

  • POST /v2/browser
  • GET /v2/browser
  • POST /v2/browser/:sessionId/execute
  • DELETE /v2/browser/:sessionId
  • POST /v2/scrape/:jobId/interact
  • DELETE /v2/scrape/:jobId/interact

목적: 브라우저 세션을 생성하고 code/prompt 기반으로 조작한다.

우리 플랫폼 수용 기준:

  • Source config에 actions를 저장하는 형태를 우선한다.
  • 자유로운 browser execute는 보안/재현성 위험이 있으므로 관리자 전용 디버깅 기능으로 제한한다.

8. Self-host 구성

docker-compose.yaml 기준 서비스:

  • api: Express API와 worker harness.
  • playwright-service: 브라우저 수집 microservice.
  • redis: queue/rate limit/cache.
  • rabbitmq: NuQ worker messaging.
  • nuq-postgres: NuQ 상태 저장.

필수/주요 환경 변수:

  • PORT, HOST
  • USE_DB_AUTHENTICATION=false로 self-host API key 없이 사용 가능
  • REDIS_URL, REDIS_RATE_LIMIT_URL
  • PLAYWRIGHT_MICROSERVICE_URL
  • NUQ_RABBITMQ_URL
  • POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT
  • OPENAI_API_KEY, OPENAI_BASE_URL, MODEL_NAME, OLLAMA_BASE_URL 등 AI 기능용
  • PROXY_SERVER, PROXY_USERNAME, PROXY_PASSWORD
  • SEARXNG_ENDPOINT
  • BULL_AUTH_KEY
  • MAX_CPU, MAX_RAM
  • ALLOW_LOCAL_WEBHOOKS

Self-host 제한:

  • Fire-engine 고급 기능은 cloud/internal 의존성이 있어 자체 호스팅에서 제한될 수 있다.
  • 기본적으로 fetch + Playwright + PDF/document 처리 중심으로 보는 것이 현실적이다.
  • Supabase/Stripe/Autumn/GCS/Sentry 의존 영역은 자체 플랫폼에서는 제거하거나 stub 처리해야 한다.

9. 현재 프로젝트와의 통합 설계

현재 프로젝트는 Python/FastAPI 기반이며 핵심 구조는 다음과 같다.

  • crawler_platform/app/core/crawler: fetch/discovery/clean/pipeline.
  • crawler_platform/app/core/extractor: rule-based/AI extractor.
  • crawler_platform/app/core/ontology: entity, relation, claim, triple store.
  • crawler_platform/app/core/database: SQLAlchemy 저장소.
  • crawler_platform/app/core/research: graph research loop.
  • crawler_platform/app/api/routes.py: 관리 API.
  • configs/perfume_subscription.yaml: Source/domain config.

권장 통합 방식:

flowchart LR
    A["Crawler Platform FastAPI"] --> B["Firecrawl Adapter"]
    B --> C["Firecrawl Self-host API"]
    C --> D["Scrape / Map / Crawl / Search"]
    D --> E["Document"]
    E --> F["Page Upsert"]
    F --> G["Ontology Extractor"]
    G --> H["Entity / Claim / Evidence"]

단계별 채택 계획

  1. FirecrawlClient adapter 추가

    • Python SDK 또는 HTTP client 사용.
    • scrape_url, map_site, crawl_site, batch_scrape, search_sources, parse_file 메서드 제공.

  2. Source config 확장

    • fetcher: firecrawl
    • firecrawl.formats
    • firecrawl.actions
    • firecrawl.crawler_options
    • firecrawl.scrape_options
    • firecrawl.search_options

  3. Page 저장 모델 확장

    • markdown
    • raw_html_hash
    • metadata_json
    • scrape_id
    • content_type
    • cache_state
    • change_status

  4. 기존 extractor 연결

    • Firecrawl Document의 markdown을 표준 입력으로 사용.
    • metadata.sourceURL을 evidence source로 유지.
    • links/images를 다음 discovery 후보 또는 evidence attachment로 저장.

  5. UI 기능 추가

    • Map preview.
    • Crawl job status.
    • Page markdown preview.
    • 실패 URL과 denial reason 표시.

10. 재사용 우선순위

즉시 재사용 권장

  • v2 API 명세와 옵션 체계.
  • scrape, map, crawl, batch scrape.
  • Document 결과 모델.
  • Python SDK 또는 HTTP adapter.
  • Docker Compose self-host 실행 방식.

부분 재사용 권장

  • actions: Source별 필요한 경우에만.
  • search: Source 후보 발굴 단계.
  • parse: 파일 ingest 단계.
  • monitor/changeTracking: 업데이트 감지 단계.
  • crawler.ts의 denial reason/URL filtering 정책: Python config validation에 반영.

초기 제외 권장

  • billing/credit/team/account 기능.
  • x402 micropayment.
  • support proxy.
  • agent signup.
  • Supabase/Stripe/Autumn/GCS/Sentry SaaS 운영 코드.
  • Fire-engine cloud 의존 기능.

11. 온톨로지 플랫폼 기능명세 초안

Firecrawl을 기반 수집기로 사용할 때 범용 온톨로지 구축 플랫폼은 다음 기능을 가져야 한다.

11.1 Source 등록

입력:

  • source name
  • base URL 또는 seed URL 목록
  • source type: official, marketplace, review, document, search
  • fetcher: requests, playwright, firecrawl
  • Firecrawl crawler/scrape/search options
  • 신뢰도 기본값
  • robots 준수 정책
  • update schedule

출력:

  • Source record
  • Map preview 결과
  • 예상 page count

11.2 URL 발견

기능:

  • Firecrawl Map 호출.
  • sitemap only/include/skip 선택.
  • include/exclude path regex 적용.
  • subdomain/external link 정책 적용.
  • query parameter 무시 여부.
  • URL 후보를 Page 상태 discovered로 저장.

검증:

  • URL 중복 제거.
  • domain/path scope 위반 차단.
  • robots 차단 URL 표시.

11.3 페이지 수집

기능:

  • 단일 URL scrape.
  • 다중 URL batch scrape.
  • site crawl job 실행.
  • Markdown, metadata, links, images 저장.
  • HTML 원문 저장 여부 선택.
  • screenshot 선택 저장.

상태:

  • discovered
  • queued
  • fetching
  • fetched
  • failed
  • blocked_by_robots
  • skipped

11.4 문서/파일 수집

기능:

  • PDF/DOCX/HTML 파일 업로드.
  • Firecrawl Parse 호출.
  • 문서 metadata와 markdown 저장.
  • 파일 기반 evidence source 생성.

11.5 구조화 추출

기능:

  • Firecrawl JSON format 또는 현재 Python extractor 선택.
  • 기본 경로는 Document.markdown -> ontology extractor.
  • JSON Schema 기반 추출은 도메인별 schema를 사용.
  • 추출 결과는 바로 확정하지 않고 Claim/Evidence로 저장.

11.6 Claim/Evidence 생성

기능:

  • Entity 후보 생성.
  • subject-predicate-object Claim 생성.
  • Evidence text와 source URL, page id, selector 또는 markdown span 저장.
  • confidence score 산출.
  • Source 신뢰도와 추출 방식에 따른 confidence 조정.

11.7 변경 감지

기능:

  • Page content hash 비교.
  • Firecrawl changeTracking format 사용 가능.
  • 변경된 페이지만 재추출.
  • 삭제/숨김/동일/변경 상태 기록.

11.8 검토 UI

기능:

  • Source별 Map preview.
  • Crawl job 진행률.
  • Page markdown 미리보기.
  • Claim 목록과 evidence 확인.
  • confidence 수동 조정.
  • entity merge.
  • 실패 URL과 denial reason 확인.

12. 리스크와 주의점

  • 라이선스: Firecrawl root LICENSE는 AGPL 계열로 보인다. 소스 자체를 서비스에 내장/수정 배포할 경우 공개 의무가 발생할 수 있으므로 별도 확인이 필요하다.
  • 언어/스택 차이: 현재 프로젝트는 Python, Firecrawl 핵심은 TypeScript다. 직접 코드 병합보다 서비스 분리가 적합하다.
  • 운영 복잡도: Redis, RabbitMQ, Postgres, Playwright service가 필요하다.
  • Cloud 의존 기능: Fire-engine, 일부 index/search/branding/agent 기능은 self-host에서 제한될 수 있다.
  • 비용/속도: Playwright/action/screenshot/stealth는 비용이 크다. Source별 정책이 필요하다.
  • 데이터 보존: raw HTML/screenshot/audio 저장은 개인정보/저작권/용량 이슈가 있으므로 기본 off 권장.
  • 검색 결과 신뢰도: Search는 후보 발굴용이며 Claim 근거로 바로 쓰면 안 된다.

13. 구현 권장안

최초 구현은 다음 범위가 좋다.

  1. Firecrawl self-host를 별도 Docker Compose로 실행한다.
  2. Python 프로젝트에 FirecrawlAdapter를 만든다.
  3. POST /crawl 또는 CLI crawl-url에 fetcher=firecrawl 옵션을 추가한다.
  4. 단일 URL scrape 결과의 markdown을 기존 extractor로 넘긴다.
  5. Map preview와 batch scrape는 두 번째 단계에서 붙인다.
  6. Monitor/changeTracking/search/parse는 세 번째 단계에서 붙인다.

이 방식이면 Firecrawl의 강한 수집 능력을 거의 변형 없이 사용하면서, 현재 프로젝트의 핵심 가치인 범용 온톨로지/Claim/Evidence/추천 구조는 Python 코드에 유지할 수 있다.

Reference in New Issue View Git Blame Copy Permalink