Back to Details

llm-context

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LLM Context

LLM Context

Requires API Key: Get one at https://api.search.brave.com
Plan: Included in the Search plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe
Brave LLM Context API delivers pre-extracted, relevance-ranked web content optimized for grounding LLM responses in real-time search results. Unlike traditional web search APIs that return links and snippets, LLM Context extracts the actual page content—text chunks, tables, code blocks, and structured data—so your LLM or AI agent can reason over it directly.
需要API Key：请前往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 Agent可以直接基于这些内容进行推理。

LLM Context vs AI Grounding

LLM Context vs AI Grounding

FeatureLLM Context (this)AI Grounding (
answers
)
OutputRaw extracted content for YOUR LLMEnd-to-end AI answers with citations
InterfaceREST API (GET/POST)OpenAI-compatible 
/chat/completions
SearchesSingle search per requestMulti-search (iterative research)
SpeedFast (<1s)Slower
PlanSearchAnswers
Endpoint
/res/v1/llm/context
/res/v1/chat/completions
Best forAI agents, RAG pipelines, tool callsChat interfaces, research mode
特性LLM Context（当前接口）AI Grounding（
answers
接口）
输出供你的LLM使用的原始提取内容带引用的端到端AI答案
接口REST API（GET/POST）兼容OpenAI的
/chat/completions
搜索方式单次请求对应单次搜索多轮搜索（迭代式研究）
速度快速（<1秒）较慢
所属套餐SearchAnswers
端点
/res/v1/llm/context
/res/v1/chat/completions
最佳适用场景AI Agent、RAG流水线、工具调用聊天界面、研究模式

Endpoint

端点

http
GET  https://api.search.brave.com/res/v1/llm/context
POST https://api.search.brave.com/res/v1/llm/context
Authentication: 
X-Subscription-Token: <API_KEY>
header
Optional Headers:
  • Accept-Encoding: gzip
    — Enable gzip compression
http
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压缩

Quick Start

快速开始

GET Request

GET请求

bash
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}"
bash
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 Request (JSON body)

POST请求（JSON请求体）

bash
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"}'
bash
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"}'

With Goggles (Inline)

结合Goggles（内联方式）

bash
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'
bash
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'

Parameters

参数

Query Parameters

查询参数

ParameterTypeRequiredDefaultDescription
q
stringYes-Search query (1-400 chars, max 50 words)
country
stringNo
US
Search country (2-letter country code or 
ALL
)
search_lang
stringNo
en
Language preference (2+ char language code)
count
intNo
20
Max search results to consider (1-50)
参数类型是否必填默认值描述
q
字符串是-搜索查询（1-400字符，最多50个单词）
country
字符串否
US
搜索国家（两位国家代码或
ALL
）
search_lang
字符串否
en
语言偏好（两位及以上字符的语言代码）
count
整数否
20
要考虑的最大搜索结果数（1-50）

Context Size Parameters

上下文大小参数

ParameterTypeRequiredDefaultDescription
maximum_number_of_urls
intNo
20
Max URLs in response (1-50)
maximum_number_of_tokens
intNo
8192
Approximate max tokens in context (1024-32768)
maximum_number_of_snippets
intNo
50
Max snippets across all URLs (1-100)
maximum_number_of_tokens_per_url
intNo
4096
Max tokens per individual URL (512-8192)
maximum_number_of_snippets_per_url
intNo
50
Max snippets per individual URL (1-100)
参数类型是否必填默认值描述
maximum_number_of_urls
整数否
20
响应中的最大URL数量（1-50）
maximum_number_of_tokens
整数否
8192
上下文的近似最大token数（1024-32768）
maximum_number_of_snippets
整数否
50
所有URL的最大摘要片段数（1-100）
maximum_number_of_tokens_per_url
整数否
4096
单个URL的最大token数（512-8192）
maximum_number_of_snippets_per_url
整数否
50
单个URL的最大摘要片段数（1-100）

Filtering & Local Parameters

过滤与本地参数

ParameterTypeRequiredDefaultDescription
context_threshold_mode
stringNo
balanced
Relevance threshold for including content (
strict
/
balanced
/
lenient
)
enable_local
boolNo
null
Local recall control (
true
/
false
/
null
, see below)
goggles
string/listNo
null
Goggle URL or inline definition for custom re-ranking
参数类型是否必填默认值描述
context_threshold_mode
字符串否
balanced
内容纳入的相关性阈值（
strict
/
balanced
/
lenient
）
enable_local
布尔值否
null
本地召回控制（
true
/
false
/
null
，详见下文）
goggles
字符串/列表否
null
Goggle URL或内联定义，用于自定义排序

