llm-context

LLM Context

API キーが必要です：https://api.search.brave.com で取得してください。

プラン：Search プランに含まれています。https://api-dashboard.search.brave.com/app/subscriptions/subscribe をご覧ください。

Brave LLM Context API は、リアルタイム検索結果に基づく LLM の応答生成に最適化された、関連性順にランク付け済みのウェブコンテンツを抽出して提供します。リンクやスニペットを返す従来のウェブ検索 API とは異なり、LLM Context は実際のページコンテンツ（テキストチャンク、表、コードブロック、構造化データ）を抽出するため、LLM や AI エージェントがそのまま内容を推論に利用できます。

LLM Context と AI Grounding の比較

機能	LLM Context（本機能）	AI Grounding（answers）
出力	お客様の LLM 向けに抽出した生のコンテンツ	引用付きのエンドツーエンドの AI 回答
インターフェース	REST API（GET/POST）	OpenAI 互換の /chat/completions
検索	リクエストごとに 1 回の検索	複数回の検索（反復的な調査）
速度	高速（<1s）	低速
プラン	Search	Answers
エンドポイント	/res/v1/llm/context	/res/v1/chat/completions
最適な用途	AI エージェント、RAG パイプライン、ツール呼び出し	チャットインターフェース、調査モード

エンドポイント

GET  https://api.search.brave.com/res/v1/llm/context
POST https://api.search.brave.com/res/v1/llm/context

認証：X-Subscription-Token: <API_KEY> ヘッダー

任意のヘッダー：

• Accept-Encoding: gzip — gzip 圧縮を有効にします

クイックスタート

GET リクエスト

curl -s "https://api.search.brave.com/res/v1/llm/context?q=tallest+mountains+in+the+world" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

POST リクエスト（JSON ボディ）

curl -s --compressed -X POST "https://api.search.brave.com/res/v1/llm/context" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"q": "tallest mountains in the world"}'

Goggles を使用する場合（インライン）

curl -s "https://api.search.brave.com/res/v1/llm/context" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=rust programming" \
  --data-urlencode 'goggles=$discard
$site=docs.rs
$site=rust-lang.org'

パラメーター

クエリパラメーター

パラメーター	型	必須	デフォルト	説明
q	string	はい	-	検索クエリ（1～400 文字、最大 50 語）
country	string	いいえ	US	検索対象の国（2 文字の国コードまたは ALL）
search_lang	string	いいえ	en	言語設定（2 文字以上の言語コード）
count	int	いいえ	20	対象とする検索結果の最大数（1～50）
spellcheck	bool	いいえ	true	検索前にクエリのスペルチェックを行うかどうか
freshness	string	いいえ	""	ページの経過時間で検索結果を絞り込みます。ページの経過時間は、公開日や最終更新日など、コンテンツが示す最も関連性の高い日付に基づいて判定されます。指定可能な値：pd（24 時間以内）、pw（7 日以内）、pm（31 日以内）、py（365 日以内）、またはカスタムの日付範囲 YYYY-MM-DDtoYYYY-MM-DD（例：2022-04-01to2022-07-30）。

コンテキストサイズのパラメーター

パラメーター	型	必須	デフォルト	説明
maximum_number_of_urls	int	いいえ	20	レスポンスに含める URL の最大数（1～50）
maximum_number_of_tokens	int	いいえ	8192	コンテキストのトークン数のおおよその上限（1024～32768）
maximum_number_of_snippets	int	いいえ	50	すべての URL を対象とするスニペットの最大数（1～256）
maximum_number_of_tokens_per_url	int	いいえ	4096	個々の URL ごとのトークン数の最大値（512～8192）
maximum_number_of_snippets_per_url	int	いいえ	50	個々の URL ごとのスニペットの最大数（1～100）

フィルタリングとローカル検索のパラメーター

パラメーター	型	必須	デフォルト	説明
context_threshold_mode	string	いいえ	null	コンテンツを含める際の関連性のしきい値（strict/balanced/lenient/disabled）
safesearch	string	いいえ	null	成人向けコンテンツのフィルター（off/moderate/strict）。未設定の場合はフィルタリングされません。ただし、ローカル検索は strict のままです。
enable_local	bool	いいえ	null	ローカル検索の制御（true/false/null。下記参照）
goggles	string/list	いいえ	null	カスタムの再ランキングに使用する Goggle の URL またはインライン定義
enable_source_metadata	bool	いいえ	false	各 sources[url] エントリに site_name、favicon、thumbnail、description を追加します

