联网搜索配置指南

本文是 V-77「web_fetch 正文提取加固 + 搜索失败优雅降级」的配套配置手册,与 builtin.py 中 _search_* / apply_search_config 互补:代码讲「能做什么」,本文讲「拿到TrueAGT后,怎么把它用得更稳」。 设计定位回顾:联网搜索是工具调用(web_search / web_fetch),不是后台服务——agent 在需要实时信息时按调用付费式触发,不预抓、不轮询、不持久化到向量库(持久化是「知识库」的事,详见《设计方案》(配套设计说明)对应章节)。

1. 一句话结论(先读这条)

本软件的联网搜索走 多引擎回退,默认首选 Bing(HTML 抓取,无需 Key),依次回退 Baidu → DuckDuckGo。当你希望摆脱「频繁超时、HTML 被反爬」时,三条路线任选其一:

路线适用场景需要你提供抗反爬成本
A. HTML 抓取(默认)内网演示、低频查询、不愿暴露 Key无弱(依赖搜索引擎 HTML 端稳定性)0
B-1. SerpAPI(Google)要 Google 排序结果、要新闻/学术混合SerpAPI Key强(官方 JSON API)按调用计费,约 50 次/$5 起
B-2. Bing Web Search API已有 Azure 订阅、企业合规优先Azure Bing Key + 终结点可选强(官方 JSON API)Azure 按量计费(含 1000 次/月 入门额度)
C. SearXNG 自托管拒绝所有第三方 API、纯内网、信审要求"数据不出域"自建 SearXNG 实例 URL中(取决于上游引擎)服务器 + 运维

⚠️ 最关键的边界:

下面分「路线选型」「TrueAGT侧配置」「验证」「排错」「安全」五部分讲清。


2. 路线选型决策树

开始 只在内网跑 demo、不接公网 路线 A 需要公网访问、结果质量可接受偶发超时 路线 A + 提超时 需要稳定产出、要 Google 排序 路线 B-1(SerpAPI) 已有 Azure 订阅、合规要求 Azure 路线 B-2(Bing) 数据不能出域、拒绝第三方 API、运维能力够 路线 C(SearXNG)

3. TrueAGT侧配置(config.json)

搜索配置位于 config.json 的顶层 search 段。修改后重启 web.py 生效(启动期加载,不走热更新;但 web.py 路由 POST /api/search/config 提供运行期热切换,热切换只改内存不落盘,便于临时切换对比)。

3.1 路线 A:HTML 抓取(默认)

{
  "search": {
    "provider": "bing",
    "url": "",
    "api_key": ""
  }
}

3.2 路线 B-1:SerpAPI

{
  "search": {
    "provider": "serpapi",
    "api_key": "你的 SerpAPI Key(在 https://serpapi.com/ 控制台获取)",
    "url": ""
  }
}

3.3 路线 B-2:Bing Web Search API(Azure)

{
  "search": {
    "provider": "bingapi",
    "api_key": "你的 Azure 订阅密钥(Ocp-Apim-Subscription-Key)",
    "url": ""
  }
}

3.4 路线 C:SearXNG 自托管

{
  "search": {
    "provider": "searxng",
    "url": "https://searxng.example.com",
    "api_key": ""
  }
}

3.5 回退链(不论选哪条路线都生效)

TrueAGT搜索失败时会自动回退:

整体受 22 秒总预算约束(_SEARCH_TOTAL_BUDGET),任一引擎期间超时即停,避免一次对话被搜索拖死。

3.6 推荐写法:环境变量注入 API Key

config.json 已在 .gitignore 中,但仍建议通过环境变量注入 Key,便于:

TrueAGT当前不解析${ENV} 占位符(避免引入模板引擎依赖),但 web.py 提供 POST /api/search/config 路由支持运行期写入;亦可写一个启动包装脚本:

# /opt/trueagt/start.sh
export TRUE_AGT_SERPER_KEY="$(cat /run/secrets/serper)"
TrueAGT.exe --config config.json
# 在 config.json 写:
#   "api_key": "env:TRUE_AGT_SERPER_KEY"
# 然后在 web.py 启动前自行替换(不属于TrueAGT自带能力)
📌 注:TrueAGT目前对 api_key 字段是字面字符串,不会展开 env:VAR。上面提到的「包装脚本替换」是你需要自写的,TrueAGT没内置该逻辑(属部署层惯例,不进核心代码)。如需内置,请通过官方网站「联系我们」页面反馈,我们评估后决定是否纳入后续版本。

4. 验证步骤(配置完怎么测)

按顺序执行以下三步,10 分钟内可判定配置是否生效。

4.1 检查加载日志

启动 web.py 时看启动日志是否包含:

[搜索 provider=serpapi, url=, api_key 已配置]

或(默认):

[搜索 provider=bing, url=, api_key 未配置]

如果出现 [搜索 provider=<unknown>,回退到 bing] 说明 provider 字段拼写错——允许值是 bing/baidu/duckduckgo/serpapi/bingapi/searxng(区分大小写)。

4.2 HTTP 连通性检查(curl)

