Kling Digital
tr
İletişim
2026-11-19
8 dk okuma
Öne Çıkan Rehber

Firecrawl Nedir? Web Sitelerini LLM ve RAG İçin Temiz Markdown'a Dönüştürme Rehberi

Firecrawl, JavaScript ağırlıklı karmaşık web sitelerini büyük dil modelleri ve RAG hatları için doğrudan işlenebilir temiz Markdown ve yapılandırılmış JSON verisine dönüştüren açık kaynaklı bir web veri katmanıdır. Bu rehberde v2 API uç noktalarını, MCP entegrasyonunu, Docker Compose ile kendi sunucunuzda barındırma mimarisini ve Browser-Use ile hibrit kullanım desenlerini inceliyoruz.

Firecrawl Nedir? Web Sitelerini LLM ve RAG İçin Temiz Markdown'a Dönüştürme Rehberi

Üretim ortamında çalışan bir RAG (Retrieval-Augmented Generation) hattının düşük doğruluk vermesi çoğu zaman vektör veritabanından veya gömme (embedding) modelinden kaynaklanmaz; sorun, kaynağın en başında modele ham HTML beslenmesiyle başlar. Çerez bildirimleri, onlarca katmanlı navigasyon menüleri, gömülü JavaScript durum nesneleri ve altbilgi bağlantıları bağlam penceresini hızla doldurarak geri getirme (retrieval) kalitesini ciddi biçimde bozar.

Firecrawl, dinamik ve JavaScript ağırlıklı web sitelerini büyük dil modellerinin doğrudan tüketebileceği temiz Markdown veya şema doğrulamalı JSON çıktısına dönüştüren açık kaynaklı (firecrawl/firecrawl) bir web veri ve bağlam API'sidir. Tek sayfa kazıma (scrape), alan adı haritalama (map), özyinelemeli tarama (crawl), şema bazlı çıkarma (extract) ve canlı arama (search) yeteneklerini MCP desteğiyle birlikte sunar.

Önemli
  • Gürültüsüz LLM Girdisi: Ham HTML etiketlerini, reklam bloklarını ve navigasyon gürültüsünü temizleyerek doğrudan başlık hiyerarşisini koruyan Markdown üretir.
  • Beş Çekirdek Uç Nokta ve MCP: /v2/scrape, /v2/crawl, /v2/map, /v2/extract ve /v2/search uç noktalarına ek olarak resmi firecrawl-mcp sunucusuyla kodlama ve araştırma ajanlarına doğrudan bağlanır.
  • AGPL-3.0 Açık Kaynak ve Kendi Sunucunda Barındırma: Docker Compose ile Playwright mikroservisi, Redis ve NuQ/PostgreSQL kuyruk katmanıyla kurum içi ağlarda çalıştırılabilir.

Ham HTML Neden RAG Hatlarını ve Ajan Bağlamını Bozar?

Modern web uygulamalarının büyük bölümü React, Next.js veya Vue gibi istemci tarafında hidrasyon (hydration) yapan çerçevelerle inşa edilir. Geleneksel HTTP istemcileriyle çekilen bir sayfa, gerçek metin içeriği yerine yalnızca boş bir kapsayıcı ve yüzlerce kilobaytlık betik etiketi döndürebilir. İçerik sunucu tarafında işlenmiş olsa dahi, bir ürün veya dokümantasyon sayfasının ham HTML boyutu genellikle gerçek bilgi yoğunluğunun beş ila on katı büyüklüğündedir.

Kling Digital mühendislik ekibinin kurumsal yapay zeka çözümleri kapsamında kurduğu bilgi erişim mimarilerinde gözlemlediğimiz temel darboğaz, yüksek token tüketiminden ziyade anlamsal parçalamanın (semantic chunking) bozulmasıdır. Gürültülü HTML parçaları vektör uzayında birbirine benzeyen ancak soruyla ilgisiz düğümler oluşturur. Benzer biçimde, kendi web sitenizin taranabilirliğini ve yapay zeka arama motorlarınca okunabilirliğini ölçmek istediğinizde SEO tarayıcı ve site örümceği ile AI ve GEO arama denetimi araçlarının ortaya koyduğu yapısal temizlik, Firecrawl gibi motorların ürettiği Markdown kalitesini doğrudan belirler.

Firecrawl, tarayıcı düzeyinde sayfa işleme (rendering) katmanını temizleme ve dönüştürme hattıyla birleştirir. Sonuçta elde edilen çıktı yalnızca daha az token harcamakla kalmaz; #, ##, kod blokları ve Markdown tablolarını koruduğu için başlık bazlı parçalama stratejilerinde kaynak doğruluk oranını yükseltir.

