> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Firecrawl

[Firecrawl](https://www.firecrawl.dev/) は、Web ページを LLM アプリケーション向けのクリーンな Markdown や構造化データに変換する、Web スクレイピング・クロール API です。その JSON 抽出機能は、ページを言語モデルに送信し、指定したスキーマに一致するデータを返します。Firecrawl をセルフホストする場合、このモデルは 3 つの環境変数で選択するため、SambaCloud のモデルに抽出を任せられます。

> [!NOTE]
>
> 本ガイドはセルフホスト版の Firecrawl を対象としています。Firecrawl のセルフホスティングドキュメントは、独自の OpenAI 互換プロバイダーの接続をセルフホスティングの選択肢として挙げています。本ガイドでは Firecrawl Cloud は扱いません。

## 前提条件

* [SambaCloud](https://cloud.sambanova.ai/?utm_source=firecrawl\&utm_medium=external\&utm_campaign=cloud_signup) のアカウントと [API キー](https://cloud.sambanova.ai/apis?utm_source=firecrawl\&utm_medium=external\&utm_campaign=cloud_signup)
* [Git](https://git-scm.com/) と、Docker Compose を含む [Docker](https://docs.docker.com/get-docker/)
* Python 3.9 以上

## インストールとセットアップ

本ガイドは Firecrawl `v2.11.0` で動作確認済みです。初回の起動では API、Playwright、データベースの各イメージをソースからビルドするため、2 回目以降の起動より時間がかかります。

**1. リリースタグでの Firecrawl のクローン**

`main` ではなくリリースタグを使用します。これにより、作業中にセットアップの内容が変わることを防げます。

```bash theme={}
git clone --branch v2.11.0 --depth 1 https://github.com/firecrawl/firecrawl.git
cd firecrawl
```

**2. Firecrawl の接続先を SambaCloud に設定**

`firecrawl` フォルダ内の `docker-compose.yaml` と同じ場所に、`.env` という名前のファイルを作成します。

```text .env theme={}
PORT=3002
USE_DB_AUTHENTICATION=false
OPENAI_API_KEY=your-sambanova-api-key
OPENAI_BASE_URL=https://api.sambanova.ai/v1
MODEL_NAME=MiniMax-M3.1-Flash
```

* `OPENAI_API_KEY` には SambaCloud の API キーを設定します。この変数名は Firecrawl のものであり、OpenAI のものではありません。
* `OPENAI_BASE_URL` は SambaCloud のベース URL です。
* `MODEL_NAME` には SambaCloud のモデル ID を設定します。Firecrawl は、本来選択するはずのモデルが何であっても、すべての抽出呼び出しにこのモデルを使用します。

> [!WARNING]
>
> `USE_DB_AUTHENTICATION=false` の場合、Firecrawl API には認証がありません。ポート `3002` は自分のマシンまたは信頼できるネットワーク内にとどめてください。また、`.env` ファイルには API キーが含まれるため、バージョン管理の対象から外してください。

**3. Firecrawl の起動**

```bash theme={}
docker compose up -d --build
```

Compose は、本ガイドでは使用しない設定について `The "..." variable is not set. Defaulting to a blank string` という警告をいくつか出力しますが、無害です。ビルドが完了したら、`api` サービスが実行中であることを確認します。

```bash theme={}
docker compose ps
```

**4. Python クライアントのインストール**

2 つ目のターミナルで、仮想環境を作成して `requests` をインストールします。

```bash macOS / Linux theme={}
python3 -m venv .venv
source .venv/bin/activate
pip install requests
```

```powershell Windows theme={}
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install requests
```

本ガイドは、Python 3.9 上の `requests` 2.32.5 で動作確認済みです。

## ページからの構造化データの抽出

`json` 形式は、JSON スキーマと、任意指定のプロンプトを受け取ります。次のスクリプトは、サンプルの書店ページに掲載されている最初の 5 冊の書籍を Firecrawl に問い合わせます。

```python extract.py theme={}
import json

import requests

payload = {
    "url": "https://books.toscrape.com/",
    "formats": [
        {
            "type": "json",
            "prompt": "Extract the first 5 books listed.",
            "schema": {
                "type": "object",
                "properties": {
                    "books": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "title": {"type": "string"},
                                "price": {"type": "string"},
                            },
                            "required": ["title", "price"],
                        },
                    }
                },
                "required": ["books"],
            },
        }
    ],
}

response = requests.post("http://localhost:3002/v2/scrape", json=payload, timeout=180)
response.raise_for_status()
data = response.json()["data"]

if "json" not in data:
    raise SystemExit("The response has no json field. Check the API logs.")
print(json.dumps(data["json"], indent=2, ensure_ascii=False))
```

```bash theme={}
python extract.py
```

```json Output theme={}
{
  "books": [
    { "price": "£51.77", "title": "A Light in the Attic" },
    { "price": "£53.74", "title": "Tipping the Velvet" },
    { "price": "£50.10", "title": "Soumission" },
    { "price": "£47.82", "title": "Sharp Objects" },
    { "price": "£54.23", "title": "Sapiens: A Brief History of Humankind" }
  ]
}
```

モデル呼び出しが失敗した場合、Firecrawl は `json` フィールドなしで `success: true` を返すことがあるため、スクリプトは `json` フィールドの有無を確認しています。[トラブルシューティング](#トラブルシューティング) をご参照ください。

## モデルの選択

Firecrawl が呼び出すのはチャット補完ではなく SambaCloud の Responses API (`/v1/responses`) であるため、このエンドポイントに対応したモデルだけが動作します。次の表の各行は、`.env` の `MODEL_NAME` だけを変更し、`docker compose up -d api` で反映して計測した、上のスクリプトのリクエスト全体の時間です。

| モデル | Firecrawl での動作 | リクエスト時間 |
| :- | :- | :- |
| `MiniMax-M3.1-Flash` | はい | 22 回中 21 回は 6〜37 秒、1 回は 103 秒 |
| `gpt-oss-120b` | はい | 12 回で 3〜4 秒 |
| `gemma-4-31B-it` | はい | 12 回で 3〜36 秒 |
| `Meta-Llama-3.3-70B-Instruct` | いいえ | データを返しません |

> [!NOTE]
>
> `MiniMax-M3.1-Flash` は Reasoning モデルです。回答を始める前に考える時間を取るため、抽出には `gpt-oss-120b` よりはるかに長い時間がかかります。リクエスト時間は実行ごとにも時間帯によっても大きく変動し、特に `gemma-4-31B-it` で顕著でした。数値を当てにする前に、ご自身の環境で計測してください。モデルを介さない同じページの単純なスクレイプは 1〜2 秒でした。多数のページを抽出する場合は、このテストで最速だった `gpt-oss-120b` を `MODEL_NAME` に設定してください。

> [!WARNING]
>
> `Meta-Llama-3.3-70B-Instruct` は SambaCloud の Responses API に対応していないため、Firecrawl から使用できません。抽出はエラーを返さないまま失敗します。[トラブルシューティング](#トラブルシューティング) の最初の項目をご参照ください。

## トラブルシューティング

> [accordion] レスポンスに json フィールドがないのに success は true になる
>
> Firecrawl はページのスクレイプには成功しましたが、モデル呼び出しが失敗したため、`json` フィールドを省き、原因をログに記録しています。API ログから原因を確認します。
>
> ```bash theme={}
> docker compose logs api | grep "LLM extraction failed"
> ```
>
> この行の `message` が問題を特定しています。続く 3 項目は、本ガイドの執筆中に再現されたものです。

> [accordion] Unsupported model ... on Response API
>
> ログには、`https://api.sambanova.ai/v1/responses` へのリクエストに対する `statusCode` 400 と `unsupported_model` が記録されています。`MODEL_NAME` のモデル (`Meta-Llama-3.3-70B-Instruct` など) は Responses API では利用できません。`MODEL_NAME` を、[モデルの選択](#モデルの選択) に記載のモデルのいずれかに設定してください。

> [accordion] Incorrect API key provided
>
> ログには `statusCode` 401 が記録されています。`OPENAI_API_KEY` の値が有効な SambaCloud のキーではありません。[SambaCloud の API キーページ](https://cloud.sambanova.ai/apis) からキーをコピーして `.env` を更新し、`docker compose up -d api` を実行してください。

> [accordion] The model does not exist or you do not have access to it
>
> ログには `statusCode` 404 が記録されています。`MODEL_NAME` の値が SambaCloud のモデル ID ではありません。現在の一覧は [SambaCloud モデル](https://docs.sambanova.ai/docs/ja/models/sambacloud-models.md) をご参照ください。

> [accordion] .env を変更しても反映されない
>
> Compose が `.env` を読み込むのは、コンテナの作成時です。ファイルを編集した後は、`docker compose up -d api` を実行して、新しい値で `api` サービスを再作成してください。

## 参考情報

* [Firecrawl のセルフホスティングガイド](https://docs.firecrawl.dev/contributing/self-host)
* [Firecrawl の JSON 抽出](https://docs.firecrawl.dev/features/llm-extract)
* [SambaCloud の対応モデル](https://docs.sambanova.ai/docs/ja/models/sambacloud-models.md)