# 用登录后拿到的 token 替换 <TOKEN>
TOKEN=$(curl -s -X POST http://127.0.0.1:8765/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"henry","password":"..."}' | jq -r .token)

curl -s -X POST http://127.0.0.1:8765/api/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"verify-search","message":"用 web_search 搜一下「TrueAGT Agent 框架」, 给我 3 条结果","stream":false}'

预期返回中包含 web_search 工具调用记录与一组带链接的结果。

4.3 单元测试(提交前校验)

项目内已有 test_webtools.py(12 用例)与 test_websearch.py(13 用例),覆盖回退链与解析逻辑;test_smoke.py §12 段(行号见 提交前检查脚本 注册)覆盖 apply_search_config。提交前跑一遍:

python test_webtools.py     # 应输出 12/12 PASS
python test_websearch.py    # 应输出 13/13 PASS
请运行项目的提交前检查(默认档全绿方可提交)

5. 故障排查(按错误信息分类)

5.1 错误:[搜索失败] 所有搜索引擎均不可达

自上而下排查:

  1. 首选 provider 配置对吗?见 §1 列出的 6 个允许值。
  2. API Key 填了吗?如果 provider=serpapi 但 api_key="",会单独报 [搜索失败] 未配置 search.api_key,进不到「全部不可达」。
  3. 网络出域允许吗?TrueAGT无出网代理配置——内网部署必须确认 _http_get 走的不是受限代理。临时验证:
   # Linux/macOS
   curl -v "https://api.bing.microsoft.com/v7.0/search?q=test&count=1" \
     -H "Ocp-Apim-Subscription-Key: 你的key"
   # Windows (PowerShell)
   Invoke-WebRequest -Uri "https://api.bing.microsoft.com/v7.0/search?q=test&count=1" `
     -Headers @{"Ocp-Apim-Subscription-Key"="你的key"}

返回 200 = 通;返回 401/403 = Key 错或区域错。

  1. SearXNG 实例开 JSON 了吗?见 §7.3。
  2. 总预算 22 秒不够?搜索多次超时 → 调高 _SEARCH_ENGINE_TIMEOUT(单引擎 8 秒)与 _SEARCH_TOTAL_BUDGET(总 22 秒),但这是代码常量,修改后跑全量测试。

5.2 错误:[无正文] 该页面未提取到可读正文

判定:目标页是 JS 动态渲染页(React/Vue SPA、需要滚动加载、需点击「加载更多」)。

选择:

5.3 SearXNG 专属:[搜索失败] 无法访问 SearXNG 实例

逐项排查:

  1. url 填的是根地址,不是 /search。代码拼成 <url>/search?q=...&format=json,所以配置应是 https://searxng.example.com 而非 https://searxng.example.com/search。
  2. SearXNG 是否开启 JSON 输出——这是最常见的坑。编辑 SearXNG 实例的 settings.yml:
   search:
     formats:
       - html
       - json    # ← 必须有这一行,否则只返回 HTML

重启 SearXNG 后用 curl 验证:

   curl -s "https://searxng.example.com/search?q=test&format=json" | head -c 200

返回 JSON = 通;返回 HTML = 没开 JSON。

  1. 跨域/反向代理问题:如果 SearXNG 在内网、TrueAGT在另一台机器,确认反向代理(Nginx/Caddy)允许 format=json query 参数,并禁用强制 Accept: text/html。

5.4 API 类错误:SerpAPI 请求失败 / Bing Web Search API 请求失败


6. 安全与合规

6.1 API Key 不进 git

6.2 搜索内容合规

TrueAGT作为编排框架,搜索内容来自第三方引擎,端侧不能做完整合规判断(详见《合规上线准备》说明)。建议:

6.3 隐私:搜索词日志


7. 已知边界(架构红线决定的不解决项)

诚实列出TrueAGT永远不打算内置的能力,以免反复讨论:

7.1 不内置 JS 渲染浏览器

为什么:内嵌 Chromium(Playwright/Puppeteer)约 200MB 外部依赖 + 二进制分平台分发,击穿「纯标准库、零三方依赖」红线。设计文档《浏览器接入方案》(配套设计说明)已明确:复用用户本机浏览器,绝不内嵌。

当前能力分档:

实际含义:JS 渲染页的「正文抓取」永远做不到,「搜索结果摘要」永远做得到(因为 search engine 自己的 snippet 字段是后端渲染好的 JSON)。

7.2 不内置第三方搜索 SDK

为什么:SerpAPI / Bing API 已有官方 JSON 端点,TrueAGT用标准库 urllib.request 直接调用,不引入 SDK。原因:

7.3 SearXNG 不内置

为什么:SearXNG 是元搜索引擎(聚合 Google/Bing/DuckDuckGo 等),不是替代品。TrueAGT不替用户选上游——这是部署方的运维决策,TrueAGT只对接 JSON 端点。


8. 与 V-77 的关系(一段话)

V-77 在代码层做了三件事(详见 CHANGELOG-DEV.md):

  1. web_fetch 正文提取加固:三级回退(<article>/<main> 优先 → <div> 块评分 → JS 渲染判定),不再塌成页头片段。
  2. 搜索全失败时的错误信息改为可操作(不再是裸的「连接失败」)。
  3. web_fetch 空正文给出明确 JS 渲染提示。

本文不替代 V-77——V-77 改的是「抓得到 / 报错友好」,本文解决「选了哪个 provider、Key 怎么填、失败怎么查」。两者配合才能把联网搜索从「偶发能用」推到「稳定能用」。


9. 附录:字段速查表

字段类型必填默认说明
search.providerenum否bing6 个允许值:bing / baidu / duckduckgo / serpapi / bingapi / searxng。区分大小写。其它值启动期忽略,回退到 bing。
search.urlstring仅 searxng 必填""SearXNG 实例根地址,不带尾斜杠。其它 provider 留空。
search.api_keystring仅 serpapi/bingapi 必填""对应平台 API Key。SearXNG 一般留空(除非启用了鉴权插件)。

10. 相关文档

本文档随 TrueAGT 安装包一同发布;如与软件实际行为不一致,以软件当前版本为准。