Context Size Guidelines

上下文大小指南

Task Typecountmax_tokensExample
Simple factual52048"What year was Python created?"
Standard queries208192"Best practices for React hooks"
Complex research5016384"Compare AI frameworks for production"
Larger context windows provide more information but increase latency and cost (of your inference). Start with defaults and adjust.
任务类型countmax_tokens示例
简单事实查询52048"Python是哪一年诞生的？"
标准查询208192"React Hooks最佳实践"
复杂研究5016384"对比适用于生产环境的AI框架"
更大的上下文窗口会提供更多信息，但会增加延迟和（你的推理）成本。建议从默认值开始调整。

Threshold Modes

阈值模式

ModeBehavior
strict
Higher threshold — fewer but more relevant results
balanced
Default — good balance between coverage and relevance
lenient
Lower threshold — more results, may include less relevant content
模式行为
strict
阈值更高——返回结果更少但相关性更强
balanced
默认值——在覆盖范围和相关性之间取得良好平衡
lenient
阈值更低——返回结果更多，可能包含相关性较弱的内容

Local Recall

本地召回

The 
enable_local
parameter controls location-aware recall:
ValueBehavior
null
(not set)		Auto-detect — local recall enabled when any location header is provided
true
Force local — always use local recall, even without location headers
false
Force standard — always use standard web ranking, even with location headers
For most use cases, omit 
enable_local
and let the API auto-detect from location headers.
enable_local
参数用于控制基于位置的召回：
值行为
null
（未设置）		自动检测——当提供任何位置请求头时启用本地召回
true
强制本地——始终使用本地召回，即使未提供位置请求头
false
强制标准——始终使用标准网页排序，即使提供了位置请求头
对于大多数使用场景，无需设置
enable_local
，让API通过位置请求头自动检测即可。

Location Headers

位置请求头

HeaderTypeDescription
X-Loc-Lat
floatLatitude (-90.0 to 90.0)
X-Loc-Long
floatLongitude (-180.0 to 180.0)
X-Loc-City
stringCity name
X-Loc-State
stringState/region code (ISO 3166-2)
X-Loc-State-Name
stringState/region name
X-Loc-Country
string2-letter country code
X-Loc-Postal-Code
stringPostal code
Priority: 
X-Loc-Lat
+ 
X-Loc-Long
take precedence. When provided, text-based headers (City, State, Country, Postal-Code) are not used for location resolution. Provide text-based headers only when you don't have coordinates.
请求头类型描述
X-Loc-Lat
浮点数纬度（-90.0至90.0）
X-Loc-Long
浮点数经度（-180.0至180.0）
X-Loc-City
字符串城市名称
X-Loc-State
字符串州/地区代码（ISO 3166-2）
X-Loc-State-Name
字符串州/地区名称
X-Loc-Country
字符串两位国家代码
X-Loc-Postal-Code
字符串邮政编码
优先级：
X-Loc-Lat
+ 
X-Loc-Long
优先级最高。当提供这两个参数时，基于文本的请求头（城市、州、国家、邮政编码）将不会用于位置解析。仅当没有坐标信息时，才提供基于文本的请求头。

Example: With Coordinates

示例：使用坐标

bash
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"
bash
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"

Example: With Place Name

示例：使用地点名称

bash
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"
bash
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 (Custom Ranking) — Unique to Brave

Goggles（自定义排序）——Brave独有功能

Goggles let you control which sources ground your LLM — essential for RAG quality.
Use CaseGoggle Rules
Official docs only
$discard\n$site=docs.python.org
Exclude user content
$discard,site=reddit.com\n$discard,site=stackoverflow.com
Academic sources
$discard\n$site=arxiv.org\n$site=.edu
No paywalls
$discard,site=medium.com
MethodExample
Hosted
--data-urlencode "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/1k_short.goggle"
Inline
--data-urlencode 'goggles=$discard\n$site=example.com'
Hosted goggles must be on GitHub/GitLab, include 
! name:
, 
! description:
, 
! author:
headers, and be registered at https://search.brave.com/goggles/create. Inline rules need no registration.
Syntax: 
$boost=N
/ 
$downrank=N
(1–10), 
$discard
, 
$site=example.com
. Combine with commas: 
$site=example.com,boost=3
. Separate rules with 
\n
(
%0A
).
Allow list: 
$discard\n$site=docs.python.org\n$site=developer.mozilla.org
— Block list: 
$discard,site=pinterest.com\n$discard,site=quora.com
Resources: Discover · Syntax · Quickstart
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=.edu
排除付费墙内容
$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注册。**内联式**规则无需注册。
语法：
$boost=N
/ 
$downrank=N
（1–10）、
$discard
、
$site=example.com
。可通过逗号组合规则：
$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
资源：探索Goggles · 语法说明 · 快速入门

