需要 OpenAI 兼容的联网问答、引用或深度研究时，用…

在已有 Brave Search API Key 和 Answers 订阅时，通过 OpenAI 兼容的 /chat/completions 快速获得带引用的联网 AI 答案，或开启 enable_research 做多轮深度研究。

适用场景

解决思路

1. 准备 API Key：在 https://api.search.brave.com 获取 Brave Search API Key，并确认订阅包含 Answers plan（https://api-dashboard.search.brave.com/app/subscriptions/subscribe）。
2. 调用端点：POST https://api.search.brave.com/res/v1/chat/completions。
3. 认证：请求头使用 X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}，或使用 Authorization: Bearer <API_KEY>。
4. 如使用 OpenAI SDK，设置 base_url 为 https://api.search.brave.com/res/v1、api_key 为 your-brave-api-key、model 为 brave，即可兼容调用。
5. messages 数组必须且只能包含 1 条 user 消息；不要传多轮 messages。
6. 选择模式：默认 single-search，即快速单次搜索答案；设置 enable_research=true 进入 research 多轮深度研究模式。
7. single-search 阻塞调用：curl 请求中设置 'stream': false，并发送 messages。
8. single-search 流式引用调用：curl 请求中设置 'stream': true 和 'enable_citations': true。
9. research 模式 curl 调用：设置 'stream': true、'enable_research': true，并按需设置 research_maximum_number_of_iterations（如 3）和 research_maximum_number_of_seconds（如 120）。
10. 标准参数 stream：bool，默认 true，开启 SSE streaming。
11. 标准参数 country：string，默认 'US'，可用两位国家代码或 'ALL'，控制搜索国家。
12. 标准参数 language：string，默认 'en'，控制响应语言。
13. 标准参数 safesearch：string，默认 'moderate'，可选 'off'、'moderate'、'strict'。
14. 标准参数 max_completion_tokens：int，默认 null，设置 completion token 上限。
15. 标准参数 enable_citations：bool，默认 false；仅 single-search streaming 时可用，开启内联 citation 标签。
16. 标准参数 web_search_options：object，默认 null；OpenAI 兼容，可设置 search_context_size 为 'low'、'medium'、'high'。
17. research 参数 enable_research：bool，默认 false，启用研究模式。
18. research 参数 research_allow_thinking：bool，默认 true，启用扩展思考。
19. research 参数 research_maximum_number_of_tokens_per_query：int，默认 8192，范围 1024-16384，控制每查询最大 token。
20. research 参数 research_maximum_number_of_queries：int，默认 20，范围 1-50，控制总搜索查询数。
21. research 参数 research_maximum_number_of_iterations：int，默认 4，范围 1-5，控制研究迭代次数。
22. research 参数 research_maximum_number_of_seconds：int，默认 180，范围 1-300，设置时间预算。
23. research 参数 research_maximum_number_of_results_per_query：int，默认 60，范围 1-60，控制每次搜索返回结果数。
24. 约束：enable_research=true 时必须 stream=true，否则报错 Blocking response doesn't support 'enable_research' option。
25. 约束：enable_research=true 不能与 enable_citations=true 同时使用，否则报错 Research mode doesn't support 'enable_citations' option。
26. 约束：enable_citations=true 时必须 stream=true，否则报错 Blocking response doesn't support 'enable_citations' option。
27. OpenAI SDK 阻塞 single-search：使用同步 OpenAI client，create(..., stream=False)，读取 response.choices[0].message.content。
28. OpenAI SDK 流式 single-search 引用：create(..., stream=True, extra_body={'enable_citations': True})，遍历 stream，打印 chunk.choices[0].delta.content。
29. OpenAI SDK research：使用 AsyncOpenAI，create(..., model='brave', stream=True, extra_body={'enable_research': True, 'research_maximum_number_of_iterations': 3, 'research_maximum_number_of_seconds': 120})，async for 遍历 chunk 并打印 delta.content。
30. 解析阻塞响应：stream=false 时返回标准 OpenAI-compatible JSON，从 choices[0].message.content 取答案。
31. 解析流式响应：SSE 返回 OpenAI-compatible chunk，逐条 data: {...} 读取，直到 data: [DONE]。
32. single-search 开启 enable_citations=true 时，处理流中的 <citation> 内联引用标签和 <usage> JSON 成本/计费标签。
33. research 模式处理流中的标签：<queries> 生成查询、<analyzing> URL 数量、<thinking> URL 选择推理、<progress> 统计信息、<blindspots> 知识盲点、<answer> 最终综合答案、<usage> JSON 成本/计费；保留 <blindspots>、<answer>、<usage>，其余用于调试。
34. 从 <usage> 标签解析 JSON-stringified 成本与 token 数据，例如 X-Request-Requests、X-Request-Queries、X-Request-Tokens-In、X-Request-Tokens-Out、X-Request-Requests-Cost、X-Request-Queries-Cost、X-Request-Tokens-In-Cost、X-Request-Tokens-Out-Cost、X-Request-Total-Cost，用于成本监控。
35. 集成聊天界面：设置 base_url 为 https://api.search.brave.com/res/v1，把 Brave Answers 作为 OpenAI SDK 的 drop-in 替代，获得联网 grounding 答案。
36. 做深度研究/综合主题调研：对复杂问题设置 enable_research=true，使用多来源综合，例如 Compare approaches to nuclear fusion。
37. 实现 cited answers：single-search 模式下设置 enable_citations=true 获取内联引用标签；research 模式的 <answer> 标签内置引用。
38. 设置超时：single-search 客户端超时至少 30s；research 模式至少 300s（5 分钟）。
39. 监控成本：解析流式响应中的 <usage> 标签。
40. 注意单条消息限制：messages 必须正好 1 条 user 消息。

适用边界 · 注意事项

• 没有 Brave Search API Key 或未订阅 Answers plan 时不可用。
• 只需要原始检索上下文交给自有 LLM 时，应使用 llm-context，而不是 answers。
• 不要在 blocking 模式下使用 enable_research 或 enable_citations；research 模式必须流式，且不能同时开 enable_citations。