本ガイドはセルフホスト版の Firecrawl を対象としています。Firecrawl のセルフホスティングドキュメントは、独自の OpenAI 互換プロバイダーの接続をセルフホスティングの選択肢として挙げています。本ガイドでは Firecrawl Cloud は扱いません。
前提条件
- SambaCloud のアカウントと API キー
- Git と、Docker Compose を含む Docker
- Python 3.9 以上
インストールとセットアップ
本ガイドは Firecrawlv2.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 は、本来選択するはずのモデルが何であっても、すべての抽出呼び出しにこのモデルを使用します。
3
Firecrawl の起動
The "..." variable is not set. Defaulting to a blank string という警告をいくつか出力しますが、無害です。ビルドが完了したら、api サービスが実行中であることを確認します。4
Python クライアントのインストール
2 つ目のターミナルで、仮想環境を作成して 本ガイドは、Python 3.9 上の
requests をインストールします。requests 2.32.5 で動作確認済みです。ページからの構造化データの抽出
json 形式は、JSON スキーマと、任意指定のプロンプトを受け取ります。次のスクリプトは、サンプルの書店ページに掲載されている最初の 5 冊の書籍を Firecrawl に問い合わせます。
extract.py
Output
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 に設定してください。トラブルシューティング
レスポンスに json フィールドがないのに success は true になる
レスポンスに json フィールドがないのに success は true になる
Firecrawl はページのスクレイプには成功しましたが、モデル呼び出しが失敗したため、この行の
json フィールドを省き、原因をログに記録しています。API ログから原因を確認します。message が問題を特定しています。続く 3 項目は、本ガイドの執筆中に再現されたものです。Unsupported model ... on Response API
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 を、モデルの選択 に記載のモデルのいずれかに設定してください。Incorrect API key provided
Incorrect API key provided
ログには
statusCode 401 が記録されています。OPENAI_API_KEY の値が有効な SambaCloud のキーではありません。SambaCloud の API キーページ からキーをコピーして .env を更新し、docker compose up -d api を実行してください。The model does not exist or you do not have access to it
The model does not exist or you do not have access to it
ログには
statusCode 404 が記録されています。MODEL_NAME の値が SambaCloud のモデル ID ではありません。現在の一覧は SambaCloud モデル をご参照ください。.env を変更しても反映されない
.env を変更しても反映されない
Compose が
.env を読み込むのは、コンテナの作成時です。ファイルを編集した後は、docker compose up -d api を実行して、新しい値で api サービスを再作成してください。