Firecrawl v2 API Mimarisi ve Beş Temel Uç Nokta

Firecrawl, ilk nesil v1 sözleşmesinin ardından kurumsal ajan iş akışları için daha tutarlı ve esnek olan v2 API tasarımını standartlaştırmıştır. Mimari, her biri farklı bir veri edinme aşamasını çözen beş ana yetenek etrafında şekillenir:

1. Tekil Sayfa Dönüştürme (/v2/scrape)

Belirli bir URL'yi işler, dinamik JavaScript bileşenlerinin yüklenmesini bekler ve isteğe bağlı olarak temiz Markdown, ham HTML, ekran görüntüsü veya yapılandırılmış JSON döndürür. RAG sistemlerinde bilinen tekil doküman güncellemeleri veya ajanların web üzerinde karşılaştığı belirli bir referans bağlantıyı okuması için idealdir.

2. Hızlı Alan Adı Haritalama (/v2/map)

Tüm sayfaları indirmeden önce bir alan adındaki erişilebilir URL envanterini yüksek hızda çıkarır. Üretim sistemlerinde doğrudan körlemesine crawl başlatmak yerine önce map çağırıp yalnızca /docs/ veya /api/ desenine uyan sayfaları filtrelemek, hem bant genişliği hem de tarama maliyetini belirgin biçimde düşürür.

3. Özyinelemeli Site Tarama (/v2/crawl)

Başlangıç URL'sinden itibaren iç bağlantıları takip ederek belirlenen derinlik ve sayfa sınırı içinde eksiksiz bir bilgi derlemi (corpus) oluşturur. İşler arka planda asenkron kuyruklar üzerinden yürütülür ve sonuçlar sayfa bazlı Markdown kayıtları halinde alınır.

4. Şema Odaklı Veri Çıkarma (/v2/extract)

Serbest metin yerine doğrudan belirli alanlara ihtiyaç duyulan senaryolarda (örneğin teknik ürün özellikleri, fiyat tabloları veya sürüm notları) Pydantic ya da JSON Schema tanımlarıyla sayfalardan yapılandırılmış veri çeker.

5. Canlı Web Araması ve İçerik Okuma (/v2/search)

Arama sorgusunu çalıştırır ve dönen sonuçların yalnızca kısa özetini değil, doğrudan temizlenmiş tam Markdown gövdesini ajanın bağlamına aktarır.

Python ve TypeScript SDK ile Temel Kullanım

Resmi Python SDK (pip install firecrawl) ve Node.js SDK (npm install firecrawl) aynı mantıksal arayüzü paylaşır. Aşağıdaki örnek, tekil sayfa kazıma, sınırlı dokümantasyon tarama ve şema doğrulamalı çıkarma akışını gösterir:

from firecrawl import Firecrawl
from pydantic import BaseModel, Field
firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")
# 1. Tekil sayfayi temiz Markdown olarak alma
page = firecrawl.scrape(
    "https://docs.firecrawl.dev",
    formats=["markdown"],
)
# 2. Alan adini sinirli kapsamda tarama
docs_corpus = firecrawl.crawl(
    url="https://docs.firecrawl.dev",
    limit=25,
    scrape_options={"formats": ["markdown"]},
)
# 3. Yapilandirilmis veri semasi tanimlama
class PricingTier(BaseModel):
    plan_name: str = Field(description="Plan adi")
    monthly_price: str = Field(description="Aylik ucret bilgisi")
    self_host_supported: bool = Field(description="Kendi sunucunda barindirma destegi")
structured = firecrawl.scrape(
    "https://www.firecrawl.dev",
    formats=["extract"],
    json_options={"schema": PricingTier.model_json_schema()},
)
print(structured)

Node.js veya TypeScript tabanlı arka uç servislerinde ise @mendable/firecrawl-js (veya güncel firecrawl paketi) benzer biçimde asenkron await firecrawl.scrape(...) çağrılarıyla Next.js sunucu eylemlerine veya arka plan kuyruk işçilerine entegre edilir.

Firecrawl, Geleneksel Kazıyıcılar ve Tarayıcı Ajanları Karşılaştırması

Bir projede hangi web veri aracının seçileceği, iş akışının salt okunur içerik toplama mı yoksa durumlu etkileşim (stateful interaction) mi gerektirdiğine bağlıdır. Aşağıdaki karşılaştırma, mühendislik ekiplerinin mimari karar alırken dikkate alması gereken temel farkları özetler:

