这阵子我把 MoltBot 和 Bocha 接在一起，做了一套可落地的开源 AI 助手 + 智能联网搜索组合方案。玩大模型助手的朋友应该都有同感：模型本身再聪明，它的知识也被训练数据的时间点卡死了，你问它“今天有什么大新闻”或者“某库最新版本号是什么”，它要么含糊其辞，要么理直气壮地编一个。解决这个问题的思路不是换更强的模型，而是给助手的对话流程里挂上一个“联网搜索工具”。MoltBot 负责把模型、工具、对话管理串起来，Bocha 负责把搜索能力封装成普通 HTTP 接口，两者一打通，助手就从“闭卷答题”变成了“开卷查资料”。
这篇内容主要适合三类人：正在做私有化 AI 助手、想给本地部署模型补充实时信息能力的开发者，以及刚开始接触工具调用机制、想找个最小闭环练手的学习者。下面讲的接入方式不绑定具体实现，MoltBot 这类开源助手框架换成别的同类项目也一样适用，重点是把思路、参数选择和踩坑点讲透。
1. 先想清楚一个问题：AI 助手的知识为什么总是慢半拍
1.1 离线模型的边界在哪里
大模型的训练过程本质上是把某个时间点之前的人类语料压缩成参数，它的知识必然有截止日期。模型可以写诗、算题、写代码，但凡是需要“此时此刻”信息的事情，它天然不擅长。我之前用本地部署的模型做过一次测试，问它“某个开源框架本周有没有新版本”，它回答得头头是道，连版本号和更新日志都像模像样，结果一查全是编的。这不是模型能力不行，而是它压根没有获取新信息的通道。
对话类场景对实时性的要求没那么高，但一旦涉及实际操作，比如查接口文档的最新改动、帮用户找近期的活动信息、了解某个行业的最新动态，离线模型就没有办法了。很多人第一反应是换更大的模型，实际上模型再大，它的知识也是静态的。真正解决问题的是给它接上外部工具，让模型在回答问题之前先去“查一查”。
1.2 为什么是工具调用，而不是换个更大的模型
工具调用机制，业内通常叫 Function Calling 或者 Tool Use，它的核心思路特别直白：不改变模型本身的参数，只在模型判断“我需要外部信息”的时候，允许它输出一段结构化的调用请求，由框架去执行对应的函数，拿到结果后再交回给模型。整个过程就像你开卷考试时翻参考书，你的知识储备没变，但你能查到资料了。
MoltBot 在这里承担的是“考试监督员”的角色：它管理模型与工具之间的对话循环。模型输出一个调用请求，MoltBot 解析这个请求，去调用注册好的 Bocha 搜索函数，获取结果，然后把这些结果拼回上下文，让模型继续组织回答。这套设计的好处是模型、工具、对话逻辑三者解耦，你可以随时换模型、换搜索服务，不会互相影响。
1.3 一次完整的消息链路是什么样的
这段链路是整个方案的地基，我建议你把它理解透：
- 用户提问，消息进入 MoltBot 的对话循环
- 模型判断当前问题是否需要外部信息
- 如果需要，模型生成一个工具调用请求，比如“调用 web_search，参数 query 等于‘某某框架最新版本’”
- MoltBot 拦截到这个请求，执行注册好的 Bocha 搜索函数
- 把搜索返回的标题、摘要、链接拼接成文本，作为工具结果回填给模型
- 模型看到搜索结果后，组织最终答案返回给用户
从代码改动量来看，真正需要你写的只有一个搜索函数和一段工具描述。后面你会看到，这两个地方的细节质量，往往决定了整个方案好不好用。
2. 四个决定成败的细节：工具描述、API 接入、参数和缓存
2.1 工具描述写不好，模型真的不会用
很多人第一次接工具调用时，最困惑的问题就是：模型明明支持工具调用，为什么死活不触发？我踩过这个坑之后才明白，问题多半出在工具描述上。
模型不是人，它不知道你的 web_search 函数什么时候该用。它只能根据工具描述里的文字来判断。所以描述必须包含两个信息：一是触发条件，二是参数含义。我常用的写法是这样的：
工具名：web_search 描述：当你需要获取最新信息、实时数据、近期新闻、项目动态、产品版本等训练数据中不存在的信息时，调用此工具。参数 query 是搜索关键词，必须是简洁的短语，不宜过长。
这里的关键词是“训练数据中不存在的信息”。你把这个触发条件写清楚，模型就会在回答“今天天气怎么样”这类问题时主动调用搜索，而不是自顾自地编答案。反过来，如果你的描述写得含糊，模型就会倾向于少调用，宁可编也不查。
2.2 Bocha 搜索接口的核心处理逻辑
Bocha 这类搜索 API 通常提供标准的 HTTP 接口，你发送一个查询词和几个控制参数，它返回一组搜索结果，每条包含标题、链接、摘要和发布时间。接入本身不复杂，但有几个处理细节值得注意。
第一，不要一股脑把完整结果塞给模型。搜索接口返回的摘要有时候很长，如果一次取回十几条，每条都原文放进去，上下文很快就爆了，而且模型会被大量噪音干扰。我一般只取前 6 到 8 条，每条标题截断到 30 字以内，摘要截断到 80 字左右，再把发布时间带上，形成紧凑的文本块。这条文本块才是真正给模型看的“资料”。
第二，排序逻辑要想清楚。搜索接口默认返回的排序不一定是最新的，很多场景下你需要的是最近三个月的信息，这时候可以靠发布时间字段做一次过滤或重排。如果接口本身支持时间范围参数，直接传参更省事。
第三，异常处理不能省。网络请求一定会遇到超时、频控、临时不可用，这些情况不能让整个助手崩溃。正确做法是捕获异常后给模型返回一段提示，比如“搜索服务暂时不可用，请基于已有知识回答”，这样至少不会让对话中断。
2.3 参数别照抄默认值，按搜索场景调
工具调用场景下的参数设置，跟普通聊天完全不同。普通聊天你希望模型自由发挥，温度可以调高一点，但工具调用场景下你希望模型“守规矩”，按格式出牌，所以很多参数要往保守方向调。
| 参数 | 建议值 | 原因 |
|---|---|---|
| temperature | 0.2 - 0.4 | 降低生成随机性，避免模型在工具调用格式上出错 |
| max_tokens | 512 - 1024 | 搜索结果可能很长，给模型足够空间组织答案，但不宜无限大 |
| 搜索客户端超时 | 10 - 15 秒 | 太短容易超时，太长会拖慢整体响应 |
| 最大重试次数 | 2 次 | 搜索接口偶发抖动，重试两次基本能扛过去 |
| 单次搜索返回条数 | 6 - 8 条 | 太少信息不足，太多上下文被噪音淹没 |
| 搜索缓存时间 | 5 - 10 分钟 | 同一问题在短时间内的重复搜索，直接命中缓存 |
这里特别说一下 temperature。工具调用依赖模型生成符合 JSON 结构的内容，如果温度太高，模型容易在参数名、引号这些细节上出错，导致 MoltBot 解析不了。我一般把温度设在 0.3 左右，既保留一点灵活性，又保证格式稳定。
3. 从零到一完整落地：部署、代码与验证
3.1 环境准备与基础安装
整套方案的环境要求不高。我本地的部署环境是 Python 3.10，系统是常规的 64 位 Linux，模型推理服务跑在独立进程里。如果你从没接触过这类项目，先把基础环境理顺，再往下操作。
先把 MoltBot 克隆到本地，按项目 README 的说明安装依赖。通常就是一条 pip install 命令的事。然后确保你有一个可用的模型推理服务，MoltBot 一般兼容 OpenAI 接口格式，所以你既可以用在线模型，也可以用本地起一个兼容接口的推理服务。我这边是本地部署，base_url 填的是 http://127.0.0.1:8000/v1。
提示：如果你还没有可用的模型服务，建议先跑通一个最简对话，确认 MoltBot 本身没问题，再接搜索功能。不要一上来就两个东西一起调试，出了问题很难定位。
3.2 编写联网搜索函数
Bocha 接入的核心代码，其实就是把“发送搜索请求、解析返回结果、整理成紧凑文本”这三步封成一个函数。我用 Python 写了一个版本，仅供参考：
import os import httpx BOCHA_API_URL = os.getenv("BOCHA_API_URL", "https://api.bocha.example.com/v1/search") BOCHA_API_KEY = os.getenv("BOCHA_API_KEY") def search_web(query: str, max_results: int = 6) -> str: headers = { "Authorization": f"Bearer {BOCHA_API_KEY}", "Content-Type": "application/json", } payload = { "query": query, "max_results": max_results, "language": "zh-CN", "recency": "1y", } try: with httpx.Client(timeout=12) as client: resp = client.post(BOCHA_API_URL, json=payload, headers=headers) resp.raise_for_status() data = resp.json() except Exception as exc: return f"搜索服务暂时不可用，错误信息：{exc}" lines = [] for item in data.get("results", [])[:max_results]: title = (item.get("title") or "")[:30] snippet = (item.get("snippet") or "")[:80] url = item.get("url") or "" pub_time = item.get("publish_time") or "" lines.append(f"- {title}（{pub_time}）\n 摘要：{snippet}\n 链接：{url}") return "\n".join(lines) if lines else "没有搜索到相关信息。"这段代码里，我把 API Key 放在环境变量里，避免硬编码到配置文件。搜索结果的摘要被截断成 80 字，标题 30 字，这个长度是我实测下来比较舒服的配置，既能覆盖关键信息，又不会让上下文爆炸。
注意我这里用的是示例域名和占位地址，你实际接入时替换成 Bocha 服务方给你的真实接口地址和 Key 就行。
3.3 注册工具并配置助手
搜索函数写好后，下一步是把它注册成 MoltBot 的工具。工具描述我上面讲过，这里放一个常见配置：
tools: - name: web_search description: 当需要获取最新信息、实时数据、近期新闻、项目动态或版本信息时调用。参数 query 为搜索关键词，需简洁明确。 parameters: query: type: string required: true max_results: type: integer required: false default: 6模型配置里指定你的本地推理服务地址，然后把工具列表挂到会话上下文上。MoltBot 启动后，会自动把工具描述发送给模型，模型在回答过程中如果判断需要搜索，就会生成对应的调用请求。
这一步做完，整套系统的骨架就已经立起来了。
3.4 启动一次真实对话验证闭环
配置完成后，用一个必须联网才能回答的问题来验证。我自己测试时问的是：“最近一个月有哪些值得关注的开源 AI 项目发布了新版本？”
打开日志，你会看到类似下面的输出：
用户：最近一个月有哪些值得关注的开源 AI 项目发布了新版本？ 模型意图：需要调用 web_search 获取最新信息 工具调用：web_search(query="开源 AI 项目 新版本 发布", max_results=8) 工具结果：返回 8 条搜索摘要 模型回答：根据搜索结果，最近一个月有以下值得关注的动态……看到这个链路走通，说明整套方案已经可以用了。第一次调试时千万别跳过这步，只有确认完整闭环，后面再去做多工具、缓存、知识库那些进阶玩法才会踏实。
3.5 首轮调优三个指标
闭环跑通后，我建议立刻做三件事：第一，把工具的“结果返回条数”从默认值降下来，如果 8 条信息里经常有一半是噪音，那就试试 5 条，反而更精准；第二，观察日志里每次搜索的 query 是否合理，如果模型生成的搜索词太长、太口语化，就在系统提示词里加一句“搜索关键词控制在 20 字以内”；第三，把相同的搜索问题重复问几遍，确认缓存是否生效，这直接关系到接口成本。
4. 真实踩过的坑：分类排查与解决记录
4.1 工具一直不触发？先查这三个地方
这是所有人都会遇到的第一个问题。我自己的排查顺序很固定：
第一，看工具描述是否写清了触发条件。描述里只写“搜索工具”，没有说明“何时使用”，模型就无法判断。把“当需要最新信息时调用”这样的触发条件写进去，通常能解决大部分问题。
第二，看模型服务是否真正支持工具调用。有些轻量模型虽然参数上写了支持，实际生成的格式却不稳定。你可以在日志里看模型有没有输出包含工具名称的内容，如果完全没有相关痕迹，就换一个对工具调用支持更好的模型。
第三，看 temperature 是否太高。我上面提过，温度太高会让格式失控，模型可能输出“我想搜索关于某某的信息”而不是一个标准的调用请求。温度调到 0.3 左右，很多问题会自然消失。
4.2 搜索返回了内容，但模型不会用
闭环通了之后，另一种尴尬情况是：搜索明明返回了一堆有价值的资料，模型却像没看到一样，继续凭空回答，或者把摘要原样粘贴。
这通常不是模型的阅读理解有问题，而是上下文里缺少引导。搜索结果回填给模型时，前面的指令写得不够明确。我习惯在工具结果的格式里加一行固定引导：“以下是网络搜索结果，请基于这些信息作答。如果信息不足，请明确告知查询不到，不要自行编造。”加完之后，模型的回答质量明显提升，而且开始学会说“没有查到相关信息”，而不是硬着头皮编。
4.3 鉴权失败、请求超时和接口频控
我把这三类问题放在一起说，因为它们的处理思路类似，都是围绕稳定性和成本。
| 异常现象 | 常见原因 | 处理办法 |
|---|---|---|
| 返回 401 或鉴权失败 | API Key 未配置或已失效 | 检查环境变量是否成功加载，确认 Key 是否在有效期内 |
| 请求超时 | 网络波动或接口响应慢 | 客户端超时调到 12-15 秒，增加一次重试 |
| 返回频控错误 | 请求频率超过接口限制 | 加缓存降低重复请求，必要时用指数退避策略 |
| 响应异常但进程崩溃 | 工具层没有 try-except | 在搜索函数里捕获所有异常，返回降级提示 |
其中缓存是大多数场景下最直接有效的解法。同样是“某某框架新版本”这个问题，用户在一个对话里反复追问是很正常的，没有缓存的话，每一次追问都会产生一次真实的搜索请求。
4.4 一个容易被忽略的上下文管理问题
搜索结果回填给模型之后，这些内容会一直留在上下文中。如果对话轮次多，上下文越积越长，模型会渐渐“忘掉”之前的信息，回答质量下降，Token 成本也更高。
我的处理经验是：给对话设置一个合理的上下文窗口，超过一定轮数就做摘要压缩。工具调用的中间结果可以单独存到一个临时变量里，不全部塞进对话历史。简单说，用户只需要知道“你查到过这个信息”，不需要每轮都重复带着那 8 条搜索摘要进入新的对话。
5. 再往前一步：缓存、知识库和多工具协作
5.1 实现一个简单的搜索缓存
缓存听起来很高级，其实实现起来特别简单。用 Python 自带的功能就能搞定：
from functools import lru_cache @lru_cache(maxsize=128) def cached_search(query: str, max_results: int = 6): return search_web(query, max_results)加上这个装饰器之后，相同的搜索请求在 5 分钟内命中缓存，不会重复调用接口。我实测的效果很明显，搜索的调用量大概掉了三分之一。如果项目对缓存时间有更精细的要求，可以改成带 TTL 的内存缓存，或者直接用 SQLite 做持久化。
5.2 搜索结果转知识库：从“搜完即忘”到“越用越准”
单次搜索的缺点是“搜完即忘”，搜索结果只在当轮对话里有效，下次遇到类似问题还得重新请求。更进一步的做法是，把每次搜索返回的高质量摘要写入一个本地知识库，下次遇到相似问题，先查本地，再决定要不要发新请求。
这就是一个轻量级的 RAG 思路。实现时不需要复杂框架，一个向量数据库加上简单的相似度检索就够了。每次搜索拿到结果后，把标题、摘要、链接存进去，附带保存时间。下一次提问时，先向量检索本地知识库，找到最相似的历史结果直接复用。这个方案特别适合有固定领域、信息更新不快的场景。
5.3 多工具协作，让助手真正“活”起来
联网搜索只是整个工具链的第一块拼图。一旦你理解了工具调用的机制，就会发现可以接的东西很多：天气查询、计算器、待办事项管理、网页正文抓取、定时任务提醒，这些能力本质上都是“模型输出一个调用请求，框架去执行对应函数”。
多工具的好处是模型可以从多个函数里选择最合适的一个，甚至在需要时组合调用。比如用户问“明天出门要不要带伞”，助手可以先调用天气工具查当地天气，再根据结果组织回答，整个过程用户感知不到工具的切换。
把搜索、天气、待办这些工具接齐之后，这个开源 AI 助手就不再只是一个聊天机器人，而是一个真正能帮忙干活的数字助手。
最后说一点我不会写进技术文档里的体会。第一次把搜索接上去的时候，我没做任何限流，也没加缓存，结果助手回答一个问题连续搜了四次，Token 消耗翻了一倍，搜索接口也被频控了。后来我只做了一个改动，在缓存装饰器外面套了一层时间判断，同一问题 5 分钟内不重复请求，并在工具描述里加了一句“仅当你确实需要最新信息时才调用”。这个小改动让整套系统的可用性提升非常明显。
如果你也想搭类似的组合，我建议先用最简配置跑通一条完整链路，确认模型能正确触发工具、能读取搜索结果，再去做缓存、知识库、多工具这些扩展。开源助手的真正价值，不在于模型参数多大，而在于你能给它接上多少接地气的工具。搜索只是第一个。
