メインコンテンツへスキップ
Firecrawl は、Web ページを LLM アプリケーション向けのクリーンな Markdown や構造化データに変換する、Web スクレイピング・クロール API です。その JSON 抽出機能は、ページを言語モデルに送信し、指定したスキーマに一致するデータを返します。Firecrawl をセルフホストする場合、このモデルは 3 つの環境変数で選択するため、SambaCloud のモデルに抽出を任せられます。
本ガイドはセルフホスト版の Firecrawl を対象としています。Firecrawl のセルフホスティングドキュメントは、独自の OpenAI 互換プロバイダーの接続をセルフホスティングの選択肢として挙げています。本ガイドでは Firecrawl Cloud は扱いません。

前提条件

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

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

リリースタグでの Firecrawl のクローン

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

Firecrawl の接続先を SambaCloud に設定

firecrawl フォルダ内の docker-compose.yaml と同じ場所に、.env という名前のファイルを作成します。
.env
  • OPENAI_API_KEY には SambaCloud の API キーを設定します。この変数名は Firecrawl のものであり、OpenAI のものではありません。
  • OPENAI_BASE_URL は SambaCloud のベース URL です。
  • MODEL_NAME には SambaCloud のモデル ID を設定します。Firecrawl は、本来選択するはずのモデルが何であっても、すべての抽出呼び出しにこのモデルを使用します。
USE_DB_AUTHENTICATION=false の場合、Firecrawl API には認証がありません。ポート 3002 は自分のマシンまたは信頼できるネットワーク内にとどめてください。また、.env ファイルには API キーが含まれるため、バージョン管理の対象から外してください。
3

Firecrawl の起動

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

Python クライアントのインストール

2 つ目のターミナルで、仮想環境を作成して requests をインストールします。
本ガイドは、Python 3.9 上の requests 2.32.5 で動作確認済みです。

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

json 形式は、JSON スキーマと、任意指定のプロンプトを受け取ります。次のスクリプトは、サンプルの書店ページに掲載されている最初の 5 冊の書籍を Firecrawl に問い合わせます。
extract.py
Output
モデル呼び出しが失敗した場合、Firecrawl は json フィールドなしで success: true を返すことがあるため、スクリプトは json フィールドの有無を確認しています。トラブルシューティング をご参照ください。

モデルの選択

Firecrawl が呼び出すのはチャット補完ではなく SambaCloud の Responses API (/v1/responses) であるため、このエンドポイントに対応したモデルだけが動作します。次の表の各行は、.env の MODEL_NAME だけを変更し、docker compose up -d api で反映して計測した、上のスクリプトのリクエスト全体の時間です。
MiniMax-M3.1-Flash は Reasoning モデルです。回答を始める前に考える時間を取るため、抽出には gpt-oss-120b よりはるかに長い時間がかかります。リクエスト時間は実行ごとにも時間帯によっても大きく変動し、特に gemma-4-31B-it で顕著でした。数値を当てにする前に、ご自身の環境で計測してください。モデルを介さない同じページの単純なスクレイプは 1〜2 秒でした。多数のページを抽出する場合は、このテストで最速だった gpt-oss-120b を MODEL_NAME に設定してください。
Meta-Llama-3.3-70B-Instruct は SambaCloud の Responses API に対応していないため、Firecrawl から使用できません。抽出はエラーを返さないまま失敗します。トラブルシューティング の最初の項目をご参照ください。

トラブルシューティング

Firecrawl はページのスクレイプには成功しましたが、モデル呼び出しが失敗したため、json フィールドを省き、原因をログに記録しています。API ログから原因を確認します。
この行の message が問題を特定しています。続く 3 項目は、本ガイドの執筆中に再現されたものです。
ログには、https://api.sambanova.ai/v1/responses へのリクエストに対する statusCode 400 と unsupported_model が記録されています。MODEL_NAME のモデル (Meta-Llama-3.3-70B-Instruct など) は Responses API では利用できません。MODEL_NAME を、モデルの選択 に記載のモデルのいずれかに設定してください。
ログには statusCode 401 が記録されています。OPENAI_API_KEY の値が有効な SambaCloud のキーではありません。SambaCloud の API キーページ からキーをコピーして .env を更新し、docker compose up -d api を実行してください。
ログには statusCode 404 が記録されています。MODEL_NAME の値が SambaCloud のモデル ID ではありません。現在の一覧は SambaCloud モデル をご参照ください。
Compose が .env を読み込むのは、コンテナの作成時です。ファイルを編集した後は、docker compose up -d api を実行して、新しい値で api サービスを再作成してください。

参考情報