コンテキストサイズのガイドライン

タスクの種類	件数	max_tokens	例
簡単な事実確認	5	2048	"Pythonが作られたのは何年ですか？"
標準的なクエリ	20	8192	"Reactフックのベストプラクティス"
複雑な調査	50	16384	"本番環境向けAIフレームワークの比較"

コンテキストウィンドウを大きくすると、より多くの情報を得られますが、推論のレイテンシとコストが増加します。まずはデフォルト値を使用し、必要に応じて調整してください。

しきい値モード

モード	動作
null（未設定）	デフォルト — 現在のAPIバージョンでは lenient に解決されます
strict	より高いしきい値 — 件数は少なくなりますが、関連性の高い結果が得られます
balanced	網羅性と関連性のバランスが取れています
lenient	より低いしきい値 — 結果は増えますが、関連性の低い内容が含まれることがあります
disabled	しきい値によるフィルタリングなし — 抽出されたコンテンツをすべて返します

ローカル検索

enable_local パラメーターは、位置情報を考慮した検索を制御します。

値	動作
null（未設定）	自動検出 — 位置情報ヘッダーが指定されている場合に、ローカル検索が有効になります
true	ローカル検索を強制 — 位置情報ヘッダーがなくても、常にローカル検索を使用します
false	標準検索を強制 — 位置情報ヘッダーがあっても、常に標準のウェブランキングを使用します

ほとんどの用途では、enable_local を省略し、APIに位置情報ヘッダーから自動検出させてください。

位置情報ヘッダー

ヘッダー	型	説明
X-Loc-Lat	float	緯度（-90.0～90.0）
X-Loc-Long	float	経度（-180.0～180.0）
X-Loc-City	string	市区町村名
X-Loc-State	string	州／地域コード（ISO 3166-2）
X-Loc-State-Name	string	州／地域名
X-Loc-Country	string	2文字の国コード
X-Loc-Postal-Code	string	郵便番号

優先順位：X-Loc-Lat + X-Loc-Long が優先されます。これらが指定されている場合、位置情報の解決にはテキストベースのヘッダー（City、State、Country、Postal-Code）は使用されません。座標がない場合にのみ、テキストベースのヘッダーを指定してください。

例：座標を使用

curl -s "https://api.search.brave.com/res/v1/llm/context" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -H "X-Loc-Lat: 37.7749" \
  -H "X-Loc-Long: -122.4194" \
  -G \
  --data-urlencode "q=best coffee shops near me"

例：地名を使用

curl -s "https://api.search.brave.com/res/v1/llm/context" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -H "X-Loc-City: San Francisco" \
  -H "X-Loc-State: CA" \
  -H "X-Loc-Country: US" \
  -G \
  --data-urlencode "q=best coffee shops near me"

Goggles（カスタムランキング）— Brave独自の機能

Gogglesを使うと、LLMの根拠となる情報源を制御できます。これはRAGの品質に欠かせません。

用途	Goggleルール
公式ドキュメントのみ	$discard\n$site=docs.python.org
ユーザーコンテンツを除外	$discard,site=reddit.com\n$discard,site=stackoverflow.com
学術情報源	$discard\n$site=arxiv.org\n$site=scholar.google.com
ペイウォールなし	$discard,site=medium.com

方法	例
ホスト型	--data-urlencode "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/1k_short.goggle"
インライン	--data-urlencode 'goggles=$discard\n$site=example.com'

ホスト型 GogglesはGitHubまたはGitLab上に置き、! name:、! description:、! author: のヘッダーを含めて、https://search.brave.com/goggles/create で登録する必要があります。インラインルールには登録は必要ありません。

構文：ルールは $ + カンマ区切りのオプションで始まります。アクション（いずれか1つ）：discard、boost[=N]、downrank[=N] — Nは1～10の整数です。サイトフィルター：site=DOMAIN。例：$site=example.com,boost=3。ルールは \n（%0A）で区切ります。

許可リスト：$discard\n$site=docs.python.org\n$site=developer.mozilla.org — ブロックリスト：$discard,site=pinterest.com\n$discard,site=quora.com

リソース：Discover · 構文 · クイックスタート