Response Format

响应格式

Standard Response

标准响应

json
{
  "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"]
    }
  }
}
json
{
  "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"]
    }
  }
}

Local Response (with 
enable_local
)

本地响应（启用
enable_local
）

json
{
  "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": null
    }
  }
}
json
{
  "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": null
    }
  }
}

Response Fields

响应字段

FieldTypeDescription
grounding
objectContainer for all grounding content by type
grounding.generic
arrayArray of URL objects with extracted content (main grounding data)
grounding.generic[].url
stringSource URL
grounding.generic[].title
stringPage title
grounding.generic[].snippets
arrayExtracted smart chunks relevant to the query
grounding.poi
object/nullPoint of interest data (only with local recall)
grounding.poi.name
string/nullPoint of interest name
grounding.poi.url
string/nullPOI source URL
grounding.poi.title
string/nullPOI page title
grounding.poi.snippets
array/nullPOI text snippets
grounding.map
arrayMap/place results (only with local recall)
grounding.map[].name
string/nullPlace name
grounding.map[].url
string/nullPlace source URL
grounding.map[].title
string/nullPlace page title
grounding.map[].snippets
array/nullPlace text snippets
sources
objectMetadata for all referenced URLs, keyed by URL
sources[url].title
stringPage title
sources[url].hostname
stringSource hostname
sources[url].age
array/nullPage modification dates (when available)
Note: Snippets may contain plain text OR JSON-serialized structured data (tables, schemas, code blocks). LLMs handle this mixed format well.
字段类型描述
grounding
对象所有按类型分类的基础数据容器
grounding.generic
数组包含提取内容的URL对象数组（主要基础数据）
grounding.generic[].url
字符串来源URL
grounding.generic[].title
字符串页面标题
grounding.generic[].snippets
数组提取的与查询相关的智能文本块
grounding.poi
对象/空值兴趣点数据（仅启用本地召回时返回）
grounding.poi.name
字符串/空值兴趣点名称
grounding.poi.url
字符串/空值POI来源URL
grounding.poi.title
字符串/空值POI页面标题
grounding.poi.snippets
数组/空值POI文本片段
grounding.map
数组地图/地点结果（仅启用本地召回时返回）
grounding.map[].name
字符串/空值地点名称
grounding.map[].url
字符串/空值地点来源URL
grounding.map[].title
字符串/空值地点页面标题
grounding.map[].snippets
数组/空值地点文本片段
sources
对象所有引用URL的元数据，以URL为键
sources[url].title
字符串页面标题
sources[url].hostname
字符串来源主机名
sources[url].age
数组/空值页面修改日期（若可用）
注意：文本片段可能包含纯文本或JSON序列化的结构化数据（表格、模式、代码段）。LLM可以很好地处理这种混合格式。

Use Cases

使用场景

  • AI Agents: Give your agent a web search tool that returns ready-to-use content in a single call
  • RAG Pipelines: Ground LLM responses in fresh, relevant web content
  • AI Assistants & Chatbots: Provide factual answers backed by real sources
  • Question Answering: Retrieve focused context for specific queries
  • Fact Checking: Verify claims against current web content
  • Content Research: Gather source material on any topic with one API call
  • AI Agent：为你的Agent提供一个网页搜索工具，单次调用即可返回可直接使用的内容
  • RAG流水线：让LLM的响应基于新鲜、相关的网页内容
  • AI助手与聊天机器人：提供由真实来源支撑的事实性答案
  • 问答系统：为特定查询检索精准的上下文
  • 事实核查：基于当前网页内容验证主张
  • 内容研究：通过一次API调用收集任意主题的素材

Best Practices

最佳实践

  • Token budget: Start with defaults (
    maximum_number_of_tokens=8192
    , 
    count=20
    ). Reduce for simple lookups, increase for complex research.
  • Source quality: Use Goggles to restrict to trusted sources. Set 
    context_threshold_mode=strict
    when precision > recall.
  • Performance: Use smallest 
    count
    and 
    maximum_number_of_tokens
    that meet your needs. For local queries, provide location headers.
  • Token预算：从默认值开始（
    maximum_number_of_tokens=8192
    ，
    count=20
    ）。简单查询可减少参数值，复杂研究可增加参数值。
  • 来源质量：使用Goggles限制为可信来源。当精准度优先于召回率时，设置
    context_threshold_mode=strict
    。
  • 性能优化：使用能满足需求的最小
    count
    和
    maximum_number_of_tokens
    。对于本地查询，请提供位置请求头。