需要为 RAG/LLM 提供实时网页内容做…

当你要给 LLM 或 AI Agent 喂入实时、相关度排序后的网页正文（而非链接和摘要）时，调用该 API 一次性拿到可直接推理的内容。

适用场景

解决思路

1. 先到 https://api.search.brave.com 申请 API Key，并确认订阅包含 Search 计划（见 https://api-dashboard.search.brave.com/app/subscriptions/subscribe）。
2. 向端点 GET 或 POST https://api.search.brave.com/res/v1/llm/context 发起请求，认证用请求头 X-Subscription-Token: <API_KEY>。
3. 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}"。
4. POST 请求示例：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"}'。
5. 可选加请求头 Accept-Encoding: gzip 启用 gzip 压缩。
6. 必填查询参数 q：搜索词，1-400 字符，最多 50 个词。
7. 可选查询参数：country（默认 US，2 位国家码或 ALL）、search_lang（默认 en）、count（默认 20，范围 1-50）、spellcheck（默认 true）、freshness（pd=24h 内、pw=7 天内、pm=31 天内、py=365 天内，或自定义 YYYY-MM-DDtoYYYY-MM-DD）。
8. 按任务复杂度调整上下文大小参数：maximum_number_of_urls（默认 20，1-50）、maximum_number_of_tokens（默认 8192，1024-32768）、maximum_number_of_snippets（默认 50，1-256）、maximum_number_of_tokens_per_url（默认 4096，512-8192）、maximum_number_of_snippets_per_url（默认 50，1-100）。
9. 按任务类型选参数：简单事实查询用 count=5、max_tokens=2048；标准查询用 count=20、max_tokens=8192；复杂研究用 count=50、max_tokens=16384。从默认值起步再调整，上下文越大延迟和推理成本越高。
10. 用 context_threshold_mode 控制相关度阈值：null（默认，当前 API 版本解析为 lenient）、strict（更少但更相关）、balanced（覆盖与相关平衡）、lenient（更多但可能不太相关）、disabled（不过滤，返回全部抽取内容）。
11. 用 safesearch 控制成人内容过滤：off/moderate/strict；不设置表示不过滤，但本地召回仍保持 strict。
12. 用 enable_local 控制本地召回：null（默认，检测到位置请求头时自动启用）、true（强制本地召回）、false（强制标准网页排序）。多数场景省略该参数，让 API 根据位置请求头自动判断。
13. 本地查询时提供位置请求头：X-Loc-Lat、X-Loc-Long、X-Loc-City、X-Loc-State、X-Loc-State-Name、X-Loc-Country、X-Loc-Postal-Code。
14. 位置解析优先级：X-Loc-Lat + X-Loc-Long 优先；提供坐标时不再使用文本类请求头（City、State、Country、Postal-Code），只有没有坐标时才用文本请求头。
15. 带坐标的本地查询示例：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"。
16. 带地名的本地查询示例：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"。
17. 用 Goggles 自定义排序来控制哪些来源参与 grounding：官方文档只用 $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。
18. Goggles 两种用法：托管式 --data-urlencode "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/1k_short.goggle"（必须托管在 GitHub/GitLab，包含 ! name:、! description:、! author: 头，并在 https://search.brave.com/goggles/create 注册）；内联式 --data-urlencode 'goggles=$discard\n$site=example.com'（无需注册）。
19. Goggles 语法：规则以 $ 开头加逗号分隔选项；动作三选一 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。
20. 需要来源元数据时设置 enable_source_metadata=true，会在每个 sources[url] 条目中附加 site_name、favicon、thumbnail 和 description。
21. 解析响应：grounding.generic 是主 grounding 数据（数组，每项含 url、title、snippets）；grounding.poi 为兴趣点数据（仅本地召回时）；grounding.map 为地图/地点结果（仅本地召回时）；sources 以 URL 为键存放所有引用页面的元数据（title、hostname、age 等）。
22. 注意 snippets 可能是纯文本，也可能是 JSON 序列化的结构化数据（表格、schema、代码块），LLM 能很好处理这种混合格式。
23. 性能优化：使用满足需求的最小 count 和 maximum_number_of_tokens；本地查询时提供位置请求头。
24. 来源质量优先于召回时设 context_threshold_mode=strict，并用 Goggles 限定可信来源。

适用边界 · 注意事项

• 需要端到端带引用的 AI 答案、或需要多轮迭代研究时，应改用 answers（/res/v1/chat/completions，OpenAI 兼容接口），而不是本 API。
• 没有 Brave Search API Key 或未订阅 Search 计划时无法使用。
• 对延迟极度敏感且无法接受额外推理成本时，不要盲目调大 maximum_number_of_tokens 和 count。