レスポンス形式

標準レスポンス

{
  "grounding": {
    "generic": [
      {
        "url": "https://example.com/page",
        "title": "Page Title",
        "snippets": [
          "Relevant text chunk extracted from the page...",
          "Another relevant passage from the same page..."
        ]
      }
    ],
    "map": []
  },
  "sources": {
    "https://example.com/page": {
      "title": "Page Title",
      "hostname": "example.com",
      "age": ["Wednesday, January 15, 2025", "2025-01-15", "392 days ago", "2025-01-15T13:45:02Z"]
    }
  }
}

ローカルレスポンス（enable_local を使用）

{
  "grounding": {
    "generic": [...],
    "poi": {
      "name": "Business Name",
      "url": "https://business.com",
      "title": "Title of business.com website",
      "snippets": ["Business details and information..."]
    },
    "map": [
      {
        "name": "Place Name",
        "url": "https://place.com",
        "title": "Title of place.com website",
        "snippets": ["Place information and details..."]
      }
    ]
  },
  "sources": {
    "https://business.com": {
      "title": "Business Name",
      "hostname": "business.com",
      "age": []
    }
  }
}

レスポンスフィールド

フィールド	型	説明
grounding	object	種類ごとのグラウンディング情報をすべて格納するコンテナ
grounding.generic	array	抽出コンテンツを含む URL オブジェクトの配列（主なグラウンディングデータ）
grounding.generic[].url	string	ソース URL
grounding.generic[].title	string	ページタイトル
grounding.generic[].snippets	array	クエリに関連する、抽出されたスマートチャンク
grounding.poi	object/null	POI データ（ローカル検索時のみ）
grounding.poi.name	string/null	POI 名
grounding.poi.url	string/null	POI のソース URL
grounding.poi.title	string/null	POI ページのタイトル
grounding.poi.snippets	array/null	POI のテキストスニペット
grounding.map	array	地図／場所の検索結果（ローカル検索時のみ）
grounding.map[].name	string/null	場所名
grounding.map[].url	string/null	場所のソース URL
grounding.map[].title	string/null	場所のページタイトル
grounding.map[].snippets	array/null	場所のテキストスニペット
sources	object	参照されたすべての URL のメタデータ。URL をキーとして格納
sources[url].title	string	ページタイトル
sources[url].hostname	string	ソースのホスト名
sources[url].age	array	ページの日付を4つの固定位置で示します：完全な日付、YYYY-MM-DD、相対的な経過時間、ISO 8601 タイムスタンプ。ページの日付が不明な場合は空です
sources[url].description	string	クエリとは無関係な、ページ自体の説明。enable_source_metadata が必要です
sources[url].site_name	string	サイト名。enable_source_metadata が必要です
sources[url].favicon	string	ファビコンの URL。enable_source_metadata が必要です
sources[url].thumbnail	object/null	ページのサムネイル（src、original）。enable_source_metadata が必要です
sources[url].snippet	string?	ページの最適なスニペット

注：スニペットにはプレーンテキスト、または JSON 形式でシリアライズされた構造化データ（テーブル、スキーマ、コードブロック）が含まれる場合があります。LLM はこの混在形式を適切に処理できます。

ユースケース

• AI エージェント：1回の呼び出しでそのまま使えるコンテンツを返すウェブ検索ツールをエージェントに提供します
• RAG パイプライン：新鮮で関連性の高いウェブコンテンツに基づいて LLM の応答をグラウンディングします
• AI アシスタントとチャットボット：実際のソースに裏付けられた事実に基づく回答を提供します
• 質問応答：特定のクエリに絞ったコンテキストを取得します
• ファクトチェック：最新のウェブコンテンツと照合して主張を検証します
• コンテンツ調査：1回の API 呼び出しで、あらゆるトピックの資料を収集します

ベストプラクティス

• トークン予算：まずデフォルト値（maximum_number_of_tokens=8192、count=20）から始めます。簡単な検索では減らし、複雑な調査では増やします。
• ソースの品質：Goggles を使って信頼できるソースに絞り込みます。再現率より精度を優先する場合は、context_threshold_mode=strict を設定します。
• パフォーマンス：ニーズを満たす範囲で、count と maximum_number_of_tokens を最小にします。ローカル検索では、位置情報のヘッダーを指定します。