llm-context

LLM Context

需要 API 密钥：前往 https://api.search.brave.com 获取

套餐：包含在 Search 套餐中。请参阅 https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Brave LLM Context API 提供经过预提取和相关性排序的网页内容，专为基于实时搜索结果为大模型响应提供依据而优化。与返回链接和摘要的传统网页搜索 API 不同，LLM Context 会提取网页的实际内容——文本块、表格、代码块和结构化数据，让你的大模型或 AI Agent 可以直接对其进行推理。

LLM Context 与 AI Grounding 的对比

功能	LLM Context（本服务）	AI Grounding（answers）
输出	为你的大模型提供原始提取内容	提供带引用的端到端 AI 答案
接口	REST API（GET/POST）	兼容 OpenAI 的 /chat/completions
搜索次数	每个请求进行一次搜索	多次搜索（迭代研究）
速度	快（<1s）	较慢
套餐	Search	Answers
端点	/res/v1/llm/context	/res/v1/chat/completions
最适合	AI Agent、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 hooks 的最佳实践"
复杂研究	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 让你可以控制哪些来源为大模型提供依据 — 这对 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 注册。内联规则无需注册。

语法：规则以 $ 开头，后接逗号分隔的选项。操作（任选其一）：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

资源：发现 · 语法 · 快速入门

响应格式

标准响应

{
  "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	兴趣点数据（仅限本地检索）
grounding.poi.name	string/null	兴趣点名称
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	页面日期，按四个固定位置排列：完整日期、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 序列化的结构化数据（表格、架构、代码块）。大模型能够很好地处理这种混合格式。

使用场景

• AI Agent：为你的 Agent 提供一个网页搜索工具，通过一次调用即可返回可直接使用的内容
• RAG 管道：以新鲜、相关的网页内容为大模型响应提供依据
• AI 助手与聊天机器人：提供有真实来源支持的事实性回答
• 问答：为特定查询检索聚焦的上下文
• 事实核查：根据当前网页内容核实说法
• 内容研究：通过一次 API 调用收集任意主题的来源资料

最佳实践

• 令牌预算：从默认值开始（maximum_number_of_tokens=8192、count=20）。简单查询时调低，复杂研究时调高。
• 来源质量：使用 Goggles 限定可信来源。精确率高于召回率时，将 context_threshold_mode=strict 设为 strict。
• 性能：使用满足需求的最小 count 和 maximum_number_of_tokens。对于本地查询，请提供位置标头。