Özellik / BoyutFirecrawlBeautifulSoup / CheerioHam PlaywrightBrowser-Use
Ana Kullanım AmacıWeb'i temiz Markdown/JSON'a çevirmeStatik HTML ayrıştırmaDeterministik tarayıcı otomasyonuLLM güdümlü etkileşimli tarayıcı ajanı
JS / SPA İşlemeYerleşik tarayıcı katmanıYok (ek motor gerekir)Tam Chromium/WebKit desteğiPlaywright + ham CDP (cdp-use)
Çıktı FormatıLLM uyumlu Markdown, JSON, HTMLHam DOM düğümleriHam DOM / ekran görüntüsüGörev sonucu, aksiyon geçmişi, DOM özeti
Form Doldurma ve Çok Adımlı TıklamaSınırlı temel sayfa aksiyonlarıYokSabit seçicilerle tam kontrolDoğal dil hedefleriyle otonom gezinme
RAG Veri Hattı VerimliliğiYüksek (toplu tarama ve temizleme)Orta (yoğun bakım gerektirir)Düşük (manuel temizleme gerekir)Özel portallar için tamamlayıcı
Lisans ModeliAGPL-3.0 (Açık kaynak çekirdek)MITApache-2.0MIT
İpucu

Hibrit RAG ve Otomasyon Deseni: Kamuya açık dokümantasyon, bilgi bankası ve haber kaynaklarını yüksek hızda indekslemek için Firecrawl kullanın; oturum açma, dinamik filtreleme veya çok adımlı form doldurma gerektiren uygulamalarda ise Browser-Use tarayıcı otomasyonu rehberinde incelediğimiz ajanı devreye alın. Bu iki katmanın Kasım 2026 ajan yığınındaki yerini görmek için Kasım 2026 açık kaynak AI ajan ekosistemi analizimize göz atabilirsiniz.

Model Context Protocol (MCP) ile Ajanlara Doğrudan Web Okuma Yeteneği

2026 itibarıyla ajanların harici araçlara bağlanmasında fiili standart haline gelen Model Context Protocol (MCP), Firecrawl için resmi firecrawl/firecrawl-mcp-server deposuyla desteklenir. Bu sunucu, Claude Desktop, Cursor, OpenCode veya özel kurumsal ajan çalışma zamanlarına firecrawl_scrape, firecrawl_map, firecrawl_crawl ve firecrawl_search araçlarını standart şemalarla sunar.

Kodlama ajanları güncel bir kütüphane dokümantasyonunu veya API değişiklik kaydını okurken eski eğitim verisine dayanmak yerine canlı kaynağa erişir. Yerel bir geliştirme ortamında npx üzerinden veya kurum içi kendi barındırdığınız Firecrawl örneğine yönlendirilmiş biçimde aşağıdaki MCP yapılandırması kullanılabilir:

{
  "mcpServers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-YOUR_API_KEY",
        "FIRECRAWL_API_URL": "http://localhost:3002"
      }
    }
  }
}

Bulut hizmetini doğrudan OAuth akışıyla bağlamak isteyen ekipler, yerel anahtar dağıtmadan https://mcp.firecrawl.dev/v2/mcp-oauth HTTP uç noktasını da tercih edebilir. Kendi sunucusunda barındırma yapan kurumlar için FIRECRAWL_API_URL değişkeni tüm MCP çağrılarının dahili Docker ağına yönlendirilmesini sağlar.

Docker Compose ile Kendi Sunucunda Barındırma ve AGPL-3.0 Sınırları

Firecrawl'ı kurum içi altyapıda çalıştırmak isteyen ekipler resmi depodaki sabit bir sürüm etiketini (main dalı yerine kararlı sürüm etiketi) klonlayarak Docker Compose yığınını ayağa kaldırabilir. Varsayılan kendi barındırma mimarisi dört ana bileşenden oluşur:

  1. Firecrawl API ve Node İşçileri: HTTP isteklerini karşılar, şema doğrulaması yapar ve işleri kuyruğa dağıtır.
  2. playwright-service: JavaScript ağırlıklı sayfaları işleyen izole başsız (headless) tarayıcı mikroservisi.
  3. Redis: Önbellekleme, hız sınırlama (REDIS_RATE_LIMIT_URL) ve çalışma zamanı koordinasyonu sağlar.
  4. NuQ / PostgreSQL Kuyruk Katmanı: Asenkron tarama ve kazıma işlerinin durum takibini güvenli biçimde saklar.

Temel yerel ve dahili ağ yapılandırmasında kök .env dosyası aşağıdaki çekirdek değişkenleri içerir:

PORT=3002
HOST=0.0.0.0
FIRECRAWL_API_URL=http://localhost:3002
USE_DB_AUTHENTICATION=false
REDIS_URL=redis://redis:6379
PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/scrape
POSTGRES_HOST=nuq-postgres
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=strong-internal-password
POSTGRES_DB=postgres

Bulut ve Kendi Sunucunda Barındırma Eşitlik Analizi

Açık kaynaklı çekirdek /v2/scrape, crawl, map ve search rotalarını eksiksiz sunar; ayrıca yapılandırılmış çıkarma için Ollama veya OpenAI uyumlu yerel dil modellerine bağlanabilir. Buna karşılık Firecrawl'ın bulut sürümünde bulunan gelişmiş anti-bot yönlendirme motoru (Fire-engine), yönetilen vekil (proxy) havuzları ve bazı derin etkileşim katmanları açık kaynaklı dağıtımda yer almaz. Bu ayrım özellikle yüksek hacimli dış kaynak taramalarında başlangıçta doğru planlanmalıdır.

Uyarı

AGPL-3.0 Lisansı ve Güvenlik İzolasyonu: Firecrawl çekirdeği AGPL-3.0 lisansıyla dağıtılır. Kaynak kodda değişiklik yapıp bunu ağ üzerinden dış kullanıcılara bir SaaS hizmeti olarak sunuyorsanız, yaptığınız değişiklikleri paylaşma yükümlülüğü doğabilir; bu nedenle ticari dağıtım öncesinde hukuki inceleme yapılmalıdır. Teknik güvenlik tarafında ise dahili playwright-service konteynerinin mutlaka çıkış (egress) güvenlik duvarıyla sınırlandırılması ve özel IP aralıklarına (127.0.0.1, 169.254.169.254, dahili RFC 1918 blokları) yönelik SSRF isteklerinin engellenmesi zorunludur.

Üretimde Sürdürülebilir RAG Veri Hattı Tasarlamak

Firecrawl'ı güvenilir bir kurumsal RAG boru hattına dönüştürmek için tek seferlik toplu tarama yerine artımlı (incremental) güncelleme modeli benimsenmelidir. Haftalık veya günlük zamanlayıcılarla önce /v2/map çalıştırılıp yeni eklenen ya da değişen URL'ler tespit edilir; ardından yalnızca değişen sayfalar /v2/scrape üzerinden çekilip başlık (##, ###) sınırlarından parçalanır. Her parçaya kaynak URL, çekilme zaman damgası ve başlık yolu üstverisi (metadata) eklendiğinde hem halüsinasyon riski düşer hem de yanıt içi kaynak gösterimi şeffaf hale gelir.

Kendi kurum içi doküman ekosisteminizde veya müşteri portallarınızda yüksek doğruluklu RAG ve ajan mimarisi kurmak istiyorsanız, Kling Digital mühendislik ekibiyle iletişim sayfamız üzerinden teknik mimari değerlendirmesi planlayabilir veya AI ve GEO arama denetimi ile mevcut web varlıklarınızın makine okunurluğunu hemen ölçebilirsiniz.

Sıkça Sorulan Sorular

Rehber ve entegrasyonla ilgili en sık sorulan sorular.

Tüm Yazılara Dön
Paylaş

Yorumlar (0)

Görüş ve deneyimlerinizi toplulukla paylaşın.

Henüz yorum yapılmamış. İlk yorumu siz yapın!

Yorum Bırak

Yorumunuz yönetici onayından sonra yayına alınacaktır.

Topical Authority & İç Bağlantı Ekosistemi

İlgili Mimari Kıyaslamalar, Rehberler & Dijital Araçlar

Projeniz için en doğru teknoloji kararını vermeniz adına hazırladığımız kıyaslama matrisleri, derinlemesine B2B rehberler ve canlı hesaplama araçları.

Teknik Kıyaslama

Next.js vs WordPress Kıyaslaması

1 saniyenin altında açılış hızı, eklenti risklerinden arındırılmış güvenlik ve 3 yıllık toplam maliyet karşılaştırması.

Kapsamlı Kıyaslamayı İnceleyin
Mimari Kıyaslama

Framer vs Next.js Karşılaştırması

Görsel tasarım araçları ile tam teşekküllü kurumsal web yazılımı farkları.

Kapsamlı Kıyaslamayı İnceleyin

Son Yazılar

En güncel teknoloji, tasarım ve yazılım rehberlerimiz.

Tümünü Gör